Merge pull request #48 from Xylopyrographer/version2-development

STAC Version 2

Author: Xylopyrographer

.gitignore

@@ -0,0 +1,7 @@
+*/.DS_Store
+.DS_Store
+Documentation/.DS_Store
+Documentation/manual/.DS_Store
+.DS_Store
+Documentation/manual/.DS_Store
+.DS_Store

Documentation/Creating the build number.md

@@ -0,0 +1,77 @@
+### Creating the STAC Software Build Number
+
+If you're not modifying the STAC software, you can ignore this document.
+
+When in the throws of development and working with multiple ATOM units, sometimes I get lost as to which version of software is actually running on which unit. I could increment the `swVer` variable in the `STAC.ino` file every time I change something there or in any file in the `STACLib` folder but that means remembering to keep some other log file or such. So here's something new I'm trying out to hopefully deconfuse what version of software is actually running on the STAC.
+
+In the `STAC.ino` file there is this line:
+
+```
+String swVer = "2.0 (1a2b3c)";    // version and (build number) of this software. Shows up on the web config page, serial monitor startup data dump & is stored in NVS
+```
+
+The string of six characters between the brackets is the build number. (`1a2b3c` is an example build number.)
+
+It is generated by doing an MD5 hash of all the contents of the `STAC` folder and using the last six characters of that hash for the build number.
+
+The utility that creates the hash is `hashdir`. Found on GitHub at:
+
+`https://github.com/ultimateanu/hashdir`
+    
+and installed using Homebrew by:
+
+`brew install ultimateanu/software/hashdir`
+
+
+To generate the build number, from Terminal run:
+
+`hashdir -a md5 <folder>`
+ 
+Where `<folder>` is the folder that contains only the `STAC.ino` file and the `STACLib` folder.
+
+For example:
+
+`hashdir -a md5 ~/Documents/SmartTallyAtomClient/STAC`
+
+will produce something like:
+
+`9c5d0c5114fab7a3f6b0770bd10bbefe  /STAC`
+
+In this example, `0bbefe` would be the build number for this version of STAC.
+
+**BUT** before you generate the hash, first edit the line:
+
+    `String swVer = "2.0 (1a2b3c)";    // version and (build number) of this software. Shows up on the web config page, serial monitor startup data dump & is stored in NVS`
+
+to remove the old build number so that it looks like this:
+
+    `String swVer = "2.0 ()";    // version and (build number) of this software. Shows up on the web config page, serial monitor startup data dump & is stored in NVS`
+    
+Then save the `STAC.ino` file and any other file that might be open from the `STACLib` foder.
+
+Now create and save the new build number:
+
+1. Generate the hash
+1. Copy the last six characters of the hash from the Terminal window - this is the new build number
+1. Open the `STAC.ino` file
+1. Paste the new build number in between the brackets on the line:
+
+      ```
+      String swVer = "2.0 ()";    // version and (build number) of this software. Shows up on the web config page, serial monitor startup data dump & is stored in NVS
+      ```
+ 
+   so it now looks like:
+ 
+       ```
+       String swVer = "2.0 (0bbefe)";    // version and (build number) of this software. Shows up on the web config page, serial monitor startup data dump & is stored in NVS
+       ```
+     
+5. Save the STAC.ino file
+6. Safe now to upload to the ATOM Matrix
+
+*Why delete the old build number before doing the hash?*
+
+By making note of the existing build number in the `STAC.ino` file, deleting the build number and then generating the hash, a quick check can be made if this version of the `STAC.ino` file and its associated `STACLib` `.h` files are the same as a version running on an ATOM. Delete the existing build number from the `STAC.ino` file, generate the hash, look at and compare the last six digits of the hash to the build number reported by the serial data dump from the STAC. If they match, odds are strong you're good.
+
+**Xylopyrographer**<br>
+  2022-08-05

Documentation/Detailed Change Log.md

