Firmware Flashing and Setup

Firmware Flashing and Setup Guide

This guide covers compiling, flashing, and provisioning the DecaTone firmware for ESP32-S3 microcontrollers, configuring custom firmware overrides, and managing Over-The-Air (OTA) updates.

---

1. Prerequisites & Compilation

Hardware Specifications

• Microcontroller: Hosyond ESP32-S3 DevKit-C (N8R8 / N16R8) with native USB-CDC.
• Clock: Xtensa Dual-Core 240MHz (scales automatically between 80MHz idle and 240MHz in-call).
• Partition Table: Dual OTA app partitions (ota_0 and ota_1) with nvs and spiffs.

Using PlatformIO (Recommended)

1. Install Visual Studio Code with the PlatformIO IDE extension (or PlatformIO CLI: pip install platformio).
2. Open the firmware/ directory.
3. Connect your ESP32-S3 board to your computer via USB (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 powers on for the first time:

1. The device launches an open WiFi Access Point named DecaTone-Setup-XXXX (where XXXX represents the last 4 characters of the hardware MAC address).
2. Connect your smartphone or computer to DecaTone-Setup-XXXX.
3. A captive portal page will appear automatically (or navigate 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 switchboard 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, Automatic Electric AE40/50, Kellogg, etc.).
   • Bell Ringing Frequency: 20.0 Hz (default North American resonance).
   • Unique Device ID: Copy this identifier for pairing.
5. Click Save & Connect. The ESP32-S3 stores credentials in non-volatile flash storage (NVS) and connects to your switchboard.

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 Phones to User Accounts

DecaTone supports pairing multiple physical telephones to a single user account (e.g., Living Room, Study, Workshop):

1. Open your DecaTone web dashboard in your browser.
2. Navigate to Phone Settings → Claim / Pair Hardware.
3. Pick up the physical telephone handset and listen for the spoken pairing word (e.g., TONE) and 4-digit code (e.g., 4821), or enter the device ID directly.
4. Click Claim & Pair Hardware.
5. Configure custom labels (Living Room, Workshop) and toggle individual ringer switches (ring_enabled) per device.

---

4. Over-The-Air (OTA) Updates & Custom Firmware Overrides

Automatic Scheduled OTA Updates

Physical phones can update automatically in the background without user intervention:

• In Phone Settings → Firmware & Over-The-Air (OTA) Updates, enable Automatic Firmware Updates.
• Specify your preferred time window (e.g. 03:00 AM).
• Updates only execute when the telephone is on-hook (idle) to prevent disrupting active calls.

Manual OTA Flashing

• When a new firmware release is published on the switchboard, an "Update Available (vX.X.X)" banner appears in the user's hardware settings.
• Users can click "Update Firmware Now (OTA)" to trigger immediate download, flash verification, and automatic reboot.

Custom Firmware Override Binary Format

Administrators can override the official GitHub firmware distribution with custom compiled builds:

1. Compile your binary in PlatformIO (pio run). The output binary is located at .pio/build/esp32-s3-devkitc-1/firmware.bin.
2. Binary Requirements:
   • Must be an uncompressed raw binary (.bin) compiled for ESP32-S3 with ESP-IDF / Arduino core framework.
   • Header magic byte must be 0xE9.
   • Partition scheme must match the dual-OTA partition layout.
3. Open Admin Center → Firmware OTA Manager in the web dashboard.
4. Enter your custom version string (e.g. v1.2.0-custom-dsp) and select firmware.bin.
5. Click Upload Custom Firmware Override.
6. The switchboard activates the custom override and notifies all online telephones.
7. To revert to the official release channel binary, click Revert to Official Release.