# CLAUDE.md: ESP-IDF firmware (ESP32)

## Commands
- `idf.py set-target esp32s3` (once) · `idf.py build` · `idf.py -p <PORT> flash monitor` (ask before flashing a device)
- Config: `idf.py menuconfig`; commit defaults in `sdkconfig.defaults`, not the generated `sdkconfig`.
- Host unit tests (where set up): `idf.py --preview set-target linux && idf.py build` or Unity tests in `test/`.

## Structure
- `main/` holds `app_main` wiring only. Features live in `components/<name>/` with `CMakeLists.txt` (`idf_component_register(... REQUIRES ...)`) and a public header in `include/`.
- External libs through the component manager (`idf_component.yml`), pinned versions.

## Code rules
- Every ESP-IDF call returning `esp_err_t` is checked: `ESP_ERROR_CHECK` only during init where a reboot is acceptable; otherwise `ESP_RETURN_ON_ERROR`/`ESP_GOTO_ON_ERROR` and propagate.
- Logging with `ESP_LOGI/W/E(TAG, ...)` and a `static const char *TAG` per file. No `printf` in components.
- FreeRTOS: each task has a sized stack (check with `uxTaskGetStackHighWaterMark`), a priority with a reason, and blocks on queues/event groups/notifications instead of busy-waiting. Use `vTaskDelay(pdMS_TO_TICKS(ms))`.
- ISRs are short, marked `IRAM_ATTR`, use only `FromISR` APIs, and defer work to a task.
- Shared data is protected by a mutex or passed through queues; no unguarded globals across tasks.
- No dynamic allocation in hot loops; check `malloc`/`heap_caps_malloc` results.
- Wi-Fi/credentials come from NVS or provisioning, never hard-coded in source.

## Done
`idf.py build` has no new warnings and binary size is reported (`idf.py size`).