firmware/esp32/README.md
Peripheral firmware for ESP32 — speaks the same JSON-over-serial protocol as the STM32 firmware. Flash this to your ESP32, then configure ZeroClaw on the host to connect via serial.
New to this? See SETUP.md for step-by-step commands and troubleshooting.
{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}\n{"id":"1","ok":true,"result":"done"}\nCommands: gpio_read, gpio_write.
RISC-V ESP-IDF (ESP32-C2/C3): Uses nightly Rust with build-std.
Python: ESP-IDF requires Python 3.10–3.13 (not 3.14). If you have Python 3.14:
brew install [email protected]
virtualenv (needed by ESP-IDF tools; PEP 668 workaround on macOS):
/opt/homebrew/opt/[email protected]/bin/python3.12 -m pip install virtualenv --break-system-packages
Rust tools:
cargo install espflash ldproxy
The project's rust-toolchain.toml pins nightly + rust-src. esp-idf-sys downloads ESP-IDF automatically on first build. Use Python 3.12 for the build:
export PATH="/opt/homebrew/opt/[email protected]/libexec/bin:$PATH"
Xtensa targets (ESP32, ESP32-S2, ESP32-S3): Use espup instead:
cargo install espup espflash
espup install
source ~/export-esp.sh
Then edit .cargo/config.toml to change the target (e.g. xtensa-esp32-espidf).
cd firmware/esp32
# Use Python 3.12 (required if you have 3.14)
export PATH="/opt/homebrew/opt/[email protected]/libexec/bin:$PATH"
# Optional: pin MCU (esp32c3 or esp32c2)
export MCU=esp32c3
cargo build --release
espflash flash target/riscv32imc-esp-espidf/release/esp32 --monitor
Add to config.toml:
[peripherals]
enabled = true
[[peripherals.boards]]
board = "esp32"
transport = "serial"
path = "/dev/ttyUSB0" # or /dev/ttyACM0, COM3, etc.
baud = 115200
Default GPIO 2 and 13 are configured for output. Edit src/main.rs to add more pins or change for your board. ESP32-C3 has different pin layout — adjust UART pins (gpio21/gpio20) if needed.
Phase 6 also envisions ZeroClaw running on the ESP32 (WiFi + LLM). This firmware is the host-mediated serial peripheral; edge-native will be a separate crate.