# ESP32_ZACUS

Workspace firmware centré sur une seule cible: Freenove FNK0102H avec `ui_freenove_allinone`.

## Docs canoniques

- `docs/QUICKSTART.md`: bootstrap, build, flash, monitor, smoke.
- `docs/FNK0102H_SOURCE_OF_TRUTH.md`: matrice board/config/pins/support.
- `README_ESP32_ZACUS.md`: notes runtime et signatures série utiles.

## Deux firmwares

- `ui_freenove_allinone/` — firmware **Arduino/PlatformIO** historique (UI/audio/caméra/réseau), chemin release stabilisé.
- `idf_zacus/` — firmware **master ESP-IDF 5.4** (migration en cours, branche `feat/idf-migration`) : voix NPC (esp-sr wakeword + bridge WS), **énigmes locales** P1 son / P3 QR (caméra OV3660 + micro), **écran LVGL** (vue scène, viewfinder, shell Workbench, intro cracktro), et une **surface REST de jeu** (`/game/step`, `/game/puzzle_state`, `/game/file`). Voir `idf_zacus/README.md`.
- `box3_voice/` — firmware annexe **ESP32-S3-BOX-3** : pipeline voix + **générateur de stimulus** (`/stim/qr`, `/stim/melody`) pour exercer les énigmes du master. Voir `box3_voice/README.md`.

## Arborescence utile

- `platformio.ini`: env PlatformIO canonique `freenove_esp32s3_full_with_ui`.
- `ui_freenove_allinone/`: firmware Arduino UI/audio/caméra/réseau.
- `idf_zacus/`: firmware master ESP-IDF (énigmes locales, écran LVGL, REST de jeu).
- `box3_voice/`: firmware BOX-3 (voix + générateur de stimulus QR/mélodie).
- `data/`: contenu LittleFS.
- `lib/`: bibliothèques runtime.
- `scripts/`: bootstrap et scripts repo.
- `tests/`: harness Sprint 1, Sprint 2, Sprint 3, Phase 9.

## Environnements supportés

- `freenove_esp32s3_full_with_ui`: chemin release/stabilisation.
- `freenove_esp32s3`: alias du chemin canonique.
- `freenove_esp32s3_touch`: expérimental, hors release, sans CI.

## Démarrage rapide

```bash
./scripts/bootstrap_platformio.sh
./scripts/doctor_repo.sh
source .venv/bin/activate
python -m platformio run -e freenove_esp32s3_full_with_ui
python -m platformio run -e freenove_esp32s3_full_with_ui -t buildfs
python -m platformio run -e freenove_esp32s3_full_with_ui -t uploadfs --upload-port <PORT>
python -m platformio run -e freenove_esp32s3_full_with_ui -t upload --upload-port <PORT>
python -m platformio device monitor -b 115200 --port <PORT>
```

## Guardrails runtime

- Si la PSRAM est détectée, le firmware démarre normalement puis autorise le réseau après validation UI.
- Si la PSRAM n'est pas détectée, le firmware bascule en `safe diagnostic mode`.
- En mode diagnostic, le firmware garde uniquement la pile série, l'affichage minimal et les boutons physiques.
- En mode diagnostic, caméra, FX, micro, audio, Wi-Fi, ESP-NOW, WebUI et partage de fichiers restent coupés.

## Vérifications minimales

```bash
./scripts/doctor_repo.sh
./scripts/check_memory_budget.sh --env freenove_esp32s3_full_with_ui --max-ram 75 --max-flash 80 --yes
python tests/sprint1_utility_contract.py --mode serial --port <PORT>
python tests/sprint2_capture_contract.py --mode serial --port <PORT>
python tests/sprint3_audio_contract.py --mode serial --port <PORT>
python tests/phase9_ui_validation.py --port <PORT>
```























<!-- CHANTIER:AUDIT START -->
## Audit & Execution Plan (2026-03-10)

### Snapshot
- Priority: `P2`
- Tech profile: `embedded`
- Workflows: `yes`
- Tests: `yes`
- Debt markers: `0`
- Source files: `258`

### Corrections Prioritaires
- [x] Vérifier target PlatformIO et budget mémoire
- [x] Ajouter/fiabiliser les commandes de vérification automatiques.
- [ ] Clore les points bloquants avant optimisation avancée.

### Optimisation
- [ ] Identifier le hotspot principal et mesurer avant/après.
- [ ] Réduire la complexité des modules les plus touchés.

### Mémoire chantier
- Control plane: `/Users/electron/.codex/memories/electron_rare_chantier`
- Repo card: `/Users/electron/.codex/memories/electron_rare_chantier/REPOS/ESP32_ZACUS.md`

<!-- CHANTIER:AUDIT END -->