Skip to content

Connecting hardware

Drive a real robot with the same Robot class: Feetech buses, Unitree DDS and the microduck. Drivers, cameras, calibration, the digital twin and the operator gate.

A real robot is the same Robot class with a port=. A driver talks to the hardware. Pass twin=True and a digital twin shows it in simulation.

d04_twind04_twin

from strands_robots import Robot

real = Robot("so101", port="/dev/ttyACM0", twin=True, operator=lambda req: input(f"{req}? ") == "y")
real.calibrate(interactive=False)  # loads the LeRobot calibration file
obs = real.observe()               # measured joints, in radians
real.confirm_act({"gripper": 1.0}, seconds=1.5)
real.twin.sim.render()             # the twin shows the measured pose
real.close()                       # torque off, port closed

Drivers

Driver Hardware Support
feetech SO-100, SO-101 (STS3215 bus) Read, write, torque, calibrate
unitree G1, Go2, H1 over DDS Observe only
microduck The microduck's robotd socket Observe only
memory No hardware Writes are stored and read back

The registry picks the driver. Pass driver= to choose one. The twin is off by default, so a hardware-only install needs no MuJoCo. Pass twin=True to mirror the robot in Simulation.default() (needs the mujoco extra).

Try it without hardware

The memory driver acts like a real robot, so the gate and e-stop behave as they would on an arm.

from strands_robots import Robot

real = Robot("so101", driver="memory", operator=lambda req: True)
real.confirm_act({"shoulder_pan": 0.3})
print(real.body.writes)  # the targets that reached the "bus"

Driver options and cameras

Extra keywords go to the driver. The Feetech driver takes robot_id= and baud=. A misspelt option raises a TypeError that lists the valid ones.

A Feetech read asks each servo for its position only (2 bytes), as LeRobot does, so velocities and efforts are NaN. read_motion=True reads velocity and load too (6 bytes per servo on every read).

Name cameras by device name, not index. Indexes change when you plug in another camera.

cameras = {"front": "Logi 4K", "wrist": {"index": 1, "width": 640, "height": 480, "fps": 30}}

The dict keys are the image keys the policy sees. A camera that delivers a different size than asked is refused.

Robot(..., cameras=...) opens every camera at connect, all at once, and refuses a camera that cannot open or sends no frame within 10 s. Each camera then has its own capture thread, so a step takes each camera's latest frame without waiting for the device. A camera whose latest frame is more than 1 s old has stopped delivering: it is left out of the observation. arm.body.cameras.ages() gives the age in seconds of each frame the last step took. A step whose policy answers needs_observation() with False (a ChunkedPolicy replaying its chunk, say) takes no frame, as in simulation; the capture threads keep draining the cameras meanwhile. A recording or a stop_when still gets every step's frames.

A camera read through OpenCV (an index or a path) asks the device for compressed MJPEG by default, so 1280x720 at 30 fps fits a USB 2.0 camera. Pass fourcc="YUYV" (or None for the device's own codec) to change it. On macOS a named camera opens through AVFoundation, which picks the device's mode by size and rate. There, pixel_format (default "uyvy422"; "nv12" copies less) only sets the frames' format in memory. A size or rate the camera lacks is refused with the mode asked and the modes the camera has:

cameras = {"wrist": {"index": "/dev/video0", "width": 1280, "height": 720, "fps": 30, "fourcc": "MJPG"}}
# OSError: camera 'USB2.0_CAM1' refused 1280x720 @ 60 fps (uyvy422): Selected framerate (60.000000) is not
# supported by the device. Its modes: 640x480@30fps, 1280x720@10fps, 1280x720@30fps

d17_driver_optionsd17_driver_options

Calibration

Calibration is a Feetech bus's: the memory driver has none and takes no calibration=. calibrate(interactive=False) loads the LeRobot file from $HF_LEROBOT_CALIBRATION/robots/, matched by Robot(id=). Pass calibration="my_arm.json" to use any file. calibrate() with no arguments walks you through LeRobot's procedure at a terminal and saves the result. A Feetech calibration must fit the servo: range_min and range_max in 0..4095, homing_offset in -2047..2047 and drive_mode 0 or 1, or connecting raises ValueError naming the joint and the file. Each joint's span must also fit its limits: the driver maps the limits onto range_min..range_max, so a span covering more than 1.5× the counts the limits take on the servo (4096 a turn) is refused too, at connect and by calibrate() before it saves. A real SO-101 sits at 1.0–1.25×. extras() reports calibration (the file) and calibration_sha256 (a hash of its values) for the calibration in use.

The operator gate

Your own code calls act(). Agents, the dashboard, mesh peers and ROS topics call confirm_act(), which first asks your operator= function with a Move: the robot, the targets by joint name in the robot's units, who sent it (source: agent, dashboard, mesh or ros), the ramp time and, for a target outside safe, why it is asked. print(move) is one line. If the function returns false, nothing is written.

An agent's run() asks the same function once with a RunPlan (policy, files, rate, duration), not every step. Without operator=, a real robot refuses both. One function answers both; tell them apart with isinstance:

from strands_robots import Robot
from strands_robots.robot.run import Move, RunPlan

def operator(req: Move | RunPlan) -> bool:
    if isinstance(req, Move):
        return abs(req.targets["shoulder_pan"]) < 0.5  # small moves only
    return req.steps is not None and req.steps <= 300  # short runs only

arm = Robot("so101", driver="memory", operator=operator)
arm.confirm_act({"shoulder_pan": 0.3})  # asked with: move so101 from agent: shoulder_pan=0.300, ...

The safety chain still checks every step. When the policy is a checkpoint or dataset on this machine, the plan's files is the SHA-256 of the files the loader reads (a preset name stays a preset, even next to a same-named folder). The run then loads a private copy of those files, hashed while it is written: if they changed after the yes, the run is refused and moves nothing, and a later write to the originals never reaches the robot. The copy is removed when the run ends. The same holds for a checkpoint you registered as a policy object (tool(policies={"pick": Policy(dir)})): it reads its files when it attaches, so it loads the approved copy; your object is not changed. For a Hub checkpoint (owner/repo, as a spec or a Policy), files is owner/repo@<commit>, the commit its revision points to when you are asked, and the run loads exactly that commit even if the branch moves. If the commit cannot be looked up (offline), the run is refused before you are asked; pass revision= a full 40-character commit to need no lookup. A spec no agent may pass (a network address) is refused before you are asked.

d16_one_yes_per_rund16_one_yes_per_run

Every refusal raises RequestRefused. If a run faults, each joint goes to its declared on_disconnect state.

Timing

Each step of run() reads the bus once and writes once. A late step counts in RunResult.deadline_misses. Pass on_miss="fault" to stop the run at the first late step.

Between steps the run sleeps until 2 ms before the next one and spins the rest, because the operating system often wakes a sleeper a millisecond or two late (macOS more than Linux). The spin costs at most 2 ms of one core per step, and an e-stop still ends the wait at once. A robot built with its own clock= waits on that clock only.

Acceptance test

Run the hardware tests on a real SO-101:

STRANDS_SO101_PORT=/dev/ttyACM0 pytest tests_integ/acceptance

Without an arm, the tests skip. See Safety and e-stop for the e-stop.

Edit page