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.
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.
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
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.
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:
Without an arm, the tests skip. See Safety and e-stop for the e-stop.
Edit page