magnus919_agent-skills/esp32-development/references/source-index.md

Source index

Checked 2026-07-15. Prefer stable or versioned pages for implementation. latest pages are discovery aids and must be rechecked when a command, default, supported target, or security behavior matters.

Coverage matrix

Requested dimension	Primary evidence group	Skill reference	Status
Board, SoC, memory, USB, and port identification	ESP-IDF, esptool, development-board docs, family datasheets	decisions-and-preflight.md	Covered; exact board artifacts remain task inputs.
Electrical limits, strapping, pins, and power	Family datasheets and hardware design guidelines	hardware-and-electrical-safety.md	Covered by procedure; no universal pin table is asserted.
ESP-IDF C/C++	ESP-IDF Programming Guide	firmware-frameworks.md, native-tool-workflows.md	Covered.
Arduino and PlatformIO	Arduino-ESP32 and PlatformIO official docs	firmware-frameworks.md, native-tool-workflows.md	Covered.
MicroPython and CircuitPython	Project docs, downloads, and ESP32 quick start	firmware-frameworks.md, native-tool-workflows.md	Covered with board-support boundaries.
ESPHome	ESPHome CLI, ESP32 platform, and component index	firmware-frameworks.md, native-tool-workflows.md	Covered.
Zephyr	Zephyr getting-started, board, devicetree, and runner docs	firmware-frameworks.md, native-tool-workflows.md	Covered.
Rust on ESP	Official Rust on ESP book, esp-generate, and espflash	firmware-frameworks.md, native-tool-workflows.md	Covered; support must be refreshed by chip/toolchain.
NuttX and additional firmware	Apache NuttX family pages	firmware-frameworks.md	Covered as an intentional secondary path, not the default.
GPIO, ADC/DAC, PWM, touch, buses, timers, USB/JTAG	ESP-IDF peripheral catalog plus framework APIs	peripherals-and-buses.md	Covered by capability and diagnostic workflow.
Sensors, displays, and actuators	Manufacturer datasheets, module schematics, maintained drivers	sensors-actuators-and-calibration.md	Covered by reusable component contract; individual parts are task inputs.
Wi-Fi, BLE, other radios, sleep, storage, and OTA	ESP-IDF and framework update/network docs	connectivity-power-and-ota.md	Covered with family-support checks.
Flashing, logs, crashes, recovery, and security	esptool, ESP-IDF monitor/fatal/JTAG/security docs	debugging-recovery-and-security.md	Covered, including irreversible-operation boundaries.
Validation and physical verification	All framework build/test docs plus hardware boundary checks	native-tool-workflows.md	Covered; successful component tests are not promoted to hardware proof.

Espressif hardware and ESP-IDF

Area	Primary source	Scope
ESP-IDF documentation and version selector	ESP-IDF Programming Guide	Select the exact SoC family; stable classic ESP32 was v6.0.2 at review.
SoC selection	ESP Product Selector	Compare current CPU, memory, radio, and peripheral capabilities; verify the resulting chip-specific datasheet.
Build, flash, and monitor	Build the Project	idf.py build, generated images/offsets, flash, monitor.
idf.py	IDF Frontend	Native project control plane and command behavior.
Serial monitoring	IDF Monitor	Decoding, reset behavior, --no-reset, filtering.
Flash failures	Flashing Troubleshooting	Port, boot mode, reset wiring, power, and connection failures.
Classic ESP32 GPIO	GPIO and RTC GPIO	Pin restrictions for classic ESP32 only. Switch URL family for S/C/H/P targets.
ESP32-S3 GPIO	GPIO and RTC GPIO	S3 strapping, flash/PSRAM, and built-in USB pin constraints.
ESP32-C3 GPIO	GPIO and RTC GPIO	C3 strapping, flash, USB, RTC GPIO, and sleep-wake constraints.
Peripheral catalog	Peripherals API	Current ESP-IDF drivers and supported peripherals.
ADC	ADC driver	Conversion modes, calibration, SoC limitations.
ADC calibration	ADC Calibration Driver	Factory eFuse calibration and documented fallback-reference behavior.
Sleep	Sleep Modes	Power domains and wake behavior.
Runtime power	Power Management	Frequency scaling, automatic light sleep, locks, and profiling.
Partitions	Partition Tables	CSV layout, offsets, types, generated tables, erase implications.
OTA	Over-the-Air Updates	OTA slots, data, rollback APIs, image validation.
HTTPS OTA	ESP HTTPS OTA	Certificate verification, partial download, resume, and encrypted-image boundaries.
Crashes	Fatal Errors	Panic, watchdog, brownout, core dump, and backtrace evidence.
Postmortem data	Core Dump	Capture and decode task/register state against the matching ELF.
JTAG	JTAG Debugging	OpenOCD/GDB, adapters, voltage, and classic ESP32 constraints.
Security	ESP-IDF Security	Entry point for secure boot, flash encryption, eFuses, signing, and hardening.
Secure Boot V1	Secure Boot V1	Legacy classic-ESP32 scheme and revision boundaries.
Secure Boot V2	Secure Boot V2	Current scheme, signing flow, chip-revision boundaries, and provisioning constraints.
Flash Encryption	Flash Encryption	Development/release modes, key lifecycle, UART restrictions, and irreversible state.
eFuses	eFuse Manager	Coding scheme, readable state, field semantics, and programming boundaries.
Hardware design	ESP Hardware Design Guidelines	Family-specific schematic, power, reset, flash/PSRAM, RF, and strapping guidance.
Silicon limitations	ESP Chip Errata	Family/revision-specific defects and workarounds.
Classic ESP32 datasheet	ESP32 Series Datasheet	Absolute limits, electrical characteristics, pins, boot configuration. Use matching family datasheet for other SoCs.
Board hardware	Espressif Development Boards	Board-specific guides, schematics, ports, headers, and jumpers.

