---
title: Commands, capabilities and events
description: Describe what a gadget can do, invoke it through the account boundary, and report what happens.
---

The device describes itself to the server in four parts. **Commands** are callable operations. **Capabilities** summarize the available hardware. **Events** report observations and explain their meaning. **Instructions** describe the device's purpose and how the agent should respond. The person's choices and the platform's permissions govern which actions are available.

## Register an exported interface

At connection, `link.register` carries the device's interface. Each command has a name, description and required/optional parameter definitions. This partial example describes a display and its button:

```json
{
  "commands_v2": {
    "display.show_text": {
      "description": "Show a short text caption on this display.",
      "required": {
        "text": { "type": "string", "description": "Caption text." }
      },
      "optional": {}
    }
  },
  "capabilities": {
    "screen": { "width": 240, "height": 240, "color": true },
    "buttons": true
  },
  "events": [
    { "name": "button_pressed", "description": "The person pressed the button to request their next meeting." }
  ],
  "instructions": "When the button is pressed, look up the next meeting in a connected calendar and show its title and time. If no calendar is connected, show that instead."
}
```

This is a partial registration example, not a complete handshake. The SDK fills the transport and device identity fields. Follow the [capability contract](https://github.com/impoai/impo-gadget-sdk/blob/main/CAPABILITIES.md) for each command's real limits.

`events` and `instructions` are optional. The gateway accepts up to 16 event descriptions, each at most 200 characters, and instructions up to 1,500 characters. Event names match `^[a-z_]{1,32}$`. It rejects a registration that exceeds those limits.

The gateway opens the gadget's Conversation with its maker instructions and event descriptions. Each event message includes its registered meaning when available. The maker does not configure a separate device prompt on the server. Keep each response bounded: one calendar lookup is more suitable than a long search, because later messages wait for the current turn.

## Implement a command

ESP32 board-specific commands use `impo_board_t.commands` and `impo_command_t` from `impo_commands.h`. Describe parameters, validate their values in the handler, and return a structured success or error. The handler runs on the Link session task and must not block it; long work needs the runtime's asynchronous pattern.

Use a board-specific command first when experimenting. Promote an operation to the shared vocabulary when multiple boards can implement the same semantics. Keep names and result meanings consistent across boards.

## Invoke through Impo

The agent first calls `impo_list_gadgets`, then selects a returned gadget and command. The server derives the account from the durable invocation, verifies that the device is owned and online, checks its registered command and calls the gateway.

The gateway sends `link.invoke`; the device responds with `link.result`. The server validates the tool envelope and command availability; the firmware handler validates the command-specific values. Registered parameter descriptions are not automatically enforced as a server-side JSON Schema. The application adapter withholds `system.*`, `link.*`, `device.ota` and `device.unpair` from model invocation.

`impo_gadget_command` uses `retry: 'never'` and a 30-second gateway command timeout. An offline device fails the request; there is no queue that replays the action when it reconnects. If transport fails after a movement or audio request, the outcome may be unknown. Report that uncertainty rather than assume the operation never ran.

## Emit an event

The control stream accepts `link.event` with an event name and data. For example, the event parameters for picking up a device can be:

```json
{
  "event": "picked_up",
  "data": { "orientation": "upright" }
}
```

Debounce sensor signals in the device. The gateway drops repeats of the same event name from the same gadget within three seconds while its in-memory guard is active. It retains the last 50 events per account route. This guard is not a durable deduplication or event-subscription system.

Events go to that gadget's continuing Conversation as events, with the registered event description when one exists; the app shows each as a thin line, not a message (`contracts/gadget-conversation.md`). They do not enter Main Chat. The agent may stay quiet about an event. For a gadget that registers `speaker.say`, the gateway also sends up to 1,000 characters of the reply to that command. A device without a speaker can use its other registered outputs when the agent calls them.

For an immediate fixed reaction, implement it in firmware: for example, play a local sound or change a light. A response that needs the person's context belongs in the Conversation. Saved user-created rules are still proposed.

The [proposed gadget-agent router](/docs/gadgets/gadget-agents/) would match structured events to saved behavior. That endpoint and subscription model are not available today.

## Verify the outcome you report

`speaker.say` can return an accepted/fetching state before audio finishes; use the speaker status contract to distinguish playback failure. A chassis command can prove that bytes were acknowledged without proving physical movement.

Test registration, malformed parameters, cross-account requests, offline devices, reconnects and unknown outcomes. Then verify the actual display, sound, sensor or actuator. Source references: the [server tool](https://github.com/impoai/impo/blob/main/server/src/tools/gadget-tools.ts) and [gateway device hub](https://github.com/impoai/impo/blob/main/server/gadget-gateway/device-hub.mjs).
