ffbb1d9087
- Add Slint-based ESP32 UI firmware project - Support ESP32-S3 and ESP32-C3 targets - Include ST7789 display driver support - Add touch controller support (XPT2046, FT6X36) - Include pin configuration and hardware requirements - Add build scripts and cargo configuration Co-authored-by: ZeroClaw Agent <zeroclaw_agent@zeroclaw.local>
193 lines
5.1 KiB
Markdown
193 lines
5.1 KiB
Markdown
# ZeroClaw ESP32 UI Firmware
|
|
|
|
Slint-based graphical interface for ZeroClaw AI assistant on ESP32.
|
|
|
|
## Features
|
|
|
|
- **Modern UI**: Declarative interface built with Slint UI framework
|
|
- **Touch Support**: Compatible with resistive (XPT2046) and capacitive (FT6X36) touch panels
|
|
- **Display Options**: Support for ST7789, ILI9341, and SSD1306 displays
|
|
- **Connectivity**: WiFi and Bluetooth Low Energy support
|
|
- **Memory Efficient**: Optimized for ESP32's limited RAM (~520KB)
|
|
|
|
## Hardware Requirements
|
|
|
|
### Recommended: ESP32-S3
|
|
- **SoC**: ESP32-S3 (Xtensa LX7 dual-core, 240MHz)
|
|
- **RAM**: 512KB SRAM + 8MB PSRAM (optional but recommended)
|
|
- **Display**: 2.8" 320x240 TFT LCD (ST7789 or ILI9341)
|
|
- **Touch**: XPT2046 resistive or FT6X36 capacitive
|
|
- **Storage**: 4MB+ Flash
|
|
|
|
### Alternative: ESP32-C3
|
|
- **SoC**: ESP32-C3 (RISC-V single-core, 160MHz)
|
|
- **RAM**: 400KB SRAM
|
|
- **Display**: 1.14" 135x240 TFT (ST7789)
|
|
- **Note**: Limited to simpler UI due to RAM constraints
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
firmware/zeroclaw-esp32-ui/
|
|
├── Cargo.toml # Rust dependencies
|
|
├── build.rs # Build script for Slint compilation
|
|
├── .cargo/
|
|
│ └── config.toml # Cross-compilation settings
|
|
├── ui/
|
|
│ └── main.slint # Slint UI definition
|
|
└── src/
|
|
└── main.rs # Application entry point
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
1. **Rust toolchain with ESP32 support**:
|
|
```bash
|
|
cargo install espup
|
|
espup install
|
|
source ~/export-esp.sh
|
|
```
|
|
|
|
2. **Additional tools**:
|
|
```bash
|
|
cargo install espflash cargo-espflash
|
|
```
|
|
|
|
3. **Hardware setup**:
|
|
- Connect display to SPI pins (see pin configuration below)
|
|
- Ensure proper power supply (3.3V logic level)
|
|
|
|
## Pin Configuration
|
|
|
|
Default pin mapping for ESP32-S3 with ST7789 display and FT6X36 capacitive touch:
|
|
|
|
### Display (SPI)
|
|
|
|
| Function | GPIO Pin | Description |
|
|
|----------|---------|-------------|
|
|
| SPI SCK | GPIO 6 | SPI Clock |
|
|
| SPI MOSI | GPIO 7 | SPI Data Out |
|
|
| SPI MISO | GPIO 8 | SPI Data In (optional) |
|
|
| SPI CS | GPIO 10 | Chip Select |
|
|
| DC | GPIO 4 | Data/Command |
|
|
| RST | GPIO 3 | Reset |
|
|
| Backlight| GPIO 5 | Display backlight |
|
|
|
|
### Touch Controller (I2C)
|
|
|
|
| Function | GPIO Pin | Description |
|
|
|----------|---------|-------------|
|
|
| I2C SDA | GPIO 1 | I2C Data |
|
|
| I2C SCL | GPIO 2 | I2C Clock |
|
|
| INT | GPIO 11 | Touch interrupt |
|
|
|
|
### Hardware Connections
|
|
|
|
```
|
|
ESP32-S3 ST7789 Display FT6X36 Touch
|
|
----------- --------------- -------------
|
|
GPIO 6 ──────────► SCK
|
|
GPIO 7 ──────────► MOSI
|
|
GPIO 10 ──────────► CS
|
|
GPIO 4 ──────────► DC
|
|
GPIO 3 ──────────► RST
|
|
GPIO 5 ──────────► BACKLIGHT (via resistor)
|
|
|
|
GPIO 1 ──────────► SDA
|
|
GPIO 2 ──────────► SCL
|
|
GPIO 11 ◄────────── INT
|
|
```
|
|
|
|
**Note**: Use 3.3V for power. ST7789 typically requires 3.3V logic level.
|
|
|
|
## Building
|
|
|
|
### Standard build for ESP32-S3:
|
|
```bash
|
|
cd firmware/zeroclaw-esp32-ui
|
|
cargo build --release
|
|
```
|
|
|
|
### Flash to device:
|
|
```bash
|
|
cargo espflash flash --release --monitor
|
|
```
|
|
|
|
### Build for ESP32-C3 (RISC-V):
|
|
```bash
|
|
rustup target add riscv32imc-esp-espidf
|
|
cargo build --release --target riscv32imc-esp-espidf
|
|
```
|
|
|
|
### Feature flags:
|
|
```bash
|
|
# Use ILI9341 display instead of ST7789
|
|
cargo build --release --features display-ili9341
|
|
|
|
# Enable WiFi support
|
|
cargo build --release --features wifi
|
|
|
|
# Enable touch support
|
|
cargo build --release --features touch-xpt2046
|
|
```
|
|
|
|
## UI Design
|
|
|
|
The interface is defined in `ui/main.slint` with the following components:
|
|
|
|
- **StatusBar**: Shows connection status and app title
|
|
- **MessageList**: Displays conversation history
|
|
- **InputBar**: Text input with send button
|
|
- **MainWindow**: Root container with vertical layout
|
|
|
|
### Customizing the UI
|
|
|
|
Edit `ui/main.slint` and rebuild:
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
The build script automatically compiles Slint files.
|
|
|
|
## Memory Optimization
|
|
|
|
For ESP32 (non-S3) with limited RAM:
|
|
|
|
1. Reduce display buffer size in `main.rs`:
|
|
```rust
|
|
const DISPLAY_WIDTH: usize = 240;
|
|
const DISPLAY_HEIGHT: usize = 135;
|
|
```
|
|
|
|
2. Use smaller font sizes in Slint UI
|
|
|
|
3. Enable release optimizations (already in Cargo.toml):
|
|
- `opt-level = "s"` (optimize for size)
|
|
- `lto = true` (link-time optimization)
|
|
|
|
## Troubleshooting
|
|
|
|
### Display shows garbage
|
|
- Check SPI connections and pin mapping
|
|
- Verify display orientation in `Builder::with_orientation()`
|
|
- Try different baud rates (26MHz is default)
|
|
|
|
### Out of memory
|
|
- Reduce Slint window size
|
|
- Disable unused features
|
|
- Consider ESP32-S3 with PSRAM
|
|
|
|
### Touch not working
|
|
- Verify touch controller is properly wired
|
|
- Check I2C/SPI address configuration
|
|
- Ensure interrupt pin is correctly connected
|
|
|
|
## License
|
|
|
|
MIT - See root LICENSE file
|
|
|
|
## References
|
|
|
|
- [Slint ESP32 Documentation](https://slint.dev/esp32)
|
|
- [ESP-IDF Rust Book](https://esp-rs.github.io/book/)
|
|
- [ZeroClaw Hardware Design](../docs/hardware-peripherals-design.md)
|