---
title: Add a board or Linux device
description: Adapt the hardware-specific edge while reusing pairing, transport and the shared runtime.
---

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:

```sh
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](https://github.com/impoai/impo-gadget-sdk/blob/main/esp32/AGENTS.md) 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](https://github.com/impoai/impo-gadget-sdk/blob/main/linux/README.md) 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](https://github.com/impoai/impo-gadget-sdk/blob/main/esp32/components/impo/boards/README.md) is the source-level checklist.