Firmware Dependency Stack

This document defines the ESP32-S3 firmware dependency versions and their compatibility matrix.

Container Environment

Development uses the official Espressif container:

docker.io/espressif/idf-rust:esp32s3_latest

Version Note (2026-01-11): esp32s3_latest currently resolves to toolchain v1.90.0.0. For reproducible builds, pin to esp32s3_1.90.0.0.

This container includes:

Xtensa Rust toolchain for ESP32-S3
espflash for firmware deployment
All required build tools

Version Matrix

Last Updated: 2026-01-11 ESP HAL Status: Testing stable 1.0.0 with existing ecosystem

ESP HAL Ecosystem

Crate	Version	Purpose
`esp-hal`	1.0.0	Hardware Abstraction Layer (stable)
`esp-rtos`	0.2.0	Embassy executor + WiFi scheduler
`esp-radio`	0.17.0	WiFi/BLE/ESP-NOW (requires `unstable`)
`esp-backtrace`	0.18.0	Panic handler with backtraces
`esp-println`	0.16.0	Serial output and logging
`esp-storage`	0.8.0	Flash storage (tower only)
`esp-alloc`	0.9.0	Heap allocator
`esp-bootloader-esp-idf`	0.3.0	ESP-IDF compatible bootloader

Upgrade Notes

Upgraded to esp-hal 1.0.0 stable ecosystem:

esp-hal 1.0.0-rc.1 → 1.0.0 (no API changes per release notes)
esp-rtos 0.1.1 → 0.2.0 (required for esp-metadata-generated compatibility)
esp-radio 0.16.0 → 0.17.0 (required for esp-metadata-generated compatibility)

Embassy Async Runtime

Crate	Version	Purpose
`embassy-executor`	0.9.x	Async task executor
`embassy-time`	0.5.x	Time and delay utilities
`embassy-sync`	0.7.x	Channels, mutexes, signals
`embassy-futures`	0.1.x	Future utilities (tower only)
`embassy-net`	0.7.x	Network stack (cat only)

Application Frameworks

Crate	Version	Purpose
`rmk`	0.8.x	Keyboard framework with Vial (tower only)
`usbd-hid`	0.9.x	USB HID types (tower only)

Serialization

Crate	Version	Purpose
`postcard`	1.x	Binary serialization (no_std)
`serde`	1.0	Serialization framework
`heapless`	0.8 (firmware) / 0.7 (common)	Fixed-capacity collections

Stability Notes

Stable APIs (esp-hal 1.0.0)

GPIO, SPI, I2C, UART drivers
Timer configuration and delays
Core HAL initialization
Memory allocation

Unstable APIs (behind `unstable` feature)

ESP-NOW (esp-radio) - next stabilization target
WiFi and BLE drivers
Some advanced peripheral features

The unstable feature is required for ESP-NOW wireless communication. While functional, these APIs may change in minor version updates.

Upgrade History

2026-01-11: esp-hal RC to Stable Ecosystem

Upgraded to esp-hal 1.0.0 stable with compatible ecosystem versions.

Crate	Before	After
esp-hal	1.0.0-rc.1	1.0.0
esp-rtos	0.1.1	0.2.0
esp-radio	0.16.0	0.17.0

esp-rtos and esp-radio upgraded to resolve esp-metadata-generated version conflict (0.2.0 vs 0.3.0).

API Change: esp-hal-smartled now takes &mut [PulseCode; N] instead of owned buffer. Use StaticCell for async tasks.

Feature Flags

Cat Crate

esp-hal = { features = ["esp32s3", "log-04", "unstable"] }
esp-rtos = { features = ["embassy", "esp-alloc", "esp-radio", "esp32s3", "log-04"] }
esp-radio = { features = ["esp-alloc", "esp-now", "esp32s3", "log-04", "smoltcp", "unstable", "wifi"] }

Tower Crate

esp-hal = { features = ["esp32s3", "log-04", "unstable"] }
esp-rtos = { features = ["embassy", "esp-alloc", "esp-radio", "esp32s3", "log-04"] }
esp-radio = { features = ["esp32s3", "wifi", "esp-now", "unstable", "log-04"] }