Add a board or Linux device

Choose ESP32 for embedded hardware and the Linux Device SDK for a Raspberry Pi or other Linux host. Start from an existing supported device when possible. A board adapter is usually small, but a new panel, codec or sensor may also need a driver.

ESP32: build an existing board first#

The current SDK requires ESP-IDF v6.0.1, Python 3 and the board's build dependencies. Activate the supported ESP-IDF environment, then build the matching profile. For the ESP-SparkBot reference board:

git clone https://github.com/impoai/impo-gadget-sdk.git
cd impo-gadget-sdk/esp32
tools/impo/board.sh build sparkbot

Use the supported-board guide for the profile that matches your hardware. Flashing is a separate step, with the correct serial port and a backup appropriate to the device. Do not flash one board's image onto another.

The Impo gateway currently does not issue or require Muse-style SDK tokens. Follow the Impo fork's current gateway notes when upstream-derived instructions mention an mgst_ token. Account pairing credentials are still required.

Implement the board interface#

Board adapters live in esp32/components/impo/boards/. Start with the closest existing adapter and implement impo_board_t:

1. Record the vendor pin map, panel initialization and codec facts, with sources in comments.
2. Supply initialization, display and audio callbacks for hardware the board actually has.
3. Add button input, power readings and shutdown behavior where supported.
4. Register a camera backend if present. Export extra features and board commands through the existing interfaces.
5. Add the board to Kconfig, CMake, its devices/sdkconfig.impo-<board> overlay, the build/port helpers and supported-board documentation.

The shared runtime owns pairing, encrypted transport, captions, avatar behavior and common commands. A maker should not fork those subsystems just to assign a new GPIO.

Linux: extend the command executor#

Follow the Linux setup guide to install the service on a supported Bluetooth-capable host. Review the installer and choose the operating-system account deliberately; local commands run with that account's permissions.

Command declarations live in linux/src/impogadget/executor.py. Add a spec to COMMAND_SPECS and its validated execution branch in Executor.run. Return structured results and enforce timeouts.

The SDK includes commands that the Impo personal agent does not expose. For example, system.*, firmware replacement and unpair operations are withheld by the application adapter. A command's presence in Linux source is not permission for the model to call it.

Pair and inspect#

Use the native app's device setup flow to pair the hardware and configure its connection. Confirm that the registered gadget appears under the expected account and advertises only working commands and capabilities. Web is not a substitute for native BLE setup.

Inspect command results through the development or operator tools before relying on model selection. A device being online proves its connection; it does not prove that a motor has power or that a speaker played sound.

Verify on hardware#

Run the SDK's relevant host tests and board build, then exercise buttons, microphone, speaker, sensors and disconnect/reconnect behavior on the actual device. Check bounded motion and local stop behavior before enabling movement.

Keep build, simulator, protocol and physical results separate in the work log. The board porting guide is the source-level checklist.