<!-- source: https://deepwiki.com/qhkm/zeptoclaw/8.9-android-and-hardware-tools -->

# Android and Hardware Tools

- docs/plans/2026-02-24-esp32-hardware-tools-design.md
- docs/plans/2026-02-24-esp32-hardware-tools-plan.md
- src/channels/email_channel.rs
- src/devices/usb.rs
- src/hardware/introspect.rs
- src/peripherals/arduino.rs
- src/peripherals/board_profile.rs
- src/peripherals/i2c.rs
- src/peripherals/mod.rs
- src/peripherals/nucleo.rs
- src/peripherals/rpi_i2c.rs
- src/peripherals/serial.rs
- src/tools/android/actions.rs
- src/tools/android/adb.rs
- src/tools/android/mod.rs
- src/tools/android/screen.rs
- src/tools/android/stuck.rs
- src/tools/android/types.rs
- src/tools/google.rs
- src/tools/hardware.rs

The ZeptoClaw system provides extensive capabilities for interacting with physical devices and mobile environments. This integration is split between the **AndroidTool** (for ADB-based mobile automation) and the **Peripheral System** (for direct hardware interaction with microcontrollers and single-board computers).

## Android Automation (AndroidTool)

The `AndroidTool` enables agents to perceive and control Android devices via the Android Debug Bridge (ADB). It supports high-level screen perception, coordinate-based interaction, and automated recovery from "stuck" states.

### Implementation and Data Flow

The tool interacts with the device by executing shell commands through an `AdbExecutor`. It translates high-level agent requests (e.g., "swipe up") into low-level ADB input events.

1. Screen Perception : Uses screencap to capture the current UI state.
2. Action Execution : Translates JSON arguments into input tap , input swipe , or input text commands.
3. Coordinate Sanitization : The parse_coordinates function src/tools/android/actions.rs 38-95 handles various input formats (arrays, strings, or concatenated integers) and validates them against a 0-10000 normalized range src/tools/android/actions.rs 118-126
4. Stuck Detection : Monitors for UI freezes or non-responsive applications to trigger recovery routines.

### Key Functions

- escape_adb_text : Escapes shell metacharacters like $ , ! , and & to ensure safe text entry via input text src/tools/android/actions.rs 15-30
- tap / swipe / scroll : Core navigation functions that wrap ADB shell calls src/tools/android/actions.rs 133-191
- type_text : Handles text input with character-level escaping src/tools/android/actions.rs 194-199

### Code Entity Space: Android ADB Integration

The following diagram maps the logical automation actions to the specific code entities responsible for executing them.

```

```

**Sources:** [src/tools/android/actions.rs1-205](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/android/actions.rs#L1-L205) [src/tools/android/adb.rs1-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/android/adb.rs#L1-L50)

## Hardware Peripheral Tools

ZeptoClaw supports direct interaction with microcontrollers (ESP32, Arduino, STM32 Nucleo) and Raspberry Pi GPIO/I2C buses. These are managed via the `Peripheral` trait [src/peripherals/traits.rs1-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/traits.rs#L1-L20)

### Architecture and Security

To prevent arbitrary system access, serial port paths are strictly validated. The `validate_serial_path` function [src/peripherals/mod.rs82-102](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/mod.rs#L82-L102) only allows paths starting with approved prefixes such as `/dev/ttyACM`, `/dev/ttyUSB`, or `COM`.

### Board Profiles

Every hardware interaction is validated against a `BoardProfile` [src/peripherals/board_profile.rs38-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/board_profile.rs#L38-L51) This ensures the agent does not attempt to toggle a reserved pin or access a non-existent I2C bus.

**Sources:** [src/peripherals/board_profile.rs79-114](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/board_profile.rs#L79-L114) [src/peripherals/mod.rs82-102](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/mod.rs#L82-L102)

### Serial Transport Protocol

For microcontrollers like Arduino and Nucleo, ZeptoClaw uses a newline-delimited JSON protocol over USB-CDC [src/peripherals/serial.rs1-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/serial.rs#L1-L5)

1. Request : {"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}
2. Response : {"id":"1","ok":true,"result":"done"}

The `SerialTransport` class [src/peripherals/serial.rs93-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/serial.rs#L93-L128) manages the `Mutex`-protected `SerialStream`, handling timeouts and response ID matching to ensure thread-safe hardware access.

### I2C and NVS Interfaces

- I2C Scan/Read/Write : Generic tools src/peripherals/i2c.rs 1-210 that work across all serial-connected boards. On Raspberry Pi, the RpiI2cScanTool uses native Linux /dev/i2c-N interfaces via the rppal crate src/peripherals/rpi_i2c.rs 30-105
- NVS (Non-Volatile Storage) : Supported on ESP32 for persistent key-value storage across reboots src/peripherals/nvs.rs 1-50

### Code Entity Space: Hardware Tool Pipeline

This diagram illustrates how a high-level tool request travels from the agent to the physical wire.

```

```

**Sources:** [src/peripherals/serial.rs93-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/serial.rs#L93-L128) [src/peripherals/i2c.rs68-86](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/i2c.rs#L68-L86) [src/peripherals/board_profile.rs67-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/peripherals/board_profile.rs#L67-L70)

## USB Device Discovery

ZeptoClaw includes a `HardwareTool` [src/tools/hardware.rs12-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/hardware.rs#L12-L24) for discovering connected devices.

### Discovery and Introspection

- USB Monitoring : On Linux, the system uses udevadm monitor to detect hotplug events src/devices/usb.rs 22-62
- Introspection : The introspect_device function src/hardware/introspect.rs 43-82 correlates serial paths (e.g., /dev/ttyACM0 ) with USB Vendor/Product IDs (VID/PID) to identify the specific board and its architecture.
- Memory Mapping : Based on the identified board, the system provides static memory map notes (e.g., Flash/RAM offsets for Nucleo boards) src/hardware/introspect.rs 85-98

**Sources:** [src/devices/usb.rs22-62](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/devices/usb.rs#L22-L62) [src/hardware/introspect.rs43-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/hardware/introspect.rs#L43-L82) [src/tools/hardware.rs80-155](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/hardware.rs#L80-L155)
