About M7
Product Introduction
M7 is the latest half-body general-purpose humanoid robot developed by Robotera, featuring 42 degrees of freedom, the industry's top-notch motors with a maximum peak torque of 95 Nm and a peak speed of 4.20 rad/s, paired with a pair of dexterous hands with 12 active degrees of freedom, and combined with a powerful 275 TOPS platform computing power, it can implement multiple algorithms such as teleoperation, imitation learning, and large robot models, supporting AGI-oriented applications in research, industrial, commercial, and home scenarios.
Overview
the overall appearance of the robot is shown below.

Overall Robot Parameters
Technical Specifications
| M7 Specification Parameters | |
|---|---|
| Size | Upright dimensions: Base dimensions 632*632mm, height adjustable from 1713 to 1760mm |
| Total Arm Length | 717mm x 2 |
| Single-arm load: | 10Kg |
| Degree of Freedom | 42 (7 degrees of freedom per arm x 2, 2 degrees of freedom for the waist, 2 degrees of freedom for the neck, 12 degrees of freedom per dexterous hand x 2) |
| Overall Robot Weight | Approximately 70kg |
| End-of-arm velocity | 3m/s |
| Arm End Accuracy | 0.02mm |
| Control and perception capabilities | 80 TOPS(x86)+275 TOPS(Orin AGX) |
| Perception Sensor Configuration | Depth Camera Voice Module |
| Dexterous Hand | It has a human hand-like shape with 12 active degrees of freedom in a single hand |
| Communication Interface | Ethernet、USB 4.0、Wi-Fi 6、USB-C |
Joints and Motors

Joint Peak Torque and Speed Specifications:
| position | Peak torque (Nm) | speed (rad/s) |
|---|---|---|
| shoulder pitch | 95 | 4 |
| shoulder roll | ||
| arm yaw | ||
| elbow pitch | ||
| elbow yaw | 35 | 4 |
| wrist roll | ||
| wrist pitch | ||
| neck pitch | 35 | 4 |
| neck yaw | ||
| waist pitch | 184 | 4 |
| waist yaw |
Range of robot for each joint:
| Robot Parts | Corresponding joint angle range |
|---|---|
| arm | Shoulder pitch: ±160° Shoulder roll: -32°~145° Shoulder yaw: -250°~70° Elbow: -135°~40° Wrist yaw: ±160° Wrist pitch: ±45° Wrist roll: ±90° |
| Neck | Neck pitch: -10°~31° Neck yaw: -60°~60° |
| waist | Waist pitch: -10°~90° Waist yaw: -90°~90° |
Onboard Computing Resource Connection Diagram
The hardware and system specifications of the onboard computing resources are listed below:
| Computing Unit Name: | AMD Ryzen AI 9 HX 370 |
|---|---|
| CPU | 12-core |
| Memory | 32GB |
| Storage | 1TB SSD |
(Optional Jetson Orin AGX Module)
| Computing Unit Name: | Jetson Orin AGX 64GB |
|---|---|
| AI Performance | 275 TOPS |
| GPU | NVIDIA Ampere architecture GPU with 2,048 CUDA cores and 64 Tensor Cores |
| GPU Maximum Frequency | 1.3 GHz |
| CPU | 12-core Arm® Cortex®-A78AE v8.2 64-bit CPU, 3 MB L2 + 6 MB L3 |
| CPU Maximum Frequency | 2.2 GHz |
| System Memory | 64GB 256-bit LPDDR5 204.8GB/s |
Operation Guide
Unboxing and Power-On
Unboxing
The robot unboxing procedure typically includes the following steps:
- Check the packaging: Before opening the box, first check whether the packaging box is damaged to ensure that the product has not been damaged during transportation.
- Remove the items: Open the packaging case and remove the robot and its accessories one by one according to the instructions in this manual, including the power supply, tools, fixtures, and other accessories.
Connect to the robot
Locate the robot’s Wi-Fi SSID under the hip roll joint. The SSID is in the format: L_v3_BOTXX.
Search for “L_v3_BOTXX” in the available Wi-Fi networks and connect to the router inside the robot body.
Note: The 5G Wi-Fi network may take longer to appear.
The default Wi-Fi password is xbot123456.
Internal Fixed Address Modification Restriction: 192.168.8.100 is the internal fixed communication address of the robot, where the "8.100" segment is a preset fixed configuration and modification is prohibited; modification will result in abnormal robot communication and malfunction of functions.
Access the Robot Management Console
Open a browser and enter the following address: http://192.168.8.100:1888. This will open the robot control console, where you can view robot status, system information, and other related information.
Set an Access Password
Create a Password

The initial security settings interface of XOS, used to configure access passwords for the one-stop robot control center to ensure the permission security of the system and devices.
Two-Factor Authentication

The two-factor authentication settings interface of XOS further strengthens the access security of the robot control center, providing a second layer of protection for the system beyond passwords.
Homepage

View the overall robot status information on the home page to monitor the current robot status in real time.
The overall robot information is displayed as follows:
INIT: State after power-on startup.
IDLE: Robot hardware connection state.
READY: Robot initialization state.
ACTIVE: The robot is ready to accept tasks.
ERROR: The robot is in an error state.
Robot Model: Model of the current robot.
Dexterous Hand Model: Model of the dexterous hand installed on the current robot.
Robot SN: Serial number of the current robot.
NUC IP Address: IP address of the NUC in the current robot.
XOS Version: Current XOS version of the robot.
CPU Usage: Overall CPU usage curve.
Robot Simulation Model: Simulation model corresponding to the current robot model.
Real-time Error Information: If an alarm or error occurs, the corresponding joint in the robot simulation model will turn red.
Robot Overview
Log Management

- The log management module has systematic capabilities for log collection, storage, and visual display.
- The operation logs of each functional module can be classified and aggregated according to the system architecture hierarchy.
- Provide display and structured parsing functions through an interactive interface.
- Supports users to manually download the log files of specified modules according to business requirements, meeting the log management needs such as system debugging and problem tracing.
CPU Frequency Dashboard

