ImpoDocs
Browse documentation

DocumentationHardware

Hardware and the Gadget SDK

Connect hardware that can talk, see, sense and act through your agent.

On this pageWhat a maker providesWhat exists todayBehavior: firmware, instructions or automationThe four ringsOne rule for authorityPick your path

A 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#

BehaviorWhere it belongsStatus
Immediate fixed reaction, such as a light or local soundFirmware on the deviceImplementable in the SDK today.
A response using personal context, such as the next calendar eventMaker instructions and the gadget's ConversationImplemented, with the owner's available connections.
A user-created rule with saved triggers, budgets, allowed tools and run controlsGadget-agent definition and runtimeProposed.

Maker instructions can already shape a response. They do not implement the separate saved-automation system below.

The four rings#

Ring 0 is the platform kernel, Ring 1 contains user-created gadget agents, Ring 2 contains devices, and Ring 3 contains ecosystem integrations. Gadget agents request actions through the kernel.

RingResponsibilityExtension owner
0 — Platform (kernel)Agent, API, worker, dispatcher and gateway. Identity, permissions, routing and execution policy.Platform maintainers.
1 — Gadget agentsPersistent user behavior: triggers, allowed actions, instructions and state. Proposed.Users with their agent, through validated creation tools.
2 — DevicesFirmware, board adapters and exported commands, capabilities and events.Makers and SDK maintainers.
3 — EcosystemProduct-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#

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.