0.3.0 TM1637_RT

Author: RobTillaart

libraries/TM1637_RT/.arduino-ci.yml

@@ -1,7 +1,11 @@
 compile:
- # Choosing to run compilation tests on different Arduino platforms
+ # Choosing to run compilation tests on 2 different Arduino platforms
  platforms:
  - uno
- - leonardo
- - due
- - zero
+ # - due
+ # - zero
+ # - leonardo
+ - m4
+ - esp32
+ # - esp8266
+ # - mega2560

libraries/TM1637_RT/.github/workflows/arduino_test_runner.yml

@@ -4,9 +4,14 @@ name: Arduino CI
 on: [push, pull_request]
 
 jobs:
- arduino_ci:
+ runTest:
  runs-on: ubuntu-latest
 
  steps:
  - uses: actions/checkout@v2
- - uses: Arduino-CI/action@v0.1.0
+ - uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: 2.6
+ - run: |
+ gem install arduino_ci
+ arduino_ci.rb

libraries/TM1637_RT/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Rob Tillaart
+Copyright (c) 2019-2021 Rob Tillaart
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

libraries/TM1637_RT/README.md

@@ -7,21 +7,18 @@
 
 # TM1637
 
-Library for TM1637 driven displays.
+Library for TM1637 driven displays and keyscans.
 
 
 ## Description
 
-The TM1637 drives 7 segment displays
+The TM1637 drives 7 segment displays and can also scan a 16 key keyboard
 
 Library is tested with Arduino UNO and a 6 digits display.
 
 ESP32 is supported since 0.2.0 see https://github.com/RobTillaart/TM1637_RT/pull/5
 
 
-TO ELABORATE
-
-
 ## Interface
 
 - **TM1637()** constructor
@@ -34,6 +31,18 @@ As the display is only tested with a 6 digit display, this is used as the defaul
 - **void displayClear()** writes spaces to all positions, effectively clearing the display.
 - **void setBrightness(uint8_t b)** brightness = 0 .. 7 default = 3.
 - **uint8_t getBrightness()** returns value set.
+- **uint8_t keyscan(void)** scans the keyboard once and return result. The keyscan() function cannot detect multiple keys.
+
+
+**displayRaw()** can display multiple decimal points, by setting the high bit (0x80) in each character for which you wish to have a decimal lit. Or you can use the pointPos argument to light just one decimal at that position.
+
+**displayRaw()** can display some of the alphabet as follows:
+ - space (blank) is 0x10
+ - - (blank) is 0x11
+ - a-f are coded as 0x0a-0x0f
+ - g-z are coded as 0x12-0x25
+
+So "hello " is coded as 0x13, 0x0e, 0x17, 0x17, 0x1a, 0x10
 
 
 ### Tuning function
@@ -44,13 +53,78 @@ To tune the timing of writing bytes.
 - **uint8_t getBitDelay()**
 
 
-### Tuning minimum pule length
+### Tuning minimum pulse length
 
 The class has a conditional code part in writeSync to guarantee the length of pulses
 when the library is used with an ESP32. The function called there **nanoDelay(n)**
 needs manual adjustment depending upon processor frequency and time needed for a digitalWrite.
 Feel free to file an issue to get your processor supported.
 