- This function allows users to view the overall CPU frequency curve in real time. Through a graphical interface, it dynamically displays the trend of the aggregate frequency across all CPU cores over time. The horizontal axis represents time, and the vertical axis represents the frequency value in GHz. It supports real-time refresh, allowing users to monitor CPU performance fluctuations, analyze CPU frequency scaling behavior, and identify abnormal conditions.
- CPU: Supports selection of
cpu,cpu_max,cpu_min,cpu_avg, and individual CPU cores. Single selection, multiple selection, and select-all are supported. - Time Range: Supports querying data within a 24-hour time range.
- Reset: Resets the query filters on the page, including the selected CPU and time range. After clicking Reset, all query filters will be cleared.
- Refresh Control: Real-time refresh is enabled by default on the curve page. When disabled, the curve will stop refreshing. When enabled, the latest data will be retrieved in real time and plotted on the curve.
Abnormal State

- Supports real-time monitoring of abnormal operating states of each module of the robot, supports pop-up notifications and voice announcements, and can quickly locate and handle faults.
Core Features:
- Exception Notification: Supports two reminder methods, pop-up notification and voice broadcast, and is enabled by default.
- Exception List: Clearly displays the exception module, name, code, location, description, and level, facilitating quick identification of issues.
- Quick handling: Each exception provides a "View solution" entry, which directly jumps to the corresponding handling guide.
Operation Instructions:
- Turn notifications on/off
- Click the switch on the right side of "Pop-up Notification" or "Voice Broadcast" to toggle the on/off state.
- View exception details
- View key information such as the abnormal module, location, and level in the list.
- Exception levels are divided into: Fatal Error, Critical Error, Error, Warning, Prompt, Information.
- Handle exceptions
- Click "View Solution" in the action bar on the right side of the abnormal row to obtain the official handling steps.
Robot Management
Tone and Volume

- This function supports a volume adjustment range of 0–100%. Users can precisely control the robot's sound volume by sliding the adjustment bar or using the plus/minus buttons. By default, the system remembers the last settings parameters and automatically restores the user's preferred settings after restarting.
- Supports users to independently select the audio output device of the robot. The system will automatically scan and list the currently available sound card list (including built-in sound cards, external USB sound cards, etc.), and the output device can be quickly switched via the drop-down menu.
Robot Control Console
For detailed usage, refer toxviz 使用说明文档
Integrated Data Center

The XOS Robot Console – Integrated Data Center is a one-stop data visualization and simulation debugging platform designed for robot users. It supports real-time monitoring of operational data such as robot joint status, as well as fault diagnosis, data recording, and simulation validation. It provides end-to-end support for robot debugging, operation analysis, and issue localization.
Data Monitoring Center

The XOS Data Monitoring Center is a real-time visualization dashboard for robot operation data. It supports real-time acquisition and visualization of key data streams, such as joint status data, including arm and elbow joint positions, through line charts and other visual formats. This helps users intuitively monitor the robot’s operating status and quickly identify data anomalies and fluctuations.
Recording Center

- Enables flexible subscription to ROS topics, including XOS-specific topics, as well as custom recording and export by time range. It supports one-click quick export and precise time-range export, adapts to the XOS data format and the small-screen layout of portable devices, and simplifies data acquisition and export operations.
Simulation Center

XOS Simulation Center – Twin Mode links the robot’s real-world operating data with a virtual model in real time, enabling visual debugging and validation through virtual–real synchronization. It supports real-time mapping of joint states, motion trajectory replay, and physics-based simulation validation. This helps developers verify control logic, identify potential risks in advance, and improve debugging efficiency and safety.
Application Management

- This page allows users to upload, install, and launch system extension applications.
- Upload the compressed application package. The page supports both drag-and-drop upload and file selection from the system file browser. After the upload is complete, click Upload and Install to install the application.
- Once the installation is complete, the application will appear in the application list. Click the application to open it.
System Upgrade
- This function is used to manage the software versions of the robot system and the dexterous hand controller. It supports both cloud-based update checking and manual upgrade.
Version Information Display:
- Version Number: Displays the current system version, RobotOS.
- Version Details: Click Version Details to view the version number of each module.

Upgrade Package Acquisition Method:
- Cloud Detection:
- One-click to detect and obtain the latest version from the cloud server.
- Click the "Check for Updates" button, and the system will re-detect the latest version from the cloud.

- Download
Click the "Download Upgrade Package vX.X.X.X" button to start downloading, and deletion is supported during the download process.
- Manually upload the upgrade package
Supports uploading local upgrade packages for offline or specified version upgrades.

Upgrade
Pre-upgrade Checks
- The robot must be in a safe and stationary state.
- The robot will restart automatically during the upgrade. Do not operate the robot during this process.
After confirming that the above conditions are met, click Upgrade to vX.X.X to start the upgrade. Do not power off or operate the robot during the upgrade to avoid upgrade failure.
Upgrade Completion Judgment
- After the upgrade is initiated, the system will automatically perform the upgrade. When the interface displays Upgrade Completed, the current upgrade has been completed successfully. Do not power off the robot during the entire process.
Security Center
For specific usage instructions, please refer to说明书——XOS安全部分
Set Password

The Set Password function of the XOS Security Center supports users to update their login password (6-8 characters, letters or numbers), and can also turn off password protection to achieve flexible management of access rights to the Robot Control Center.
Authenticator Management

The Authenticator Management feature of XOS Security Center supports users in adding, renaming, and deleting TOTP verification devices, with a maximum of 5 devices that can be bound, facilitating users to flexibly manage backup devices for two-factor authentication and ensuring the security of system access.
Login History

The Login History feature of the XOS Security Center can display the latest 50 login records, including login IP, time, result, and client information, helping users trace access behavior and promptly detect abnormal login risks.
ROS-IP Management

ROS-IP Allowlist Managementfunction of XOS Security Center is used to configure trusted IP addresses for CycloneDDS communication, supports adding and deleting IPs, and only allows devices within the allowlist to communicate with the robot system, enhancing the security and controllability of ROS communication.
Firewall Management

