# Pioneer firmware: compile once, then name + flash from the browser

The browser flasher at `/pioneer/flasher.html` loads three compiled binaries from
the top-level `/firmware/pioneer/` folder. You build them **once**; after that every
Pioneer is named and flashed from the browser with no rebuild. Firmware source:
`pioneer_v1_4_1.ino` (repo root). Partition map: `partitions.csv` (in this folder).

## 1. Compile (one time)

1. Open `pioneer_v1_4_1.ino` in the Arduino IDE. Put `partitions.csv` in the
   **same sketch folder** (arduino-esp32 core 3.x picks up a sketch-folder
   `partitions.csv` automatically; if your board menu has Partition Scheme,
   choose **Custom**).
2. Install the **NimBLE-Arduino** library.
3. Tools: your **ESP32-S3** board, **USB CDC On Boot = Enabled**, **Flash Size = 4MB**.
4. **Sketch -> Export Compiled Binary.** The IDE writes the `.bin` files into a
   `build/` folder in the sketch directory.

## 2. Drop the binaries into `/firmware/pioneer/`

Copy these out of `build/` into the top-level `firmware/pioneer/` folder, keeping
their export names:

```
firmware/pioneer/pioneer_v1_4_1.ino.bootloader.bin
firmware/pioneer/pioneer_v1_4_1.ino.partitions.bin
firmware/pioneer/pioneer_v1_4_1.ino.bin          (the app)
firmware/pioneer/pioneer_v1_4_1.ino.merged.bin   (optional, single-file flash)
```

The flasher fetches them from `/firmware/pioneer/`, writes the three parts plus the
chosen name blob, and resets. Until they are present, the flasher shows each one as
"pick it" and stays disabled, or you can choose them by hand. When you bump the
version, update the filenames in `pioneer.binaries` in `shared/firmware/registry.js`
and the fetch list in `pioneer/flasher.html`.

## Flash layout (must stay in sync)

| Part            | Address    |
| --------------- | ---------- |
| bootloader.bin  | 0x0        |
| partitions.bin  | 0x8000     |
| pioneer.bin     | 0x10000    |
| name blob (4 KB)| 0x310000   |

The chosen name is written as a 4 KB blob into the `pioneer` data partition at
**0x310000**, which is set in both `partitions.csv` and the flasher's
`ADDR_NAME`. Change one, change both. Flash settings: `dio / 80m / 4MB`.

Web Serial needs **https or localhost** and desktop Chrome, Edge, or Opera.