Software Architecture
AI Sapiens K1 runs its robot software inside the ai_sapiens Docker container on the NVIDIA® Jetson Orin™ NX 16GB module. The base system uses Cyclo OS, a Yocto Project-based operating system, with ROS 2 Jazzy and rmw_zenoh_cpp for low-latency robot communication.
The control stack is built around ROS 2 control. High-level robot commands are converted into joint commands, passed through the ROS 2 controller manager, written to DYNAMIXEL-Q actuators over multiple RS-485 buses at 6 Mbps, and reported back through ROS 2 state topics.
Architecture Flow
Runtime Stack
| Layer | Role |
|---|---|
| NVIDIA® Jetson Orin™ NX 16GB | Onboard compute module for robot runtime, ROS 2 nodes, and policy execution |
| Cyclo OS | Yocto Project-based robot operating system |
ai_sapiens Docker container | Robot software container for the AI Sapiens ROS 2 stack |
| ROS 2 Jazzy | Robot middleware, node graph, topics, services, and ROS 2 control runtime |
rmw_zenoh_cpp | Default ROS 2 RMW layer for communication between robot-side nodes, containers, and external PCs |
External PC setup is documented separately in ROS 2 Communication. The sections below focus on the onboard software architecture.
Control Flow
The command path moves from a policy or user command down to the actuator bus:
ai_sapiens_sim2real produces robot joint commands from policy output, mode logic, and user command inputs. The joint_group_position_controller receives those commands and exposes them to dynamixel_hardware_interface through ROS 2 control command interfaces. The hardware interface uses DynamixelSDK to write position, feedforward torque, and impedance-control gains to the DYNAMIXEL-Q actuators.
State Flow
The feedback path moves from the robot hardware back into ROS 2:
DYNAMIXEL-Q actuators report present position, present velocity, and present current through the hardware interface. The HAT board and IMU board are also exposed through the same ROS 2 control hardware layer, so battery state, emergency-stop state, remote-controller channels, and IMU measurements can be published as ROS 2 topics.
ROS 2 Control Layer
AI Sapiens K1 uses controller_manager at a 1 kHz update rate. The controller layer includes:
| Component | Purpose |
|---|---|
joint_state_broadcaster | Publishes actuator position, velocity, and effort as /joint_states |
imu_sensor_broadcaster | Publishes IMU orientation, angular velocity, and linear acceleration |
ai_sapiens_rc_broadcaster | Publishes remote-controller input and RC link status from the HAT board state interfaces |
ai_sapiens_joint_group_position_controller | Receives joint position, feedforward, kp, and kd commands for impedance control mode |
dynamixel_hardware_interface | Bridges ROS 2 control command/state interfaces to DynamixelSDK |
DynamixelSDK | Handles packet communication with DYNAMIXEL-Q actuators and boards over RS-485 |
The controller command order is defined by the bringup controller configuration. For the detailed joint index map and command message definition, see ROS 2 Package Structure.
Main ROS 2 Interfaces
/joint_statesHardware to ROS 2sensor_msgs/msg/JointStateJoint position, velocity, and effort feedback.
/imu_sensor_broadcaster/imuHardware to ROS 2sensor_msgs/msg/ImuPelvis IMU orientation, angular velocity, and linear acceleration.
/joint_group_position_controller/commandsROS 2 to controllerai_sapiens_controller_msgs/msg/JointPositionGainsCommandJoint position, feedforward torque, and impedance-control gain command.
/ai_sapiens_rc/inputRC broadcaster to ROS 2sensor_msgs/msg/JoyNormalized remote-controller axes and buttons.
/ai_sapiens_rc/statusRC broadcaster to ROS 2ai_sapiens_rc_broadcaster/msg/AiSapiensRcStatusRC link, failsafe, and HAT-board status.
/cmd_velUser/API to runtimegeometry_msgs/msg/TwistVelocity command input for API-controlled behavior.
/ai_sapiens/request_mode_by_nameUser/API to runtimeai_sapiens_sim2real/srv/RequestModeByNameRequests a named robot control mode.
/ai_sapiens/list_modesUser/API to runtimeai_sapiens_sim2real/srv/ListModesLists available robot control modes.
/ai_sapiens/mode_statusRuntime to ROS 2ai_sapiens_sim2real/msg/ModeStatusCurrent mode and command authority status.