The firewall management function of the XOS Security Center is used to manage the port allowing rules of the nftables INPUT chain, supports viewing system built-in rules and customs adding new rules, controls network port access of the robot system, and strengthens network security protection.
Robot Intranet teleoperation

Upload the teleoperation authorization file
- Upload the teleoperation authorization file. After successful upload and verification, the teleoperation function can be used.
- This page supports manual configuration of camera parameters.

Open the remote operation app
- Open the teleoperation app and enter the main page. The robot will start up, raises both arms after startup is completed, and enters the state of waiting to connect to VR devices.
- After the VR device is successfully connected, start remote operation via the Xingyao App.
- Click to exit remote operation, the page will return to xos, and the robot will exit the remote operation state.

Connect to MetaQuest
- Turn on the Meta Quest device and enter the system settings.
- Select the network connection method:
Wired Connection: Directly connect the Meta Quest to the robot via a data cable.
WiFi Connection: Find the WiFi corresponding to the robot, enter the password, and complete the connection.
- Find the "Xingyao App" icon in the Meta Quest app list, and click it to launch.
For detailed usage, refer to:星遥App软件使用说明
Robot Data Acquisition
星动数据管理平台使用说明
Emergency Stop
M7 provides an emergency stop remote control to promptly cut off power in case of unexpected situations, ensuring safety.
The following figure shows the emergency stop remote control:

Press the A button once to turn off the power of the onboard computer, and press it again to restore it
Press the D button once to turn off the power of the joint motor, and press it again to restore it
exclamation Important: Please ensure that the emergency stop remote control is ready during debugging. In an emergency, press the D button to cut power to the joint motors.
Development Guide
Overall robot software architecture

