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

./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

./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>

Audit & Execution Plan (2026-03-10)

Snapshot

• Priority: P2
• Tech profile: embedded
• Workflows: yes
• Tests: yes
• Debt markers: 0
• Source files: 258

Corrections Prioritaires

• Vérifier target PlatformIO et budget mémoire
• 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