# Debugging, recovery, and security

Diagnose from the lowest unproven layer. Do not rewrite application code while power, boot mode, port ownership, or bus electrical state remains unknown.

## Failure ladder

1. **Host/tool:** command exists, expected version/environment active, permissions correct.
2. **USB/serial:** data-capable cable, stable USB identity, correct port, no competing process.
3. **Power/reset/boot:** rails stable, EN/reset and BOOT/strapping levels correct, boot log captured.
4. **ROM loader/flash:** targeted `chip-id`, image target/layout, transfer, verification.
5. **Bootloader/partition:** valid image headers, selected slot, partition table, security state.
6. **Runtime:** crash reason, watchdog, heap/stack, task state, exception/backtrace.
7. **Peripheral:** pin routing, voltage, pulls, bus waveform, address/identity, driver sequence.
8. **Network/service:** radio state, IP, DNS/time/TLS, endpoint, auth, application protocol.
9. **Physical behavior:** calibration, load, thermal, EMI, mechanical/environmental constraints.

## Flash and connection failures

Capture the complete native-tool error. Common categories:

- `No serial data received`: wrong/non-ESP port, target not in download mode, reset wiring, cable, permissions, port owner, native-USB state, or power.
- Invalid packet/header or intermittent transfer: marginal power, signal/cable, excessive baud, USB hub, competing access, or boot-mode instability.
- Wrong chip argument/image: stop and obtain the exact target artifact; do not force it.
- Write succeeds but no boot: capture boot log; inspect reset loop, image target, flash mode/frequency/size, offsets, partition table, boot slot, and security state.

Try a lower baud only after the basic target/port/power checks. Manual BOOT/RESET sequencing is board-specific. Use the board guide instead of random button timing.

## Boot loops and crashes

Preserve the first complete boot log after power-on. Note reset reason, boot mode, image/partition choice, exception, program counter, and backtrace.

ESP-IDF Monitor can decode addresses against the matching ELF. A backtrace from another build is not evidence. Keep the ELF, map, `sdkconfig`, commit, and toolchain version for a released image.

Common classes:

- brownout: measure supply at the board during peaks;
- watchdog: find the blocked/starved task or interrupt path; do not merely extend the timeout;
- stack overflow: inspect task stack sizing and call depth;
- heap failure/fragmentation: capture free/largest-block metrics and allocation lifetime;
- illegal access/panic: decode against the exact ELF and inspect ownership/lifetime/concurrency;
- reset caused by serial DTR/RTS: reproduce with monitor `--no-reset` or equivalent;
- crash only with peripheral attached: isolate power, pin conflict, bus lock, interrupt storm, and driver sequence.

## Bus diagnosis

### I2C

Measure SDA/SCL idle high, effective pull-ups, and voltage. Scan at conservative speed, then inspect start/address/ACK with a logic analyzer. A device that ACKs but returns bad data points to register, timing, mode, endian, readiness, or signal-integrity issues.

### SPI

Inspect CS, clock, MOSI, and MISO together. Verify mode and transaction boundaries. Floating MISO, wrong CS polarity, and a reset pin left asserted can resemble a software driver failure.

### UART

Loop back the ESP32 UART, then loop back or independently test the peripheral. Verify voltage standard and framing. Capture bytes rather than relying on rendered text.

## Recovery order

Use the least destructive rung that can restore observability:

1. close port owners and capture logs with no-reset behavior;
2. reset/power-cycle using the documented board path;
3. enter documented ROM download or bootloader mode;
4. query chip/flash identity;
5. reflash the known-good build with generated/authoritative offsets;
6. reflash bootloader/partition/application set when the framework requires it;
7. erase only the specific corrupt data partition when supported and authorized;
8. full-chip erase only after backup/impact review and explicit authorization;
9. hardware debugger or board-level repair.

Before erase, preserve readable flash or at least record partition layout, MAC/identity, security state, calibration implications, credentials/data impact, and the known-good recovery artifact. Do not read or publish secret-bearing flash without authorization.

## JTAG and debugger use

Use an ESP32-compatible OpenOCD configuration and voltage-compatible adapter. The exact JTAG pins and built-in USB JTAG support vary by family. Confirm pin conflicts and production security state. A debugger can change timing; reproduce without it before concluding the race is fixed.

## Security provisioning

Secure boot, flash encryption, eFuses, JTAG/download-mode controls, signing keys, and anti-rollback are product lifecycle decisions. Some transitions are irreversible.

Before provisioning:

1. identify exact SoC revision and supported security scheme;
2. read the matching stable ESP-IDF security pages and eFuse documentation;
3. define development, manufacturing, RMA, field-update, and decommission paths;
4. protect signing/encryption keys outside source and build logs;
5. verify image signing and encrypted-flash behavior on disposable hardware;
6. verify OTA, rollback/anti-rollback, serial recovery restrictions, and RMA path;
7. record non-secret provisioning evidence without publishing key material.

Secure Boot V1 and V2 are not interchangeable; choose the scheme supported by the exact chip revision and current ESP-IDF documentation. Flash Encryption development mode preserves reflashing paths for testing, while release mode applies production restrictions. Do not ship a development-mode security posture by accident: select the mode from the threat model only after OTA, recovery, manufacturing, and RMA behavior is proven.

Do not copy eFuse commands from a generic guide. Capture the chip-specific eFuse summary, coding scheme, and remaining writable fields before any burn. Do not enable flash encryption or secure boot merely to satisfy a checklist. The correct state depends on the threat model and a proven update/recovery lifecycle.

## Bounded escalation

After two genuinely different approaches fail at the same layer, stop and report:

- exact board/SoC and evidence;
- wiring/power state;
- tool versions and commands;
- complete errors/logs;
- what each attempt proved or disproved;
- the next action and its risk.

A third blind reset, framework switch, erase, or guessed image adds risk faster than information.