Ehu shubham shaw contribution --> Hardware support (#306)
* feat: add ZeroClaw firmware for ESP32 and Nucleo * Introduced new firmware for ZeroClaw on ESP32 and Nucleo-F401RE, enabling JSON-over-serial communication for GPIO control. * Added `zeroclaw-esp32` with support for commands like `gpio_read` and `gpio_write`, along with capabilities reporting. * Implemented `zeroclaw-nucleo` firmware with similar functionality for STM32, ensuring compatibility with existing ZeroClaw protocols. * Updated `.gitignore` to include new firmware targets and added necessary dependencies in `Cargo.toml` for both platforms. * Created README files for both firmware projects detailing setup, build, and usage instructions. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> * feat: enhance hardware peripheral support and documentation - Added `Peripheral` trait implementation in `src/peripherals/` to manage hardware boards (STM32, RPi GPIO). - Updated `AGENTS.md` to include new extension points for peripherals and their configuration. - Introduced comprehensive documentation for adding boards and tools, including a quick start guide and supported boards. - Enhanced `Cargo.toml` to include optional dependencies for PDF extraction and peripheral support. - Created new datasheets for Arduino Uno, ESP32, and Nucleo-F401RE, detailing pin aliases and GPIO usage. - Implemented new tools for hardware memory reading and board information retrieval in the agent loop. This update significantly improves the integration and usability of hardware peripherals within the ZeroClaw framework. * feat: add ZeroClaw firmware for ESP32 and Nucleo * Introduced new firmware for ZeroClaw on ESP32 and Nucleo-F401RE, enabling JSON-over-serial communication for GPIO control. * Added `zeroclaw-esp32` with support for commands like `gpio_read` and `gpio_write`, along with capabilities reporting. * Implemented `zeroclaw-nucleo` firmware with similar functionality for STM32, ensuring compatibility with existing ZeroClaw protocols. * Updated `.gitignore` to include new firmware targets and added necessary dependencies in `Cargo.toml` for both platforms. * Created README files for both firmware projects detailing setup, build, and usage instructions. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> * feat: enhance hardware peripheral support and documentation - Added `Peripheral` trait implementation in `src/peripherals/` to manage hardware boards (STM32, RPi GPIO). - Updated `AGENTS.md` to include new extension points for peripherals and their configuration. - Introduced comprehensive documentation for adding boards and tools, including a quick start guide and supported boards. - Enhanced `Cargo.toml` to include optional dependencies for PDF extraction and peripheral support. - Created new datasheets for Arduino Uno, ESP32, and Nucleo-F401RE, detailing pin aliases and GPIO usage. - Implemented new tools for hardware memory reading and board information retrieval in the agent loop. This update significantly improves the integration and usability of hardware peripherals within the ZeroClaw framework. * feat: Introduce hardware auto-discovery and expanded configuration options for agents, hardware, and security. * chore: update dependencies and improve probe-rs integration - Updated `Cargo.lock` to remove specific version constraints for several dependencies, including `zerocopy`, `syn`, and `strsim`, allowing for more flexibility in version resolution. - Upgraded `bincode` and `bitfield` to their latest versions, enhancing serialization and memory management capabilities. - Updated `Cargo.toml` to reflect the new version of `probe-rs` from `0.24` to `0.30`, improving hardware probing functionality. - Refactored code in `src/hardware` and `src/tools` to utilize the new `SessionConfig` for session management in `probe-rs`, ensuring better compatibility and performance. - Cleaned up documentation in `docs/datasheets/nucleo-f401re.md` by removing unnecessary lines. * fix: apply cargo fmt * docs: add hardware architecture diagram. --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
ehu shubham shaw
GitHub
parent
b36f23784a
commit
de3ec87d16
59 changed files with 9607 additions and 1885 deletions
217
docs/arduino-uno-q-setup.md
Normal file
217
docs/arduino-uno-q-setup.md
Normal file
|
|
@ -0,0 +1,217 @@
|
|||
# ZeroClaw on Arduino Uno Q — Step-by-Step Guide
|
||||
|
||||
Run ZeroClaw on the Arduino Uno Q's Linux side. Telegram works over WiFi; GPIO control uses the Bridge (requires a minimal App Lab app).
|
||||
|
||||
---
|
||||
|
||||
## What's Included (No Code Changes Needed)
|
||||
|
||||
ZeroClaw includes everything needed for Arduino Uno Q. **Clone the repo and follow this guide — no patches or custom code required.**
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| Bridge app | `firmware/zeroclaw-uno-q-bridge/` | MCU sketch + Python socket server (port 9999) for GPIO |
|
||||
| Bridge tools | `src/peripherals/uno_q_bridge.rs` | `gpio_read` / `gpio_write` tools that talk to the Bridge over TCP |
|
||||
| Setup command | `src/peripherals/uno_q_setup.rs` | `zeroclaw peripheral setup-uno-q` deploys the Bridge via scp + arduino-app-cli |
|
||||
| Config schema | `board = "arduino-uno-q"`, `transport = "bridge"` | Supported in `config.toml` |
|
||||
|
||||
Build with `--features hardware` (or the default features) to include Uno Q support.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Arduino Uno Q with WiFi configured
|
||||
- Arduino App Lab installed on your Mac (for initial setup and deployment)
|
||||
- API key for LLM (OpenRouter, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Initial Uno Q Setup (One-Time)
|
||||
|
||||
### 1.1 Configure Uno Q via App Lab
|
||||
|
||||
1. Download [Arduino App Lab](https://docs.arduino.cc/software/app-lab/) (AppImage on Linux).
|
||||
2. Connect Uno Q via USB, power it on.
|
||||
3. Open App Lab, connect to the board.
|
||||
4. Follow the setup wizard:
|
||||
- Set username and password (for SSH)
|
||||
- Configure WiFi (SSID, password)
|
||||
- Apply any firmware updates
|
||||
5. Note the IP address shown (e.g. `arduino@192.168.1.42`) or find it later via `ip addr show` in App Lab's terminal.
|
||||
|
||||
### 1.2 Verify SSH Access
|
||||
|
||||
```bash
|
||||
ssh arduino@<UNO_Q_IP>
|
||||
# Enter the password you set
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Install ZeroClaw on Uno Q
|
||||
|
||||
### Option A: Build on the Device (Simpler, ~20–40 min)
|
||||
|
||||
```bash
|
||||
# SSH into Uno Q
|
||||
ssh arduino@<UNO_Q_IP>
|
||||
|
||||
# Install Rust
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
|
||||
source ~/.cargo/env
|
||||
|
||||
# Install build deps (Debian)
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y pkg-config libssl-dev
|
||||
|
||||
# Clone zeroclaw (or scp your project)
|
||||
git clone https://github.com/theonlyhennygod/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
# Build (takes ~15–30 min on Uno Q)
|
||||
cargo build --release
|
||||
|
||||
# Install
|
||||
sudo cp target/release/zeroclaw /usr/local/bin/
|
||||
```
|
||||
|
||||
### Option B: Cross-Compile on Mac (Faster)
|
||||
|
||||
```bash
|
||||
# On your Mac — add aarch64 target
|
||||
rustup target add aarch64-unknown-linux-gnu
|
||||
|
||||
# Install cross-compiler (macOS; required for linking)
|
||||
brew tap messense/macos-cross-toolchains
|
||||
brew install aarch64-unknown-linux-gnu
|
||||
|
||||
# Build
|
||||
CC_aarch64_unknown_linux_gnu=aarch64-unknown-linux-gnu-gcc cargo build --release --target aarch64-unknown-linux-gnu
|
||||
|
||||
# Copy to Uno Q
|
||||
scp target/aarch64-unknown-linux-gnu/release/zeroclaw arduino@<UNO_Q_IP>:~/
|
||||
ssh arduino@<UNO_Q_IP> "sudo mv ~/zeroclaw /usr/local/bin/"
|
||||
```
|
||||
|
||||
If cross-compile fails, use Option A and build on the device.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Configure ZeroClaw
|
||||
|
||||
### 3.1 Run Onboard (or Create Config Manually)
|
||||
|
||||
```bash
|
||||
ssh arduino@<UNO_Q_IP>
|
||||
|
||||
# Quick config
|
||||
zeroclaw onboard --api-key YOUR_OPENROUTER_KEY --provider openrouter
|
||||
|
||||
# Or create config manually
|
||||
mkdir -p ~/.zeroclaw/workspace
|
||||
nano ~/.zeroclaw/config.toml
|
||||
```
|
||||
|
||||
### 3.2 Minimal config.toml
|
||||
|
||||
```toml
|
||||
api_key = "YOUR_OPENROUTER_API_KEY"
|
||||
default_provider = "openrouter"
|
||||
default_model = "anthropic/claude-sonnet-4"
|
||||
|
||||
[peripherals]
|
||||
enabled = false
|
||||
# GPIO via Bridge requires Phase 4
|
||||
|
||||
[channels_config.telegram]
|
||||
bot_token = "YOUR_TELEGRAM_BOT_TOKEN"
|
||||
allowed_users = ["*"]
|
||||
|
||||
[gateway]
|
||||
host = "127.0.0.1"
|
||||
port = 8080
|
||||
allow_public_bind = false
|
||||
|
||||
[agent]
|
||||
compact_context = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Run ZeroClaw Daemon
|
||||
|
||||
```bash
|
||||
ssh arduino@<UNO_Q_IP>
|
||||
|
||||
# Run daemon (Telegram polling works over WiFi)
|
||||
zeroclaw daemon --host 127.0.0.1 --port 8080
|
||||
```
|
||||
|
||||
**At this point:** Telegram chat works. Send messages to your bot — ZeroClaw responds. No GPIO yet.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: GPIO via Bridge (ZeroClaw Handles It)
|
||||
|
||||
ZeroClaw includes the Bridge app and setup command.
|
||||
|
||||
### 5.1 Deploy Bridge App
|
||||
|
||||
**From your Mac** (with zeroclaw repo):
|
||||
```bash
|
||||
zeroclaw peripheral setup-uno-q --host 192.168.0.48
|
||||
```
|
||||
|
||||
**From the Uno Q** (SSH'd in):
|
||||
```bash
|
||||
zeroclaw peripheral setup-uno-q
|
||||
```
|
||||
|
||||
This copies the Bridge app to `~/ArduinoApps/zeroclaw-uno-q-bridge` and starts it.
|
||||
|
||||
### 5.2 Add to config.toml
|
||||
|
||||
```toml
|
||||
[peripherals]
|
||||
enabled = true
|
||||
|
||||
[[peripherals.boards]]
|
||||
board = "arduino-uno-q"
|
||||
transport = "bridge"
|
||||
```
|
||||
|
||||
### 5.3 Run ZeroClaw
|
||||
|
||||
```bash
|
||||
zeroclaw daemon --host 127.0.0.1 --port 8080
|
||||
```
|
||||
|
||||
Now when you message your Telegram bot *"Turn on the LED"* or *"Set pin 13 high"*, ZeroClaw uses `gpio_write` via the Bridge.
|
||||
|
||||
---
|
||||
|
||||
## Summary: Commands Start to End
|
||||
|
||||
| Step | Command |
|
||||
|------|---------|
|
||||
| 1 | Configure Uno Q in App Lab (WiFi, SSH) |
|
||||
| 2 | `ssh arduino@<IP>` |
|
||||
| 3 | `curl -sSf https://sh.rustup.rs \| sh -s -- -y && source ~/.cargo/env` |
|
||||
| 4 | `sudo apt-get install -y pkg-config libssl-dev` |
|
||||
| 5 | `git clone https://github.com/theonlyhennygod/zeroclaw.git && cd zeroclaw` |
|
||||
| 6 | `cargo build --release --no-default-features` |
|
||||
| 7 | `zeroclaw onboard --api-key KEY --provider openrouter` |
|
||||
| 8 | Edit `~/.zeroclaw/config.toml` (add Telegram bot_token) |
|
||||
| 9 | `zeroclaw daemon --host 127.0.0.1 --port 8080` |
|
||||
| 10 | Message your Telegram bot — it responds |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **"command not found: zeroclaw"** — Use full path: `/usr/local/bin/zeroclaw` or ensure `~/.cargo/bin` is in PATH.
|
||||
- **Telegram not responding** — Check bot_token, allowed_users, and that the Uno Q has internet (WiFi).
|
||||
- **Out of memory** — Use `--no-default-features` to reduce binary size; consider `compact_context = true`.
|
||||
- **GPIO commands ignored** — Ensure Bridge app is running (`zeroclaw peripheral setup-uno-q` deploys and starts it). Config must have `board = "arduino-uno-q"` and `transport = "bridge"`.
|
||||
- **LLM provider (GLM/Zhipu)** — Use `default_provider = "glm"` or `"zhipu"` with `GLM_API_KEY` in env or config. ZeroClaw uses the correct v4 endpoint.
|
||||
Loading…
Add table
Add a link
Reference in a new issue