Developer Docs¶

This section is for maintainers working on firmware provenance, architecture, scripts, and validation policy.

Maintainer Charter¶

Purpose¶

This repository is the canonical, reproducible workflow for running ESP32-H2 as an OpenThread RCP. It exists to remove fragmented setup knowledge and unstable flashing practices.

Scope Boundaries¶

In scope:

RCP firmware build, flash, validation, and troubleshooting.
Environment checks and deterministic script entry points.
Provenance tracking for upstream firmware baseline and local overrides.

Out of scope:

Sensor-node firmware provisioning.
Server application behavior beyond host-side RCP integration.
Fleet orchestration.

Design Principles¶

Reproducibility over convenience.
Single source of truth in-repo.
Deterministic, scriptable workflows.
Clear separation of concerns.
Minimal abstraction unless it improves reliability.

Success Criteria¶

A new maintainer can clone the repository, run setup, build/flash firmware, and verify operation without external guides or ad-hoc patching.

Ownership And Change Rule¶

This repository is authoritative for the lab RCP workflow. Any intentional divergence from upstream firmware baseline must be captured in this page.

Architecture Snapshot¶

For operational commissioning steps, use User Guide. This section captures the maintainer-facing system model and interface decisions.

System Diagram¶

[ Sensor Node(s) ]
        |
        v
[ Thread Network ]
        |
        v
[ RCP (ESP32-H2 running OpenThread firmware) ]
        |
        v
[ Host / Server ]

This repository owns only the RCP firmware layer.

RCP-Host Link¶

The host and RCP communicate using Spinel.

Transport path for this repository:

Host process (otbr-agent or other Spinel client)
USB cable
ESP32-H2 native USB Serial JTAG interface (CDC-ACM)
OpenThread RCP firmware
802.15.4 radio

Hardware Interface Choice¶

The ESP32-H2-DevKitM-1 has two USB-C ports:

Native ESP32-H2 USB (USB Serial/JTAG)
CP210x UART bridge

Canonical workflow uses the native ESP32-H2 USB port.

Reasons:

No extra driver install on Linux or Windows 10/11 for CDC-ACM.
Aligns with first-class ot_rcp USB transport configuration.
Removes bridge-chip path as an avoidable failure point for Spinel transport.

Runtime Port Expectations¶

Linux: /dev/ttyACM* (typically /dev/ttyACM0)
Windows: COM*

What Runs Where¶

ESP32-H2 board: OpenThread RCP firmware from firmware/rcp.
Host/server: Spinel client stack such as otbr-agent.

Core References¶

User Guide
Retrospective document (internal-history context; excluded from published site)

Repository Principles¶

Keep the workflow reproducible from a clean machine.
Prefer deterministic scripts over manual ad-hoc steps.
Keep terminology and operational instructions aligned across docs.

Firmware Provenance And Local Overrides¶

Canonical Upstream Source¶

Repository: https://github.com/espressif/esp-idf
Tag: v6.0
Commit: 662a3be35475 (detached HEAD from git clone --depth 1 --branch v6.0)
Example path: examples/openthread/ot_rcp
Verified and re-synced: 2026-04-07

Verification Summary¶

A direct diff showed the initial local _reference/esp-idf-master snapshot was not identical to upstream v6.0.
firmware/rcp was re-seeded directly from the verified upstream v6.0 example.
After re-seed, only the intentional local overrides listed below are maintained.

Local Modifications¶

firmware/rcp/sdkconfig.defaults
Added: CONFIG_OPENTHREAD_RCP_SPINEL_CONSOLE=y CONFIG_LOG_DEFAULT_LEVEL_INFO=y CONFIG_OPENTHREAD_RCP_USB_SERIAL_JTAG=y
Reason:
Enables RCP Spinel console by default and raises default log level for operational diagnostics.
Selects native USB Serial JTAG transport (native ESP32-H2 USB port, /dev/ttyACM* or COM*) instead of UART bridge transport.
Symbol reference: examples/openthread/ot_rcp/sdkconfig.ci.rcp_usb

GitHub Pages Publishing Model¶

This site deploys through GitHub Actions artifact deployment (not branch publishing).

Settings -> Pages -> Build and deployment -> Source = GitHub Actions