update readme.md

CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.3.9] - 2023-11-22
+- update readme.md
+  - section about hardware performance (Kudos to SteveMicroCode #29)
+  - badges to platformIO + issues
+  - improve related section
+- update keywords.txt
+- **keyScan()** replaces keyscan() => prefer camelCase (prep 0.4.0)
+  - patched examples.
+- minor edits
+
+
 ## [0.3.8] - 2023-07-15
 - fix #27
 - replaced function data\[8] with a class level data\[8].
@@ -17,12 +28,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - fix bug in **displayRaw()** (add bool hasPoint).
 - update readme.md
 
-
 ## [0.3.7] - 2023-04-17
 - move code from .h to .cpp
 - add **displayTwoInt(int ll, int rr, bool colon = true)**
 - add **displayCelsius(int temp, bool colon = false)**
-- add '°' degree character (18)
+- add '°' degree character (18)
 - add examples
 - update readme.md
 

README.md

@@ -1,8 +1,12 @@
-[![Arduino CI](https://github.com/robtillaart/TM1637_RT/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
+
+[![Arduino CI](https://github.com/RobTillaart/TM1637_RT/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
 [![Arduino-lint](https://github.com/RobTillaart/TM1637_RT/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/TM1637_RT/actions/workflows/arduino-lint.yml)
 [![JSON check](https://github.com/RobTillaart/TM1637_RT/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/TM1637_RT/actions/workflows/jsoncheck.yml)
+[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/TM1637_RT.svg)](https://github.com/RobTillaart/TM1637_RT/issues)
+
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/TM1637_RT/blob/master/LICENSE)
 [![GitHub release](https://img.shields.io/github/release/RobTillaart/TM1637_RT.svg?maxAge=3600)](https://github.com/RobTillaart/TM1637_RT/releases)
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/TM1637_RT.svg)](https://registry.platformio.org/libraries/robtillaart/TM1637_RT)
 
 
 # TM1637
@@ -14,14 +18,47 @@ Library for TM1637 driven displays and key scans.
 
 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 and 4 digit (clock) display.
+The library is mainly tested with Arduino UNO, both a 6 digits display and 4 digit (clock) display.
+The TM1637 can scan max 2 rows and 8 columns or a smaller keyboard.
+It is therefore not possible to scan a "standard" 3x4 or 4x4 matrix keypad.
 
 ESP32 is supported since 0.2.0 see https://github.com/RobTillaart/TM1637_RT/pull/5
 
 
 #### Related
 
 - https://docs.wokwi.com/parts/wokwi-tm1637-7segment#simulator-examples
+- https://github.com/SteveMicroCode/PIC-TM1637-Library-CodeOn 
+  - includes interesting hardware notes.
+- https://github.com/RobTillaart/HT16K33
+- https://github.com/RobTillaart/AnalogKeypad
+- https://github.com/RobTillaart/I2CKeyPad
+- https://github.com/RobTillaart/I2CKeyPad8x8
+
+
+#### Hardware connection and performance
+
+From tests of SteveMicroCode (See #29) it became clear that the proposed hardware in the
+datasheet is very robust but slow. See page 8 datasheet.
+Leaving out the 100 pF capacitors on the CLK and DIO line, or dimension them smaller,
+allows for faster communication and thus more efficient CPU use. 
+More about his tests see - https://github.com/SteveMicroCode/PIC-TM1637-Library-CodeOn 
+
+Additional tests of wfdudley (See Keyboard Scanner section) shows that reducing
+the pull up resistor from 10 KΩ to 1000 Ω improves the signal quality.
+This too allows for faster communication and efficient CPU use.
+
+Datasheet page 3: _and the clock frequency should be less than 250K_ (KHz)   
+This implies that the **setBitDelay()** could be set much lower than the default 10 micro
+seconds of the library. On "slower" platforms it might even be 0.
+However it is always important to do your own tests if you want to tweak performance
+beyond the specifications of the datasheet. 
+Interference from other electronic components is often nearby, and if you need longer
+cables consider shielded ones.
+
+If you have additional performance tweaks, please let me know.
+
+Note: Ω = ALT-234
 
 
 ## Interface
@@ -78,13 +115,17 @@ Applications include:
   - meters + centimetre MM:CC  (e.g distance sensor)
   - feet + inches FF:II
   - any pair of integers (-9 .. 99) side by side.
+
+
+#### Display functions III
+
 - **void displayCelsius(int temp, bool colon = false)** print temperature in **Celsius** format.
-The function allows a range from -9 .. 99 + °C.
+The function allows a range from -9 .. 99 + °C.
 The colon is default false.
 Works only on a 4 digit display.
 Colon can be used e.g. to indicate under- or overflow, or any other threshold.
 - **void displayFahrenheit(int temp, bool colon = false)** print temperature in **Fahrenheit** format.
-The function allows a range from -9 .. 99 + °F.
+The function allows a range from -9 .. 99 + °F.
 The colon is default false.
 Works only on a 4 digit display.
 Colon can be used e.g. to indicate under- or overflow, or any other threshold.
@@ -93,16 +134,19 @@ Colon can be used e.g. to indicate under- or overflow, or any other threshold.
 TM.displayCelsius(temperature, (temperature < -9) || (temperature > 99));
 ```
 
-##### Notes on temperature
+Note that the effective range of Celsius and Fahrenheit differs.
+When Fahrenheit goes from -9 to 99 Celsius goes from -26 to 37 (etc).
 
-Note that the effective range of C and F differs
-|   F   |   C   |   F   |   C   |
-|:-----:|:-----:|:-----:|:-----:|
-|  -9   | -26   |   16  |  -9   |
-|  99   |  37   |  210  |  99   |
+|   F   |   C   |      |   C   |   F   |
+|:-----:|:-----:|:----:|:-----:|:-----:|
+|  -9   | -26   |      |  -9   |   16  |
+|  99   |  37   |      |  99   |  210  |
 
-Need to think about a 3 digit temperature to extend the range -99 .. 999
-or to have one decimal.
+A three digit temperature, e.g. range -99 .. 999, or -9.9 .. 99.9 would be possible.
+Then one has to leave out either the ° character or the C/F.
+As the C/F is far more informative, the choice is fairly easy.
+Question is how to API should change, new function of new behaviour?
+See future.
 
 
 #### Brightness
@@ -113,8 +157,8 @@ or to have one decimal.
 
 #### KeyScan
 
-- **uint8_t keyscan(void)** scans the keyboard once and return result. 
-The keyscan() function cannot detect multiple keys.
+- **uint8_t keyScan(void)** scans the keyboard once and return result. 
+The keyScan() function cannot detect multiple keys.
 
 
 #### DisplayRaw explained
@@ -203,18 +247,21 @@ 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.  
+- Kudos to wfdudley for this section - See #11
+
+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.
+   keyScan results are reversed left for right from the data sheet.
 </TD>
 </TR>
 <TR>
@@ -231,41 +278,69 @@ If a key is pressed, then the values are as follows:
 </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>
+
+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.
+
+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.
+
+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.
+
+
+The unmodified generic TM1637 board (front and back).
+
 <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>
+
+
+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.
+
 <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.
+The 4 button keyboard plugged into the TM1637 board.
+
+<IMG src="images/disp_plus_kbd.jpg">
+
+
+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.
+
+<IMG src="images/slow_rise.jpg">
+
 
+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.
 
-## Keyscan
+<IMG src="images/fast_rise.jpg">
+
+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
+//  on the TM1637 boards tested by @wfdudley, keyScan() works well 
+//  if you add a 910 ohm or 1000 ohm 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.
@@ -283,32 +358,34 @@ See examples
 
 - (0.4.0)
   - remove obsolete **init()** from code
+  - remove keyscan() => keyScan()
   - **setLeadingZeros(bool on = false)** leading zeros flag, set data array to 0.
   - **getLeadingZeros()**
 
-
 #### Should
 
 - testing other platforms.
 - refactor readme.md
-- remove degree sign from **displayCelsius()** ?
+- remove degree sign from **displayCelsius()**
   - would allow one extra digit.
   - **displayFahrenheit()** idem.
   - could be optional when needed e.g. below -9 or above 99
 
-
 #### Could
 
-- **keyScan()** camelCase ?
 - add parameter for **hideSegement(idx, character == SPACE)** to overrule hide char.
   - space underscore or - are possible.
 - add **TM1637_UNDERSCORE** to char set. ```seg[19] == 0x08```
+- add **TM1637_UPPERSCORE** to char set. ```seg[20] == 0x01```
 - return bytes written as return value for display functions.
+  - like print(); or write();
 - **void displayHumidity(int hum, bool colon = false)** print humidity in **percent** format.
 The function allows a range from 0.00H .. 99.9H or 00.0H ?
 Colon to indicate rising / falling ????
 - generic function that displays three digits and one char ACDEFH ???
-  - common for celsius and fahrenheit and humidity?
+  - common for Celsius and Fahrenheit and Humidity?
+- **void displayAmpere(float amps)** Ampere 0.00 - 999 A
+
 
 #### Wont (unless requested)
 
@@ -328,8 +405,16 @@ Colon to indicate rising / falling ????
   - is now commented code, good enough + dumpcache()
 - extend some functions to 6 digit display too?
   - time(hh.mm.ss)
-  - Celsius (nn.nn°C)
+  - Celsius (nn.nn°C)
   - twoInt => threeInt
   - on request only
 
 
+## Support
+
+If you appreciate my libraries, you can support the development and maintenance.
+Improve the quality of the libraries by providing issues and Pull Requests, or
+donate through PayPal or GitHub sponsors.
+
+Thank you,
+