micheleandCursor
8439ec4055
Update READMEs, manual chapters, agent guides, CONTRIBUTING, and TODO to reflect T1–T8 done, encrypted NVS, CI gates, and pending HIL checklist. Co-authored-by: Cursor <cursoragent@cursor.com>
104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
# instructions.md — DigiRadio firmware, agent kickoff
|
||
|
||
Read this together with `AGENTS.md` and everything under
|
||
`.cursor/rules/`. Those define *how* to write code; this file defines
|
||
*what we are building* and the current state on `main`.
|
||
|
||
**Firmware on `main`:** **0.8.3** — all agent tasks T1–T8 complete; device
|
||
HIL pending PCB arrival.
|
||
|
||
## What DigiRadio is
|
||
|
||
An open-source Hi-Fi DAB+/FM digital radio board. Firmware runs on an
|
||
ESP32-S3 and coordinates three companion chips:
|
||
- **Si4684** — DAB+/FM tuner (delivers the audio stream).
|
||
- **ADAU1701** — SigmaDSP: equaliser + input mixer between the Si4684
|
||
and the ESP32 audio path. Program is written to DSP RAM at every boot
|
||
(no self-boot EEPROM).
|
||
- **FSC-BT1035 (QCC3056)** — Bluetooth 5.2 out with aptX Adaptive,
|
||
controlled by AT commands over UART.
|
||
|
||
Plus: tabbed web UI for provisioning and control; **encrypted NVS** for
|
||
Wi-Fi credentials, presets, audio profiles, and last-preset index.
|
||
|
||
Repository: https://github.com/manvalan/DigiRadio
|
||
|
||
## Confirmed technical decisions (do not re-litigate)
|
||
|
||
| Area | Decision |
|
||
|-------------|-------------------------------------------------------|
|
||
| Framework | ESP-IDF v5.5.x (native, not Arduino) |
|
||
| Language | C++23, pinned `-std=gnu++23` |
|
||
| Errors | `std::expected<T, Error>` (native); exceptions OFF |
|
||
| DSP boot | ESP32 writes ADAU1701 RAM at every boot (no EEPROM) |
|
||
| Architecture| Functional core (pure, host-tested) + imperative shell|
|
||
| Security | NVS + flash encryption (dev mode); see `docs/security-flash-nvs.md` |
|
||
| Docs | Doxygen + LaTeX manual sync (CI enforced) |
|
||
| HW licence | CERN-OHL-S v2 · FW licence: Apache-2.0 |
|
||
|
||
## Roadmap status
|
||
|
||
| Slice / task | Status | Notes |
|
||
|--------------|--------|-------|
|
||
| 1 Walking skeleton | Done | SoftAP, gzipped UI, `/api/health` |
|
||
| 2 Secure store + Wi-Fi | Done | `ISecureStore`, STA provisioning |
|
||
| 3 Companion-chip boot | Done | Si4684 + ADAU1701 from `Firmware/` |
|
||
| 4 Station presets | Done (0.7.0) | NVS `station_list`, full `/api/stations/*` |
|
||
| 5 ADAU1701 runtime | Done | EQ, mixer, enhancements, audio API |
|
||
| 6 Si4684 tuning | Done | FM/DAB tune, seek, RSQ, RDS, DAB services/DLS |
|
||
| 7 BT1035 | Mostly done | Pairing, A2DP stat/disconnect; name/plist AT open |
|
||
| 8 Integration | Done (0.8.1) | `IntegrationService`, last-preset NVS |
|
||
| T6 Web UI | Done (0.8.2) | Tabbed SPA, all REST endpoints |
|
||
| T7 Si4684 blobs | Done (0.8.2) | Local-only `.bin`, CI policy check |
|
||
| T8 NVS encryption | Done (0.8.3) | `initEncryptedStorage`; HIL when PCB ready |
|
||
|
||
Next work: **hardware-in-the-loop** (`docs/TODO.md` § P4), not new features
|
||
unless the user requests them.
|
||
|
||
## Working agreement
|
||
|
||
- **Blockers first** — state risks before solutions.
|
||
- **One vertical slice at a time** — `main` always builds; host tests green.
|
||
- Apache header + Doxygen doc blocks on every file/class/method.
|
||
- Never invent register/opcode/boot steps — cite the datasheet or stop.
|
||
- After changes: `ctest`, `doxygen`, `check-manual-sync.py`, `check_si4684_blobs.py`.
|
||
|
||
## Slice 1 — Walking skeleton (complete)
|
||
|
||
- ESP-IDF `esp32s3`, C++23, `components/core` host-testable.
|
||
- SoftAP `DigiRadio-setup`, gzipped page, `GET /api/health`.
|
||
- Current health JSON includes `fw` (today **0.8.3**) and companion-chip flags.
|
||
|
||
## Slice 2 — Secure store + Wi-Fi STA (complete)
|
||
|
||
- `ISecureStore`, `NvsSecureStore`, `StaClient`, `NetBootstrap`.
|
||
- `POST /api/wifi` + Wi-Fi tab in web UI.
|
||
- NVS encryption enabled in fw 0.8.3 via `initEncryptedStorage()`.
|
||
|
||
## Slice 3 — Companion-chip boot (complete)
|
||
|
||
- Si4684 blobs local-only (`tools/fetch_si4684_firmware.py`).
|
||
- `Si4684Driver`, `Adau1701Driver`, `HardwareBootstrap` before network.
|
||
- Device flash: pending HIL on first PCB.
|
||
|
||
## Slices 4–8 — Presets, audio, tuner, BT, integration (complete)
|
||
|
||
- Presets: `StationService`, reorder, integration recall with audio profile.
|
||
- Audio: six-band EQ, enhancements, `NvsAudioProfileStore`.
|
||
- Tuner: RDS/DLS metadata in status JSON and Now Playing UI.
|
||
- Bluetooth: `BluetoothService`, pairing REST + UI.
|
||
- Integration: boot loads last preset; `POST /api/stations/tune` orchestrates tune + audio + NVS.
|
||
|
||
## Quality gates (from `Software/`)
|
||
|
||
```bash
|
||
cmake -S components/core/test -B build-host && cmake --build build-host
|
||
ctest --test-dir build-host --output-on-failure
|
||
doxygen Doxyfile
|
||
python3 tools/check-manual-sync.py
|
||
python3 tools/check_si4684_blobs.py
|
||
```
|
||
|
||
First device flash with encryption: `idf.py erase-flash flash` — see
|
||
`docs/security-flash-nvs.md`.
|