Controlling the Robot:

Head & Waist Control

Recommended Control Pathways

Select the head and waist control pathway in the following priority order:

Pathway	Interface	Position & Usage Conditions
Recommended	ROS 2 /robot/command	Recommended for controlling the head and waist via the ROS 2 service. The service type is rm_robot_interfaces/srv/StringCmd; both the request and the response contain a single string data field.
Restricted	S100 TCP JSON (192.168.127.11:8080)	Low-level direct connection interface, not recommended for ordinary secondary development; if low-level integration is genuinely required, contact RealMan technical support for interface confirmation and safety review.

Service Type and Request Structure

The ROS 2 service type is rm_robot_interfaces/srv/StringCmd; both the request and the response contain a single string data field.

The request string MUST be parsed as a two-layer object: outer wrapper + inner payload.

• The outer device determines which control connection rm_aloha_slave uses;
• The inner device is used by the S100 to distinguish waist vs. head.

When controlling the waist, set both the outer device and payload.device to 2; when controlling the head, set both to 3. If the two values are inconsistent, the command may fail to route correctly or may not take effect.

Part Codes and Degrees of Freedom

device	Control Object	State Feedback	Example Safety Range
2	Waist (5 DOF)	body in /robot_slave/states	Max relative 0.2° per joint
3	Head (2 DOF)	head in /robot_slave/states	Max relative 3°

State Retrieval and Freshness

• position in /robot_slave/states is in 0.001° units; the current publishing frequency is approximately 2 Hz;
• Positions in /mcap/body are in radians and velocities in rad/s, with a nominal publishing period of 5 ms.

Note

Freshness MUST be determined jointly via timestamps, position deltas, and ros2 topic hz.

movej Motion Command

The current shape of the head/waist movej payload is shown below. Each J* MUST be replaced with an integer target freshly read back and validated against both drive limits and project safety ranges; historical postures are intentionally not included in the example:

{
  "device": 3,
  "payload": {
    "command": "movej",
    "joint": ["J1", "J2"],
    "v": 1,
    "r": 0,
    "trajectory_connect": 0,
    "device": 3
  }
}

• For waist motion, change both device values to 2 and use five joints;
• v, r, and trajectory_connect are mandatory fields of the current wrapper;

Stop Command

Stopping MUST use the same part code and include the deceleration fields.

{
  "device": 3,
  "payload": {
    "command": "set_stop_teach",
    "device": 3,
    "v": 5,
    "r": 0
  }
}

• For waist stopping, change both device values to 2;
• Any timeout means the result is unknown: stop once, read fresh state, and do NOT blindly resend stale targets.

Drive Limit Queries

The read-only drive limit commands are get_joint_drive_min_pos and get_joint_drive_max_pos; they also require identical outer and inner device values.

Limits MUST be re-read before every motion; hard-coded inheritance is not allowed.

Joint Teach

Joint teach is continuous motion and carries higher risk than point-to-point movej.

• teach_joint: joint index, not an angle;
• direction: string, "pos" (positive) or "neg" (negative), not an integer.

The message structure is set_joint_teach + teach_joint + direction + v + device.

Safety requirement: after teach starts, set_stop_teach MUST be sent explicitly in all scenarios — normal completion, timeout, exception, and connection loss; relying on TCP disconnection to automatically stop motion is prohibited.