@@ -0,0 +1,91 @@
+
+## Detailed Change Log
+
+Intended for developers and others interested in the nitty gritty.
+
+### Version 2.0
+
+* Require arduino-esp32 core 2.0.3 or greater
+    * there are irreconcilable breaking changes in WiFiClient from core 1.0.6
+
+* Replace M5Stack ATOM libraries:
+  * M5Stack are making library changes that are not backward compatible.
+  * use JC_Button library for the display button;
+  * use I2C_MPU6886 library for the IMU;
+  * use FastLED library for the display;
+    * replace "M5.dis.X" functions with bespoke display drawing routines.
+  * directly initialize Serial.
+  
+* Break code into separate `.h` files by function group into a new STACLib folder.
+  * add appropriate `#include` statements to `STAC.ino`.
+
+* Rewrite of the `loop()` tally display code to better facilitate error handling.
+  * error handling should now be done in `loop()`.
+
+* Add user configurable polling interval via the web config page.
+  * add polling interval as an NVS item.
+  * increment the NVS `NOM_PREFS_VERSION`.
+
+* Correct improper use of the `Preferences` library.
+
+* No longer reformats the NVS when doing a factory reset.
+  * clears all `Preferences` name spaces instead.
+
+* Change layout of the startup data dump.
+  * display the arduino-esp32 core version used.
+  * display the ESP-IDF SDK version used. 
+  * show the polling interval.
+  * items above the "`-----`" line are hard coded.
+  * items above the "`=-=-=`" line are web config items.
+  * items below the "`=-=-=`" line are run-time configurable.
+
+* Add macros for setting the tally state on the GROVE connector.
+
+* Set WiFi hostname to the STAC ID.
+
+* Set the normal operating mode default polling interval to 300 ms.
+
+* Set the Peripheral Mode polling interval to 0 ms.
+
+* Remove left over debug code in `parseForm()`.
+
+* Change all `drawGlyph()` `colors[]` parameter data type to `const int`.
+
+* Remove `buttonClicked()` function in favour of native `JC_Button` library calls.
+  * remove all references to `btnWas` & `btnNow`.
+
+* Change `stIP` to use data type `IPAddress` instead of `char[]`.
+
+* Fix the "set" order in `STACWiFi.h` so setting the hostname works with core v2.0.3.
+
+* Fix a coding error in `getCreds()` in `STACWeb.h` that greatly improves error handling.
+
+* Add `fetchInfo()` function to `STACUtil.h`.
+  * interesting for debugging; not used in normal operation.
+
+* With core v2.0.3 & greater, the default WiFi authentication/encryption 
+    mode of the STAC when being provisioned is now WAP2-PSK (AES).
+
+* Rework of the error handling in `loop()`.
+
+* Add "BigOrangeX" display error as notification that there is no STS connection at all (Camera operator mode only).
+  
+* Add filtering for erroneous `stClient` connection cases.
+  * require eight consecutive errors of the same type before the glyph for that error type is displayed.
+  * exception is when there is no connection at all to the STS (aka "BigOrangeX"), for which the error glyph is always displayed immediately.
+  * all error counters are reset after an error glyph is displayed,
+
+* Add setting of STS re-poll interval on errors by error type, independent of the re-poll interval; currently set as:
+  * 1500 ms for "BigOrangeX"
+  * 1000 ms for unknown "BigRedX"
+  * 50 ms for all other errors
+
+* Add `stClient.stop()` if we have an STS connection but the STS response timed out.
+
+* Display the arduino-esp32 core version used on the STAC web config form.
+
+* Display the ESP-IDF SDK version used on the STAC web config form.
+
+* Add STAC software build number.
+    * displayed in brackets after the software number on the Serial data dump and on the STAC web config form.
+    * see `Documentation/Creating the build number.md` for details.

Documentation/Peripheral Mode Application Note.md

@@ -42,7 +42,7 @@ In Peripheral Mode, the STAC continually monitors the state of G26 and G32 on it
 
 Here's the cool part. This allows the opportunity for developers to use a STAC set in Peripheral Mode as a tally indicator driven by an external piece of gear. Simply connect a cable to the GROVE port, apply power and drive pins G26 and G32 as needed.
 
-**Be aware that the ATOM Matrix GPIO pins use 3.3V logic levels and are not 5V tolerant.<br>Driving any GPIO pin beyond 3.3 V will irreparably damage the device.**
+**Be aware that the ATOM Matrix GPIO pins use 3.3V logic levels and are not 5V tolerant.<br>Driving any GPIO pin beyond 3.3V will irreparably damage the device.**
 <br><br>
 
 ### Normal State (Controller) Output Signals
