Robots

Register a robot and connect its sensors and actuators to Servo.

A Servo robot record identifies one physical rig. Your robot application opens its hardware devices, applies local calibration, and manages motor bus communication. Servo executes policy models, validates camera frames and joint states across the network boundary, and streams validated joint targets back to your application.

Prerequisites

Before registering a robot with Servo, ensure you have:

1. A Calibrated Robot: Servo does not communicate directly with motor buses or perform joint zeroing. Calibrate your robot using your hardware driver’s normal bringup tools before connecting to Servo.
2. Local Configuration Files: Have the paths to your robot driver’s local configuration files on disk (for example, left and right arm configs).
   • Servo uses these files strictly to record a SHA-256 fingerprint (configuration_digest). Servo never parses, modifies, or uploads them.
   • If developing or testing without physical hardware, create two placeholder files:
     mkdir -p /opt/yam/configs
     echo "arm: left" > /opt/yam/configs/yam_left.yaml
     echo "arm: right" > /opt/yam/configs/yam_right.yaml
     
3. A Python Runtime Factory (open_yam): A zero-argument function in your robot application that opens and returns your calibrated RobotEnv (implementing get_obs(), step_command_only(joints), and close()). See Connect sensors and actuators for a complete reference implementation.

Bimanual YAM contract

servo robot catalog

Bimanual YAM
  Type: servo.yam.bimanual-joint-position.v1
  Cameras: top, left, right
  State values: 14
  Action values: 14
  Rate: 30 Hz

The state and action order is:

left joint 0..5, left gripper, right joint 0..5, right gripper

Each camera supplies a 360 × 640 RGB frame. Servo checks the role, color format, and dimensions, then prepares the frame for the selected model.

Register a physical robot

Run setup on the computer wired to the robot, passing the paths to your local configuration files:

servo robot setup yam-cell-01 \
  --config /opt/yam/configs/yam_left.yaml \
  --config /opt/yam/configs/yam_right.yaml \
  --region us-west-2 \
  --site sf-lab \
  --label line=assembly

--config accepts the hardware configuration files identified in the prerequisites. Pass the left arm configuration file first and the right arm configuration file second.

Servo reads their raw bytes and stores a SHA-256 digest (configuration_digest) to record an immutable hardware revision fingerprint. This allows Servo to detect if a physical arm’s zero-offsets or motor setup have changed without coupling Servo core to specific motor or driver tooling.

Bimanual YAM is the default type. Use --manifest for a custom robot.

Give every physical rig a unique name. Running setup again with the same name and type keeps its rob_* ID across process restarts, operating-system reinstalls, and robot-computer replacements. If the configuration changes, run setup again to record the new hash.

View the inventory from any signed-in computer:

servo robot list

yam-cell-01
  ID: rob_01...
  Type: servo.yam.bimanual-joint-position.v1
  Region: us-west-2
  Site: sf-lab

yam-cell-02
  ID: rob_02...
  Type: servo.yam.bimanual-joint-position.v1
  Region: us-west-2
  Site: sf-lab

Choose a model

Choose the model after registering the robot:

servo model list yam-cell-01

π0.5
  Slug: pi0.5
  Vendor: Physical Intelligence

MolmoAct2
  Slug: molmoact2
  Vendor: Allen Institute for AI

The list contains models that accept the registered camera roles, joint order, and action shape.

Connect sensors and actuators

Servo accepts a runtime factory from your robot application. A runtime factory is a zero-argument function that opens and returns the YAM RobotEnv:

import os

import servo
# Replace with the factory function defined in your robot application:
from my_robot_app import open_yam

sv = servo.Servo(
    base_url=os.environ["SERVO_BASE_URL"],
    api_key=os.environ["SERVO_API_KEY"],
)
robot = sv.robots.attach("yam-cell-01", runtime=open_yam)

Each call to open_yam() returns a YAM runtime instance implementing three methods:

• get_obs(): returns a dictionary containing camera frames and joint positions:
  • left_rgb, front_rgb, right_rgb: 360 × 640 RGB image frames as numpy.ndarray (uint8); and
  • joint_positions: 14 float values in radians (left arm joints 0..5, left gripper, right arm joints 0..5, right gripper).
• step_command_only(joints): applies a 14-value target array in radians to the motor controllers; and
• close(): releases the arms, cameras, and communication buses.

A minimal standalone reference implementation looks like:

from typing import Any
import numpy as np


class MinimalYamEnv:
    def get_obs(self) -> dict[str, Any]:
        return {
            "left_rgb": np.zeros((360, 640, 3), dtype=np.uint8),
            "front_rgb": np.zeros((360, 640, 3), dtype=np.uint8),
            "right_rgb": np.zeros((360, 640, 3), dtype=np.uint8),
            "joint_positions": np.zeros(14, dtype=np.float32),
        }

    def step_command_only(self, joints: np.ndarray) -> None:
        # Apply validated 14-dim joint target to hardware controllers
        pass

    def close(self) -> None:
        pass


def open_yam() -> MinimalYamEnv:
    return MinimalYamEnv()

Servo maps front_rgb to the registered top camera role, validates all three frames and the 14-value joint state, and passes validated 14-value targets to step_command_only. If your runtime loads local configuration files to configure its motor buses, pass those same files to servo robot setup so Servo can record their configuration fingerprint. Servo never passes files into the runtime; your robot application owns device discovery, camera role assignment, bus addresses, and controller setup.

The local controller enforces motor limits and emergency-stop behavior. Servo rejects malformed or expired action rows and enforces a measured action-jump limit when one exists for the selected model and robot.

Calibration

Concern	Owner
Motor offsets, limits, and controller setup	Robot application
Camera intrinsics, extrinsics, and physical role assignment	Robot application
Calibration procedure and schedule	Robot application
Camera names, joint order, units, dimensions, and rate	Servo robot contract
Model input and output validation	Servo

Calibrate the robot with its normal hardware tools before a Servo run. Servo treats calibration as a local precondition. Calibration files remain on the robot computer.

Add a custom robot

Generate a local integration package:

servo robot scaffold lab-arm --output ./lab-arm-servo
cd ./lab-arm-servo

The scaffold generates:

• servo-robot.json: Starts with type ID local.lab-arm.v1. Edit its camera roles, state axes, action axes, units, and control rate, then set status to ready.
• integration.py: Contains SensorSource and ActuatorSink drivers, plus a Configuration Pydantic model defining local settings (such as port: str).
• config.yaml: Create your local hardware config file containing device settings (for example, port: /dev/ttyACM0).

Validate the contract and install the local package:

servo robot validate ./servo-robot.json
pytest
pip install -e .

Register the physical robot with the generated manifest:

servo robot setup lab-arm-01 \
  --manifest ./servo-robot.json \
  --config ./config.yaml \
  --region us-west-2

--config records the cryptographic fingerprint of your local configuration file.

Open the installed integration from the robot application:

robot = sv.robots.attach(
    "lab-arm-01",
    manifest="./servo-robot.json",
    configuration={"port": "/dev/ttyACM0"},
)

The configuration dictionary passed to sv.robots.attach is validated against the Configuration schema defined in integration.py. Run sv.models.for_robot(robot) to list available hosted models. An empty list means no hosted model matches that robot type yet.