Magnus HedemarkandGitHub
36638256a8
* feat: add portable ESP32 development skill Add source-backed workflows, safe templates, native CLI routing, and a read-only preflight for ESP32 hardware and firmware work.\n\nAI assistance: research, drafting, implementation, and review used OpenAI Codex and delegated DeepSeek agents under human direction. * docs: harden ESP32 family and security guidance Add source-backed family traps, brownout, calibration, USB recovery, and security-mode boundaries found during independent review.\n\nAI assistance: independent audits and drafting used delegated DeepSeek agents and OpenAI Codex under human direction.
4.8 KiB
Decisions and preflight
Use this before selecting a framework, opening a serial port, or copying a pin map.
Evidence to collect
| Question | Strong evidence | What it does not prove |
|---|---|---|
| What board is connected? | Silkscreen, product page, schematic, USB VID/PID/product string | A marketing name may cover multiple board revisions. |
| What SoC/module is fitted? | Module shield marking, board BOM/schematic, esptool chip-id after a successful bootloader connection |
A serial device name alone does not identify the SoC. |
| What memory is present? | Module/board specification plus esptool flash-id or framework build metadata |
Configured size is not measured size. |
| Which port is it? | Disconnect/reconnect diff, stable /dev/serial/by-id/, USB location/serial number |
First port in a list is not necessarily the target. |
| What firmware is running? | Boot log, REPL banner, application version endpoint, image metadata | USB manufacturer text can describe the board, not the active firmware. |
| Can it be recovered? | Documented ROM download mode, BOOT/RESET access, known-good image and offsets | OTA availability is not a substitute for serial recovery. |
Run the bundled non-mutating classifier first:
python3 scripts/esp32-preflight.py --json
Then use whichever native enumerator is already installed:
pio device list --json-output
mpremote connect list
On Linux, prefer /dev/serial/by-id/ over an unstable /dev/ttyUSB0 assignment when available. Confirm group/udev permissions before using elevated privileges. On macOS, /dev/cu.* is normally appropriate for outgoing serial sessions. On Windows, use Device Manager or a framework-native device list to map the COM port to its USB descriptor.
Do not open every port
Bluetooth pseudo-ports, debug consoles, unrelated radios, and non-ESP32 microcontrollers may appear beside the target. Probe only a port tied to the expected USB device. Opening a monitor or flasher can toggle DTR/RTS and reset hardware. ESP-IDF Monitor supports:
idf.py monitor --no-reset -p PORT
A failed esptool chip-id means only that the ROM loader handshake did not complete. Common explanations include the wrong port, charge-only cable, permission problem, port already open, target not in download mode, unsupported reset wiring, native-USB mode, weak power, or a non-Espressif device. Do not respond by erasing flash.
Framework decision
Choose the smallest supported control plane that meets the product need:
| Constraint | Default | Why |
|---|---|---|
| Full Espressif feature access, production controls, C/C++ | ESP-IDF | Canonical SDK and source of partition, OTA, security, and low-level driver behavior. |
| Arduino libraries or beginner C++ workflow | Arduino core | Familiar API and large library ecosystem; still validate ESP32-specific pin and peripheral behavior. |
| Arduino/ESP-IDF with reproducible CLI environments and tests | PlatformIO | Project-level platform/framework/board declaration and native build/upload/monitor/test commands. |
| Fast interactive Python iteration on constrained hardware | MicroPython | REPL plus mpremote; API and board support differ from CPython. |
| Board-first Python library ecosystem and supported CircuitPython board | CircuitPython | board aliases and Adafruit library workflow; verify whether the exact ESP32 board/SoC is supported. |
| Declarative Home Assistant device | ESPHome | Generated firmware, native API/OTA, extensive component catalog, and config validation. |
| RTOS portability, devicetree, Kconfig, upstream drivers | Zephyr | Appropriate when the application needs Zephyr's architecture and the board/peripherals are supported. |
| Rust safety and ecosystem are explicit requirements | Rust on ESP | Use official Espressif Rust guidance; choose no_std esp-hal or ESP-IDF-based std deliberately. |
| POSIX-like RTOS/NuttShell or existing NuttX product | NuttX | Mature RTOS option, but not a default for a new general-purpose ESP32 prototype. |
Do not migrate a working project merely because another framework is listed. Cross-framework rewrites change drivers, timing, partitions, networking, and recovery behavior.
Board and feature questions
Before committing to a family, verify the exact SoC documentation for:
- CPU architecture and core count;
- Wi-Fi generation and whether Bluetooth, BLE, Zigbee/Thread, Ethernet MAC, or no radio is present;
- native USB, USB Serial/JTAG, external bridge, or UART-only download path;
- flash and PSRAM interfaces and module-installed memory;
- GPIO count and restrictions;
- ADC/DAC/touch capabilities;
- low-power modes and wake sources;
- JTAG exposure and production security interactions.
The ESP32 name is a family label. A feature present on classic ESP32 may be absent or materially different on C-, S-, H-, or P-series parts.