ROS 2 Package Structure and Topic Description

This section describes the ROS 2 package structure and related topics for AI Sapiens.

Bringup Options

Coming Soon

Bringup option details will be added here.

Control Topic Description (Impedance Control Mode)

AI Sapiens uses a ROS 2 control controller configuration file to define the joint command order for Impedance Control Mode. The controller manager loads this YAML file at bringup time, and the joint_group_position_controller reads the joints list as the command array order.

For the AI Sapiens K1 configuration, the controller file is:

ai_sapiens_bringup/config/k1_rev1/k1_rev1_controllers.yaml

Controller YAMLk1_rev1_controllers.yamlDefines the joint order used by the controller.

Command MessageJointPositionGainsCommandPublishes position, feedforward torque, stiffness, and damping arrays.

Impedance Control Mode/joint_group_position_controller/commandsApplies each array value to the matching joint index.

When the controller is named joint_group_position_controller, its private command topic resolves to:

/joint_group_position_controller/commands

Each index in positions, feedforward, kp, and kd must match the same index in the YAML joints list. For example, index 0 commands left_hip_pitch_joint, index 1 commands left_hip_roll_joint, and so on.

Controller YAML

The controller manager receives the controller parameters from the bringup package. The important part for command indexing is the joints list under joint_group_position_controller.ros__parameters.

joint_group_position_controller:
  ros__parameters:
    # === Command array order (/joint_group_position_controller/commands JointPositionGainsCommand) ===
    joints:
      - left_hip_pitch_joint
      - left_hip_roll_joint
      - left_hip_yaw_joint
      - left_knee_joint
      - left_ankle_pitch_joint
      - left_ankle_roll_joint
      - right_hip_pitch_joint
      - right_hip_roll_joint
      - right_hip_yaw_joint
      - right_knee_joint
      - right_ankle_pitch_joint
      - right_ankle_roll_joint
      - waist_yaw_joint
      - left_shoulder_pitch_joint
      - left_shoulder_roll_joint
      - left_shoulder_yaw_joint
      - left_elbow_joint
      - left_wrist_roll_joint
      - right_shoulder_pitch_joint
      - right_shoulder_roll_joint
      - right_shoulder_yaw_joint
      - right_elbow_joint
      - right_wrist_roll_joint

Command Message

The command topic uses ai_sapiens_controller_msgs/msg/JointPositionGainsCommand.msg.

std_msgs/Header header

# Desired joint positions [rad]
float64[] positions

# Feedforward torque [N*m]
float64[] feedforward

# Position gains [N*m/rad]
float64[] kp

# Damping gains [N*m*s/rad]
float64[] kd

The four arrays are parallel arrays:

Field	Meaning
positions[i]	Desired joint position for joints[i] in $\mathrm{rad}$.
feedforward[i]	Feedforward torque for joints[i] in $\mathrm{N}\cdot\mathrm{m}$.
kp[i]	Position gain for joints[i] in $\mathrm{N}\cdot\mathrm{m}/\mathrm{rad}$.
kd[i]	Damping gain for joints[i] in $\mathrm{N}\cdot\mathrm{m}\cdot\mathrm{s}/\mathrm{rad}$.

All four arrays should have the same length as the configured joints list. If the array lengths or order do not match the controller YAML, commands may be applied to the wrong joint or rejected by the controller.

In short, the YAML file is the source of truth for joint indexing. Any node publishing JointPositionGainsCommand should build its arrays in exactly this order before sending commands to the impedance controller.