Skip to content

About M7 ​

Product Introduction ​

M7 is a half-body general-purpose humanoid robot developed by Robotera. It has 42 degrees of freedom, motors with a maximum peak torque of 184 Nm and a peak speed of 4.20 rad/s, and two dexterous hands with 12 active degrees of freedom each. It supports teleoperation, imitation learning, and robot foundation-model algorithms for logistics, data collection, and research applications.

Overview ​

The overall appearance of the robot is shown below.

M7 product overview

Illustrations in this manual are for reference only. Refer to the physical product delivered for your project.

Product Features ​

Fast Deployment and Ease of Use ​

  • Low risk and cost, quick return, high flexibility, and easy upgrades and expansion.
  • Sound and light alarms plus voice prompts support a user-friendly human–robot interface.
  • Supports data-collection teleoperation and robot foundation-model applications.
  • Plug-and-play operation without battery-life limitations.

High Sorting Efficiency and Space Utilization ​

  • Supports small-item sorting at a rate of 1,000 items per hour or higher.
  • Operates directly within the existing human workspace without requiring additional space.

Broad Compatibility ​

  • Supports grasping at a variety of fixed workstations.
  • Supports small-package feeding with multiple SKUs and unrestricted package types.

Product Dimensions ​

When planning the deployment and installation site, account for the robot's footprint and operating space. The following dimensions are for the standard version and are for reference only; the actual dimensions depend on the project configuration.

Robot dimensions

Overall Robot Parameters ​

Technical Specifications ​

M7 Specification Parameters
SizeUpright dimensions: Base dimensions 632*632mm, height adjustable from 1713 to 1760mm
Total Arm Length717mm x 2
Single-arm load3 kg (rated load with dexterous hand)
Degree of Freedom42 (7 per arm × 2, 2 at the waist, 2 at the neck, and 12 per dexterous hand × 2)
Overall Robot WeightApproximately 70 kg
End-of-arm velocity3m/s
Arm End Accuracy0.02mm
Control and perception capabilitiesDetermined by the onboard control and inference units delivered for the project
Perception Sensor ConfigurationDepth Camera Voice Module
Dexterous HandIt has a human hand-like shape with 12 active degrees of freedom in a single hand
Communication InterfaceEthernet、USB 4.0、Wi-Fi 6、USB-C

Joints and Motors ​

Joints and motors

Joint Peak Torque and Speed Specifications:

positionPeak torque (Nm)speed (rad/s)
shoulder pitch954
shoulder roll
arm yaw
elbow pitch
elbow yaw354
wrist roll
wrist pitch
neck pitch354
neck yaw
waist pitch1844
waist yaw

Range of robot for each joint:

Robot PartsCorresponding joint angle range
ArmShoulder pitch: ±160°; shoulder roll: -32°~145°; shoulder yaw: -250°~70°; elbow: -135°~40°; wrist yaw: ±160°; wrist pitch: ±45°; wrist roll: ±90°
NeckNeck pitch: -10°~30°; neck yaw: -60°~60°
WaistWaist pitch: -10°~90°; waist yaw: -145°~145°

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 470
CPU12-core
Memory32GB
Storage1TB SSD

Inference unit specifications:

Inference Uniti9-14900HX, 32 GB memory, 1 TB PCIe 4.0 storage, RTX 5070 Ti 16 GB

Component Overview ​

Robot Composition ​

The fixed M7 humanoid robot consists of the head and neck, torso, arms, dexterous hands, waist, fixed stand, and base.

Front component overview

Rear component overview

Head and Neck ​

  • The head and neck include a 2-DoF neck and the head. The head integrates a microphone array, depth camera, light strip, and other sensors and hardware, and connects to the torso through a modular interface.
  • The neck has yaw and pitch degrees of freedom, with ranges of ±60° and +30° to -10°, respectively.
  • The microphone array supports voice interaction, sound-source localization, and foundation-model dialogue.
  • The depth camera is mounted on the forehead and angled downward to cover the tabletop work area together with the neck pitch joint.
  • The light strip can display necessary robot information through the electronic control system.

Torso ​

  • The torso provides electromechanical mounting interfaces for the head, neck, and limbs, as well as robot interaction interfaces. It contains the main control, power, and communication hardware.
  • Active airflow and passive structural cooling help reduce the risk of hardware overheating.

External Interfaces and Controls ​

External interfaces and controls

No.InterfaceElectrical specificationFunction
1EthernetGigabit industrial EthernetConnects to the M7 robot
2USBUSB 4.0Connects external USB devices

Arms ​

  • Each arm has 7 degrees of freedom with a P-R-Y-P-Y-P-R joint layout. The ranges are ±160°, outward 145°/inward 30°, outward 70°/inward 250°, forward 135°/backward 40°, ±160°, ±45°, and ±90°, respectively, with no coupling or interference between ranges.
  • The rated load of one arm with a dexterous hand is no more than 3 kg. An arm without a dexterous hand has 7 degrees of freedom.
  • The wrist includes a standard USB 2.0 monocular camera, a wrist EtherCAT interface, and external cable routing.
  • In addition to the XHand dexterous hand, the wrist end can use an adapter to support specified electric grippers.