Flashing and C/C++ ecosystems

Area	Primary source	Scope
esptool commands	Basic Commands	Identification, read/write/erase, image inspection; select exact chip docs.
esptool diagnosis	Troubleshooting	Connection and flashing failure signatures.
Arduino core	Arduino-ESP32 documentation	Install, APIs, board pages, migration, OTA, troubleshooting. Version 3.3.10 was documented at review.
Arduino APIs	Arduino-ESP32 Libraries	GPIO, ADC, I2C, SPI, UART, BLE, USB, networking, and family support.
PlatformIO	Espressif 32 platform	Board IDs, frameworks, build settings, partitions, filesystems, OTA.
PlatformIO CLI	PlatformIO Core CLI	Project, run, upload, device, test, and debug commands.

Python firmware and ESPHome

Area	Primary source	Scope
MicroPython ESP32	ESP32 quick reference	Port-specific networking, pins, ADC/PWM, buses, timers, sleep. v1.28.0 was current at review.
MicroPython host tool	mpremote	Discovery, REPL, filesystem, run, mount, reset, packages.
MicroPython images	ESP32 downloads	Board/SoC image selection and exact installation instructions.
CircuitPython boards	CircuitPython downloads	Exact supported board, firmware, and install method.
CircuitPython on ESP32	ESP32 quick start	Serial esptool and web workflow boundaries for ESP32 boards.
CircuitPython APIs	CircuitPython Documentation	board, busio, digitalio, analogio, pwmio, library compatibility.
CircuitPython libraries	circup	Discover, install, freeze, and update libraries on mounted or Web Workflow devices.
ESPHome CLI	Command Line ESPHome	config, compile, upload, logs, run.
ESPHome ESP32 platform	ESP32 Platform	Families, boards, framework choice, flash/PSRAM options.
ESPHome components	Component index	Supported sensors, buses, outputs, displays, automations, and exact config.

Wireless detail

Area	Primary source	Use
Wi-Fi	ESP-IDF Wi-Fi Driver Guide	Initialization, events, modes, reconnect behavior, and chip-specific driver boundaries.
BLE with NimBLE	NimBLE Host APIs	Host architecture, initialization, threading, and BLE feature support.

Zephyr, Rust, and NuttX

Area	Primary source	Scope
Zephyr setup	Getting Started	west, SDK, build, flash, and board discovery. Latest was 4.4.0 at review.
Zephyr ESP32 board	ESP32-DevKitC	Board target, supported features, flash/debug and reset details. Use exact board page.
Zephyr hardware model	Devicetree	Board overlays, bindings, aliases, and generated hardware description.
Zephyr flash/debug	Flash and Debug	West runners, host tools, debug probes.
Zephyr on Espressif status	Espressif Zephyr Support Status	Current chip/peripheral support and known gaps; check before committing to Zephyr.
Rust on ESP	The Rust on ESP Book	Official environment, architecture choice, generation, build, flash, and debugging.
Rust generator	esp-generate	Current generator installation, project layouts, and options.
Rust flasher	espflash	Installation, supported chips, flashing, serial monitor.
NuttX classic ESP32	Espressif ESP32	Board configs, build/flash, JTAG, wireless, crash decoding.
NuttX ESP32-C3	Espressif ESP32-C3	RISC-V C3-specific board and build support.
NuttX ESP32-S3	Espressif ESP32-S3	S3-specific board and build support.

Component sources

For every attached device, prefer:

1. component manufacturer's current datasheet and errata;
2. breakout/module vendor schematic and pinout;
3. framework-maintained component/driver documentation;
4. vendor-maintained driver source and examples;
5. independent tutorials only as clearly labeled practice evidence.

Record URLs, document revisions, access date, exact claims used, and gaps in templates/component-contract.md.

Refresh rules

Recheck sources when changing ESP-IDF major/minor version, Arduino core major version, ESPHome release train, MicroPython/CircuitPython major version, Zephyr release, Rust toolchain/HAL generation, NuttX release, SoC family/revision, bootloader/partition/security state, board revision, or attached component revision. Always recheck irreversible security commands and flash offsets immediately before execution.