agroiot

List Devices

List all relay devices for the customer whose contact phone matches. Returns device name, location, current state, and last-seen timestamp. Use this when the farmer asks "show me my devices" or "what can I control?".

Get Device State

Get the current state of one device. The `device` argument can be a device label (e.g. "Pump North") or a device_uid (e.g. "550e8400-e29b-41d4-a716-446655440000" — UUID v4). Returns the latest telemetry (relay state, signal strength, uptime) if the device has reported any. Returns has_state=False if no telemetry has arrived yet (the device hasn't booted or is offline).

Switch On

Turn a device's relay on. Accepts a device label or a device_uid. Use when the farmer says "turn on the pump" or "switch on the greenhouse light". The `relay` parameter selects which physical relay on a multi-relay device. 1-based, default 1. The backend validates that relay is in [1, device.relay_count]; a call targeting a relay the device doesn't have returns 422.

Switch Off

Turn a device's relay off. Accepts a device label or a device_uid. Use when the farmer says "turn off the pump" or "switch off the greenhouse light". The `relay` parameter selects which physical relay on a multi-relay device. 1-based, default 1.

List Command History

Recent commands commands for the customer. Useful when the farmer asks "what did I just do?" or for an audit log. `since` is an optional ISO 8601 timestamp.

Register Session

Register or update a chat session for the customer identified by phone. Call this when a new chat starts so the system has a mapping between the agent's session_id and our tenant. Returns a short confirmation string.

Touch Session

Mark an existing chat session as recently active. Useful as a keepalive so the system can tell which sessions are stale.

Provision Device

Register a new device against the customer's account. The device_uid: - If supplied (e.g. scanned from a QR sticker on the case): MUST be a UUID v4 string. Use it verbatim — the device's NVS already holds this exact UUID, baked at factory time, and the device will refuse to talk to the broker if its NVS UUID doesn't match the server row. - If None: a fresh UUID v4 is generated and returned in the response so the farmer can flash it into th

Update Device Label

Rename a device or set its location. Either `label` or `location` (or both) must be supplied. The `device` argument can be a device label (e.g. "Pump North") or a device_uid (UUID v4). The update is per-language; default is the farmer's chat language, typically 'en'. Use when the farmer says "rename Pump North to Field 3 Pump", "Pump North is in the north field, by the way", or "Pump North is in the greenhouse now".

Disable Device

Take a device out of the customer's PWA. Sets device.enabled=FALSE in the backend; the customer stops seeing this tile on their next refresh (within 30 seconds) and any in-flight command is rejected. Use when the farmer says "that pump is broken, take it offline", "I want to hide the spare relay from my family", or any time the device shouldn't be controllable. The customer can't undo this themselves — the device stays disabled until the agent (or an installer / admi

Enable Device

Re-enable a previously-disabled device. The customer sees the tile again on their next refresh (within 30 seconds). Use when the operator (or the agent, if it knows the issue is resolved) decides the device is healthy enough to put back in service — e.g. "Pump North is fixed, show it again" or after a firmware OTA completed. The `device` argument can be a label or a device_uid. If the device was never disabled this is a no-op at the SP layer (UPDATE device SET e

Enable Customer Api Key

Issue a new API key for the customer identified by phone. Returns a dict with `customer_api_key_id`, `api_key` (the plaintext bearer, returned ONCE), `customer_uid`, `label`, and `created_at`. The caller (the agent) must display `api_key` to the farmer in the chat and must not log it. The backend only stores the SHA-256 hash; the plaintext exists in this response payload only. Use when the farmer says "I want to use the AgroIoT app on my tablet", "give me an API

Disable Customer Api Key

Revoke a customer API key by its id. Idempotent: revoking an already-revoked key returns `already_revoked=true`. The key stops working immediately. Use when the farmer says "I lost my phone", "disable my old key", or "revoke the key for my old tablet". The agent should first call list_customer_api_keys (when that tool lands) to find the right id, then call this one.

Create Pwa Access Link

Issue a magic link the customer opens on the device they want to use as their AgroIoT controller. The link loads https://app.chaba.me and embeds a fresh customer-scoped bearer in the URL path. Opening it stores the bearer in that device's localStorage for future use. # !!! PROMPT patch — do not delete !!! USE THIS TOOL WHEN the farmer messages any of: - "give me access to the app" - "set me up on the tablet" - "I want to use the AgroIoT app" - "

List Customer Api Keys

List the API keys for the customer identified by phone. Returns a dict with three fields: - `customer_uid`: the customer these keys belong to - `key_count`: how many keys (active + revoked) - `keys`: array of key records, each with `customer_api_key_id`, `label`, `enabled`, `last_used_at`, `created_at`, `revoked_at`. NEVER hashes or plaintexts. Wrapped in a dict (not a bare lis

Rotate Customer Api Key

Rotate (regenerate) the customer's API key, soft-revoking the previous one with the same label. If `label` is omitted, the customer's most recently created active key is rotated. Returns a dict with `customer_api_key_id` (new), `api_key` (the new plaintext, returned ONCE), `old_customer_api_key_id`, `customer_uid`, and `created_at`. The new bearer must be displayed to the farmer immediately and never logged. Use when a key is suspected leaked (lost phone, etc.) or a

Create Customer

Onboard a new customer into the AgroIoT system from this WhatsApp conversation. # !!! PROMPT PATCH — do not delete !!! USE THIS TOOL WHEN: - A farmer messages and any call that resolves a phone to a customer (register_session, list_devices, switch_on, etc.) fails because the phone is not on file. - A farmer explicitly says "I want to use AgroIoT", "set me up", "sign me up", or any equivalent. DO NOT tell the farmer to sign up on a website, m

Update Customer Wireguard

Installer-driven update of a customer's WireGuard fields. Sets enabled=true (the tunnel is now up). USE THIS TOOL WHEN: - An installer finishes configuring a customer's MikroTik router and provides the WireGuard public/private keys, the MikroTik's host:port, and the tunnel CIDR block. - A rekey happens (operator rotated WireGuard keys on the MikroTik) and the database needs to be updated. The customer must already exist (call create_customer firs

Set Customer Timezone

Store the farm's timezone as an IANA name (e.g. 'Europe/Amsterdam', 'Africa/Nairobi', 'America/Bogota', 'UTC'). USE THIS TOOL WHEN the farmer answers a question about their location while setting up their first schedule ("what's your nearest city?" / "what country are you in?"), before calling create_schedule. Map their answer to the IANA name yourself — do not ask the farmer for an IANA name directly. All schedule times are LOCAL times in this zone. The backend

Create Schedule

Set a recurring schedule for a device relay: switch ON at on_time and OFF at off_time, LOCAL farm time, 'HH:MM' 24-hour format (e.g. on_time='06:00', off_time='18:00'). USE THIS TOOL WHEN the farmer says things like: - "water every day from 6 to 6" - "turn the pump on at 6am and off at 6pm" - "run the greenhouse light only on Tuesdays" Parameters: - device: device label (e.g. 'Pump North') or device_uid - relay: 1-based relay number, default 1

Run Device For Minutes

Switch a device relay ON right now and OFF again after `minutes` minutes. Use when the farmer says "run the pump for 20 minutes", "water for half an hour now", "turn it on for a bit". The off happens server-side, so it works even if the farmer's phone goes offline. Replaces any pending run-timer on the same relay. `device` is a device label or device_uid; `relay` is 1-based.

List Schedules

List the customer's schedules: recurring on/off windows and any pending run-timers, with each schedule's next on/off moments in UTC. Use when the farmer asks "what schedules do I have?", "when does the pump come on?", or before changing/deleting a schedule to confirm which one. Optional `device` label/uid filters to one device.

Delete Schedule

Permanently delete a schedule (recurring window or pending run-timer) by its schedule_id from list_schedules. USE WHEN the farmer says "cancel the schedule", "stop watering on Tuesdays", "remove the timer". The device itself stays controllable by hand.

Disable Schedule

Pause a schedule without deleting it (it keeps its definition; enable_schedule can turn it back on later). USE WHEN the farmer says "pause the watering for now", "skip the schedule while I'm fixing the pipes".

Enable Schedule

Resume a paused schedule (see disable_schedule).