Joint Axis
SDK Call Instructions
M7 uses ROS2 Humble to interact with the entire machine. Developers can connect to the robot via wired/wireless networks, or communicate with the host system by logging into the developer container to write and run programs.
Ros2 domain: 211
If you wish to connect to the robot via another host for control:
- Connect to the robot via a wired connection or directly connect to the robot's WIFI
- Prerequisite: The host has a ros-humble + cyclonedds environment
- Messages used by the robot need to be deployed on its own host
git clone https://github.com/roboterax/teleop_client.git
cd teleop_client
colcon build
source install/setup.bash- Set environment variables
export ROS_DOMAIN_ID=211
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp- Configure unicast, and directly execute the following command on the host:
sudo mkdir /etc/xbot/
sudo tee /etc/xbot/cyclonedds.xml > /dev/null << 'EOF'
<?xml version="1.0"?>
<CycloneDDS xmlns="https://cdds.io/config">
<Domain id="211">
<General>
<AllowMulticast>false</AllowMulticast>
</General>
<Discovery>
<Peers>
<Peer address="127.0.0.1"/>
<Peer address="192.168.8.100"/>
</Peers>
<ParticipantIndex>auto</ParticipantIndex>
<MaxAutoParticipantIndex>300</MaxAutoParticipantIndex>
</Discovery>
</Domain>
</CycloneDDS>
EOF
export CYCLONEDDS_URI=file:///etc/xbot/cyclonedds.xml
ros2 daemon stop
ros2 daemon start- Set the ROSIP allowlist on Robot-XOSROSIP设置说明文档
- Simply add the host IP to the xos ros allowlist
- Jump directly to the
**Underlying Joint Control SDK **section
Robot Port Usage Specification
Port Usage Prohibited
Commonly used built-in ports for system reserved ports:
tcp dport { 22, 80, 443, 2222 } accept
tcp dport { 5555, 8888, 1688, 1788, 1888, 1988 } accept
tcp dport { 8765, 8080, 8090 } accept
tcp dport 1788-1888 accept
Developer Available Ports
Only:1024 ~ 65535
Enter the developer container
Username: developer
Initial Password: developer
Port Number: 2222
ssh developer@192.168.8.100 -p 2222 #SSH into the robot backend and enter the workspace.Underlying Joint Control SDK
Joint Control Process
flowchart TD
A[Check robot hardware status<br>(Confirm EtherCAT connection, joint power-on,<br>green power light is on)] --> B{Select mode}
B -->|Full-body mode (with XHAND)| C[Start low-level joint control service<br>/dynamic_launch<br>launch_mode: 'pos']
B -->|Full-body mode(without XHAND)| C2[Start low-level joint control service<br>/dynamic_launch<br>launch_mode: 'no_hand_pos']
C & C2 --> D[Initialize joint control service<br>/ready_service<br>(Wait about 20 seconds, interface returns success)]
D --> E[Move joints to standard start position<br>/simple_trajectory]
E --> G1[Enable control<br>/activate_service]
G1 --> H[Send joint control command<br>]
H --> I[Stop low-level joint control service<br>/stop_launch]
Overall Robot Joint Name
The joint list is as follows, and the overall structure refers to the product structure diagram
| Joint Name |
|----------------------------|
| left_shoulder_pitch_joint |
| left_shoulder_roll_joint |
| left_arm_yaw_joint |
| left_elbow_pitch_joint |
| left_elbow_yaw_joint |
| left_wrist_pitch_joint |
| left_wrist_roll_joint |
| neck_yaw_joint |
| neck_pitch_joint |
| right_shoulder_pitch_joint |
| right_shoulder_roll_joint |
| right_arm_yaw_joint |
| right_elbow_pitch_joint |
| right_elbow_yaw_joint |
| right_wrist_pitch_joint |
| right_wrist_roll_joint |
| waist_pitch_joint |
| waist_yaw_joint |
| XHAND Joint Name |
|------------------------------|
| left_hand_thumb_bend_joint |
| left_hand_thumb_rota_joint1 |
| left_hand_thumb_rota_joint2 |
| left_hand_index_bend_joint |
| left_hand_index_joint1 |
| left_hand_index_joint2 |
| left_hand_mid_joint1 |
| left_hand_mid_joint2 |
| left_hand_ring_joint1 |
| left_hand_ring_joint2 |
| left_hand_pinky_joint1 |
| left_hand_pinky_joint2 |
| right_hand_thumb_bend_joint |
| right_hand_thumb_rota_joint1 |
| right_hand_thumb_rota_joint2 |
| right_hand_index_bend_joint |
| right_hand_index_joint1 |
| right_hand_index_joint2 |
| right_hand_mid_joint1 |
| right_hand_mid_joint2 |
| right_hand_ring_joint1 |
| right_hand_ring_joint2 |
| right_hand_pinky_joint1 |
| right_hand_pinky_joint2 |Joint Control Instructions
Control Mode
The M7 system does not have lower limb, upper limb support including the waist torque control mode and position control mode. Differentiated by different startup methods
Under different startup modes
- For joints with torque control, only the following parameters can be set:
- velocity: Joint target velocity
- position: Joint target position
- feedforward: Feedforward force
- kp: Proportional Gain
- kd: Differential Gain
- For joints with position control, only the position (target position of each joint) parameter needs to be set. The remaining parameters include:
- velocity: Joint target velocity
- feedforward: feedforward force or torque
- kp: Proportional Gain
- kd: Differential Gain
The above parameters do not take effect in position control mode. Please ensure that only the position field is filled to avoid redundant data or misuse of the interface.
Control Frequency
The joint control frequency of L3 can reach 500Hz, and the control frequency of the dexterous hand is 83Hz (serial data)
Brake
The robot is equipped with a brake mechanism at the joints in the pitch and yaw directions of the waist.
- When entering position control mode, the brakes of these joints will automatically release, allowing the joints to move freely; when the control ends or the system is powered off, the brakes will automatically close to ensure the posture safety and mechanical stability of the robot in the non-control state.
- Before entering the PD mode, the brake needs to be manually released. The command to release the brake is as follows:
# Release brake
ros2 service call /control_brake xbot_common_interfaces/srv/SetJointIntegerParam "joint_name: ['waist_pitch_joint']
param_value: [1]"
ros2 service call /control_brake xbot_common_interfaces/srv/SetJointIntegerParam "joint_name: ['waist_yaw_joint']
param_value: [1]"
# Engage brake
ros2 service call /control_brake xbot_common_interfaces/srv/SetJointIntegerParam "joint_name: ['waist_pitch_joint']
param_value: [0]"
ros2 service call /control_brake xbot_common_interfaces/srv/SetJointIntegerParam "joint_name: ['waist_yaw_joint']
param_value: [0]"This mechanism does not require manual intervention from users, is automatically managed by the system, and is applicable to scenarios of normal start-stop and abnormal power outage.
Underlying joint control interface
1. Joint Control Command Interface
| Interface Name | Type | Function Description | Message Type |
|---|---|---|---|
/hybrid_body_controller/commands | ROS2 Topic | Issue joint control commands | xbot_common_interfaces/msg/HybridJointCommand |
xbot_common_interfaces/msg/HybridJointCommandParameter Description:- header: Standard message header (including timestamp and frame_id)
- joint_name: string[], list of joint names, corresponding to each control joint
- position: float64[], target position (rad) of each joint
- velocity: float64[],target velocity (rad/s) for each joint
- feedforward: float64[], feedforward force or torque (N·m)
- kp: float64[], proportional gain for each joint
- kd: float64[], current force/torque of differential gain for each joint
2. Hand Joint Control Command Interface
| Interface Name | Type | Function Description | Message Type |
|---|---|---|---|
/hand_controller/commands | ROS2 Topic | Issue joint control commands | xbot_common_interfaces/msg/HybridJointCommand |
xbot_common_interfaces/msg/HybridJointCommandParameter Description:- header: Standard message header (including timestamp and frame_id)
- joint_name: string[], list of joint names, corresponding to each control joint
- position: float64[], target position (rad) of each joint
- velocity: float64[],target velocity (rad/s) for each joint
- feedforward: float64[], feedforward force or torque (N·m)
- kp: float64[], proportional gain for each joint
- kd: float64[], current force/torque of differential gain for each joint
3. Joint Status Interface
| Interface Name | Type | Function Description | Message Type |
|---|---|---|---|
/joint_states | ROS2 Topic | Publish joint state command | sensor_msgs/msg/JointState |
sensor_msgs/msg/JointStateParameter Description:- header: Standard message header (including timestamp and frame_id)
- name: string[], all joint names
- position: float64[], target position (rad) of each joint
- velocity: float64[],target velocity (rad/s) for each joint
- effort: float64[], joint torque (N·m)
4. Hand Sensor Status Interface
XHAND
| Interface Name | Type | Function Description | Message Type |
|---|---|---|---|
/hand_sensor | ROS2 Topic | Publish joint state command | xbot_common_interfaces::msg::XhandHandSensor |
xbot_common_interfaces::msg::XhandHandSensorParameter Description:- header: standard message header (including timestamp and frame_id)
- hand_type: string[], hand type
- fx: int8[], force in the x direction of the fingers, unit 0.1 N
- fy: int8[], force in the y direction of the fingers, unit 0.1 N
- fz: int8[], force in the z direction of the fingers, unit 0.1 N
- temperature: uint8[], finger temperature, degrees Celsius
- calc_temperature: uint8, calculated temperature, degrees Celsius
Each Sensor contains 121 groups of fx, fy, and fz data: the first group is the resultant force, and the remaining 120 groups are component forces arranged as 10 * 12.
There are 5 Sensors in total, with IDs 0x11, 0x12, 0x13, 0x14, and 0x15.
Example of Low-Level Joint Control
Control via the command line
The joints of the M7 robot use EtherCAT for communication, so please confirm the robot's hardware status before starting. Currently, the M7 supports the following modes:
# Full-body configuration with both left and right XHAND — position mode
launch_mode: 'pos'
# Full-body configuration without XHAND — position mode
launch_mode: 'no_hand_pos'
# Full-body configuration with both left and right XHAND — torque mode
launch_mode: 'pd'
# Full-body configuration without XHAND — torque mode
launch_mode: 'no_hand_pd'Taking the example of starting a full-body form with two XHANDs (left and right), the startup script is as follows:
# SSH into the robot backend and enter the workspace
ssh developer@192.168.8.100 -p 2222
# Source message definitions
git clone https://github.com/roboterax/teleop_client.git
cd teleop_client
colcon build
source install/setup.bash
# Start joint service
ros2 service call /dynamic_launch xbot_common_interfaces/srv/DynamicLaunch "app_name: ''
sync_control: false
launch_mode: 'pos'"
# Initialize joint modules (this process takes about 20 seconds, M7 full robot joints use Et)
ros2 service call /ready_service std_srvs/srv/Trigger {}
# Set joints to the standard initial position (this process takes about 4 seconds)
ros2 action send_goal /simple_actions xbot_common_interfaces/action/SimpleActions "{action_name: 'initpose_handsdown', time_cost: 4.0}"
# Lift forearms
ros2 action send_goal /simple_actions xbot_common_interfaces/action/SimpleActions "{action_name: 'lift_up', time_cost: 4.0}"
# Xhand: both hands slightly close (note: must execute the previous step to raise the arms first)
ros2 topic pub /hand_controller/commands xbot_common_interfaces/msg/HybridJointCommand "header:
stamp:
sec: 0
nanosec: 0
frame_id: ''
joint_name: ['left_hand_thumb_bend_joint', 'left_hand_thumb_rota_joint1', 'left_hand_thumb_rota_joint2', 'left_hand_index_bend_joint', 'left_hand_index_joint1', 'left_hand_index_joint2',
'left_hand_mid_joint1', 'left_hand_mid_joint2', 'left_hand_ring_joint1', 'left_hand_ring_joint2', 'left_hand_pinky_joint1', 'left_hand_pinky_joint2',
'right_hand_thumb_bend_joint', 'right_hand_thumb_rota_joint1', 'right_hand_thumb_rota_joint2', 'right_hand_index_bend_joint', 'right_hand_index_joint1', 'right_hand_index_joint2',
'right_hand_mid_joint1', 'right_hand_mid_joint2', 'right_hand_ring_joint1', 'right_hand_ring_joint2', 'right_hand_pinky_joint1', 'right_hand_pinky_joint2']
position: [0.5, 0.5, 1.0, 0.3, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
0.5, 0.5, 1.0, 0.3, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
velocity: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
feedforward: [350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0,
350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0]
kp: [100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0]
kd: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]"
# Enable algorithm control permission
ros2 service call /activate_service std_srvs/srv/Trigger {}
# Read joint information
ros2 topic echo /joint_states --once
# Stop the low-level joint control service
ros2 service call /stop_launch std_srvs/srv/Trigger {}Python example code:
import rclpy
from rclpy.node import Node
from xbot_common_interfaces.srv import DynamicLaunch, SwitchController
from std_srvs.srv import Trigger
from xbot_common_interfaces.action import SimpleActions
from rclpy.action import ActionClient
from sensor_msgs.msg import JointState
from xbot_common_interfaces.msg import Imu
import time
class RobotStartupDemo(Node):
def __init__(self):
super().__init__('robot_startup_demo')
# Service clients
self.dynamic_launch_cli = self.create_client(DynamicLaunch, '/dynamic_launch')
self.ready_service_cli = self.create_client(Trigger, '/ready_service')
self.activate_cli = self.create_client(Trigger, '/activate_service')
self.stop_launch_cli = self.create_client(Trigger, '/stop_launch')
# Action client
self.simple_actions_client = ActionClient(self, SimpleActions, '/simple_actions')
# State reading related
self.joint_state_sub = None
self.imu_sub = None
self.joint_state_msg = None
self.imu_msg = None
def call_service(self, client, request):
future = client.call_async(request)
rclpy.spin_until_future_complete(self, future)
return future.result()
def wait_for_services(self):
self.get_logger().info('Waiting for services...')
self.dynamic_launch_cli.wait_for_service()
self.ready_service_cli.wait_for_service()
self.activate_cli.wait_for_service()
self.stop_launch_cli.wait_for_service()
def send_simple_action_goal(self, action_name: str, time_cost: float) -> bool:
goal_msg = SimpleActions.Goal()
goal_msg.action_name = action_name
goal_msg.time_cost = time_cost
self.simple_actions_client.wait_for_server()
send_goal_future = self.simple_actions_client.send_goal_async(goal_msg)
rclpy.spin_until_future_complete(self, send_goal_future)
goal_handle = send_goal_future.result()
if not goal_handle or not goal_handle.accepted:
self.get_logger().error(f'SimpleActions goal was not accepted: {action_name}')
return False
get_result_future = goal_handle.get_result_async()
rclpy.spin_until_future_complete(self, get_result_future)
return True
def run_startup_sequence(self):
self.wait_for_services()
# 1. Start joint service
self.get_logger().info('Starting joint service...')
dyn_launch_req = DynamicLaunch.Request()
dyn_launch_req.app_name = ''
dyn_launch_req.sync_control = False
dyn_launch_req.launch_mode = 'pos'
self.call_service(self.dynamic_launch_cli, dyn_launch_req)
# 2. Initialize joint modules
self.get_logger().info('Initializing joint modules...')
self.call_service(self.ready_service_cli, Trigger.Request())
time.sleep(20) # As suggested by documentation, can be optimized in real deployment
# 3. Set joints to the standard initial position (takes about 4 seconds)
self.get_logger().info('Sending SimpleActions: initpose_handsdown')
if not self.send_simple_action_goal('initpose_handsdown', 4.0):
return
# 4. Enable algorithm control permission
self.call_service(self.activate_cli, Trigger.Request())
# 5. Read joint information
self.get_logger().info('Reading one joint state message...')
self.joint_state_msg = None
self.joint_state_sub = self.create_subscription(
JointState, '/joint_states', self.joint_state_callback, 10
)
self.wait_for_msg('joint_state_msg')
# 6. Read IMU information
self.get_logger().info('Reading one IMU message...')
self.imu_msg = None
self.imu_sub = self.create_subscription(
Imu, '/imu_feedback', self.imu_callback, 10
)
self.wait_for_msg('imu_msg')
# 7. Stop low-level joint control service
self.get_logger().info('Stopping low-level joint control service...')
self.call_service(self.stop_launch_cli, Trigger.Request())
self.get_logger().info('Process finished.')
def joint_state_callback(self, msg):
if self.joint_state_msg is None:
self.joint_state_msg = msg
self.get_logger().info(f'Received joint state: {msg}')
self.joint_state_sub.destroy()
def imu_callback(self, msg):
if self.imu_msg is None:
self.imu_msg = msg
self.get_logger().info(f'Received IMU data: {msg}')
self.imu_sub.destroy()
def wait_for_msg(self, attr_name, timeout=5.0):
start = time.time()
while getattr(self, attr_name) is None and rclpy.ok():
if time.time() - start > timeout:
self.get_logger().warning(f'{attr_name} timeout while waiting')
break
rclpy.spin_once(self, timeout_sec=0.1)
def main(args=None):
rclpy.init(args=args)
node = RobotStartupDemo()
node.run_startup_sequence()
node.destroy_node()
rclpy.shutdown()
if __name__ == '__main__':
main()Machine Zeroing
- Remove the calibration tooling and secure the machine to the calibration tooling according to the calibration tooling specification
- After confirming the completion of the robot installation on the calibration fixture, start the machine e
# SSH into the robot backend and enter the workspace
ssh developer@192.168.8.100 -p 2222
# Start joint service in PD mode
ros2 service call /dynamic_launch xbot_common_interfaces/srv/DynamicLaunch "app_name: ''
sync_control: false
launch_mode: 'pd'"
# Initialize joint modules (this process takes about 20 seconds)
ros2 service call /ready_service std_srvs/srv/Trigger {}
# Call zero-position calibration service
ros2 service call /set_zero_pos std_srvs/srv/Trigger {}
# After receiving True, stop the low-level joint control service
ros2 service call /stop_launch std_srvs/srv/Trigger {}
# Use the emergency stop remote controller and press the "D" button twice to power cycle the joints
# Start joint service again
ros2 service call /dynamic_launch xbot_common_interfaces/srv/DynamicLaunch "app_name: ''
sync_control: false
launch_mode: 'pd'"
# Initialize joint modules (this process takes about 20 seconds)
ros2 service call /ready_service std_srvs/srv/Trigger {}
# Verify calibration result
ros2 topic echo /joint_states
# Check the position values; if the absolute value is less than 0.02, the calibration is successful;
# otherwise, check whether the joint positions are correctly in place, and after confirming, repeat the above stepsUpper-level Control SDK
Note: The operation of the upper-level control SDK depends on the lower-level control. Please complete the underlying joint control service first before invoking the upper-level control.
MPC Interface Description
exclamation When using this interface, please follow the following steps and precautions to ensure the stability and security of the operation:
- Read the current pose: Before sending control commands, the current pose of the robotic arm should be read first to serve as the starting point for trajectory control.
- Gradually approach the target: It is recommended tocontinuously send target poses in small incrementsto gradually guide the robotic arm to the target position.
- Avoid sudden movements: Please avoid sending large pose changes at once. Rapid or large-scale movements may cause instability in the robotic arm's motion or safety risks related to robot posture or motion.
- It is recommended to combine with trajectory planning: This interface is suitable for continuous control. It is recommended to combine with an external trajectory generator or smoothing algorithm to improve control accuracy and safety.
1. servoPose Interface
| Interface Name | Type | Function Description | Message Type |
|---|---|---|---|
/servo_poses | ROS2 Topic | Control the target poses of the left and right hands | xbot_common_interfaces/msg/ServoPose |
ServoPose.msgincludes three fields:- geometry_msgs/PoseStamped left_pose
- geometry_msgs/PoseStamped right_pose
- geometry_msgs/PoseStamped head_pose
geometry_msgs/PoseStampedStructure:- std_msgs/Header header
- geometry_msgs/Pose pose
2. getPose Interface
| Interface Name | Type | Function Description | Message Type |
|---|---|---|---|
/get_pose | ROS2 Topic | Get the current poses of the left and right hands | xbot_common_interfaces/msg/ServoPose |
ServoPose.msgincludes two fields:- geometry_msgs/PoseStamped left_pose
- geometry_msgs/PoseStamped right_pose
- geometry_msgs/PoseStamped head_pose
geometry_msgs/PoseStampedStructure:- std_msgs/Header header
- geometry_msgs/Pose pose
Use MPC
exclamation Upper limb control is a control program designed for operations on the waist, head, and both arms, precisely controlling the arm end-effector to a set position through dynamic means. If you need to use it, please first start the robot up to the step of "initializing joint modules" and then continue.
Use via command line
# SSH into the robot backend and enter the workspace
ssh developer@192.168.8.100 -p 2222
# Start robot joint motors via the lower-level SDK
# Move the robot to the zero position
# Omitted here, please refer to the low-level joint control section
# Enable algorithm control permission
ros2 service call /activate_service std_srvs/srv/Trigger {}
# Download l3_pub_client.py for starting MPC
git clone https://github.com/roboterax/teleop_client.git
cd teleop_client
colcon build
cp ~/teleop_client/l3_pub_client.py ~/
cd ~/
# Start MPC algorithm
python l3_pub_client.py --type mpc --cmd start
# Check MPC status; status=1 means started, 0 means not started
python l3_pub_client.py --type mpc --cmd query
# Reset MPC; mode 0 lifts the arms
# --mode 0 is also the robot's initial position after enabling MPC
python l3_pub_client.py --type mpc --cmd reset --mode 0
# Use ROS command to control arm lifting independently
# The value after -r indicates the message publishing frequency; -r 100 means 100Hz, which controls the speed
ros2 topic pub -r 20 /servo_poses xbot_common_interfaces/msg/ServoPose "{
left_pose: {
header: {frame_id: 'base_link'},
pose: {position: {x: 0.425, y: 0.3, z: 0.292}, orientation: {x: 0.612, y: -0.016, z: 0.79, w: -0.006}}
},
right_pose: {
header: {frame_id: 'base_link'},
pose: {position: {x: 0.417, y: -0.146, z: 0.382}, orientation: {x: 0.521, y: 0.1, z: 0.842, w: -0.096}}
},
head_pose: {
header: {frame_id: 'base_link'},
pose: {position: {x: 0.0, y: 0.0, z: 0.0}, orientation: {x: 0.0, y: 0.0, z: 0.0, w: 1.0}}
}
}"
# Stop MPC algorithm
python l3_pub_client.py --type mpc --cmd stop
# Disable algorithm control permission
ros2 service call /deactivate_service std_srvs/srv/Trigger {}Python code example
import rclpy
from rclpy.node import Node
from std_srvs.srv import Trigger
import subprocess
import time
import textwrap
class MPCStartupDemo(Node):
def __init__(self):
super().__init__('mpc_startup_demo')
self.cli_activate = self.create_client(Trigger, '/activate_service')
self.cli_activate.wait_for_service()
def call_activate_service(self):
self.get_logger().info('Enabling algorithm control permission...')
req = Trigger.Request()
future = self.cli_activate.call_async(req)
rclpy.spin_until_future_complete(self, future)
resp = future.result()
if resp.success:
self.get_logger().info('Algorithm control permission enabled successfully')
else:
self.get_logger().error(f'Failed to enable: {resp.message}')
def launch_mpc(self):
self.get_logger().info('Starting MPC algorithm...')
# Launch ros2 process (note: use shell=True or subprocess.Popen for interactive terminal if needed)
# Here subprocess.run is used; can be terminated with Ctrl+C
subprocess.run(["python", "l3_pub_client.py", "--type", "mpc", "--cmd", "start"])
self.get_logger().info('MPC algorithm started (use Ctrl+C to stop this script if needed)')
def publish_servo_pose_rate(self, rate_hz: int = 10):
"""Continuously publish lifting arm pose to /servo_poses at specified frequency (default 10Hz)"""
message = textwrap.dedent(
"""
{
left_pose: {
header: {frame_id: 'base_link'},
pose: {position: {x: 0.425, y: 0.3, z: 0.292}, orientation: {x: 0.612, y: -0.016, z: 0.79, w: -0.006}}
},
right_pose: {
header: {frame_id: 'base_link'},
pose: {position: {x: 0.417, y: -0.146, z: 0.382}, orientation: {x: 0.521, y: 0.1, z: 0.842, w: -0.096}}
},
head_pose: {
header: {frame_id: 'base_link'},
pose: {position: {x: 0.0, y: 0.0, z: 0.0}, orientation: {x: 0.0, y: 0.0, z: 0.0, w: 1.0}}
}
}
"""
).strip()
self.get_logger().info(f'Publishing /servo_poses lift command at {rate_hz}Hz...')
subprocess.run([
'ros2', 'topic', 'pub', '-r', str(rate_hz),
'/servo_poses', 'xbot_common_interfaces/msg/ServoPose',
message
], check=True)
def main(args=None):
rclpy.init(args=args)
node = MPCStartupDemo()
node.call_activate_service()
# Wait 1 second to ensure the service takes effect
time.sleep(1)
node.launch_mpc()
node.publish_servo_pose_rate()
node.destroy_node()
rclpy.spin(node)
rclpy.shutdown()
subprocess.run(["python", "l3_pub_client.py", "--type", "mpc", "--cmd", "stop"])
if __name__ == '__main__':
main()Directly use audio devices in the developer environment
The robot integrates a microphone and a speaker, which can be directly used in the system
Usage Instructions
Test whether the device is functioning properly via the command line
# Log in to the developer environment (password: developer)
ssh developer@192.168.8.100 -p 2222 # SSH into the robot backend and enter the workspace
# Install audio libraries
sudo apt update
sudo apt install libportaudio2 python3-pyaudio portaudio19-dev
# Install virtual environment dependencies
curl -L -A "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36" \
-o python3-pip-whl_22.0.2+dfsg-1_all.deb \
"https://mirrors.ustc.edu.cn/ubuntu/pool/universe/p/python-pip/python3-pip-whl_22.0.2+dfsg-1_all.deb"
sudo dpkg -i python3-pip-whl_22.0.2+dfsg-1_all.deb
sudo apt-get install --fix-broken python3.10-venv
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies (if installation fails, you can specify a mirror source)
# Aliyun mirror example: pip install sounddevice scipy -i https://mirrors.aliyun.com/pypi/simple/
# Tsinghua mirror example: pip install sounddevice scipy -i https://pypi.tuna.tsinghua.edu.cn/simple/ --trusted-host pypi.tuna.tsinghua.edu.cn
pip install sounddevice scipy --timeout=1000
# Grant permissions to snd devices to avoid issues
sudo chmod 777 /dev/snd/*
# Query sound card information:
python3 -c "import sounddevice as sd; print(sd.query_devices())"
# If successful, you should see output similar to the following:
developer@xbot-NUC:~$ python3 -c "import sounddevice as sd; print(sd.query_devices())"
< 0 HD-Audio Generic: HDMI 0 (hw:0,3), ALSA (0 in, 8 out)
1 HD-Audio Generic: HDMI 1 (hw:0,7), ALSA (0 in, 8 out)
2 HD-Audio Generic: HDMI 2 (hw:0,8), ALSA (0 in, 8 out)
3 HD-Audio Generic: HDMI 3 (hw:0,9), ALSA (0 in, 8 out)
> 4 POROSVOC: USB Audio (hw:1,0), ALSA (1 in, 0 out)
5 HD-Audio Generic: ALC897 Analog (hw:2,0), ALSA (2 in, 2 out)
6 USB Audio Device: - (hw:3,0), ALSA (1 in, 2 out)
7 hdmi, ALSA (0 in, 8 out)
# Command to exit the virtual environment
deactivatePython code example
import sounddevice as sd
import numpy as np
from scipy.signal import resample
duration = 2.0 # seconds
# Adjust input and output devices as needed
sd.default.device = (6, 6) # M7 default audio device is index 6
# Get default device indices
input_device, output_device = sd.default.device
# Get device parameters
input_info = sd.query_devices(input_device)
output_info = sd.query_devices(output_device)
input_samplerate = int(input_info['default_samplerate'])
output_samplerate = int(output_info['default_samplerate'])
channels = input_info['max_input_channels']
print(f"🎤 Recording from default input device (device {input_device}) for {duration} seconds @ {input_samplerate} Hz, channels: {channels}")
sd.default.device = (input_device, output_device)
# Record audio
recording = sd.rec(int(input_samplerate * duration), samplerate=input_samplerate, channels=channels, dtype='int16')
sd.wait()
# Amplify volume (adjust as needed)
amplified = recording * 1
amplified = np.clip(amplified, -32768, 32767).astype(np.int16)
# Resample if input and output sample rates differ
if input_samplerate != output_samplerate:
print(f"🔁 Resampling audio from {input_samplerate} Hz to {output_samplerate} Hz for playback")
num_samples = int(output_samplerate * duration)
amplified = resample(amplified, num_samples).astype(np.int16)
print(f"🔊 Playing back through default output device (device {output_device})...")
sd.play(amplified, samplerate=output_samplerate)
sd.wait()
print("✅ Playback finished")Use the camera in the developer environment
The M7 robot integrates cameras (binocular or realsense) and can be directly used in the developer environment
Usage Instructions
Binocular Camera
# Log in to the developer environment (password: developer)
ssh developer@192.168.8.100 -p 2222 # SSH into the robot backend and enter the workspace
# Create symbolic links
sudo bash /usr/local/bin/map_video.sh
# Install v4l device tools
sudo apt install v4l-utils
# List video devices
sudo v4l2-ctl --list-devices
# If successful, you should see output similar to the following:
developer@xbot-NUC:~$ v4l2-ctl --list-devices
PayCam: PayCam (usb-0000:66:00.4-1):
/dev/video0
/dev/video1
# Capture a single frame
# Save as YUV format
sudo v4l2-ctl --device=/dev/video4 \
--set-fmt-video=width=1280,height=720,pixelformat=YUYV \
--stream-mmap --stream-count=1 \
--stream-to=frame.raw
# Convert YUV to JPEG
sudo apt install ffmpeg
ffmpeg -f rawvideo -pixel_format yuyv422 -video_size 1280x720 -i frame.raw frame.jpgRealsense camera
- Download Mobaxterm in Windows environment for access: https://mobaxterm.mobatek.net/
ssh -X developer@192.168.8.100 -p 2222- Re-enter the Linux environment:
ssh -X developer@192.168.8.100 -p 2222- Launching realsense - viewer in the terminal can open the GUI for operation
realsense-viewer- Launching realsense2_camera enables real-time external transmission of image-related data via ROS
# Launch RealSense camera
ros2 launch realsense2_camera rs_launch.py
# If you want to set resolution
ros2 launch realsense2_camera rs_align_depth_launch.py depth_module.depth_profile:=848x480x60 rgb_camera.color_profile:=848x480x60- Use ros2 topic list to view image messages
/camera/camera/color/camera_info
/camera/camera/color/image_raw
/camera/camera/color/metadata
/camera/camera/depth/camera_info
/camera/camera/depth/image_rect_raw
/camera/camera/depth/metadata
/camera/camera/extrinsics/depth_to_color
/tf_static| topic name | Data Type | Meaning |
|---|---|---|
| /camera/camera/color/camera_info | sensor_msgs/msg/CameraInfo | Internal parameters of the color camera (K matrix, distortion parameters, etc.) |
| /camera/camera/color/image_raw | sensor_msgs/msg/Image | RGB color image raw data |
| /camera/camera/color/metadata | realsense2_camera_msgs/msg/Metadata | Frame metadata (timestamp, exposure, gain, etc.) |
| /camera/camera/depth/camera_info | sensor_msgs/msg/CameraInfo | Internal parameters of the depth camera |
| /camera/camera/depth/image_rect_raw | sensor_msgs/msg/Image | Aligned or rectified depth map |
| /camera/camera/depth/metadata | realsense2_camera_msgs/msg/Metadata | Frame metadata (timestamp, exposure, gain, etc.) |
| /camera/camera/extrinsics/depth_to_color | realsense2_camera_msgs/msg/Extrinsics | Extrinsic matrix of depth→color camera |
| /tf_static | tf2_msgs/msg/TFMessage | Static coordinate transformation (camera coordinate system, etc.) |
Recording and playback of robot actions in the developer environment
Start remote operation
exclamation Teleoperation requires two people to cooperate simultaneously. Before stopping the MPC, the head-mounted display operator must not move unexpectedly.
Reference: Operation Guide: Robot Teleoperation and Development Guide: Using Teleoperation in the Developer Environment
Record robot actions
exclamation Note:Remote operation can only be initiated after ensuring that human movements are consistent with the robot's movements.
# Log in as developer
ssh developer@192.168.8.100 -p 2222 # password: developer
# If teleop_client is already cloned
cd teleop_client
colcon build
source install/setup.bash
# If teleop_client directory does not exist, please follow step 1 in the teleoperation service startup instructions
# Start recording
ros2 bag record /hand_controller/commands /servo_poses -o [bag package name]
# The name after -o defines the output bag package name
# Save the recording: press Ctrl+C in the terminal running the recording to stop and savePlay robot actions
Play in the developer container
# Start SDK (do not start again if already running)
python l3_pub_client.py --cmd start_sdk
# Start MPC algorithm
python l3_pub_client.py --type mpc --cmd start
# Play
ros2 bag play [bag package name]
# [bag package name] contains the recorded robot motions
# Stop MPC algorithm
python l3_pub_client.py --type mpc --cmd stop
# Stop
Ctrl-C in the MPC terminal
python l3_pub_client.py --cmd stop_sdkConfigure program auto-start in the developer environment
In the developer environment, you can configure programs to start automatically by modifying /ros_entrypoint.sh. This script is executed when the developer environment starts, and can be used to launch background services or user programs automatically.
Open and edit the
/ros_entrypoint.shfile.Add the command for the program to be started before the last line
exec "$@". For example:
#!/bin/bash
set -e
# setup ros2 environment
source "/opt/ros/$ROS_DISTRO/setup.bash"
sudo /usr/sbin/sshd -D &
sudo bash /usr/local/bin/maps/video.sh &
exec "$@"Note: Add & at the end of the command so that the program runs in the background.