Firmware Flashing and Setup

Firmware Flashing and Setup Guide

This guide covers compiling and flashing the DecaTone firmware onto your ESP32-S3 board, initial provisioning via the built-in Captive Portal, and remote Over-The-Air (OTA) updates.

---

1. Prerequisites & Compilation

Using PlatformIO (Recommended)

1. Install Visual Studio Code with the PlatformIO IDE extension (or install PlatformIO Core via CLI: pip install platformio).
2. Open the firmware/ directory in VS Code / PlatformIO.
3. Connect your ESP32-S3 board to your computer via USB (ensure you connect to the Native USB / CDC port).
4. Run the upload command:

   cd firmware
   pio run --target upload

5. Monitor serial output at 115,200 baud:

   pio device monitor -b 115200

---

2. Captive Portal WiFi Provisioning

When an unconfigured ESP32-S3 boots up for the first time:

1. The device automatically launches an open WiFi Access Point named DecaTone-Setup-XXXX (where XXXX are the last four characters of the MAC address).
2. Connect your smartphone or laptop to DecaTone-Setup-XXXX.
3. A captive portal popup will appear automatically. (If it doesn't, navigate your browser to http://192.168.4.1).
4. Configuration Fields:
   • WiFi SSID: Select your 2.4GHz home WiFi network.
   • WiFi Password: Enter your WiFi network password.
   • DecaTone Server Base URL: Enter your self-hosted server address (e.g. https://phone.example.com or http://192.168.1.100:4000).
   • Hardware Profile: Select your telephone model (e.g. Western Electric 500, AE40, etc.).
   • Bell Ringing Frequency: 20.0 Hz (default).
   • Unique Device ID: Copy this identifier for pairing in your web portal.
5. Click Save & Connect. The ESP32-S3 will save your credentials to non-volatile flash storage (NVS) and reboot into station mode.

Tip

To re-enter setup mode at any time, hold down the BOOT button (GPIO 0) for 5 seconds upon powering on the device.

---

3. Pairing Your Phone to Your User Account

1. Open your DecaTone web dashboard in your browser.
2. Navigate to Phone Settings → Device Pairing.
3. Enter the 4-letter Pairing Word or 4-digit Numeric Code generated by your switchboard, or enter your device's Unique Device ID.
4. Click Claim & Pair Hardware. Your phone is now linked to your extension!

---

4. Over-The-Air (OTA) Updates

Administrators can broadcast new firmware updates to all deployed phones without unplugging any hardware:

1. Compile a new firmware binary in PlatformIO (pio run). The output binary is located at .pio/build/esp32-s3-devkitc-1/firmware.bin.
2. Go to Admin Center → Firmware OTA Manager in the DecaTone web interface.
3. Upload firmware.bin and specify the version tag (e.g. v1.1.0).
4. Click Broadcast OTA Update. The switchboard will notify all connected phones, which will safely download the binary, verify the cryptographic checksum, write to the secondary flash partition, and reboot automatically.