@@ -66,7 +66,7 @@ Starting with software v1.10, a STAC running it its normal operating state (not
 
 This allows the opportunity for developers to use a STAC running in its normal state to provide tally information to another piece of gear.
 
-To do this, connect a cable to the GROVE port, apply power and monitor the state of pins G26 and G32.
+To do this, connect a cable to the GROVE port, power up the STAC and monitor the state of pins G26 and G32.
 
 This could allow the STAC to:
 
@@ -76,7 +76,11 @@ This could allow the STAC to:
 
 The "UNSELECTED" state is useful as it indicates normal operation and communication of the controller STAC with the Roland (or emulated) device being monitored even if that channel is not active in either PGM or PVW.
 
+<<<<<<< HEAD
+With proper cabling, multiple STACs operating in Peripheral Mode could be connected in parallel to a STAC operating in its normal state. No testing has been done to confirm how many STACs could be driven in this manner. Power supply would be an issue to consider as well.
+=======
 With proper cabling, multiple STACS operating in Peripheral Mode could be connected in parallel to a STAC operating in its normal state. No testing has been done to confirm how many STACs could be driven in this manner. Power supply would be an issue to consider as well.
+>>>>>>> main
 
 **Note**: Apply power to the STAC either via its USB port or via a cable connected to its GROVE connector. Do one or the other only, *never* both.
 <br><br>
@@ -105,5 +109,6 @@ To disable Peripheral Mode and return the STAC it to its normal operating state:
 
 ### Document Revision History  
 
+**2022-08-06:** Cleaned up a few more things.<br>
 **2022-06-27:** Cleaned up a few things.<br>
 **2022-01-04:** First release.<br>

Documentation/Release Notes.md

@@ -6,24 +6,31 @@ __New Features__
 * _Configurable Polling Interval_
 
   * The amount of time, in milliseconds, between polls of the Smart Tally Server can now be set when configuring the STAC.
+  * As a result, if an older version of STAC is running, the STAC will need to be reconfigured using a web browser after installing this update. Refer to the *STAC Users Guide*.
 
-__Internal Improvements__
+__Improvements__
 
   * The STAC ID is now used as the WiFi hostname, making each STAC uniquely identifiable in the attached devices table of the WiFi router.
 
   * The WiFi authentication/encryption mode of the STAC when it is being provisioned is now WAP2-PSK (AES).
 
-  *  When operating in busy networks, the "Big Purple X" won't flicker, only activating when there is a number of consecutive communications errors with the Smart Tally Server.
+  *  When operating in busy networks, the "Big Purple X" won't flicker, only activating when there is a number of consecutive communication errors with the Smart Tally Server.
 
-  * Added a "Big Orange X" display error when the STAC cannot connect to the Smart Tally Server. Helps with troubleshooting to distinguish between "Big Purple X" and "Purple Question Mark" type errors.
+  * Added a "Big Orange X" display error when the STAC cannot connect to the Smart Tally Server. Helps with troubleshooting to distinguish between "Big Purple X" and "Purple Question Mark" type errors. More info in the *STAC Users Guide*.
 
   * Revised the format of the information dump sent to the serial port on startup.
 
   * A bunch of house cleaning and other tweaks to speed things up and what not. You know, the usual stuff developers do when realizing they shouldn't have done something a certain way to begin with.
 
   * Now based on arduino-esp32 core v2.0.3 or greater.
+    * To compile the code, arduino-esp32 core v2.0.3 as a minimum is required. Core v1.0.6 is no longer supported.
+
+  * No longer requires modified core or M5Stack libraries.
+    * But does require new libraries as per the `README.md` file.   
 
-  * A new "_Detailed Release Notes_" document intended for developers is in the `STAC/Code` folder.
+  * A new "*Detailed Change Log*" document intended for developers in the `Documentation` folder. It's the TLDR; version of this document.
+   
+  * A new "*Creating the build number*" document intended for developers in the `Documentation` folder.
 
 
 ## v1.10

Documentation/STAC_README.md

@@ -0,0 +1,3 @@
+# To Compile the STAC Sketch...
+
+Make sure the `STACLib` folder is located in the same folder as the `STAC.ino` file.

Documentation/Using screen for STAC Information.md

@@ -23,27 +23,31 @@ In the Terminal window, you should see the STAC startup information.
 Something like:
 
 ```
-=======================================
+=========================================
                  STAC
    A Smart Tally ATOM Matrix Client
             by: Team STAC
-https://github.com/Xylopyrographer/STAC
+ https://github.com/Xylopyrographer/STAC
+
+    Version: 2.0 (53cb81)
+    Core: 2.0.4
+    SDK: v4.4.1-472-gc9140caf8c
+    MAC: 24:A1:60:46:06:3C
 
-     Software Version: 2.0
-   Configuration SSID: STAC-78B5927E
-     Configuration IP: 192.168.6.14
-     -------------------------------
+    Configuration SSID: STAC-3C064660
+    Configuration IP: 192.168.6.14
+    -------------------------------
     WiFi Network SSID: StreamNet
-    Smart Tally IP: 192.168.1.13
+    Smart Tally IP: 192.168.22.31
     Port #: 80
     Max Tally Channel: 8
-    Polling Interval: 300 ms
-     =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-    Auto start: Disabled
+    Polling Interval: 299 ms
+    =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+    Auto start: Enabled
     Operating Mode: Camera Operator
-    Active Tally Channel: 5
+    Active Tally Channel: 2
     Brightness Level: 1
-======================================
+=========================================
 ```
 Items above the "`=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=`" line are set when configuring the STAC via a web browser. Items below that line are set using the STAC display button.
 
@@ -56,16 +60,19 @@ If it is operating in Peripheral Mode, it'll send that info out, something like.
                  STAC
    A Smart Tally ATOM Matrix Client
             by: Team STAC
-https://github.com/Xylopyrographer/STAC
+ https://github.com/Xylopyrographer/STAC
 
-     Software Version: 2.0
-   Configuration SSID: STAC-78B5927E
-     Configuration IP: 192.168.6.14
-     -------------------------------
-     OPERATING IN PERIPHERAL MODE
+    Version: 2.0 (53cb81)
+    Core: 2.0.4
+    SDK: v4.4.1-472-gc9140caf8c
+    MAC: 24:A1:60:46:06:3C
+
+    Configuration SSID: STAC-3C064660
+    Configuration IP: 192.168.6.14
+    --------------------------------
+      OPERATING IN PERIPHERAL MODE
           Brightness Level: 1
 =======================================
-
 ```
 In Peripheral Mode, only the display brightness level can be set, using the display button.
 
@@ -92,4 +99,26 @@ Computers are fussy that way.
 
 The `screen` app is also available on most *nix distributions. The serial communications port descriptor is different, but once you discover that, use it on the command line and things should function as described above.
 
-Windows systems have a number of options for serial communications programs. Consult the documentation for the connection syntax. The STAC only communicates at 115200 baud.
+Windows systems have a number of options for serial communications programs. Consult the documentation for the connection syntax. The STAC only communicates at 115200 baud.
+
+### Geek Info
+
+If you're curious, part of the info dump looks like: 
+
+```
+    Version: 2.0 (53cb81)
+    Core: 2.0.4
+    SDK: v4.4.1-472-gc9140caf8c
+    MAC: 24:A1:60:46:06:3C
+```
+Here:
+
+`Version` is the version number of the STAC software. The characters in brackets are the "build number" of this version.
+
+`Core` is the arduino-esp32 core version used by the STAC software version.
+
+`SDK` is the espressif ESP-IDF software development kit version used by the arduino-esp32 core.
+
+`MAC` is the network interface MAC address.
+
+Useful info if you're interested in tweaking the STAC software. File it in the trivia bucket otherwise.

Documentation/manual/STAC Users Guide.md

@@ -177,7 +177,27 @@ The SSID and Password fields stop accepting input after their limits are reached
 
 Taping the "Reset" button on the browser form will clear all information entered and set the port number, number of channels and the polling interval to their defaults, leaving the form open.
 
-At the bottom of the form, the version number of the STAC software is shown as a bit of trivia.
+At the bottom of the form some info about the STAC is shown as a bit of trivia.
+
+Unit ID is the unique identifier for this STAC. It is SSID of the STAC when being configured and the label you'd see in the WiFi router client table for this STAC when it is operating.
+
+Version is the version number of the STAC software. The characters in brackets are the "build number" of this version.
+
+Core is the arduino-esp32 core version used by the STAC software version.
+
+SDK is the espressif ESP-IDF software development kit version used by the arduino-esp32 core.
+
+MAC is the network interface MAC address. Skip ahead a couple of paragraphs for why you might need that.
+
+Totally geeky stuff but that's where it is if we ask for it if you contact us with a question.
+
+One last point regarding the WiFi network. Configuring the STAC with a static IP address is not supported. Therefore, when the STAC negotiates a connection to the specified network, the network must supply an IP address via DHCP. If a static STAC IP address is desired, the STAC MAC can be used to assign the IP from the router. The MAC address of the STAC can be found:
+
+* via the WiFi router client table after the STAC has an address assigned from the DHCP pool;
+* on the web configuration form;
+* from the STAC startup serial data information dump (refer to the *Using screen for STAC Information* document).
+
+Egads. That was a lot of jargon. Find a friend that knows networks if you need a hand with this.
 
 **Some advice:** If you are configuring multiple STACs in one go, it is quite important to close the Confirmation browser window each time before moving onto the next one. Using a desktop or laptop computer and browser is recommend. Some browsers, notably the mobile variety, get hung up when connecting to the IP address of the STAC (as each one is the same) even though the STAC and its WiFi SSID are unique.
 <br><br>
@@ -766,8 +786,9 @@ No warranties are given. The license may not give you all of the permissions nec
 ### Revision History
 <br>
 
-**2022-07-02**<br>
+**2022-08-09**<br>
 &nbsp;&nbsp;&nbsp;&nbsp;- Revise for STAC software version 2.0.<br>
+&nbsp;&nbsp;&nbsp;&nbsp;- Add note about IP addressing under *First Time Configuration*.<br>
 &nbsp;&nbsp;&nbsp;&nbsp;- Add "Orange X" error description section.<br>
 &nbsp;&nbsp;&nbsp;&nbsp;- Add "Polling Interval" configuration option.<br>
 &nbsp;&nbsp;&nbsp;&nbsp;- Revise configuration screen images.