zeroclaw/firmware/zeroclaw-esp32-ui/README.md

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:

   cargo install espup
   espup install
   source ~/export-esp.sh
   

2. Additional tools:

   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:

cd firmware/zeroclaw-esp32-ui
cargo build --release

Flash to device:

cargo espflash flash --release --monitor

Build for ESP32-C3 (RISC-V):

rustup target add riscv32imc-esp-espidf
cargo build --release --target riscv32imc-esp-espidf

Feature flags:

# 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:

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:

   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
• ESP-IDF Rust Book
• ZeroClaw Hardware Design