+### Keyboard Scanner usage and notes
+
+
+Calling keyscan() returns a uint8_t, whose value is 0xff if no keys are being pressed at the time. The TM1637 can only see one key press at a time, and there is no "rollover". If a key is pressed, then the values are as follows:
+
+<CENTER>
+<TABLE>
+<TR>
+<TD colspan = 10 align="center">
+ keyscan results are reversed left for right from the data sheet.
+</TD>
+</TR>
+<TR>
+<TH>pin</TH><TD>&nbsp</TD><TD>2</TD><TD>3</TD><TD>4</TD><TD>5</TD><TD>6</TD><TD>7</TD><TD>8</TD><TD>9</TD>
+</TR>
+<TR>
+</TD><TD>&nbsp;</TD><TH>name</TH><TD>sg1</TD><TD>sg2</TD><TD>sg3</TD><TD>sg4</TD><TD>sg5</TD><TD>sg6</TD><TD>sg7</TD><TD>sg8</TD>
+</TR>
+<TR>
+</TD><TD>19</TD><TD>k1</TD><TD>0xf7</TD><TD>0xf6</TD><TD>0xf5</TD><TD>0xf4</TD><TD>0xf3</TD><TD>0xf2</TD><TD>0xf1</TD><TD>0xf0</TD>
+</TR>
+<TR>
+</TD><TD>20</TD><TD>k2</TD><TD>0xef</TD><TD>0xee</TD><TD>0xed</TD><TD>0xec</TD><TD>0xeb</TD><TD>0xea</TD><TD>0xe9</TD><TD>0xe8</TD>
+</TR>
+</TABLE>
+</CENTER>
+<P>
+To modify a "generic" TM1637 board for use with a keyboard, you must add connections to either or both of pins 19 and 20 (these are the "row" selects) and then to as many of pins 2 through 9 (the "columns") as needed. It is easiest to connect to the "column pins" (2-9) by picking them up where they connect to the LED displays (see second photo). Generic keyboards that are a 4x4 matrix won't work; the TM1637 can only scan a 2x8 matrix. Of course, fewer keys are acceptable; I use a 1x4 keyboard in my projects.
+</P>
+<P>
+Further, the TM1637 chip needs a fairly hefty pull-up on the DIO pin for the keyscan() routine to work. There is no pull-up in the TM1637 itself, and the clone boards don't seem to have one either, despite the data sheet calling for 10K ohms pull-ups on DIO and CLOCK. 10K is too weak anyway. The slow rise-time of the DIO signal means that the "true/high" value isn't reached fast enough and reliably enough for the processor to read it correctly. The new pull-up reduces the rise time of the signal, so that true/high values are achieved in a few microseconds. I find that a 1K (1000) ohm resistor from DIO to 3.3 v works well. This is perfect with a 3.3 volt processor like the ESP8266 or ESP32, and a 5V Atmega 328 ("Arduino UNO") family processor is happy with that as well.
+</P>
+<P>
+The TM1637 boards want to be run off of 5 volts, regardless of what the processor voltage is. Their logic levels are compatible with 3.3 volt processors, and they need 5 volts to make sure the LEDs light up.
+</P>
+The unmodified generic TM1637 board (front and back).</br>
+<IMG src="images/unmodified.jpg">
+</br>
+The modified generic TM1637 board with connector for 1x4 keyboard. The blue wire is bringing out pin 19 (k1). Four segments/columns are picked up from the LEDs.</br>
+<IMG src="images/modified.jpg">
+</br>
+The 4 button keyboard plugged into the TM1637 board.</br>
+<IMG src="images/disp_plus_kbd.jpg"></br>
+</br>
+Scope photo showing slow rise time of DIO pin (upper trace) on the unmodified TM1637. The lower trace is the CLK. The 8 fast CLK pulses on the left represent the 0x42 command to read keyboard being sent to the TM1637.</br>
+<IMG src="images/slow_rise.jpg"></br>
+</br>
+Scope photo showing faster rise time of DIO pin (upper trace) with 1000 ohm pull-up on DIO. In both scope photos, the F5 key is pressed; the bits are least significant bit (LSB) first, so read as 10101111 left to right.</br>
+<IMG src="images/fast_rise.jpg"></br>
+
+The scope photos were taken using the TM1637_keyscan_raw example, with the scope trigger hooked to the TRIGGER pin, and the two channel probes hooked to DIO and CLK. Vertical sensitivity is 2v/division, horizontal timebase is 20usec/division.
+
+## Keyscan
+
+Implemented in version 0.3.0 Please read the datasheet to understand the limitations.
+
+```
+// NOTE: 
+// on the TM1637 boards tested by @wfdudley, keyscan() works well 
+// if you add a 910 ohm or 1 Kohm pull-up resistor from DIO to 3.3v
+// This reduces the rise time of the DIO signal when reading the key info.
+// If one only uses the pull-up inside the microcontroller, 
+// the rise time is too long for the data to be read reliably.
+```
+
 
 ## Operation
 

libraries/TM1637_RT/TM1637.cpp

@@ -2,7 +2,7 @@
 // FILE: TM1637.cpp
 // AUTHOR: Rob Tillaart
 // DATE: 2019-10-28
