Expand all README files for firmware 0.8.3.

Align root, Software, and Firmware READMEs with security, CI, web UI, blob policy, and six-band EQ details. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-07 07:50:00 +02:00
parent 8439ec4055
commit 2f9f3ef9b3
5 changed files with 133 additions and 63 deletions
@@ -1,6 +1,7 @@
 # ADAU1701 SigmaStudio export

-SigmaStudio project **DigiRadio**, IC1 = ADAU1701.
+SigmaStudio project **DigiRadio**, IC1 = ADAU1701. Shipped with DigiRadio firmware
+**0.8.3**.

 ## Key files

@@ -12,29 +13,32 @@ SigmaStudio project **DigiRadio**, IC1 = ADAU1701.
 | `DigiRadio_NetList.xml` | Schematic netlist (reference) |
 | `SigmaStudioFW.h` | Safeload / I2C glue API |

-The ESP32 replays `default_download_IC_1()` over I2C on every boot via
-`adau1701::Adau1701Driver`. Runtime mixer/EQ/master changes use the
-ADAU1701 safeload mechanism (`sigma_safeload_param` /
-`sigma_safeload_block` in `components/drivers/adau1701/src/SigmaStudioFW.c`).
+## Runtime (fw 0.8.3)

-I2C address: 7-bit `0x34` (ADDR0=ADDR1=GND), matching `board_pins.hpp`.
+- **Boot:** ESP32 replays `default_download_IC_1()` over I2C via
+  `adau1701::Adau1701Driver` on every power-up.
+- **Live control:** six-band PEQ, input mixer, master volume, stereo/bass
+  enhancement overlays — safeload via `audio::AudioService` and REST
+  `/api/audio/*`; profile persisted in encrypted NVS.
+- **Web UI:** **Audio** tab — 6 EQ sliders + mixer/enhance controls.

-Sample rate: **48 kHz** (see `DigiRadio_NetList.xml`).
+I2C address: 7-bit `0x34` (ADDR0=ADDR1=GND). Sample rate: **48 kHz**.
+
+Safeload implementation: `components/drivers/adau1701/src/SigmaStudioFW.c`.
+Parameter map: `components/drivers/adau1701/include/adau1701/Adau1701ParamMap.hpp`.

 ## After re-exporting from SigmaStudio

 1. **Action → Export System Files** into this folder (overwrite headers).
-2. Reconcile new `ADDR_*` symbols in `components/drivers/adau1701/include/adau1701/Adau1701ParamMap.hpp` if block names moved.
-3. Rebuild and flash firmware.
-4. Update the manual: `docs/manual/ch-sigmastudio.tex` (design) and
-   `docs/manual/ch-adau1701.tex` (driver/API) if the signal chain changed.
+2. Reconcile new `ADDR_*` symbols in `Adau1701ParamMap.hpp` if block names moved.
+3. Rebuild and flash firmware (`idf.py build`).
+4. Update manual: `docs/manual/ch-sigmastudio.tex`, `docs/manual/ch-adau1701.tex`.
+
+Do **not** use SigmaStudio *Link Compile Download* on DigiRadio — export only;
+the ESP32 programs the DSP at every power-up.

 ## Documentation

- **Manual — SigmaStudio design:** `docs/manual/ch-sigmastudio.tex`
- **Manual — driver & usage:** `docs/manual/ch-adau1701.tex` (boot, safeload,
-  `Adau1701Driver`, `AudioService`, HTTP `/api/audio/*`)
- **HTTP schemas:** `docs/manual/ch-api.tex`
-
-Do **not** use SigmaStudio *Link Compile Download* on DigiRadio — export
-only; the ESP32 programs the DSP at every power-up.
+- Design: `docs/manual/ch-sigmastudio.tex`
+- Driver & API: `docs/manual/ch-adau1701.tex`
+- HTTP: `docs/manual/ch-api.tex` (`/api/audio/*`)
@@ -1,26 +1,49 @@
 # DigiRadio — companion-chip firmware assets

-Binary and SigmaStudio exports loaded by the ESP32 at every boot.
+Binary and SigmaStudio exports loaded by the ESP32 at every boot (fw **0.8.3**).

-| Directory | Chip | Contents |
-|-----------|------|----------|
-| `ADAU1701-Firmware/` | ADAU1701 SigmaDSP | SigmaStudio export (`DigiRadio_IC_1.h`, …) — RAM program |
-| `Si4684-Firmware/` | Si4684 DAB+/FM tuner | ROM patch + DAB + FM application images (`.bin`) |
+| Directory | Chip | In git? | Loaded by |
+|-----------|------|---------|-----------|
+| `ADAU1701-Firmware/` | ADAU1701 SigmaDSP | Yes (headers) | `Adau1701Driver` — RAM program every boot |
+| `Si4684-Firmware/` | Si4684 DAB+/FM | README only | `Si4684Driver` — HOST_LOAD embedded blobs |

-## Si4684 blobs
+## Before first device build

-Proprietary Skyworks images — **local only**, gitignored (`*.bin`). See
-[`Si4684-Firmware/README.md`](Si4684-Firmware/README.md) for procurement and
-legal notes. Populate with:
+Si4684 application images are **proprietary** and **gitignored**. Populate locally:

 ```bash
 cd Software
 python3 tools/fetch_si4684_firmware.py --dab-only
 python3 tools/fetch_si4684_firmware.py --si46xx-dir /path/to/si46xx_firmware
 python3 tools/check_si4684_blobs.py
+ls Firmware/Si4684-Firmware/*.bin   # expect 3 files
 ```

+Without blobs, `idf.py build` fails at embed/link time.
+
+Full procurement and legal notes: [`Si4684-Firmware/README.md`](Si4684-Firmware/README.md).
+
+## Si4684 blobs
+
+| File | Role |
+|------|------|
+| `rom_patch_016.bin` | ROM patch (HOST_LOAD before main image) |
+| `dab_firmware.bin` | DAB+ application (PE5PVB / Skyworks) |
+| `fm_firmware.bin` | FM application (Skyworks eval or community source) |
+
+Boot sequence: AN649 — POWER_UP → LOAD_INIT → HOST_LOAD(patch) → LOAD_INIT →
+HOST_LOAD(image) → BOOT.
+
 ## ADAU1701 export

-Generated by Analog Devices SigmaStudio for the DigiRadio DSP schematic.
-Loaded on every boot (no self-boot EEPROM on this board).
+SigmaStudio project **DigiRadio** — exported headers replayed over I2C on every
+boot (no self-boot EEPROM). Runtime EQ/mixer/enhancements via safeload and the
+Web UI **Audio** tab (`/api/audio/*`).
+
+Details: [`ADAU1701-Firmware/README.md`](ADAU1701-Firmware/README.md) · manual:
+`docs/manual/ch-adau1701.tex`, `docs/manual/ch-sigmastudio.tex`.
+
+## Security note
+
+User settings (Wi-Fi, presets, audio profiles) live in **encrypted NVS**, not in
+this folder. See `docs/security-flash-nvs.md`.
@@ -1,8 +1,8 @@
 # Si4684 firmware images (local only — not in git)

-Skyworks Si4684 application firmware is **proprietary**. This directory holds
-the three binary blobs your build embeds via `HOST_LOAD`; they must **never**
-be committed to the public repository.
+Skyworks Si4684 application firmware is **proprietary**. DigiRadio fw **0.8.3**
+embeds these blobs via ESP-IDF `EMBED_FILES`; they must **never** be committed.
+CI runs `tools/check_si4684_blobs.py` on every push to `main`.

 | File | Size (typ.) | Role |
 |------|-------------|------|