Version 1.7.0

README.md

@@ -1,5 +1,19 @@
 ![ module pics ](https://github.com/gavinlyonsrepo/TM1638plus/blob/master/extra/images/tm16383.jpg)
 
+Table of contents
+---------------------------
+
+  * [Overview](#overview)
+  * [Installation](#installation)
+  * [Features](#features)
+  * [Model One](#model-one)
+  * [Model Two](#model-two)
+  * [Model Three](#model-three)
+  * [Notes](#notes)
+  * [Memory](#memory)
+  * [Pic Ports](#pic-port)
+
+
 Overview
 --------------------------------------------
 * Name: TM1638plus
@@ -16,31 +30,17 @@ This library supports 3 different models, pictured above from left to right.
 
 * Tested on Development platforms: 
 
-1. Arduino UNO & NANO .
+1. Arduino UNO & NANO v3 .
 2. ATtiny85 .
 3. ESP32.
 4. STM32 STM32F103C8T6 "the blue pill".
 5. ESP8266.
-6. Teensy 4.0.
-
-See Issue B in issue section below for potential problems with high  frequency  MCU's.
+6. Teensy 4.0. (may not work at highest frequency see  notes section)
 
 * History: see CHANGELOG.md in extra folder
-* Contributors: [gabormay](https://github.com/gabormay)  [centic9](https://github.com/centic9)
+* Contributors: [gabormay](https://github.com/gabormay)  [centic9](https://github.com/centic9) [wunderbaum](https://github.com/wunderbaum)
 
-Table of contents
----------------------------
 
-  * [Overview](#overview)
-  * [Installation](#installation)
-  * [Features](#features)
-  * [Model One](#model-one)
-  * [Model Two](#model-two)
-  * [Model Three](#model-three)
-  * [Issues](#issues)
-  * [Memory](#memory)
-  * [See Also](#see-also)
-
 Installation
 ------------------------------
 
@@ -75,18 +75,13 @@ will be named Model 1 ,Model 2 and Model 3.
 | 2 | TM1638 KEYS, QYF  | 0 | 16 |
 | 3 | TM1638 V1.3 or LKM1638  | 8 bi color,  red and green  | 8 |
 
-There are two sets of files to support model 1 & 2 . I kept them separate as the models are wired quite different Model 1 address by digit, while Model 2 address by segment. So the code is quite different  for many functions. Also helps with hardware  testing and modularity.
-The same ASCII font file is used all models.
-Model 3 uses same code base as Model 1, just different example file and different use of setLED functions.
+There are two sets of files to support model 1 & 2 . I kept them separate as the models are wired quite different, Model 1 address by digit, while Model 2 address by segment. So the code is quite different  for most functions. Model 3 uses same code as Model 1, just different example file and different use of LED functions. Common settings, data and functions are in the TM1638plus_common.x files.
 
-| Model | Header | Code file | Example files | 
+| Model | Header | Code file | TEST files | 
 | ------ | ------ |  ------ | ------ |
-| 1 | TM1638plus.h       | TM1638plus.cpp | TM1638plus_BASIC_TEST.ino TM1638plus_TEST.ino |
+| 1 | TM1638plus.h       | TM1638plus.cpp | TM1638plus_HELLOWORLD_Model1.ino TM1638plus_TEST_Model1.ino |
 | 3 |  Same as  model 1     |  Same as  model 1 | TM1638plus_TEST_Model3.ino |
-| 2 | TM1638plus_Model2.h  | TM1638plus_Model2.cpp | TM1638plus_BASIC_TEST_Model2 TM1638plus_TEST_Model2.ino TM1638plus_ADC_TEST_Model2.ino TM1638plus_SCROLL_TEST_Model2.ino |
-
-It is possible to drive multiple modules and share the DIO and CLK lines see issue number 10
-at github for example code.
+| 2 | TM1638plus_Model2.h  | TM1638plus_Model2.cpp | TM1638plus_HELLOWORLD_Model2 TM1638plus_TEST_Model2.ino |
 
 Model One
 --------------------------------------
@@ -98,19 +93,15 @@ TM1638 Module 8 Push buttons 8 LEDS (LED & KEY)
 ![ sch ](https://github.com/gavinlyonsrepo/pic_16F18446_projects/blob/master/images/TM1638_2.jpg)
 
 This variant consist of an 8-digit seven segment display with decimal points,
-8 Leds and 8 Push buttons.
-
-Two 4 digit 3461AS-1 (.34 inch, 4 digit ,common Cathode,  decimal point, RED) are used in this module
-giving a total of 8 digits. A TM1638 controller chip drives the unit.
+8 Leds and 8 Push buttons. Two 4 digit 3461AS-1 (.34 inch, 4 digit ,common Cathode,  decimal point, RED) are used in this module giving a total of 8 digits. A TM1638 controller chip drives the unit.
 The unit is marked (LED & KEY).
 
-**Model 1 Library Functions and example files**
+**Model 1 Library Functions**
 
 The commented functions can be found in library header file TM1638plus.h.
 The library support ASCII ,text ,Hex and allows for setting individual segments,
 and the decimal point of segment.
 The TM1638plus_TEST.ino contains a set of tests demonstrating library functions.
-
 For more information see the commented headers in header file. 
 
 1. Print an ASCII character.
@@ -142,22 +133,15 @@ TM1638 Module 16 Push buttons (16 KEY) (QYF).
 
 ![ sch ](https://github.com/gavinlyonsrepo/TM1638plus/blob/master/extra/images/tm16382.jpg)
 
-
 They consist of an 8-digit seven segment display with decimal points,
-and 16 Push buttons.
-
-Two 4 digit 3461BS-1 (.34 inch, 4 digit ,common Anode,  decimal point, RED)are used in this module
-giving a total of 8 digits. A TM1638 controller chip drives the unit.
+and 16 Push buttons.Two 4 digit 3461BS-1 (.34 inch, 4 digit ,common Anode,  decimal point, RED)are used in this module giving a total of 8 digits. A TM1638 controller chip drives the unit.
+NB :  If your display shows "56781234" for "12345678" see Notes section. Note A.
 
-NB :  If your display shows "56781234" for "12345678" see Issues section. issue A.
-
-**Model 2 Library Functions and example files**
+**Model 2 Library Functions**
 
 The commented functions can be found in library header file TM1638plus_Model2.h.
 The library support Strings,decimal ,Hex ,raw ASCII data, setting individual segments,
-and the decimal point.
-
-For more detailed information on functions see commented headers in header file(.h).
+and the decimal point. For more detailed information on functions see commented headers in header file(.h).
 
 1. Print a Hexadecimal number with or without leading zeros
 2. Print a decimal number with or without leading zeros
@@ -166,59 +150,57 @@ For more detailed information on functions see commented headers in header file(
 5. Print a text string, dot function supported. 
 6. Read buttons status. User may want to debounce buttons depending on application.
 See TM1638plus_ADC_TEST_Model2.ino for debounce button example. 
+Two different functions to read buttons. 
 7. Reset and init module functions.
 8. Adjust brightness of module. Support 8 degree brightness adjustment.
 If user wishes to change the default brightness at start-up change,
 The "DEFAULT_BRIGHTNESS" define in header file. 
 9. Print raw ASCII data without reference to font file.
-10. Example file general contains a set of general function tests: TM1638plus_TEST_model2.ino 
-11. Example file ADC shows some practical data examples : TM1638plus_ADC_TEST_Model2.ino 
-12. Example file for one method of scrolling text: TM1638plus_SCROLL_TEST_Model2.ino  
 
 Model Three
 -----------------------------------------
 
 There are different PCB's  of these modules on market, 
-This library was tested on version 1.3 below. I think this software will work for all of them 
+This library was tested on no 3 below. I think this software will work for all of them 
 and the differences in PCB are related to connectors, layout and component placement. 
-
-1. LKM1638 v1.1
-2. LKM1638 v1.2
-3. TM1638 V1.3 
-
 This module is a variant of Model 1. The differences are the LEDs are bigger and bi-color
 both red and green, The seven segment display is larger and extra connectors are added for Daisy chaining. 
-
 Two 4 digit KYX-5461AS-7.3 (.54 inch, 4 digit ,common cathode,  decimal point, RED)are used in this module
 giving a total of 8 digits. 
 
+1. LKM1638 v1.1
+2. LKM1638 v1.2
+3. TM1638 V1.3 
+
 ![ module ](https://github.com/gavinlyonsrepo/TM1638plus/blob/master/extra/images/tm16384.jpg)
 
-**Model 3 Library Functions and example files**
+**Model 3 Library Functions**
 
-The code is largely the same as model 1 and there is one unique model 3 example file. 
+The code is the same as model 1 and there is one unique model 3 example file. 
 setLED and setLEDs functions behaviour is the only difference in code base between 1 and 3.
-
-SetLED: The difference is when you call the setLED function you pass the following to get LEDs to change colour.
+SetLED: The difference is when you call the setLED function you pass the following to get LEDs to change colour. For more detailed information on functions see commented headers in header file(.h).
 
 | Model | setLED Value | result | 
 |    ----   |    ----   |    ----   |
 |    1 & 3  |    0   |    LED off   |
-|    3   |    1   |    Led green  |
-|    3   |    2   |    LED red   |
+|    3   |    1   |    Led green on  |
+|    3   |    2   |    LED red on  |
 |    1   |    1   |    LED on   |
 
-SetLEDs: When you pass call the setLEDs function you can pass a word pattern where upper byte is turns LEDs green and lower byte turns LEDs red. Model one ignores lower byte always set to 0x00. 
+SetLEDs: When you pass call the setLEDs function you can pass a word pattern where upper byte is turns LEDs green on and lower byte turns LEDs red on . Model one ignores lower byte, Set to 0x00 always. 
 
 1. Model 3 setLEDs(word) = 0xGGRR
 3. Model 1 setLEDs(word) = 0xRR00
 
-For more detailed information on functions see commented headers in header file(.h).
-
-Issues
+Notes
 --------------------------
 
-*Issue A* : Swapped display Issue: Model 2 only
+1. Swapped data on Display issue on some Model 2 modules
+2. Anomaly's  on High frequency micro-controllers.
+3. Driving multiple displays.
+4. Detecting multiple buttons pressed together.
+
+*Note A* : Swapped display Issue: Model 2 only
 
 For Some users using this library the nibbles in information display byte 
 where swapped around. This is because there are different versions of modules on market with different wiring.  See issue #3 on github called Swapped display :: "12345678" becomes "56781234". 
@@ -230,17 +212,14 @@ Object, set the fourth parameter "swap_nibbles" to True, The default is false.
 | QYF-TM1638 | default operation | false | 
 | QYF-TM1638 -Ver 1.0 | Swapped display Fix |  true  | 
 
-
-*ISSUE B* :  High frequency micro-controllers.
+*Note B* :  High frequency micro-controllers.
 
 This library uses a software SPI-like protocol and may not work fully on 
 micro-controllers running at a very high frequency, without some adjustments to timing.
 Its a SPI-like interface with a single bidirectional data wire DIO.
 The TM1638 is basically a slow SPI device (< 500kHz) in DIO mode. The clock uses the equivalent of SPI mode 3 (normally high, clocks data on the rising edge). The problem is that the native Arduino shiftIn()/shiftOut() wire functions are simply too fast for this device (technically the clock signalling for the TM1638 is inverted but as it triggers on a rising edge still it is tolerant of that).
 To make this work with fast devices, the shift clocking is slowed with a small delay (on the order of a microsecond).  As of version 1.6 a new parameter *(_HIGH_FREQ)* has been introduced to constructor it is false by default. Set to true for high frequency MCU ~> 100Mhz.  This will fix the issue of HF MCU not reading buttons correctly(ESP-Xs).  The High_Freq parameter causes a custom shift-in function to be used.
-
-The  Teensy results have been sent to me, I don't have these MCU's them at time of writing.
-also this Teensy data results where pre v1.6 so buttons issue should be fixed. In theory changing the shiftout routine's the same way as shiftin changed in v1.6 should fix any display issues here. 
+The  Teensy results have been sent to me, I don't have these MCU's them at time of writing. 
 
 | IC |  frequency | Status | 
 | ------ | ------ | ------ | 
@@ -251,8 +230,27 @@ also this Teensy data results where pre v1.6 so buttons issue should be fixed. I
 | ESP8266 | 160Mhz | Working |
 | ESP 32  |   240 MHz  | Working, with high_freq set to  true | 
 | Teensy 4.0| 150Mhz | Working model 1,  no Data rest of models |
-| Teensy 4.0| 396Mhz | buttons not working , display issues on model1 ,  no Data rest of models |
+| Teensy 4.0| 396Mhz | Not working on  model1 ,  no Data rest of models |
+
+*Note C* : Driving multiple displays.
+
+It is possible to drive multiple modules. Share the DIO and CLK lines and use a unique
+STB line for each device. see issue number 10 at github for example code.
+
+*Note D* : Detecting multiple buttons pressed together.
+
+Model 1 and Model 3 CAN detect multiple buttons pressed.
+
+Model 3 has two different functions:
+
+1. ReadKey16 returns a byte with decimal value 1-16 this function cannot 
+detect multiple buttons pressed.
 
+2. ReadKey16Two returns a 16 bit integer where each bit corresponds to the 16 switch's.
+However due to the wiring  of the module, see SG-X lines  on schematic,
+Pressing Certain combinations of buttons will cause the  data on Seven Segments to 
+change. So the simultaneous use of multiple key presses and the seven segments display 
+is problematic. See issue 12 on github for more details.
 
 Memory
 -------------------------------
@@ -270,8 +268,9 @@ Sketch uses 1536 bytes (5%) of program storage space.
 Global variables use 23 bytes (1%) of dynamic memory.
 
 
-See Also
+Pic Port
 -------------------
-MicroChip PIC XC8 forks.
 
-I have forked this library to the PIC for the XC8 compiler the forks can be found at [Link](https://github.com/gavinlyonsrepo/pic_16F18446_projects)
+MicroChip PIC XC8 port.
+I have ported this library to the PIC for the XC8 compiler: 
+[ Link ](https://github.com/gavinlyonsrepo/pic_16F18446_projects)

examples/TM1638plus_ADC_TEST_Model2/TM1638plus_ADC_TEST_Model2.ino → examples/TM1638plus_ADC_Model2/TM1638plus_ADC_Model2.ino

@@ -1,6 +1,6 @@
 /*
   Project Name: TM1638
-  File: TM1638plus_ADC_TEST_Model2.ino
+  File: TM1638plus_ADC_Model2.ino
   Description: demo file library for model 2 TM1638 module(16 KEY 16 pushbuttons).
   
   Carries out tests demonstrating arduino library TM1638plus displaying ADC data.

examples/TM1638plus_BASIC_TEST_Model1/TM1638plus_BASIC_TEST_Model1.ino → examples/TM1638plus_HELLOWORLD_Model1/TM1638plus_HELLOWORLD_Model1.ino

@@ -1,23 +1,23 @@
 /*
   Project Name: TM1638
-  File: TM1638plus_BASIC_TEST.ino
-  Description: A demo file library for TM1638 module(LED & KEY).
-  Carries out series most basic test , "hello world"
+  File: TM1638plus_HELLOWORLD_TEST_Model1.ino
+  Description: A demo file library for TM1638 module(LED & KEY). Works on Model 1 and 3
+  Carries out series most basic test , "hello world" helo wrld
   Author: Gavin Lyons.
   Created: feb 2020
   URL: https://github.com/gavinlyonsrepo/TM1638plus
 */
 
-#include <TM1638plus.h>
+#include <TM1638plus.h> //include the library
 
 // GPIO I/O pins on the Arduino connected to strobe, clock, data,
 //pick on any I/O you want.
-#define  STROBE_TM 4
-#define  CLOCK_TM 6
-#define  DIO_TM 7
+#define  STROBE_TM 4 // strobe = GPIO connected to strobe line of module
+#define  CLOCK_TM 6  // clock = GPIO connected to clock line of module
+#define  DIO_TM 7 // data = GPIO connected to data line of module
 bool high_freq = false; //default false, If using a high freq CPU > ~100 MHZ set to true. 
 
-//Constructor object (GPIO STB , GPIO CLOCK , GPIO DIO, use high freq MCU)
+// Constructor object (GPIO STB , GPIO CLOCK , GPIO DIO, use high freq MCU)
 TM1638plus tm(STROBE_TM, CLOCK_TM , DIO_TM, high_freq);
 
 void setup()

examples/TM1638plus_BASIC_TEST_Model2/TM1638plus_BASIC_TEST_Model2.ino → examples/TM1638plus_HELLOWORLD_Model2/TM1638plus_HELLOWORLD_Model2.ino

@@ -1,7 +1,7 @@
 /*
-  Project Name: TM1638plus
-  File: TM1638plus_BASIC_TEST_Model2.ino
-  Description: ABasic test library for model 2, TM1638 module(16 KEY 16 pushbuttons).
+  Project Name: TM1638plus (arduino library)
+  File: TM1638plus_HELLOWORLD_Model2.ino
+  Description: A Basic test file for model 2, TM1638 module(16 KEY 16 pushbuttons).
   Author: Gavin Lyons.
   Created Feb 2020
   URL: https://github.com/gavinlyonsrepo/TM1638plus
@@ -13,8 +13,8 @@
 #define  STROBE_TM 4  // strobe = GPIO connected to strobe line of module
 #define  CLOCK_TM 6  // clock = GPIO connected to clock line of module
 #define  DIO_TM 7 // data = GPIO connected to data line of module
-bool swap_nibbles = false; //Default is false if left out, see note in readme at URL
-bool high_freq = false; //default false,, If using a high freq CPU > ~100 MHZ set to true. 
+bool swap_nibbles = false; //Default is false if left out, see issues section in readme at URL
+bool high_freq = false; //default false, If using a high freq CPU > ~100 MHZ set to true. 
 
 // Constructor object Init the module
 TM1638plus_Model2 tm(STROBE_TM, CLOCK_TM , DIO_TM, swap_nibbles, high_freq);
@@ -25,7 +25,6 @@ void setup() {
 }
 
 void loop() {
-
-	tm.DisplayStr("helowrld", 0);
+	tm.DisplayStr("helowrld", 0);  // Display "helowrld" in seven segments with zero decimal points set.
 	delay(5000);
 }