-// VERSION: 0.2.0
+// VERSION: 0.3.0
 // PURPOSE: TM1637 library for Arduino
 // URL: https://github.com/RobTillaart/TM1637_RT
 //
@@ -11,14 +11,26 @@
 // 0.1.1 2021-02-15 first release + examples. 
 // 0.1.2 2021-04-16 update readme, fix default values.
 // 0.2.0 2021-09-26 add ESP32 support - kudos to alexthomazo
+// 2021-10-07 add support for letters g-z; added keyscan()
+// tested on ESP8266
+// 0.3.0 2021-10-27 improved keyscan + documentation - kudos to wfdudley
+
 
 // tested on 6 digits display only for now.
 
 
+// NOTE: on the inexpensive TM1637 boards @wfdudley has used, keyscan
+// works if you add a 1000 ohm pullup resistor from DIO to 3.3v
+// This reduces the rise time of the DIO signal when reading the key info.
+// If one only uses the pull-up inside the microcontroller, 
+// the rise time is too long for the data to be read reliably.
+
+
 #include "TM1637.h"
 
 
 #define TM1637_ADDR_AUTO 0x40
+#define TM1637_READ_KEYSCAN 0x42
 #define TM1637_ADDR_FIXED 0x44
 
 #define TM1637_CMD_SET_DATA 0x40
@@ -50,6 +62,14 @@ static uint8_t seg[] =
  0x77, 0x7c, 0x39, 0x5e, 0x79, 0x71, 0x00, 0x40 // A - F, ' ', '-'
 };
 
