zclaw docs

chapter 2

Tool Surface

Tools are the execution boundary: model chooses calls, firmware enforces schema and executes side effects.

Built-In Tools

GroupToolsUse
Hardwaregpio_write, gpio_read, gpio_read_all, delay, i2c_scan, i2c_write, i2c_read, i2c_write_read, dht_readPins, timing-sensitive sensors, and generic I2C bus transactions (including one-call full GPIO state reads).
Memorymemory_set, memory_get, memory_list, memory_deletePersistent user state (u_* keys).
Schedulescron_set, cron_list, cron_deletePeriodic, daily, and one-shot jobs.
Clockget_time, set_timezone, get_timezoneTimezone-aware schedule behavior.
Systemget_version, get_health, get_diagnosticsFirmware version plus quick/scoped runtime diagnostics.
User toolscreate_tool, list_user_tools, delete_user_toolRuntime macro layer (no reflash). For firmware-coded tools, see Chapter 5.

Sensors and Bus Tools

zclaw now splits hardware access by protocol instead of forcing everything through raw GPIO. That keeps schemas clearer and gives firmware a place to enforce timing and validation.

  • dht_read is for dht11 and dht22 only. DHT uses a timing-sensitive single-wire protocol on one GPIO pin. It is not I2C.
  • i2c_scan finds responding 7-bit addresses on a chosen SDA/SCL pair.
  • i2c_write sends space-separated hex bytes to one 7-bit address.
  • i2c_read reads raw bytes from one 7-bit address.
  • i2c_write_read writes first, then reads from the same address. Use this for register reads.
{"sda_pin":8,"scl_pin":9,"address":118,"write_hex":"0xD0","read_length":1}
{"pin":5,"model":"dht22"}

Hex payload fields accept space-separated bytes such as 0xF4 0x2E. Tool JSON uses decimal I2C addresses, so 118 means 0x76.

Runtime Diagnostics

get_diagnostics extends get_health with scoped checks and optional verbose output.

  • scope: quick (default) for one-line status.
  • scope: runtime for uptime + boot/version context.
  • scope: memory for free/min/largest heap and fragmentation hint.
  • scope: rates for request counters.
  • scope: time for sync + timezone.
  • scope: all for a multi-line summary across categories.
  • verbose: true includes expanded details.
{"scope":"memory","verbose":true}

Natural-language prompts like “run diagnostics” or “show full diagnostics” should trigger this tool.

Chat Commands

CommandBehavior
/startShows local command help without calling the LLM.
/helpAlias of /start; returns local command help without calling the LLM.
/settingsShows local bot status (including paused/active intake state).
/stopPauses inbound message processing (used to stop spam loops).
/resumeRe-enables inbound message processing after /stop.

These commands work in Telegram and on the USB console. Hardware/admin commands live on the USB console only.

USB Local Admin Commands

CommandBehavior
/gpio [all|pin|pin high|pin low]Reads or drives tool-allowed GPIO pins locally without an LLM call.
/diag [scope] [verbose]Runs local diagnostics over USB, including in safe mode or while intake is paused.
/wifi statusShows provisioned SSID, driver/link state, IP, RSSI (when connected), and last disconnect reason.
/wifi scanRuns a local Wi-Fi scan and lists visible APs with RSSI, auth mode, and channel.
/bootcountShows persisted boot-failure count and safe-mode threshold state.
/rebootReboots the board immediately after sending a local acknowledgement.
/factory-resetShows the destructive warning and required confirmation syntax.
/factory-reset confirmErases NVS (credentials, schedules, memory, boot state) and reboots.

These commands are USB-local only. Telegram and web relay callers are rejected instead of falling through to the LLM path. See Chapter 8.

Schedule Grammar

cron_set accepts three schedule types:

TypeRequired InputsBehavior
periodicinterval_minutes, actionRepeats every N minutes.
dailyhour, minute, actionRuns at local device time daily.
oncedelay_minutes, actionRuns once after N minutes, then auto-removes itself.
 
{"type":"once","delay_minutes":20,"action":"check garage sensor"}

Scheduler resolution is minute-based. A one-shot fires on the next due cron scan.

User Tool Model

User-defined tools do not compile code. They store short action text that the model later translates into built-in tool calls.

You: Create tool "water_plants" to turn GPIO 5 on for 30 seconds then off
Agent internals:
1) create_tool(name="water_plants", action="Turn GPIO 5 on, wait 30 seconds, turn off")
2) Later invocation returns action text
3) Model executes via gpio_write + delay + gpio_write

Operational Boundaries

  • GPIO is constrained by configured safety policy.
  • DHT support is explicit and model-scoped today: use dht_read for DHT11/DHT22, not generic GPIO or I2C tools.
  • I2C bus access still uses the same GPIO safety policy for SDA/SCL pins.
  • Memory keys for user values must use u_ prefix.
  • Schedule action payload is bounded by CRON_MAX_ACTION_LEN.