API Reference:
REST and Command Services TIP
The examples/ scripts referenced on this page are obtained through the delivery package provided via official delivery channels; use the delivery package version matching your software version. The paths shown in this document are for illustrating script structure only.
Common Contract
The base URL is http://$ROBOT_IP:9091, and all calls MUST use JSON POST. REST control interfaces are NOT verified in this manual to possess public-network-grade authentication, TLS, or rate limiting, and MUST NOT be exposed directly to the public Internet. Cross-host invocations must be routed via private LANs, ACLs, and approved secure proxies.
Responses must be parsed as JSON objects, and code MUST be the integer 200; booleans, string "200", or float 200.0 are NOT equivalent. Even when both HTTP status and business codes indicate success, motion execution results MUST be jointly determined via /robot_slave/states, /odom, error bit registers, and timeout flags. If a response is lost, the command result is classified as "Unknown Outcome"—execute a stop command and read back state immediately without blind retransmission.
INFO
The safety closed-loop for control Services is strictly fixed as follows:
Acquire exclusive control authority → Read current values and joint limits → Dispatch small-step, low-speed commands → Validate via state telemetry feedback → Issue target-body precise stop → Restore original values and execute secondary readback.
Neither an empty Service response nor a returned "Success" message constitutes evidence of motion completion.
REST API Index
| Endpoint | Key Request Payload | Response / Error Judgment | Stop Method | Telemetry Feedback Criteria | Units | Risk Level | Status |
|---|---|---|---|---|---|---|---|
/robot/version | {} | Integer code=200; data must be parsable with non-empty version fields | N/A | Model and SW/HW build versions align with Appendix Software Version Compatibility Matrix | String | Read-Only | Officially Released |
/joints/getJointLimit | {"device":N} | Strict code check; upper/lower limit array lengths match device DOFs | N/A | Intersect driver limits with software limits | Return values converted to degrees per endpoint definition | Read-Only | Officially Released |
/move/moveJ | {"device":N,"joint":[...],"v":1} | code=200 indicates request acceptance ONLY; timeouts/disconnects mean Unknown Outcome | /move/setArmStop using the identical device | position, joint_err, sys_err, and target-reached timeout | joint in 0.001°; v as speed profile index | Managed Risk | Officially Released |
/move/setArmStop | {"device":N} | Strict code=200; report to manual emergency stop channel on failure | Self-stopping for target body | Position remains stationary across two consecutive reads; no new error bits | N/A | Managed Risk | Officially Released |
/joints/setJointsEnable | device and joint selectors | Response does NOT imply safe device movement capability | Disable state or physical E-stop per plan | joint_en, error bits, and physical E-stop status | Boolean/Enum per official protocol spec | High Risk | Reference Only |
/joints/clearJointsErr / /robot/clearArmErr | {"device":N} | Error clearance success does NOT imply root cause resolution | Stop current body part | Error bits cleared to 0 and root cause resolved | N/A | High Risk | Reference Only |
/joints/setZeroJoints & Limit Write Endpoints | Parameters depend on target body | Immediate STOP on any non-200 code or readback mismatch | Physical E-stop / Body part stop | Pre-write snapshot, post-write readback, and verified rollback plan | Degrees/Encoders per endpoint specification | High Risk | Reference Only |
/robot/setRobotPower | Power channel and switch parameters | Response does NOT guarantee normal load power delivery | Execute approved reverse operation | RobotPower channel values, load status, and fault bits | 0.01 V encoded | High Risk | Reference Only |
Device indices are standardized in this manual as follows:
| device Index | Target Body Part |
|---|---|
0 | Left Arm |
1 | Right Arm |
2 | Waist |
3 | Head |
Customer wrappers MUST use enums instead of hardcoded magic numbers, and MUST validate degrees of freedom against Appendix Device Identifiers and Joint Limits.
/robot/command wrapper
The ROS 2 request definition for /robot/command contains only a single string field: data. Applications must first construct a outer JSON object containing the outer device index and inner payload, then serialize this entire object into the data string; payload is a valid JSON object prior to outer serialization, NOT an individually escaped nested string.
Head and waist movej calls MUST include an inner device index matching the outer index inside payload.
Flat JSON structures, inconsistent outer/inner device indices, incorrect array lengths, or head/waist movej calls missing trajectory_connect MUST NOT be judged as executed—even if the Service returns a response.
Outer device | Target Entity | payload Structure | Current Release Boundary |
|---|---|---|---|
0 | Left Arm | movej + 7 joint targets | Message structure reference only |
1 | Right Arm | movej + 7 joint targets | safe_staged_actuator_control.py opens single-joint relative motion up to 0.5° max, with set_arm_stop after homing |
2 | Waist | movej + inner device=2 + 5 joint targets | safe_staged_actuator_control.py opens single-joint relative motion up to 0.2° max, with set_stop_teach after homing |
3 | Head | movej + inner device=3 + 2 joint targets | Upper limit: relative 3° at speed level 1 |
1 (Current HW) | Right Single-DOF End-Effector | hand_follow_pos + single-element hand_pos | Relative increase capped at 50/1000 max, with set_rm_plus_ctrl_mode=0 after homing |
The example below uses symbolic target values to illustrate wrapper formatting shape; all-zero or historical pose copy-pasting is intentionally avoided:
{
"device": 3,
"payload": {
"command": "movej",
"joint": ["J1", "J2"],
"v": "V",
"r": 0,
"trajectory_connect": 0,
"device": 3
}
}During actual transmission, J1, J2, and V MUST be converted to valid integers validated against current positions, real-time limits, and project safety bounds, and MUST NOT remain as string literals. The outer object is serialized as a JSON string prior to assignment to StringCmd.data.
The current Python examples use set_stop_teach with the same device for head and waist, with payload containing v=5 and r=0; set_arm_stop for the right arm; and set_rm_plus_ctrl mode=0 for the right single-DOF end-effector. A false Service response, timeout, stale feedback, state error, or homing tolerance violation is judged as failure: do NOT re-send the previous motion target, and do NOT clear errors automatically.
The C++ sample in this document only constructs and displays the head wrapper, without executing real physical Service calls.
Dual arms, waist, and end-effector tools do NOT provide directly copyable ros2 service call examples until their respective stopping, homing, and state consistency acceptances are complete.
Unified Stop Criteria and Success Judgment
| Target Control Object | Stop Command | Mandatory Simultaneous Telemetry Conditions |
|---|---|---|
| Left Arm / Right Arm | POST /move/setArmStop with original device; direct path follows the corresponding robotic-arm protocol stop | Positions enter tolerance band; joint_err all 0s; sys_err=0; re-verify original values upon recovery |
| Waist / Head | Send set_stop_teach within the ROS2 wrapper, keeping inner and outer layers on the same device, with v=5 and r=0 | Two consecutive position readings show no continuing trend; joint_err all 0s; sys_err=0; returns to the current sample start point |
| Chassis | Stop active publisher on /teleop_cmd_vel or /cmd_vel; publish zero Twist continuously; invoke /StopMotor if approved in project plan | /odom.twist.twist velocities approach 0; pose coordinates remain stationary |
If non-zero error bits, telemetry timeouts, unparsable responses, or position trajectories moving outside safety limits occur, execute the corresponding stop procedure immediately, retain on-site diagnostic logs, and HALT further step execution.