Dexterous Hands ​

ItemSpecificationItemSpecification
Weight1100 gFingertip gripping force15 N
Dimensions (L × W × H)191 mm × 94 mm × 47 mmLoad5 kg (per finger)
Active DoF12Furthest thumb oppositionLittle finger
Passive DoF0Repeated opening/closing speed>2 Hz
DoF distributionThumb ×3, index ×3, middle ×2, ring ×2, little ×2Backdriving damping≤0.1 Nm
Thumb transmission3 self-developed geared force-control joint modulesFour-finger transmission9 self-developed geared force-control joint modules
Fingertip shapeRoundedSide-swing range-15° to +15° (index finger)
Fingertip repeatability±0.20 mmCommunication interfaceEtherCAT, RS485 (USB)
Control modesPosition control, current-loop force control, force-position controlCommunication rateEtherCAT: 100 MHz; RS485: 3 MHz

Waist ​

  • The waist uses H9015 modules with pitch and yaw degrees of freedom arranged in series.
  • Pitch range: 90° forward and 10° backward. Yaw range: 145° to either side.
  • The waist has a power-off brake that automatically engages during emergency stop or power loss.

Stand ​

The stand supports the robot and adjusts its height. Its feet can be used for fixation and leveling, casters facilitate onsite transport, and shims adjust the stand height for different work-platform heights. The power supply converts AC to DC for the product.

Stand overview

Product Functions ​

Visual Recognition ​

  • A 3D stereo camera in the head provides an ultra-wide field of view for environment localization and global package recognition.

Head vision

  • A monocular camera at the wrist provides precise grasp-point localization.

Wrist vision

  • Multi-camera visual perception provides long-range, wide-coverage, and precise grasping capability.

Arm Grasping ​

  • One arm with a dexterous hand has a rated load of 3 kg and a maximum load of 5 kg, enabling compliant grasping of small packages and objects.
  • Under load, the body tilt angle does not exceed 3°, preventing tip-over risk.
  • Custom stand heights are supported.

Voice Interaction ​

The built-in microphone array and high-fidelity speaker support two-way audio communication, onsite voice prompts, fault voice alarms, and voice warnings for safety zones.

Network Communication ​

  • Supports wired network communication with the inference unit for model inference.
  • Supports wired network communication with scheduling and business systems.

Sound and Light Alerts ​

  • The robot head provides status lights and visual fault alarms.

The battery-level light indications are as follows (the brightness of the white segments must be adjusted):

Battery LevelLight ColorFlash PatternBattery Display Logic and BrightnessIndication
100% while chargingGreenSteadyThe battery is fully charged.
30%–100%Blue/whiteSteady1. The remaining-charge segments are blue.
2. The consumed-charge segments are white.
1. The robot can be used normally while the battery level is above 30%.
2. The ten light segments dim progressively to indicate battery consumption.
20%–30%Yellow/whiteSteady1. The remaining-charge segments are yellow.
2. The consumed-charge segments are white.
1. Below 30%, the lights change to yellow to remind the user to recharge the robot.
2. The ten light segments dim progressively to indicate battery consumption.
10%–20%Orange-red/whiteSteady1. The remaining-charge segments are orange-red.
2. The consumed-charge segments are white.
1. Below 20%, continued use may exceed the battery's ability to supply normal operating power, and the lights change to orange-red as a warning.
2. The ten light segments dim progressively to indicate battery consumption.
0–10%RedRemaining segments flash; consumed segments remain steady1. The remaining-charge segments are red.
2. The consumed-charge segments are white.
Below 10%, the robot may lose power at any time and could be damaged. The remaining-charge segments flash red as an alarm.
  • The robot head provides voice alarms so users can monitor the robot's operating state from alarm messages in real time.

Safety Protection ​

Emergency Stop Protection ​

Emergency stop is the robot's highest-priority safety function. It uses hardwired priority and software redundancy, independent of control logic, component crashes, or communication interruption. When triggered, it immediately cuts motion power, stops all movement, and locks the waist brake to prevent collision and tip-over incidents.

Runaway Prevention ​

Runaway prevention is a core safety function of the robot control system. It monitors robot motion in real time and triggers an emergency-stop response when it detects risks such as uncontrolled speed or abnormal commands.

Waist Brake ​

The waist bears the upper body's load and torsional moment. It automatically locks during power loss, emergency stop, or system failure to prevent tip-over, falling parts, or unintended movement.

Intelligent Management ​

Robot Support ​

  • Supports model-command, remote-controller, and teleoperation control modes.
  • Provides ROS 2.0 driver packages and an SDK.
  • Supports access to joint PID parameters.

System Collaboration and Extension ​

  • Supports tasks assigned by WCS.
  • Supports autonomous tasks, local manual override, remote teleoperation, and physical-button control. Priority is emergency braking > manual control > autonomous control.
  • Supports remote OTA upgrades and secondary integration through an SDK package.

Safety Information ​

Before using this product, carefully read and follow the precautions below to avoid hazardous situations and ensure optimal product performance.

Notice

