From b84a633016efe22c520aed59a96fee40411d810d Mon Sep 17 00:00:00 2001
From: Fabrice Bellamy <12b@distrilab.fr>
Date: Sat, 31 Jan 2026 13:10:00 +0100
Subject: [PATCH] add some instruction about building/debugging from the
 command line

---
 README.md          | 43 ++++++++++++++++++++++++++++++++-----------
 bibotron.ino       |  2 +-
 esp32s3-remote.cfg |  5 +++++
 3 files changed, 38 insertions(+), 12 deletions(-)
 create mode 100644 esp32s3-remote.cfg

diff --git a/README.md b/README.md
index 1545b6b..af00f30 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,13 @@ Then in the `Tools` menu, select :
 - `Programmer` > `esptools`
 - `Port` > the tty port of the board (if programming through USB)
 
+Before building the project, you need to add in your working copy the secret.h file that contains the sensitive information that we not want to publish in the this git repository
+**ToDo :** The secret.h needs to be stored in the password manager used by Le Bib
+If your are building the source code for a different site than Le Bib, you can create your own secret.h based on secret.h.example
+
+To update the firmware through Web OTA, first create the binary using the menu `Sketch` > `Export compiled Binary`.  
+
+
 ### Alternative: Compilation via Arduino CLI (Linux/Mac)
 
 If you prefer the command line, you can use `arduino-cli`.
@@ -123,26 +130,40 @@ If you prefer the command line, you can use `arduino-cli`.
     arduino-cli lib install "FastLED" "EthernetESP32" "ESPping" "ElegantOTA" "ArduinoJson"
     ```
 
-4.  **Compile the project**:
+4.  **Compile the project for uploading through Web OTA**:
     ```bash
     arduino-cli compile --fqbn esp32:esp32:esp32s3box:USBMode=hwcdc --build-property "build.partitions=default_16MB" --output-dir ./build  .
     ```
 
-5.  **Compile the project and upload to the board though USB serial **:
+5.  **Compile the project and upload to the board through USB serial **: 
+    To compile and upload a normal build :  
     ```bash
-    arduino-cli compile --fqbn esp32:esp32:esp32s3box:USBMode=hwcdc,DebugLevel=debug --build-property "build.partitions=default_16MB" && \
-    arduino-cli upload -p /dev/ttyACM0 --fqbn esp32:esp32:esp32s3box:USBMode=hwcdc,DebugLevel=debug
+    arduino-cli compile --fqbn esp32:esp32:esp32s3box:USBMode=hwcdc --build-property "build.partitions=default_16MB" && \
+    arduino-cli upload -p /dev/ttyACM0 --fqbn esp32:esp32:esp32s3box:USBMode=hwcdc
     ```
-   Note : the `DebugLevel=debug` option can be omitted
 
-Before building the souce code, you need to add in your working copy the secret.h file that contains the sensitive information that we not want to publish in the this git repository
-**ToDo :** The secret.h needs to be stored in the password manager used by Le Bib
-If your are building the source code for a different site than Le Bib, you can create your own secret.h based on secret.h.example
+    To upload a debug build and debug locally from the command line with GDB :  
+    ```bash
+    arduino-cli compile --fqbn esp32:esp32:esp32s3box:USBMode=hwcdc,DebugLevel=verbose --build-property "build.partitions=default_16MB" --build-property "build.code_debug=5" --optimize-for-debug  && \
+    arduino-cli debug -p /dev/ttyACM0 --fqbn esp32:esp32:esp32s3box:USBMode=hwcdc,DebugLevel=verbose
+    ```
 
-To update the firmware through Web OTA, first create the binary using the menu `Sketch` > `Export compiled Binary`.  
-Then :
+    To compile adebug build, upload it and debug remotely or from an IDE:  
+    ```bash
+    arduino-cli compile --fqbn esp32:esp32:esp32s3box:USBMode=hwcdc,DebugLevel=verbose --build-property "build.partitions=default_16MB" --build-property "build.code_debug=5" --optimize-for-debug && \
+    arduino-cli upload -p /dev/ttyACM0 --fqbn esp32:esp32:esp32s3box:USBMode=hwcdc,DebugLevel=verbose && \
+    openocd -f ~/esp32s3-remote.cfg
+    ```
 
-- In your web browser, go to http://bibotron.local/update (or use the local IP address if the MDNS resolution of bibotron.local is not working : 10.13.12.40)
+ToDo : Need more detailed documentation for debugging
+- how to install esptool
+- how to install/configure openocd
+- how to attach gdb to remote openocd
+- how to attach to openocd from vs-code/vs-codium
+
+### Update the firmware through Web OTA
+
+- In your web browser, go to http://bibotron.local/update (or use the local IP address if the MDNS resolution of bibotron.local is not working, example :http://10.13.12.40/update )
 - **ToDo :** The user and password to use need to be stored in the password manager used by Le Bib
 - In `OTA Mode` select firmware
 - Click on `Select file` and select the file `bibotron.ino.bin` that should have been generated somewhere under the project build folder (do not used any of the other .bin files that have been generated).
diff --git a/bibotron.ino b/bibotron.ino
index dfd4ce7..93d223e 100644
--- a/bibotron.ino
+++ b/bibotron.ino
@@ -60,7 +60,7 @@
 #define LEDS_BRIGHTNESS 50   // Min 0, Max 255
 #define HEARTBEAT_PERIOD 20  // Cycle time for aniating the heartbeat LED (in ms)
 // #define PING_PERIOD 60000    // Cycle time for checking network connectivity by ping of our reverse proxy
-#define PING_PERIOD 1000    // Cycle time for checking network connectivity by ping of our reverse proxy
+#define PING_PERIOD 10000    // Cycle time for checking network connectivity by ping of our reverse proxy
 
 // SPI ethernet chip driver
 W5500Driver driver(W5500_CS);
diff --git a/esp32s3-remote.cfg b/esp32s3-remote.cfg
new file mode 100644
index 0000000..f991032
--- /dev/null
+++ b/esp32s3-remote.cfg
@@ -0,0 +1,5 @@
+# Bind to all interfaces (not just localhost)
+bindto 0.0.0.0
+
+# Include the standard ESP32-S3 config
+source [find board/esp32s3-builtin.cfg]