theheavenlyd3mon ESP32 Development
Treat the board, attached circuit, firmware, and host toolchain as one system. An ESP32 task is complete only when the intended behavior is observed at the hardware boundary, not when compilation or flashing alone succeeds.
Operating contract
- Identify the exact board, SoC family, module, flash/PSRAM size, USB transport, power source, and board revision. Do not transfer a pin map between ESP32, S2, S3, C2, C3, C5, C6, H2, or P4 variants.
- Read the board schematic or pinout, the matching SoC/module datasheet, and every attached component datasheet before choosing pins or voltage levels.
- Start with read-only host and USB discovery. Opening a serial monitor may toggle DTR/RTS and reset the target; use a no-reset option when the running state matters.
- Choose one framework based on the product constraint. Reuse its project generator, examples, drivers, build system, flasher, monitor, and debugger before writing wrappers.
- Bring up one layer at a time: power and boot, serial log, one GPIO, one bus, bus scan or loopback, device identity register, raw readings, calibration, then application behavior.
- Before the first flash or hardware mutation, confirm the target port, chip family, image/partition layout, rollback or reflashing path, and electrical safety. Never guess a flash offset.
- Preserve calibration controls for real sensors, clocks, ADCs, PWM devices, and actuators. Physical variation is expected.
Pre-response evidence gate
Complete this gate before drafting a non-trivial plan or recommendation:
- Build a claim ledger for every material positive claim, negative claim, command, and numeric design choice. A URL in
source-index.mdis navigation, not evidence; retrieve the exact chip/current-version page or mark the claimUNKNOWN. - Command help proves syntax only. Record required target state plus reset, DTR/RTS, download-mode, RAM-stub, port, and mutation effects from current documentation. If operational preconditions are unverified, do not present the command as executable.
- Missing hardware artifacts stay missing. Do not replace them with archetypes, examples, or words such as
usually,typical, orsome modules; state what the observed label does not establish. - Do not invent thresholds, margins, intervals, durations, point counts, percentages, or model forms. Derive them from an authoritative source or a measurement criterion; otherwise leave them
UNKNOWN. - Audit the final response against the ledger. Remove or downgrade every material claim that lacks its required evidence.
First read-only discovery
python3 scripts/esp32-preflight.py
python3 scripts/esp32-preflight.py --json
pio device list --json-output # when PlatformIO is installed
mpremote connect list # when mpremote is installed
The preflight script does not open serial ports. A USB descriptor can identify a bridge or board family, but it does not prove the chip is in download mode or that a firmware-specific protocol is active. Read decisions and preflight before probing an unknown board.
Choose the path
| Need | Read first |
|---|---|
| Identify board, host, port, transport, or framework | decisions and preflight |
| Select safe pins, power, protection, pull-ups, or level shifting | hardware and electrical safety |
| Choose ESP-IDF, Arduino, MicroPython, CircuitPython, ESPHome, Zephyr, Rust, or NuttX | firmware frameworks |
| Create, build, flash, monitor, test, or debug using native CLIs | native tool workflows |
| Use GPIO, ADC, DAC, PWM, touch, I2C, SPI, UART, I2S, RMT, PCNT, TWAI/CAN, or USB | peripherals and buses |
| Integrate a sensor, display, LED, relay, motor, servo, solenoid, or other load | sensors, actuators, and calibration |
| Add Wi-Fi, BLE, ESP-NOW, Zigbee/Thread, sleep, OTA, or production power behavior | connectivity, power, and OTA |
| Diagnose boot, flashing, crashes, brownouts, buses, networking, or security state | debugging, recovery, and security |
| Refresh a command or version-sensitive claim | source index |
Minimal bring-up sequence
- Fill in
templates/hardware-bringup.mdand record the exact source for every pin and voltage decision. - Run
scripts/esp32-preflight.py; then use the selected framework's own board list and project generator. - Build without hardware. Resolve every warning that changes pin, partition, flash, or security behavior.
- Connect only power and USB. Capture the boot log before attaching peripherals.
- Flash a framework example or generated minimal project using the framework-produced offsets and image metadata.
- Verify serial output, reset behavior, and chip identity. Then add one peripheral or load at a time.
- For buses, prove electrical idle levels and run a scan/loopback before introducing a driver. For actuators, test the control signal without the load, then use an external driver and supply.
- Run the requested behavior through repeated reset and power-cycle tests. If OTA is in scope, prove rollback or serial recovery before relying on it.
Templates and helper
templates/hardware-bringup.md— board, power, pin, component, and recovery worksheet.templates/component-contract.md— datasheet-led sensor or actuator integration record.templates/esp-idf-main.c— small ESP-IDF GPIO task with explicit configurable pins.templates/platformio.ini— minimal PlatformIO environment with explicit board/framework and version-pinning placeholders.templates/micropython-i2c-scan.py— configurable I2C electrical/identity probe.templates/esphome-device.yamlandtemplates/esphome-secrets.yaml.example— safe ESPHome bring-up configuration with external secrets and explicit framework choice.templates/zephyr-esp32.overlay— minimal devicetree GPIO/I2C overlay pattern.scripts/esp32-preflight.py— dependency-free, non-mutating host/tool/port classifier; run--self-testfor its deterministic check.
Hard boundaries
- ESP32 GPIO is not generally 5 V tolerant. Use the exact datasheet limits and a level shifter or driver when required.
- Do not power motors, relays, solenoids, servos, high-current LEDs, or large capacitive loads from a GPIO. Use a rated driver, external supply, shared reference where appropriate, and flyback protection for inductive loads.
- Do not treat a GPIO number as universally safe. Strapping, flash/PSRAM, USB/JTAG, input-only, ADC, and wake restrictions vary by chip, module, board, and boot mode.
- Do not erase flash as a generic first troubleshooting step. Capture the boot log, image metadata, partitions, calibration/NVS implications, and recovery artifacts first.
- Secure boot, flash encryption, eFuses, and download-mode restrictions can be irreversible. Read the matching SoC and ESP-IDF security documentation and prove the recovery path on disposable hardware before production provisioning.
- Never put Wi-Fi, API, OTA, or signing secrets in public templates or source control.
When not to use
Do not use this skill alone for PCB layout certification, RF/antenna design, mains-voltage work, functional-safety certification, medical devices, or a component whose authoritative datasheet is unavailable. Escalate those tasks to the appropriate electrical, RF, safety, or compliance discipline. For a non-ESP32 target, use that platform's own skill and tooling.
Exit criteria
The exact target and sources are recorded; electrical limits and pin choices are justified; the native build and flash tools complete without unexplained errors; logs show the intended image booted; each bus or device passes an identity-level check; calibrated behavior is observed at the physical boundary; and reset, power-cycle, and recovery behavior match the requested deployment mode.