The safety precautions in this manual supplement applicable safety rules. Operators and maintenance personnel must also comply with applicable local and international laws, regulations, and standards.

Warning Labels ​

LabelDescriptionLocation
Electric-shock warningWarning label: risk of electric shockCenter of the outward-facing side of the power adapter
Grounding labelGrounding label, 15 mm diameterAbove the hole between the reinforcing ribs at the bottom of the stand

General Safety ​

General precautions:

  • Before using the robot, carefully read the user manual and understand the robot's functions, operating methods, and safety precautions.
  • Use the robot on a level surface. Avoid excessively high or low temperatures, humid environments, steep slopes, floors with large level differences, fragile surfaces, and areas subject to vibration.
  • Provide sufficient operating space for the robot. Avoid working in narrow or crowded environments to reduce collision and crushing risks.
  • Before operation, ensure that all cables, plugs, and sockets are intact. Immediately disconnect the power supply in the event of an abnormal condition such as a short circuit or overheating.
  • Before starting the robot, ensure that no personnel or other obstacles are in its work area, especially near moving parts.
  • Before starting the robot, verify that the system is operating normally and has completed its self-check.

Operating precautions:

  • Use all robot components and accessories correctly. Unauthorized modification or disassembly is prohibited.
  • Keep fingers, hair, and clothing away from robot joints, gaps, and moving parts to prevent pinching or entanglement.
  • Do not touch motor surfaces during operation to prevent burns.
  • Do not insert foreign objects into robot gaps; doing so may cause electric shock or a short circuit.
  • Do not cover sensor areas on the torso, head, or other parts, as this may interfere with perception and control.
  • Do not use the robot in harsh environments involving humidity, high temperature, or strong magnetic fields. The normal operating temperature is 0–30°C, with relative humidity below 75%.
  • Do not move or transport the robot while it is powered on or before the battery has entered sleep mode.
  • While the robot is executing motions, personnel must keep their distance and remain outside the motion range of the arms and legs to prevent collision injuries.
  • Use dedicated relocation equipment when moving the robot. A single person must not carry or drag it manually.
  • If the robot moves out of control or another abnormal condition occurs, immediately press C on the remote controller to stiff-stop all robot joints, then take protective measures as soon as possible.
  • If remote-stop operations do not take effect promptly, immediately press the emergency-stop button on the robot's back to cut power and ensure safety.
  • Do not disassemble the robot yourself. Contact Robotera after-sales personnel if repair is required.

Cleaning precautions:

  • Keep the robot surface clean and regularly remove dust, oil, and other contaminants.
  • Before cleaning the robot, disconnect the power supply and use a dry or slightly damp cloth to clean the equipment.

Transport Safety ​

To ensure safe transport, observe the following requirements:

  • Before transport, ensure that both the robot power switch and the battery switch are off.
  • During transport, the robot must not hold any object, and all mechanisms must be locked and kept stationary.
  • Avoid excessive vibration and impact during transport, as these may affect robot performance.

Maintenance Safety ​

Before performing robot maintenance, observe the following safety requirements:

  • Before maintenance, pause the robot or switch it to offline mode in the management system.
  • Before maintenance, turn off the robot's power supply.
  • Do not use materials that may scratch surfaces, such as metal brushes or steel wool, to clean the equipment or charging-station surface.
  • Establish a safety isolation zone when troubleshooting within the robot's operating area.
  • For technical support, contact Robotera using the information provided in this manual. Unauthorized technical service may invalidate the warranty.
  • Notify Robotera personnel before replacing any part. Replacement may proceed only after written approval from Robotera. Robotera accepts no liability for losses or equipment downtime caused by unauthorized replacement.
  • If an equipment component or power supply is defective or damaged during use, do not attempt to repair it yourself. Consult technical personnel authorized by Robotera.

Environmental Requirements ​

The robot has the following environmental requirements:

  • The environment must be free of excessive dust, oil fumes, flammable or explosive substances, and corrosive gases.
  • The floor must meet the relevant deployment requirements. Refer to the deployment-environment requirements in the technical specifications table for details.
  • Avoid complex environmental interference from electromagnetic waves, scattered light, ultrasound, and similar sources wherever possible.
  • Ambient illumination must be below 10,000 lx for artificial light and below 6,000 lx for daylight, with no direct sunlight.

Personnel Requirements ​

  • This product may be used only by persons aged 18 or older and only in accordance with this manual.
  • Maintain a safe distance of at least 50 cm from the robot's working range to avoid accidental collisions. Do not stand near the motion path, especially when the robot is executing high-speed motions.
  • Do not directly intervene in robot motions during operation. Any adjustment or manual intervention must be performed only after the robot has stopped completely and has been powered off.
  • Personnel responsible for installing, operating, or maintaining Robotera products must first receive rigorous training, understand all safety precautions, and master the correct operating and maintenance procedures to prevent accidents caused by improper operation.
  • Only personnel trained by Robotera or a Robotera-authorized organization, or personnel with equivalent professional skills, may install or maintain the equipment.
  • Personnel involved in installation and commissioning, operation and maintenance, programming, or system-solution development must carefully read this manual before work and use the product in strict accordance with the safety requirements.