+static uint8_t alpha_seg[] =
+{
+ 0x00, 0x74, 0x10, 0x00, // g, h, i, j,
+ 0x00, 0x38, 0x00, 0x54, // k, l, m, n,
+ 0x5c, 0x00, 0x00, 0x50, // o, p, q, r,
+ 0x00, 0x31, 0x1c, 0x1c, // s, t, u, v,
+ 0x00, 0x00, 0x00, 0x00 // w, x, y, z
+};
 
 TM1637::TM1637()
 {
@@ -160,7 +180,7 @@ void TM1637::setBrightness(uint8_t b)
 
 void TM1637::displayRaw(uint8_t * data, uint8_t pointPos)
 {
- uint8_t b;
+ uint8_t b, dp;
  start();
  writeByte(TM1637_ADDR_AUTO);
  stop();
@@ -169,14 +189,28 @@ void TM1637::displayRaw(uint8_t * data, uint8_t pointPos)
  writeByte(TM1637_CMD_SET_ADDR);
  for (uint8_t i = 3; i < 6 ; i++)
  {
- b = seg[data[i]];
- if (i == pointPos) b |= 0x80;
+ dp = data[i] & 0x80;
+ data[i] &= 0x7f;
+ if(data[i] <= 17) {
+ b = seg[data[i]];
+ }
+ else if(data[i] <= 37) {
+ b = alpha_seg[data[i]-18];
+ }
+ if (i == pointPos || dp) b |= 0x80;
  writeByte(b);
  }
  for (uint8_t i = 0; i < 3 ; i++)
  {
- b = seg[data[i]];
- if (i == pointPos) b |= 0x80;
+ dp = data[i] & 0x80;
+ data[i] &= 0x7f;
+ if(data[i] <= 17) {
+ b = seg[data[i]];
+ }
+ else if(data[i] <= 37) {
+ b = alpha_seg[data[i]-18];
+ }
+ if (i == pointPos || dp) b |= 0x80;
  writeByte(b);
  }
  stop();
@@ -244,6 +278,47 @@ void TM1637::writeSync(uint8_t pin, uint8_t val)
 }
 
 
+// keyscan results are reversed left for right from the data sheet.
+// here are the values returned by keyscan():
+// pin 2 3 4 5 6 7 8 9
+// sg1 sg2 sg3 sg4 sg5 sg6 sg7 sg8
+// 19 k1 0xf7 0xf6 0xf5 0xf4 0xf3 0xf2 0xf1 0xf0
+// 20 k2 0xef 0xee 0xed 0xec 0xeb 0xea 0xe9 0xe8
+
+uint8_t TM1637::keyscan(void)
+{
+ uint8_t halfDelay = _bitDelay >> 1;
+ uint8_t key;
+ start();
+ key = 0;
+ writeByte(TM1637_READ_KEYSCAN);// includes the ACK, leaves DATA low
+ pinMode(_data, INPUT_PULLUP);
+
+ for (uint8_t i = 0; i <= 7; i++) {
+ writeSync(_clock, LOW);
+ delayMicroseconds(halfDelay);
+ writeSync(_clock, HIGH);
+ delayMicroseconds(halfDelay);
+ key >>= 1;
+ key |= (digitalRead(_data)) ? 0x80 : 0x00 ;
+ }
+
+ writeSync(_clock, LOW);
+ delayMicroseconds(halfDelay);
+ writeSync(_clock, HIGH);
+
+ // wait for ACK
+ delayMicroseconds(halfDelay);
+
+ // FORCE OUTPUT LOW
+ pinMode(_data, OUTPUT);
+ digitalWrite(_data, LOW);
+ delayMicroseconds(halfDelay);
+ stop();
+ return key;
+}
+
+
 // nanoDelay() makes it possible to go into the sub micron delays. 
 // It is used to lengthen pulses to be minimal 400 ns but not much longer. See datasheet.
 void TM1637::nanoDelay(uint16_t n)

libraries/TM1637_RT/TM1637.h

@@ -3,7 +3,7 @@
 // FILE: TM1637.h
 // AUTHOR: Rob Tillaart
 // DATE: 2019-10-28
-// VERSION: 0.2.0
+// VERSION: 0.3.0
 // PUPROSE: TM1637 library for Arduino
 // URL: https://github.com/RobTillaart/TM1637_RT
 
@@ -13,7 +13,7 @@
 
 #include "Arduino.h"
 
-#define TM1637_LIB_VERSION (F(0.2.0))
+#define TM1637_LIB_VERSION (F(0.3.0))
 
 
 class TM1637
@@ -35,6 +35,7 @@ class TM1637
  // tune the timing of writing bytes.
  void setBitDelay(uint8_t bitDelay = 10) { _bitDelay = bitDelay; };
  uint8_t getBitDelay() { return _bitDelay; };
+ uint8_t keyscan(void);
 
  private:
  uint8_t _clock = -1;

libraries/TM1637_RT/examples/TM1637_alpha/TM1637_alpha.ino

@@ -0,0 +1,57 @@
+//
+// FILE: TM1637_alpha.ino
+// AUTHOR: William F. Dudley Jr.
+// VERSION: 0.1.0
+// PURPOSE: demo TM1637 library
+// DATE: 2021-10-12
+// URL: https://github.com/RobTillaart/TM1637
+
+
+#include "TM1637.h"
+
+TM1637 TM;
+
+void setup()
+{
+ Serial.begin(115200);
+ Serial.println(__FILE__);
+
+ TM.init(2, 3);
+ TM.setBrightness(2);
+}
+
+void ascii_to_7segment(char *buff, uint8_t *data) {
+ for(int8_t i = 0, j=5 ; j > -1 && i < 12 && buff[i] ; i++) {
+ if(isalpha(buff[i])) { buff[i] = tolower(buff[i]); }
+ if(buff[i] >= '0' && buff[i] <= '9') {
+ data[j--] = buff[i] - '0';
+ }
+ else if(buff[i] >= 'a' && buff[i] <= 'f') {
+ data[j--] = buff[i] - 'a' + 10;
+ }
+ else if(buff[i] >= 'g' && buff[i] <= 'z') {
+ data[j--] = buff[i] - 'g' + 18;
+ }
+ else if(buff[i] == '.') {
+ data[j+1] |= 0x80; // decimal point on previous digit
+ }
+ else {
+ data[j--] = 0x10; // blank
+ }
+ }
+}
+
+void loop()
+{
+char buff[20];
+uint8_t data[10];
+ strcpy(buff, "hello ");
+ Serial.println("hello");
+ ascii_to_7segment(buff, data);
+ TM.displayRaw(data, -1);
+ delay(1000);
+ TM.displayClear();
+ delay(1000);
+}
+
+// -- END OF FILE --