Connect new hardware

To connect a new robot, adapt its arm, parallel gripper, and wrist camera to the shared RoboAPI interfaces. The resulting hardware setup can use shared calibration, model calls, task execution, and the local console.

This guide follows a complete adapter project: generate the project, implement all three drivers, install and select the components, then calibrate and run the robot. Reuse existing components where suitable; the optional section at the end explains how to extend one component independently.

This guide is for developers integrating a vendor SDK. Prepare a Python environment, the vendor SDK, and device connection details. Install RoboAPI 0.4.5 in the environment that will run it and check the generator:

uv pip install 'roboapi==0.4.5'
roboapi new-embodiment --help

1. Generate an adapter projectCopy Anchor Link

Run this in the Python environment containing RoboAPI:

roboapi new-embodiment acme

The generated roboapi-acme/ directory is an independent Python project:

roboapi-acme/
├── pyproject.toml
├── README.md
└── src/roboapi_acme/
    ├── __init__.py
    ├── arm.py
    ├── gripper.py
    └── camera.py

Replace acme with your adapter name. Start with a lowercase letter and use lowercase letters, digits, hyphens, or underscores. The name must not conflict with a built-in name for a selected component. The command creates a directory and stops if it already exists.

The project includes registration entries, configuration classes, and driver interfaces. Generated driver methods raise NotImplementedError; implement the SDK calls before connecting hardware.

2. Implement the driversCopy Anchor Link

Add SDK dependencies to pyproject.toml and implement the corresponding files:

Keep devices disconnected when importing adapters, constructing configurations, and creating driver objects. Defer optional SDK imports and device access to explicit connection operations such as connect().

Arm control and feedback use the flange centre, with the same native base coordinates and flange axes. Supply native measurements; RoboAPI applies the calibration mapping. See Hardware adapter interfaces for signatures, units, and quaternion ordering.

If an arm and gripper share one CAN connection or SDK session, the adapter package owns the connection and coordinates targets and feedback. Separate component registration can still share a physical connection.

3. Install into the RoboAPI environmentCopy Anchor Link

After implementing the drivers, install into the same Python environment that runs RoboAPI:

uv pip install -e ./roboapi-acme

Use editable installation while developing the drivers. Restart RoboAPI after installation so it discovers the new entries.

The generator has already written the roboapi.arms, roboapi.grippers, and roboapi.cameras entry points in pyproject.toml. Discovery uses these entries directly.

4. Select components and configure devicesCopy Anchor Link

Create a separate configuration for the new hardware and provide addresses, device paths, and model credentials:

roboapi init -c ~/.config/roboapi-acme/config.yaml
roboapi http -c ~/.config/roboapi-acme/config.yaml

The wizard selects the arm, gripper, and camera in that order. Choose all three acme components or combine them with other installed adapters. The model Base URL defaults to https://api.pokebot.com/v1. Enter a key, connect, and select a model from the returned list. For a compatible custom service, enter its address. Keep the model service reachable during setup.

An adapter's configure() function provides questions for its own address, path, or credentials. Store passwords and keys through the wizard's credential-file helper.

An arm that needs external load data can register configure_tool() to collect the complete flange assembly's mass, centre of mass, and inertia. Controllers with their own dynamics model can handle loads as required by the driver. See Tool load for fields and callback behavior.

5. Calibrate and runCopy Anchor Link

Open http://127.0.0.1:8080/ on the control computer:

1. Check that the camera updates continuously and read-only arm feedback matches the measured position.
2. Open Settings → Devices → Coordinate calibration and capture Home and A/B/C.
3. Use the axis controls when native hand guiding is available; otherwise use the robot's own teaching controls. After Capture C, the browser returns Home, saves calibration, and initializes the devices.
4. Complete the direction checks. Confirm coordinates, gripper opening, and physical motion, then send a task from the local console.
5. Use Robot Stop to check stopping and holding. For a device fault, correct the condition before using recovery.

Recalibrate after changing the assembly, Home, or task axes. The arm should hold position while inference is pending. See Connection and runtime behavior for target updates, stopping, and recovery.

Distribute the adapterCopy Anchor Link

Package the adapter as an independent wheel for users to install into their RoboAPI environment. Declare the vendor SDK dependencies and supported RoboAPI version range in pyproject.toml, using a lower bound that actually contains the interfaces you use.

Document device models, controller requirements, connections, load configuration, and calibration. See Hardware adapter interfaces for the complete registration and device contracts.