Installation and Delivery ​

Unpacking Inspection ​

  1. Before opening the package, check for damage and confirm that the product was not damaged in transit.
  2. Remove the robot and accessories, including the power supply and tools, one by one according to the instructions.
  3. Follow the video guidance to remove the robot from the shipping case.

Transport ​

  • Use the custom flight case designed for the robot and its accessories.
  • Before moving the robot, fully power it off and confirm that the emergency-stop state has been released.
  • Joints can pinch fingers, other body parts, loose clothing, or long hair; exercise particular care during transport.
  • The robot is heavy and difficult to move. At least two people should use safe lifting techniques to prevent injury, falls, or equipment damage.

Installation ​

Stand Installation ​

The product can be installed on a steel platform or concrete floor. Complete stand fixation, leveling, and acceptance according to the onsite delivery plan; confirm stability before proceeding.

Stand installation

Robot Body and Stand Installation ​

Waist screw installation
Waist screw installation
Power, network, and harness connections
Power, network, and harness connections

Inference Unit Installation ​

Install the inference unit in the same way as a desktop host, then connect it to the robot over Ethernet.

Robot-side interface
Robot side

Storage ​

  • Store the robot indoors in a clean, dry, ventilated environment at -10 to 45°C.
  • Avoid corrosive substances, direct sunlight, fire sources, strong electromagnetic fields, and flammable or explosive materials.
  • For long-term storage, place the robot in its original shipping case.

Common Tools ​

ItemPart number
Hex key set1010507005
Long screwdriver bit1000400066
Diagonal cutter, FO-1116B1010409001
Multimeter1020301003
Torque wrench1010511005
Crimping pliers1010040001
Crimping pliers1010040002
Ratchet wrench set with magnetic bits1004000031
Low-cost anti-static tweezers1000500026
Kafuter K-1668 yellow sealant5530030001
Acetate adhesive tape5500400015
Green Forest heavy-duty tool bag1001800062

Unboxing, Installation, and Power-Off Videos ​

The following videos are for delivery-operation reference. If they conflict with onsite labels, delivery-engineer instructions, or safety requirements, stop the operation and follow the onsite requirements.

Power-on video

Robot body and stand installation video

Power-off video

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.

Each robot has a unique Wi-Fi password. Please contact the delivery engineer to obtain it.

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 ​

图片

This is the initial security setup interface of XOS. It is used to configure the access password for the one-stop robot control center and ensure the security of system and device permissions.

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 ​

图片

  1. View the overall robot status information on the home page to monitor the current robot status in real time.
  2. 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.
  3. 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 ​

图片

  1. The log management module supports log collection, storage, and visualization.
  2. Operation logs from each functional module can be classified and aggregated based on the system architecture hierarchy.
  3. The interactive interface supports log display and structured parsing.
  4. Users can manually download log files for specified modules according to operational needs, supporting system debugging, issue tracing, and troubleshooting.

Abnormal State ​

图片

  1. 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:

  • Abnormal 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 Processing: Each exception provides a "View Solution" entry, which directly jumps to the corresponding handling instructions.

Operation Instructions:

  1. Turn on/off notifications
  • Click the switch on the right side of "Pop-up Notification" or "Voice Broadcast" to toggle the on/off state.
  1. View exception details
  • View key information such as abnormal modules, locations, and levels in the list.
  • Exception levels are divided into: fatal error, serious error, error, warning, prompt, and information.
  1. Handle exceptions
  • Click "View Solution" in the action bar on the right side of the abnormal row to obtain the official processing steps.

Robot Management ​

Sound Settings ​

图片

  1. 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.
  2. 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.

Visual Sensor Configuration ​

图片

Provides a visual configuration interface for camera sensors. Supports full camera labeling with installation positions at the head, left wrist, and right wrist. Resolution and frame rate can be configured manually; changes take effect after restarting the camera. Designed for flexible multi-camera management.

Robot Control Console ​

Refer to the detailed usage method in xviz usage documentation.

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.

System Settings ​

Robot Info ​

图片

  • Basic Info: View the robot model and full-unit SN code, which is required for after-sales and warranty service. Click "View Manual" to access the complete manual.
  • Resource Status: Monitor CPU, memory, and storage usage to determine whether the system load is normal.
  • Joint SN Codes: Unique identifiers for all motion joints. Required when repairing or replacing joints.

exclamation Note: Do not modify SN codes. If storage or memory usage is too high, contact operations.

System Upgrade ​

图片

  1. 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.
  2. Users can view the current system version, RobotOS, and the version details of each module.
  3. The page supports checking for updates, downloading upgrade packages, manually uploading upgrade packages, and starting the upgrade after the robot is stationary, the battery level is sufficient, or an external power source is connected.

exclamation The robot will restart automatically during the upgrade. Do not operate or power off the robot during this process.

Security Center ​

For specific usage instructions, please refer to the User Manual – XOS Security Section.

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 Management function 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.

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:

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: Keep the emergency stop remote control ready during debugging. In an emergency, press D to cut power to the joint motors.

Maintenance, Troubleshooting, and After-Sales Service ​

Maintenance ​

