Home › Embedded / firmware › ESP32 ESP-IDF firmware CLAUDE.md

ESP32 ESP-IDF firmware CLAUDE.md

CLAUDE.md for ESP32 firmware on ESP-IDF 5.x in C: components, FreeRTOS tasks, error handling, and logging.

Claude Code (CLAUDE.md)Embedded / firmware

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# 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`).