esp32-development

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

1. 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.
2. Read the board schematic or pinout, the matching SoC/module datasheet, and every attached component datasheet before choosing pins or voltage levels.
3. 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.
4. Choose one framework based on the product constraint. Reuse its project generator, examples, drivers, build system, flasher, monitor, and debugger before writing wrappers.
5. 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.
6. 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.
7. 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:

1. Build a claim ledger for every material positive claim, negative claim, command, and numeric design choice. A URL in source-index.md is navigation, not evidence; retrieve the exact chip/current-version page or mark the claim UNKNOWN.
2. 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.
3. Missing hardware artifacts stay missing. Do not replace them with archetypes, examples, or words such as usually, typical, or some modules; state what the observed label does not establish.
4. 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.
5. Audit the final response against the ledger. Remove or downgrade every material claim that lacks its required evidence.