ROS 2 robots¶
A ROS 2 robot as a strands-robots Robot, the use_ros agent tool, and your own robot from a profile and a codec.
A ROS 2 robot becomes a normal hardware Robot, with the safety chain, e-stop, mesh and dashboard. What is robot-specific (topics, message types, QoS, joint ids, gains, what "armed" means)
lives in a JSON profile. Two are built in:
rclpy and the message packages come from your ROS 2 install (Humble or Jazzy), never from pip. Source the distro
and use a venv made with --system-site-packages. import strands_robots never imports rclpy.
Connect¶
from strands_robots import Robot, ros
arm = ros.connect("ros2_control", host="arm.local") # model from the robot's /robot_description
g1 = Robot("unitree_g1", driver="ros", released=True) # on the G1's Jetson, low-level /lowcmd at 500 Hz
host= is the robot's address: a zenoh router or a DDS peer.
A forward position controller's Float64MultiArray carries no joint names: each slot is the joint at that index of
the controller's joints parameter. connect reads it from /<controller>/get_parameters (or takes
command.joints from the profile) and refuses to stream when it is missing or is not exactly the model's joints.
Stream rules¶
One command stream owns the command topic. It sends on a timer (trigger: timer) or answers every sensor
frame (trigger: state). A late policy gets its last target repeated; no target for deadman_ms holds the
measured pose. It never damps. Writes are refused unless the profile's status.armed fields
hold. shadow=True builds every command, publishes none, and reports shadow_max_err against the profile's
shadow topic. kp/kd from Robot.set_gains or a policy's stiffness and damping go out with each command.
The use_ros tool¶
from strands import Agent
from strands_robots.ros import use_ros
agent = Agent(tools=[use_ros()])
agent("What topics are up? Echo /joint_states once.")
Reads are free. Every write needs an exact STRANDS_ROS_ALLOW entry or an operator's yes; the only free writes are
publishes to /rosout, /diagnostics and /visualization_marker[_array]. Targets known to move a robot (named in
the refusal) include velocity and joint command topics, ros2_control's /<controller>/commands, parameter writes
(set_param, which is gated as <node>/set_parameters, and the set_parameters[_atomically] services) and the
controller manager's switch_controller, load_controller, configure_controller, unload_controller and
set_hardware_component_state. A topic a Robot streams is always refused: use that robot's own tool.
record writes a timestamped bag under a directory you choose, use_ros(record_dir="~/bags"). The model never names
the path, and without record_dir the verb is off.
Your own robot¶
Put a profile in a directory on STRANDS_ROBOTS_ROS_PROFILES, or ship it in a package under the
strands_robots.ros_profiles entry point. If its messages are not sensor_msgs/JointState or Unitree's,
subclass Codec and point at it:
from strands_robots.robot.drivers.ros import Codec
class MyCodec(Codec): # profile: "codec": "my_robot.codec:MyCodec"
needs_gains = True
def read(self, frame): ... # -> JointState in action_keys order
def build(self, q, kp, kd, frame, sender): ... # -> the command message
Arming, id echo (command.echo) and the shadow comparison stay data in the profile.