Maintenance is preventive work performed periodically while the robot is functioning normally. Its purpose is to keep the robot intact and fit for operation, maintain it in good condition, identify and eliminate potential faults promptly, and keep it orderly, clean, lubricated, and safe.

Personnel responsible for maintaining the robot must use this manual together with local conditions and actual operating conditions to establish an appropriate maintenance schedule. They must perform routine inspections and maintenance and address faults promptly.

Scheduled Cleaning ​

The robot and its operating area must be cleaned regularly to avoid affecting normal operation. Before cleaning, ensure that the robot is powered off, the emergency-stop button is released, and the charging cable is disconnected.

Cleaning tools: a soft, clean, lint-free cloth; a soft-bristle brush; water, alcohol, or an amino-based cleaning substance; and lens-cleaning paper.

Cleaning primarily covers the robot surface, buttons, cameras, interfaces, and similar areas.

ItemCleaning Method
Robot surfaceWipe the robot surface with a slightly damp cloth, then dry it with a dry cloth.
CamerasUse lens-cleaning paper to remove dust and other debris from the head and wrist cameras.
ButtonsUse a soft-bristle brush to remove dust and debris from the button recesses, wipe the button surfaces with a slightly damp cloth, and then dry them with a dry cloth.
InterfacesUse a soft-bristle brush to remove dust and debris from interface recesses, then wipe the interfaces clean with a dry cloth.

Monthly Maintenance ​

ItemMaintenance Requirement
AppearanceRemove dust and debris from the robot body and keep it clean. A soft, lint-free, slightly damp cloth may be used on the robot surface.
Inspect the robot housing for defects.
Check whether any screws or nuts on the arms, waist, or wrists are missing or loose. Replace missing fasteners and tighten loose ones.
FunctionCheck overall robot operation and verify that there are no abnormal noises, vibrations, or other abnormalities.
ComponentsCheck whether the leveling-foot nuts are loose and ensure that the feet are secure.
Check whether the leveling feet have shifted at their mounting positions and caused robot displacement.
Visually inspect the wrist housing, connectors, links, and similar parts for damage.
Remove dust and debris from the cameras and confirm visually that they are clean.

Quarterly Maintenance ​

ItemMaintenance Requirement
Arm-axis joint modules and bearingsWith power on, exercise each joint module individually within its motion range and check for abnormal noise or vibration.
With power off, move each joint module slightly by hand and check joint-module backlash and bearing clearance.
With power off, move each joint module slowly through a larger range by hand and check for abnormal noise and uneven resistance.
Wrist connecting rodsWith the robot stationary, inspect the wrist connecting rods for deformation or cracks.

Common Fault Handling ​

Mechanical or environmental factors may cause abnormalities while the robot is operating. These can generally be resolved through recovery mode or a restart. This section lists common faults for onsite reference.

If a fault remains after following the instructions in the troubleshooting tables, or if disassembly or component replacement is required, contact Robotera or technical support authorized by Robotera.

General Fault Recovery ​

Notice

When a robot fault occurs, first try the following procedure to perform an initial recovery. At the same time, record the fault symptoms by taking photos or videos, save the relevant log files, and then follow the handling steps for the specific fault.

Restart the robot as follows:

  1. Turn off the power switch on the lower part of the robot by moving it downward.

    Move the power switch downward to turn off the robot
  2. Wait five seconds, then turn the power switch back on by moving it upward.

    Move the power switch upward to turn on the robot
  3. Wait several seconds for the robot to restart automatically.

If restarting does not clear the fault, contact Robotera or technical support authorized by Robotera.

System Faults ​

Fault CodeDescriptionCorrective Action
System lagCheck network communication quality.
Router Wi-Fi disconnectsCheck whether the power supply, address, and configuration are correct.
Poor or interrupted communication during teleoperationCheck communication quality and try replacing the network cable.
Teleoperation cannot return to the initial positionRestart and check whether normal operation is restored.
Poor communication between the main controller and power boardReplace the communication cable.
6102001Motion-control frequency is too low
6101002Motion-control module crashed or is unresponsive
6101003Behavior-control module crashed or is unresponsive
6101004Monitoring module crashed or is unresponsive
6101005Diagnostic module crashed or is unresponsive
6101006Network interface unavailable
6101007No available slave detectedCheck whether the power supply is normal.

Model Faults ​

Fault CodeDescriptionCorrective Action
Inference execution interrupted
Runaway motion
1901001Robot has fallen; body tilt exceeds the limitReturn the robot to a normal state, then repeat the operation.
1903012Abnormal MPC trajectory planning; trajectory oscillation
1902003Model inference is too slowIf computing resources are insufficient, shut down and restart.
1902009Used to identify which joint experienced a collisionStop the motion and restore the factory motion.
Robot stops unexpectedly while executing a task

Joint-Module Faults ​

