mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-18 15:06:28 +03:00
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.
108 lines
6.5 KiB
Markdown
108 lines
6.5 KiB
Markdown
# 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.
|