Merge remote-tracking branch 'upstream/main'

Author: CircuitSetup

README.md

@@ -27,9 +27,9 @@ Firmware features include
 - [Wireless communication](#bttf-network-bttfn) with [Time Circuits Display](https://circuitsetup.us/product/complete-time-circuits-display-kit/); used for synchonized time travels, alarm, night mode, fake power and remote control through TCD keypad
 - [Music player](#the-music-player): Play mp3 files located on an SD card [requires TCD connected wirelessly for control]
 - [SD card](#sd-card) support for custom audio files for effects, and music for the Music Player
-- Advanced network-accessible [Config Portal](#the-config-portal) for setup (http://gauges.local, hostname configurable)
+- advanced network-accessible [Config Portal](#the-config-portal) for setup (http://gauges.local, hostname configurable)
 - [Home Assistant](#home-assistant--mqtt) (MQTT 3.1.1) support
-- Built-in installer for default audio files in addition to OTA firmware updates
+- built-in OTA installer for firmware updates and audio files
 
 ## Firmware Installation
 
@@ -69,11 +69,19 @@ The first step is to establish access to the configuration web site ("Config Por
 
 #### Connecting to a WiFi network
 
-As long as the device is unconfigured, it creates a WiFi network of its own named "DG-AP". This is called "Access point mode", or "AP-mode". 
+Your Dash Gauges know two ways of WiFi operation: Either they create their own WiFi network, or they connect to a pre-existing WiFi network.
 
-It is ok to leave the Dash Gauges in this mode, especially if it run stand-alone. In a typical home setup and/or if you also have a [Time Circuits Display](https://circuitsetup.us/product/complete-time-circuits-display-kit/), however, you might want to connect the Dash Gauges to a WiFi network (in case of using it together with a TCD: to the same WiFi network the TCD is connected to). If you have your Dash Gauges, along with a Time Circuits Display, mounted in a car, you might want to connect the Dash Gauges to the TCD's very own WiFi network "TCD-AP"; see [here](#car-setup).
+As long as the device is unconfigured, it creates its own WiFi network named "DG-AP". This mode of operation is called "Access point mode", or "AP-mode". 
 
-In order to connect your Dash Gauges to a WiFi network, click on "Configure WiFi". The bare minimum is to select an SSID (WiFi network name) and a WiFi password.
+It is ok to leave it in AP-mode, predominantly if used stand-alone. (To operate your Dash Gauges in AP-mode, do not configure a WiFi network as described below, or click on "Erase WiFi config" on the Config Portal's main page.)
+
+>For experts: In the following, the term "WiFi network" is used for both "WiFi network" and "ip network" for simplicity reasons. However, for BTTFN/MQTT communication, the devices must (only) be on the same ip network, regardless of how they take part in it: They can be can be connected to different WiFi networks, if those WiFi networks are part of the same ip network, or, in case of the MQTT broker, by wire. If the TCD operates as access point for other props, connecting a prop to the TCD's WiFi network also takes care of suitable ip network configuration through DHCP.
+
+##### ▶ Home setup with a pre-existing local WiFi network
+
+In this case, you can connect your Dash Gauges to your home WiFi network: Click on "Connect to WiFi" and either select a network from the top of the page or enter a WiFi network name (SSID), and enter your WiFi password. After saving the WiFi network settings, the device reboots and tries to connect to your configured WiFi network. If that fails, it will again start in access point mode.
+
+>If you have a [Time Circuits Display](https://tcd.out-a-ti.me) note that in order to have both Dash Gauges and TCD communicate with each other, your Dash Gauges must be connected to the same network your TCD is connected to. In order to use MQTT, your Dash Gauges must be connected to the same network your broker is connected to.
 
 >Note that the device requests an IP address via DHCP, unless you entered valid data in the fields for static IP addresses (IP, gateway, netmask, DNS). If the device is inaccessible as a result of incorrect static IPs, 
 >- power-down the device,
@@ -86,7 +94,11 @@ In order to connect your Dash Gauges to a WiFi network, click on "Configure WiFi
 >
 >This procedure causes static IP data to be deleted; the device will return to DHCP after a reboot.
 
-After saving the WiFi network settings, the device reboots and tries to connect to your configured WiFi network. If that fails, it will again start in access point mode.
+##### ▶ Places without a WiFi network
+
+If no TCD is present, keep your Dash Gauges operating in AP-mode.
+
+If you have a [Time Circuits Display](https://tcd.out-a-ti.me), you can connect your Dash Gauges to the TCD's own WiFi network: Click on "Connect to WiFi" and either select "TCD-AP" from the top of the page or enter "TCD-AP" under *WiFi network name (SSID)*. If you password-proteced your TCD-AP, enter this password below. See [here](#car-setup) for more details.
 
 After completing this step, your Dash Gauges are ready to be configured through the "Config Portal".
 
@@ -259,6 +271,8 @@ The Dash Gauges are way more fun when other props (TCD, FC, SID) are present as
     </tr>
 </table>
 
+[Here](https://github.com/realA10001986/Dash-Gauges/blob/main/CheatSheet.pdf) is a cheat sheet for printing or screen-use. (Note that MacOS' preview application has a bug that scrambles the links in the document. Acrobat Reader does it correctly.)
+
 ## Time travel
 
 To trigger a "time travel" stand-alone, you need to install a "Time Travel" button. Pressing that button briefly will let the Dash Gauges play their time travel sequence. Please see [here](hardware/#connecting-a-time-travel-button) for how to wire that button.
@@ -294,6 +308,18 @@ The firmware supports some additional user-provided sound effects, which it will
 
 Those files are not provided here. You can use any mp3, with a bitrate of 128kpbs or less.
 
+### Installing Custom & Replacement Audio Files
+
+As of version 1.20 of the Dash Gauges firmware, above mentioned audio files (both replacements and custom sounds) can either be copied to the SD card using a computer, or uploaded through the Config Portal.
+
+Uploading through the Config Portal works exactly like [installing the default audio files](#audio-data-installation); on the main menu, click "UPDATE". Afterwards choose the file to upload in the bottom file selector, and click "UPLOAD". The firmware recognizes mp3 files, and stores them on the SD card. (Unlike with the default files, no further "installation" takes place.)
+
+In order to delete a file from the SD card, upload a file whose name is prefixed with "delete-". For example: To delete "key1.mp3" from the SD card, either rename your "key1.mp3" into "delete-key1.mp3", or create a new file named "delete-key1.mp3", and upload this file. The firmware detects the "delete-" part and, instead of storing the uploaded file, it throws it away and deletes "key1.mp3" from the SD card.
+
+For technical reasons, the Dash Gauges must reboot after a file is uploaded in this way.
+
+Please remember that the maximum bitrate for mp3 files is 128kbps. Also note that the uploaded file is stored to the root folder of the SD card, so this way of uploading cannot be used to upload songs for the Music Player. 
+
 ## The Music Player
 
 The firmware contains a simple music player to play mp3 files located on the SD card. This player requires a TCD connected through BTTFN for control.
@@ -406,19 +432,19 @@ If your Dash Gauges, along with a [Time Circuits Display](https://tcd.out-a-ti.m
 #### Dash Gauges
 
 Enter the Config Portal on the Dash Gauges (as described above), click on *Setup* and
-  - enter *192.168.4.1* into the field **_IP address or hostname of TCD_**
+  - enter *192.168.4.1* into the field **_IP address or hostname of TCD_** under BTTFN settings;
   - check the option **_Follow TCD fake power_** if you have a fake power switch for the TCD (like eg a TFC switch)
   - click on *Save*.
 
 After the Dash Gauges have restarted, re-enter the Dash Gauges's Config Portal (while the TCD is powered and in *car mode*) and
-  - click on *Configure WiFi*,
-  - select the TCD's access point name in the list at the top or enter *TCD-AP* into the *SSID* field; if you password-protected your TCD's AP, enter this password in the *password* field. Leave all other fields empty,
+  - click on *Connect to WiFi*,
+  - select the TCD's access point name in the list at the top ("TCD-AP") or enter *TCD-AP* into the *WiFi network name (SSID)* field; if you password-protected your TCD's AP, enter this password in the *password* field. Leave all other fields empty,
   - click on *Save*.
 
-Using this setup enables the Dash Gauges to receive notifications about time travel and alarm wirelessly, and to query the TCD for data. Also, the TCD keypad can be used to remote-control the Dash Gauges.
-
 In order to access the Dash Gauges's Config Portal in your car, connect your hand held or computer to the TCD's WiFi access point ("TCD-AP"), and direct your browser to http://gauges.local ; if that does not work, go to the TCD's keypad menu, press ENTER until "BTTFN CLIENTS" is shown, hold ENTER, and look for the Dash Gauges's IP address there; then direct your browser to that IP by using the URL http://a.b.c.d (a-d being the IP address displayed on the TCD display).
 
+This "car setup" can also be used in a home setup with no local WiFi network present.
+
 ### Door Switches
 
 The Dash Gauges have a connector for two door switches. These switches trigger door open/close sounds.
@@ -437,11 +463,13 @@ In order to reduce the number of write operations and thereby prolong the life o
 
 ### Main page
 
-##### &#9654; Configure WiFi
+##### &#9654; Connect to WiFi
+
+Click this to connect your Dash Gauges to your local WiFi network (which can also be provided by your [Time Circuits Display](https://tcd.out-a-ti.me) operating in AP mode/car mode). All you need to do is either to click on one of the networks listed at the top or to enter a WiFi network name (SSID), and optionally a passwort (WPAx).
 
-Clicking this leads to the WiFi configuration page. On that page, you can connect your Dash Gauges to your WiFi network by selecting/entering the SSID (WiFi network name) as well as a password (WPA2). By default, the Dash Gauges request an IP address via DHCP. However, you can also configure a static IP by entering the IP, netmask, gateway and DNS server. All four fields must be filled for a valid static IP configuration. If you want to stick to DHCP, leave those four fields empty.
+>By default, the Dash Gauges request an IP address via DHCP. However, you can also configure a static IP for the Dash Gauges by entering the IP, netmask, gateway and DNS server. All four fields must be filled for a valid static IP configuration. If you want to stick to DHCP, leave those four fields empty. If you connect your Dash Gauges to your Time Circuits Display acting as access point ("TCD-AP"), leave these all empty.
 
-Note that this page has nothing to do with Access Point mode; it is strictly for connecting your Dash Gauges to an existing WiFi network as a client.
+Note that this page is strictly for connecting your Dash Gauges to an existing WiFi network. If your Dash Gauges are supposed to operate stand-alone, they run in "access point mode" (AP-Mode). Settings for AP mode are on the *Setup* page.
 
 ##### &#9654; Setup
 
@@ -457,9 +485,11 @@ You can also install the Dash Gauges' audio data on this page; download the curr
 
 Note that either a firmware or audio data can be uploaded at once, not both at the same time.
 
+Finally, this page is also for uploading [custom or replacement sound files](#installing-custom--replacement-audio-files) to the SD card. Select an mp3 file in the bottom file selector and click upload. (Requires firmware 1.20 or later.)
+
 ##### &#9654; Erase WiFi Config
 
-Clicking this (and saying "yes" in the confirmation dialog) erases the WiFi configuration (WiFi network and password) and reboots the device; it will restart in "access point" mode. See [here](#short-summary-of-first-steps).
+Clicking this (and saying "yes" in the confirmation dialog) erases the WiFi connection configuration (as set up through the *Connect to WiFi* page) and reboots the device; it will restart in "access point" (AP) mode. See [here](#short-summary-of-first-steps).
 
 ---
 
@@ -544,7 +574,7 @@ If your Dash Gauges are connected wirelessly, this option has no effect.
 
 ##### &#9654; IP address or hostname of TCD
 
-If you want to have your Dash Gauges to communicate with a Time Circuits Display wirelessly ("BTTF-Network"), enter the IP address of the TCD here. If your TCD is running firmware version 2.9.1 or later, you can also enter the TCD's hostname here instead (eg. 'timecircuits').
+If you want to have your Dash Gauges to communicate with a Time Circuits Display wirelessly ("BTTF-Network"), enter the TCD's hostname - usually 'timecircuits' - or IP address here.
 
 If you connect your Dash Gauges to the TCD's access point ("TCD-AP"), the TCD's IP address is 192.168.4.1.
 
@@ -694,10 +724,7 @@ then reload the page in your browser.
 
 
 
-_Text & images: (C) Thomas Winischhofer ("A10001986"). See LICENSE._ Source: https://dg.out-a-ti.me
- 
-
-
-
+_Text & images: (C) Thomas Winischhofer ("A10001986"). See LICENSE._ Source: https://dg.out-a-ti.me  
+_Other props: [Time Circuits Display](https://tcd.out-a-ti.me) ... [Flux Capacitor](https://fc.out-a-ti.me) ... [SID](https://sid.out-a-ti.me) ... [VSR](https://vsr.out-a-ti.me) ... [Remote Control](https://remote.out-a-ti.me) ... [TFC](https://tfc.out-a-ti.me)_
 
 

install/dashgauges-A10001986.ino.nodemcu-32s.bin

@@ -115,6 +115,19 @@
 
 /*  Changelog
  *  
+ *  2025/09/15 (A10001986) [1.20]
+ *    - Refine mp3 upload facility; allow deleting files from SD by prefixing
+ *      filename with "delete-".
+ *    - WiFi manager: Remove lots of <br> tags; makes Safari display the
+ *      pages better.
+ *  2025/09/14 (A10001986)
+ *    - Allow uploading .mp3 files to SD through config portal. Uses the same
+ *      interface as audio container upload. Files are stored in the root
+ *      folder of the SD; hence not suitable for music player.
+ *    - WiFi manager: Remove (ie skip compilation of) unused code
+ *    - WiFi manager: Add callback to Erase WiFi settings, before reboot
+ *    - WiFi manager: Build param page with fixed size string to avoid memory 
+ *      fragmentation; add functions to calculate String size beforehand.
  *  2025/02/13 (A10001986) [1.13.1]
  *    - Delete temp file after audio installation
  *  2025/01/15 (A10001986) [1.13]

src/dashgauges-A10001986.ino

@@ -15,8 +15,8 @@
  ***                          Version Strings                          ***
  *************************************************************************/
 
-#define DG_VERSION       "V1.13.1"
-#define DG_VERSION_EXTRA "FEB132025"
+#define DG_VERSION       "V1.20"
+#define DG_VERSION_EXTRA "SEP152025"
 
 //#define DG_DBG              // debug output on Serial
 

src/dg_global.h

@@ -1489,11 +1489,7 @@ static void execute_remote_command()
 
         switch(command) {
         case 64738:                               // 64738: reboot
-            allOff();
-            mp_stop();
-            stopAudio();
-            flushDelayedSave();
-            unmount_fs();
+            prepareReboot();
             delay(500);
             esp_restart();
             break;
@@ -1878,6 +1874,17 @@ void allOff()
     emptyLED.specialSignal(0);
 }
 
+void prepareReboot()
+{
+    mp_stop();
+    stopAudio();
+    allOff();
+    flushDelayedSave();
+    delay(500);
+    unmount_fs();
+    delay(100);
+}
+
 /*
  * Others
  */

src/dg_main.cpp

@@ -91,6 +91,7 @@ void endWaitSequence();
 void showCopyError();
 
 void allOff();
+void prepareReboot();
 
 void mydelay(unsigned long mydel);
 

src/dg_main.h

@@ -98,6 +98,7 @@ static const char *CONID  = "DGAA";
 static uint32_t   soa = AC_TS;
 static bool       ic = false;
 static uint8_t*   f(uint8_t *d, uint32_t m, int y) { return d; }
+static char       *uploadFileName = NULL;
 
 static const char *cfgName    = "/dgconfig.json";   // Main config (flash)
 static const char *ipCfgName  = "/dgipcfg.json";    // IP config (flash)
@@ -1066,6 +1067,7 @@ void doCopyAudioFiles()
     }
 
     mydelay(500);
+    allOff();
 
     flushDelayedSave();
 
@@ -1354,9 +1356,72 @@ void closeACFile(File& file)
     file.close();
 }
 
-void removeACFile()
+void removeACFile(bool isUPLFile)
 {
     if(haveSD) {
-        SD.remove(CONFN);
+        if(!isUPLFile) {
+            SD.remove(CONFN);
+        } else if(uploadFileName) {
+            SD.remove(uploadFileName);
+        }
+    }
+}
+
+bool openUploadFile(const char *fn, File& file, bool& isDel)
+{
+    if(haveSD) {
+
+        isDel = false;
+
+        if(!strlen(fn))
+            return false;
+      
+        if(!(uploadFileName = (char *)malloc(strlen(fn)+4)))
+            return false;
+
+        uploadFileName[0] = '/';
+        uploadFileName[1] = '-';
+        uploadFileName[2] = 0;
+        strcat(uploadFileName, fn);
+
+        if((strlen(uploadFileName) <= 9) ||
+           (strstr(uploadFileName, "/-delete-") != uploadFileName)) {
+    
+            if((file = SD.open(uploadFileName, FILE_WRITE))) {
+                isDel = false;
+                return true;
+            }
+
+        } else {
+
+            uploadFileName[8] = '/';
+            SD.remove(uploadFileName+8);
+            isDel = true;
+          
+        }
+
+        free(uploadFileName);
+        uploadFileName = NULL;
+    }
+
+    return false;
+}
+
+void renameUploadFile()
+{
+    if(haveSD && uploadFileName) {
+
+        char *t = (char *)malloc(strlen(uploadFileName)+4);
+        t[0] = uploadFileName[0];
+        t[1] = 0;
+        strcat(t, uploadFileName+2);
+        
+        SD.remove(t);
+        SD.rename(uploadFileName, t);
+        
+        free(t);
+
+        free(uploadFileName);
+        uploadFileName = NULL;
     }
 }

src/dg_settings.cpp

@@ -204,9 +204,11 @@ bool check_allow_CPA();
 void delete_ID_file();
 
 #include <FS.h>
-bool openACFile(File& file);
+bool   openACFile(File& file);
 size_t writeACFile(File& file, uint8_t *buf, size_t len);
-void closeACFile(File& file);
-void removeACFile();
+void   closeACFile(File& file);
+void   removeACFile(bool isUPLFile);
+bool   openUploadFile(const char *fn, File& file, bool& isDel);
+void   renameUploadFile();
 
 #endif