Fault CodeDescriptionCorrective Action
Joint-module communication disconnectedCheck the harness or replace the module.
Joint-module overtemperatureCheck whether the joint has reached its limit position or replace the module.
Joint step-change fault
Joint lag or stickingReplace the module.
Joint low-voltage faultCheck the power supply and harness, or replace the module.
1201011Joint-module encoder fault1. Power off and restart.
2. Configure the parameters with technical support or replace the module.
1201012Joint-module overcurrent protectionThis may occur during high-amplitude motions. Power off and restart.
1201013Joint-module internal-state errorPerform internal initialization.
1201014Joint-module stallReplace the module and return it for repair.
1201015Joint-module EtherCAT communication errorCheck whether the interface cable is properly connected, whether the interface device is correct, and whether there is a system issue such as a network-adapter fault.
1201016Joint-module DRV errorRestart or power off and restart.
1201018Joint connection errorCheck the harness.
1201019Joint startup failed
1201020Joint-mode switching failedCheck switching between Boot initialization mode and normal App operating mode.
1201021Joint communication abnormalFollow the joint-communication fault procedure.

Harness Faults ​

Fault CodeDescriptionCorrective Action
Wrist-camera harness disconnected
Wrist communication harness disconnected
Wrist power-supply harness disconnected
Arm joint offline

Encoder Faults ​

Fault CodeDescriptionCorrective Action
1301001Magnet installation or encoder-circuit issue
1301002The module's internal storage does not contain the parameters required to calculate the zero position, or the module has not been zeroed
1301004Failed to calculate the encoder initial value; the module stator may not be stationary or the encoder data may be fluctuating significantly
1301005During startup, the module rotor may not be stationary or the encoder data may be fluctuating significantly
1301006The module reduction-ratio parameter may be incorrect, preventing zero-position calculation
1301007The calculated multi-turn value is invalid
1301008The number of encoder error flags read by the motor-side encoder exceeds the threshold
1301009The number of motor-side encoder CRC errors exceeds the threshold (default: 5,000), possibly due to communication interference
1301010The motor-side encoder packet-loss rate exceeds the threshold (default: 10%), possibly due to communication interference or a communication-cable connection problem

Camera Faults ​

Fault CodeDescriptionCorrective Action
2101001RealSense cannot connectCheck the harness and main-controller port.
2101002RealSense data-stream interruption

NUC Faults ​

Fault CodeDescriptionCorrective Action
1702001Temperature exceeds the normal threshold (70–80°C)
1701002Temperature exceeds the maximum threshold (100°C)

Storage ​

Before long-term storage, power off the robot, clean it, and inspect its exterior. Store it indoors in a clean, dry, ventilated environment at -10 to 45°C. Keep it away from corrosive substances, direct sunlight, fire sources, strong electromagnetic fields, and flammable or explosive materials. For extended storage, use the original shipping case. Before reuse, inspect the exterior, cables, fasteners, and functions.

After-Sales Warranty ​

Warranty Policy ​

  • For the complete robot and related products, the warranty period begins on the date the goods are signed for and accepted. If a non-user-caused performance fault occurs during normal use within the warranty period, Robotera will provide the corresponding repair or component replacement free of charge.
  • Warranty periods for major components:
TypeCoverageWarranty Period
Main unitRobot main unit and its constituent parts1 year
Actuation componentsJoint motors and similar components1 year
AccessoriesPower adapter and similar accessories1 year
  • During the warranty period, unauthorized modification, disassembly, or opening of the enclosure will immediately invalidate the warranty.
  • If the product is outside the warranty period, support remains available as a separately purchased service. Repair fees are charged according to Robotera's applicable rates.

Warranty Exclusions ​

  • The warranty period has expired.
  • Damage was caused by failure to follow the user manual.
  • Damage was caused by improper use or operating error.
  • Damage was caused by human action or an accident.
  • Damage was caused by unauthorized modification, disassembly, enclosure opening, installation of additional components, repair, or component replacement.

Repair-Service Responsibilities ​

  • The customer is responsible for losses caused by an incorrect delivery address supplied by the customer or by the recipient refusing delivery.
  • After receiving a product submitted for warranty service, Robotera will inspect it to determine the cause. If the issue is confirmed to be a product-quality defect, Robotera will cover the inspection, materials, labor, and return-shipping costs. If the product does not qualify for free repair, the customer may choose paid repair or return of the unrepaired product; the customer is responsible for return shipping in the latter case.
  • If the issue is outside warranty coverage, Robotera will still provide repair service but will charge applicable inspection, replacement-part, testing, labor, and transportation fees based on the specific issue.
  • Repair may result in data loss. Back up all data in advance; the customer is responsible for consequences resulting from failure to do so.
  • To provide necessary after-sales support, Robotera may access the customer's equipment. Repair may involve system operation and access to logs; by requesting service, the customer authorizes Robotera to perform this access.
  • During the warranty period, damaged components removed during replacement become the property of Robotera, and the replacement components become the property of the customer. Outside the warranty period, removed damaged components remain the property of the customer.
  • Robotera does not authorize third parties to provide repair services. Contact Robotera directly for after-sales service.
  • Contact Robotera for any additional information about warranty service.

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:

  1. Connect to the robot via a wired connection or directly connect to the robot's WIFI
  2. Prerequisite: The host has a ros-humble + cyclonedds environment
  3. Messages used by the robot need to be deployed on its own host
