# 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](https://code.visualstudio.com/) 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:
   ```bash
   cd firmware
   pio run --target upload
   ```
5. Monitor serial output at 115,200 baud:
   ```bash
   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**.