DocumentationHardware
Hardware and the Gadget SDK
Connect hardware that can talk, see, sense and act through your agent.
On this page
What a maker providesWhat exists todayBehavior: firmware, instructions or automationThe four ringsOne rule for authorityPick your pathA gadget is hardware connected to your agent: a display, microphone, speaker, camera, button, sensor or actuator. ESP32 firmware and the Linux Device SDK connect it to the Impo server. Each device describes its capabilities, commands, events and maker instructions, then exchanges messages and actions with its own Conversation.
The hardware SDK lives in impo-gadget-sdk. The API, worker and gateway live in impo. A board port belongs in the SDK; account policy belongs in the application platform.
What a maker provides#
- Capabilities and commands: what the hardware has and what it can do, such as capturing a photo, showing text or playing speech.
- Events and their meaning: what happened on this device, such as a button press or being picked up.
- Instructions: what the device is for and how the agent should respond, using the person's available connections.
These descriptions travel with the device. Adding a board or an ordinary command does not require a separate server definition for that device. The shared SDK handles its connection; the Impo server supplies agent execution and access to the person's connected services.
What exists today#
Gadgets pair to an account and exchange commands, results and events. The agent discovers the registered interface through impo_list_gadgets and calls impo_gadget_command. Hardware availability depends on the board and its firmware; listing a command is not proof that its physical result has been tested.
Each gadget has one continuing Conversation, represented by a Task in the Impo API. Its voice, text and events go there; the maker's instructions and event descriptions are the agent's context, not messages (contracts/gadget-conversation.md). The gateway creates the binding on first input or when the owner opens it in the app. It reuses that binding across reconnects. Person-initiated Main Chat requests stay in Main Chat, including photos returned by a requested camera command.
iOS provides Bluetooth setup. Android, Web and Mac hand off pairing to the Impo app for iPhone. After setup, sign in to the same account on any client to open the gadget's Conversation, see its connection and use Live. A connected gadget talks directly to the server. Mac's native computer tools are not registered through the gadget gateway.
Before pairing, explore the hardware catalog, project ideas and platform setup guides. Check each device's support status: entries marked “To review” have not been confirmed compatible with Impo, and project ideas are concepts to prototype.
An offline gadget fails a command now; the server does not save it for later playback or movement. The gadget's Conversation can still hold history and accept cloud-only work. Conversation separation does not create a new account or a per-gadget tool permission boundary.
Behavior: firmware, instructions or automation#
| Behavior | Where it belongs | Status |
|---|---|---|
| Immediate fixed reaction, such as a light or local sound | Firmware on the device | Implementable in the SDK today. |
| A response using personal context, such as the next calendar event | Maker instructions and the gadget's Conversation | Implemented, with the owner's available connections. |
| A user-created rule with saved triggers, budgets, allowed tools and run controls | Gadget-agent definition and runtime | Proposed. |
Maker instructions can already shape a response. They do not implement the separate saved-automation system below.
The four rings#
| Ring | Responsibility | Extension owner |
|---|---|---|
| 0 — Platform (kernel) | Agent, API, worker, dispatcher and gateway. Identity, permissions, routing and execution policy. | Platform maintainers. |
| 1 — Gadget agents | Persistent user behavior: triggers, allowed actions, instructions and state. Proposed. | Users with their agent, through validated creation tools. |
| 2 — Devices | Firmware, board adapters and exported commands, capabilities and events. | Makers and SDK maintainers. |
| 3 — Ecosystem | Product-specific skills and integrations for other devices. Impo's home-network tunnel is not implemented. | Integration authors. |
These are responsibility boundaries, not CPU protection levels. The four numbered layers are Impo's adaptation of the kernel/user-space idea discussed in the Dreamer interview, especially 21:55–23:23. They are not a claim about Dreamer's hardware architecture.
One rule for authority#
Ring 1 asks Ring 0 to act. It does not receive device administration credentials or bypass account policy. The same applies to a Ring 3 integration: a skill can explain an operation, but cannot grant permission to perform it.
Kernel mediation means server-enforced policy. It does not require a fresh main-chat model turn for every fixed action. The planned rules runtime can execute a validated action without calling a model.
Pick your path#
- Have hardware to support? Start with add a board or Linux device.
- Need a new operation or sensor event? Read commands and events.
- Want reusable, user-created behavior? Read the gadget-agent design.
- Connecting another product? Check ecosystem integrations and the current transport limits.
The SDK's architecture decisions describe the hardware/server interaction and extension points. The Gadgets design record covers the proposed automation layers. The SDK's capability vocabulary owns command names, parameters and results.