shell
git clone https://github.com/roboterax/teleop_client.git
cd teleop_client
colcon build
source install/setup.bash
  1. Set environment variables
shell
export ROS_DOMAIN_ID=211
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
  1. Configure unicast, and directly execute the following command on the host:
shell
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
  1. Set the ROSIP allowlist on Robot-XOSROSIP设置说明文档
    1. Simply add the host IP to the xos ros allowlist
  2. 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

plaintext
ssh developer@192.168.8.100 -p 2222      #SSH into the robot backend and enter the workspace.

Underlying Joint Control SDK ​

Joint Control Process ​

mermaid

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 -->|Enable control| 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

XHAND 1 Pro Joint Name

  • left_hand_thumb_bend_joint
  • left_hand_thumb_rota_joint1
  • left_hand_thumb_rota_joint2
  • left_hand_thumb_rota_joint3
  • left_hand_index_bend_joint
  • left_hand_index_rota_joint1
  • left_hand_index_rota_joint2
  • left_hand_index_rota_joint3
  • left_hand_mid_bend_joint
  • left_hand_mid_rota_joint1
  • left_hand_mid_rota_joint2
  • left_hand_mid_rota_joint3
  • left_hand_ring_bend_joint
  • left_hand_ring_rota_joint1
  • left_hand_ring_rota_joint2
  • left_hand_ring_rota_joint3
  • left_hand_pinky_bend_joint
  • left_hand_pinky_rota_joint1
  • left_hand_pinky_rota_joint2
  • left_hand_pinky_rota_joint3
  • left_hand_ltspalm_joint
  • right_hand_thumb_bend_joint
  • right_hand_thumb_rota_joint1
  • right_hand_thumb_rota_joint2
  • right_hand_thumb_rota_joint3
  • right_hand_index_bend_joint
  • right_hand_index_rota_joint1
  • right_hand_index_rota_joint2
  • right_hand_index_rota_joint3
  • right_hand_mid_bend_joint
  • right_hand_mid_rota_joint1
  • right_hand_mid_rota_joint2
  • right_hand_mid_rota_joint3
  • right_hand_ring_bend_joint
  • right_hand_ring_rota_joint1
  • right_hand_ring_rota_joint2
  • right_hand_ring_rota_joint3
  • right_hand_pinky_bend_joint
  • right_hand_pinky_rota_joint1
  • right_hand_pinky_rota_joint2
  • right_hand_pinky_rota_joint3
  • right_hand_ltspalm_joint

Note: The KP and KD values vary by hand type. Please refer to the relevant hand documentation.

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

  1. 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
  1. 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:
shell
# 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 NameTypeFunction DescriptionMessage Type
/hybrid_body_controller/commandsROS2 TopicIssue joint control commandsxbot_common_interfaces/msg/HybridJointCommand
  • xbot_common_interfaces/msg/HybridJointCommand Parameter 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 NameTypeFunction DescriptionMessage Type
/hand_controller/commandsROS2 TopicIssue joint control commandsxbot_common_interfaces/msg/HybridJointCommand
  • xbot_common_interfaces/msg/HybridJointCommand Parameter 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 NameTypeFunction DescriptionMessage Type
/joint_statesROS2 TopicPublish joint state commandsensor_msgs/msg/JointState
  • sensor_msgs/msg/JointState Parameter 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 NameTypeFunction DescriptionMessage Type
/hand_sensorROS2 TopicPublish joint state commandxbot_common_interfaces::msg::XhandHandSensor
  • xbot_common_interfaces::msg::XhandHandSensor Parameter 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:

bash
# 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:

bash
# 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: ​

python
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
bash
# 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 steps

Upper-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 NameTypeFunction DescriptionMessage Type
/servo_posesROS2 TopicControl the target poses of the left and right handsxbot_common_interfaces/msg/ServoPose
  • ServoPose.msg includes three fields:

    • geometry_msgs/PoseStamped left_pose
    • geometry_msgs/PoseStamped right_pose
    • geometry_msgs/PoseStamped head_pose
  • geometry_msgs/PoseStamped Structure:

    • std_msgs/Header header
    • geometry_msgs/Pose pose

2. getPose Interface ​

Interface NameTypeFunction DescriptionMessage Type
/get_poseROS2 TopicGet the current poses of the left and right handsxbot_common_interfaces/msg/ServoPose
  • ServoPose.msg includes two fields:

    • geometry_msgs/PoseStamped left_pose
    • geometry_msgs/PoseStamped right_pose
    • geometry_msgs/PoseStamped head_pose
  • geometry_msgs/PoseStamped Structure:

    • 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 ​

bash
# SSH into the robot backend, enter workspace
ssh developer@192.168.8.100 -p 2222

# Start robot joint motors via the lower-level SDK
# Move the robot to 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 {}

# Source message definitions
git clone https://github.com/roboterax/teleop_client.git
cd teleop_client
colcon build
source install/setup.bash

# Start MPC algorithm
ros2 service call /teleoperation/service xbot_common_interfaces/srv/StringMessage \
'data: "{\"type\":\"mpc\",\"message\":{\"command\":\"start\"}}"'

