d7c1fd7bf8
* security(deps): remove vulnerable xmas-elf dependency via embuild * chore(deps): update dependencies and improve ESP-IDF compatibility - Updated `bindgen`, `embassy-sync`, `embedded-svc`, and `embuild` versions in `Cargo.lock`. - Added patch section in `Cargo.toml` to use latest esp-rs crates for better compatibility with ESP-IDF 5.x. - Enhanced README with updated prerequisites and build instructions for Python and Rust tools. - Introduced `rust-toolchain.toml` to pin nightly Rust and added necessary components. - Modified GPIO handling in `main.rs` to improve pin management and added support for 64-bit time_t in ESP-IDF. - Updated `.cargo/config.toml` for new linker and runner configurations. * docs: add detailed setup guide for ESP32 firmware and link in README - Introduced a new `SETUP.md` file with comprehensive step-by-step instructions for building and flashing the ZeroClaw ESP32 firmware. - Updated `README.md` to include a link to the new setup guide for easier access to installation and troubleshooting information. * chore: update .gitignore and refactor main.rs for improved readability - Added .embuild/ to .gitignore to exclude ESP32 build cache. - Refactored code in main.rs for better readability by adjusting the formatting of the handle_request function call. * docs: add newline for better readability in README.md - Added a newline in the protocol section of README.md to enhance clarity and formatting. * chore: configure workspace settings in Cargo.toml - Added workspace configuration to `Cargo.toml` with members and resolver settings for improved project management. --------- Co-authored-by: ehushubhamshaw <eshaw1@wpi.edu> Co-authored-by: Will Sarg <12886992+willsarg@users.noreply.github.com>
80 lines
2.4 KiB
Markdown
80 lines
2.4 KiB
Markdown
# ZeroClaw ESP32 Firmware
|
||
|
||
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](SETUP.md) for step-by-step commands and troubleshooting.
|
||
|
||
## Protocol
|
||
|
||
|
||
- **Request** (host → ESP32): `{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}\n`
|
||
- **Response** (ESP32 → host): `{"id":"1","ok":true,"result":"done"}\n`
|
||
|
||
Commands: `gpio_read`, `gpio_write`.
|
||
|
||
## Prerequisites
|
||
|
||
1. **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:
|
||
```sh
|
||
brew install python@3.12
|
||
```
|
||
|
||
**virtualenv** (needed by ESP-IDF tools; PEP 668 workaround on macOS):
|
||
```sh
|
||
/opt/homebrew/opt/python@3.12/bin/python3.12 -m pip install virtualenv --break-system-packages
|
||
```
|
||
|
||
**Rust tools**:
|
||
```sh
|
||
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:
|
||
```sh
|
||
export PATH="/opt/homebrew/opt/python@3.12/libexec/bin:$PATH"
|
||
```
|
||
|
||
2. **Xtensa targets** (ESP32, ESP32-S2, ESP32-S3): Use espup instead:
|
||
```sh
|
||
cargo install espup espflash
|
||
espup install
|
||
source ~/export-esp.sh
|
||
```
|
||
Then edit `.cargo/config.toml` to change the target (e.g. `xtensa-esp32-espidf`).
|
||
|
||
## Build & Flash
|
||
|
||
```sh
|
||
cd firmware/zeroclaw-esp32
|
||
# Use Python 3.12 (required if you have 3.14)
|
||
export PATH="/opt/homebrew/opt/python@3.12/libexec/bin:$PATH"
|
||
# Optional: pin MCU (esp32c3 or esp32c2)
|
||
export MCU=esp32c3
|
||
cargo build --release
|
||
espflash flash target/riscv32imc-esp-espidf/release/zeroclaw-esp32 --monitor
|
||
```
|
||
|
||
## Host Config
|
||
|
||
Add to `config.toml`:
|
||
|
||
```toml
|
||
[peripherals]
|
||
enabled = true
|
||
|
||
[[peripherals.boards]]
|
||
board = "esp32"
|
||
transport = "serial"
|
||
path = "/dev/ttyUSB0" # or /dev/ttyACM0, COM3, etc.
|
||
baud = 115200
|
||
```
|
||
|
||
## Pin Mapping
|
||
|
||
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.
|
||
|
||
## Edge-Native (Future)
|
||
|
||
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.
|