# Check MPC status; status=1 means started, 0 means not started
ros2 service call /teleoperation/service xbot_common_interfaces/srv/StringMessage \
'data: "{\"type\":\"mpc\",\"message\":{\"command\":\"query\"}}"'

# Reset MPC; mode 0 lifts the arms
# mode 0 is also the robot's initial position after enabling MPC
ros2 service call /teleoperation/service xbot_common_interfaces/srv/StringMessage \
'data: "{\"type\":\"mpc\",\"message\":{\"command\":\"reset\",\"mode\":0}}"'

# Control arm lifting using ROS command only. The value after -r indicates the publishing frequency;
# -r 100 means 100Hz, which controls the motion 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
ros2 service call /teleoperation/service xbot_common_interfaces/srv/StringMessage \
'data: "{\"type\":\"mpc\",\"message\":{\"command\":\"stop\"}}"'

# Disable algorithm control permission
ros2 service call /deactivate_service std_srvs/srv/Trigger {}

Python code example ​

python
import rclpy
from rclpy.node import Node
from std_srvs.srv import Trigger
from xbot_common_interfaces.srv import StringMessage
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_teleoperation = self.create_client(StringMessage, '/teleoperation/service')
        self.cli_activate.wait_for_service()
        self.cli_teleoperation.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...')
        req = StringMessage.Request()
        req.data = '{"type":"mpc","message":{"command":"start"}}'
        future = self.cli_teleoperation.call_async(req)
        rclpy.spin_until_future_complete(self, future)
        resp = future.result()
        if resp.result:
            self.get_logger().info('MPC algorithm started')
        else:
            self.get_logger().error(f'Failed to start MPC algorithm: {resp.message}')

    def stop_mpc(self):
        self.get_logger().info('Stopping MPC algorithm...')
        req = StringMessage.Request()
        req.data = '{"type":"mpc","message":{"command":"stop"}}'
        future = self.cli_teleoperation.call_async(req)
        rclpy.spin_until_future_complete(self, future)
        resp = future.result()
        if resp.result:
            self.get_logger().info('MPC algorithm stopped')
        else:
            self.get_logger().error(f'Failed to stop MPC algorithm: {resp.message}')

    def publish_servo_pose_rate(self, rate_hz: int = 10):
        """Continuously publish arm-lift 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 arm-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.stop_mpc()
    node.destroy_node()
    rclpy.spin(node)
    rclpy.shutdown()

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 ​

bash
# 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
deactivate

Python code example ​

python
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")

Camera Data ​

The M7.1 robot is equipped with a head camera by default, which publishes head image-related topics after startup. The left and right hand cameras need to be connected and enabled separately before their corresponding topics are published. Use ros2 topic list to view camera-related topics.

PositionTopic NameData TypeMeaning
Head (default)/head/camera_infosensor_msgs/msg/CameraInfoCamera intrinsic parameters (K matrix, distortion parameters, etc.)
Head (default)/head/image_rawsensor_msgs/msg/ImageRGB image raw data
Head (default)/head/image_raw/compressedsensor_msgs/msg/CompressedImageRGB image compressed data
Left hand (requires connection)/left/camera_infosensor_msgs/msg/CameraInfoCamera intrinsic parameters (K matrix, distortion parameters, etc.)
Left hand (requires connection)/left/image_rawsensor_msgs/msg/ImageRGB image raw data
Left hand (requires connection)/left/image_raw/compressedsensor_msgs/msg/CompressedImageRGB image compressed data
Right hand (requires connection)/right/camera_infosensor_msgs/msg/CameraInfoCamera intrinsic parameters (K matrix, distortion parameters, etc.)
Right hand (requires connection)/right/image_rawsensor_msgs/msg/ImageRGB image raw data
Right hand (requires connection)/right/image_raw/compressedsensor_msgs/msg/CompressedImageRGB image compressed data

View topic information examples:

bash
ros2 topic info /head/camera_info
ros2 topic info /left/image_raw
ros2 topic info /right/image_raw/compressed

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

Record robot actions ​

exclamation Note:Remote operation can only be initiated after ensuring that human movements are consistent with the robot's movements.

bash
# 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 save

Play robot actions ​

Play in the developer container

bash
# Start SDK (do not restart if already running)
ros2 service call /dynamic_launch xbot_common_interfaces/srv/DynamicLaunch "app_name: ''
sync_control: false
launch_mode: 'pos'"

# Start MPC algorithm
ros2 service call /teleoperation/service xbot_common_interfaces/srv/StringMessage \
'data: "{\"type\":\"mpc\",\"message\":{\"command\":\"start\"}}"'

# Play
ros2 bag play [bag package name]
# [bag package name] contains the recorded robot motions

# Stop MPC algorithm
ros2 service call /teleoperation/service xbot_common_interfaces/srv/StringMessage \
'data: "{\"type\":\"mpc\",\"message\":{\"command\":\"stop\"}}"'

# Stop SDK
ros2 service call /stop_launch std_srvs/srv/Trigger {}

Configure 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.

  1. Open and edit the /ros_entrypoint.sh file.

  2. Add the command for the program to be started before the last line exec "$@". For example:

bash
#!/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.