Deployment Process

The system middleware adopts the ROS2 architecture and performs performance tuning for FastDDS. Based on the RT-Linux kernel, the process priority is configured, and the microsecond-level parallel solution algorithm and thread pool mechanism are utilized to ensure system real-time performance. This solution achieves 200Hz real-time control of 23 motors across four CAN buses, with the CAN bus load stably around 33% and extremely low packet loss rate. The system supports functions such as zero point setting, fault clearing, status information reading, and motion control, and is designed using the factory pattern, supporting the expansion of communication protocols and sensors.

Based on ONNX Runtime, it implements cross-platform model inference deployment, and uses a one-time loading and context switching mechanism to achieve dynamic switching of multi-strategy runtimes. The system supports reading action data in NPZ format, uses a lock-free structure to ensure real-time performance during the inference process, and supports joystick access and the /cmd_vel standard interface.

Open Source Address: RPO deployment repository

The deployment framework has been fully verified on Orange Pi 5 Plus and RDK X5 .

• Orange Pi 5 Plus: The system is Ubuntu 22.04, and the kernel version is 5.10

• RDK X5: The system is Ubuntu 22.04, and the kernel version is 6.1.83

For the connection method and related information about the main controller, refer to Orange Pi 5 Plus Wiki and RDK X5 Doc.

1. First, install ROS2 Humble, referring to the official ROS for installation.

2. Deployment also depends on ccache, fmt, spdlog, eigen3, screen and other libraries. Execute commands in the master control to install them:

1. If you need to use the joystick for control, you also need to install the joy package of ROS2:

1. If you need to use Python scripts in the repository (such as scripts/set_zero.py), you also need to install the corresponding Python dependencies:

1. Then pull the deployment code:

1. If you are using Orange Pi 5 Plus, execute the following command to install the 5.10 real-time kernel : > Note: RDK X5 does not need to perform this step. Please directly flash the mirroring provided by us, which has the real-time kernel pre-installed.

1. Next, grant the user the permission to set real-time priority:

Add the following two lines at the end of the file (make sure to replace orangepi with your actual username, for example, the default username of RDK X5 is sunrise)：

Restart the device to make the configuration take effect, and then verify it through the following command:

> Hint: An output of 98 indicates successful configuration.

To facilitate debugging without a network cable and monitor, you can enable a WiFi hotspot (AP) for the main control board. The configuration files are located in the tools/create_ap directory.

Note: Due to the limitation of a single network card, after enabling AP mode, the built-in WiFi of the main control board will have difficulty connecting to other external networks such as home routers.

• If you need to connect to the external network to load packages or environments , please connect the main control board to a wired network .
• If you want to temporarily resume wireless internet access , you can stop the service using the following command (requires an external monitor or network cable to log in):

sudo systemctl stop create_ap.service

1. Execute in the project root directory to install and grant permissions:

1. Deploy systemd service files:

1. Copy the configuration file according to your main control board: Orange Pi 5 Plus Please use this configuration:

RDK X5 Please use this configuration:

> Description: Under the default configuration, the hotspot name (SSID) is atom, and the connection password (PASSPHRASE) is jujujuju. If you need to customize the hotspot name or password, you can edit the /etc/create_ap.conf file and modify the corresponding fields.

1. Enable auto-start on boot and immediately start the hotspot:

Before connecting, please complete the settings for the motor ID, IMU baud rate, and frequency.

For motor ID , please refer to the definition of motor ID in the product installation manual , and use the Damiao host computer tool for setting. For the usage tutorial, please refer to Damiao Technology Documentation .

For IMU, we default to using 921600 baud rate and 500HZ frequency . For how to modify it using the host computer, refer to HiPNUC Product Manual.

Hint: Other baud rates can also be used, but please ensure the frequency is greater than 200HZ. If using other baud rates, please synchronously modify the IMU configuration in src/inference/config/robot.yaml.

The default CAN mapping relationship for motor drive is as follows (numbered according to the order in which the USB-to-CAN is inserted into the main controller, with the first inserted being can0) :

• can0 corresponds to left leg

• can1 corresponds to right leg plus waist

• can2 corresponds to left hand

• can3 corresponds to right hand

Recommendation: Plug the USB to CAN into the USB 3.0 port of the main controller. If using a USB docking station, please also use a 3.0 port docking station and plug it into a 3.0 port; the IMU and joystick can be plugged into USB 2.0 ports. For details, please refer to the wiring instructions.

If udev rules are not configured, you need to strictly follow the above order to insert the USB to CAN and manually configure the CAN and IMU serial ports after inserting the IMU:

Write udev rules to physically bind USB interfaces to corresponding devices, so thatthere is no need to insert devices in order. The example provides99-auto-up-devs-orangepi.rules and 99-auto-up-devs-sunrise.rules. If the wiring method is completely consistent with the wiring instructions, it can be used directly.

If the wiring is inconsistent, you need to modify the KERNELS item in the file to map it to the actually bound USB interface. Enter the following command on the main controller to monitor USB events:

When a device is plugged into a USB port, the terminal will display the KERNELS attribute item of that USB port, such as /devices/pci0000:00/0000:00:14.0/usb3/3-8 . When matching the KERNELS attribute item, simply use 3-8 . If it is a USB port on a dock attached to this USB port, 3-8.x will appear. In this case, use 3-8.x to match the USB port on the dock.

After writing is completed, execute the following in the project root directory:

Restarting the main controller will take effect.

This udev rule also includes IMU serial port configuration. If the rule takes effect properly, all CAN interfaces should be automatically configured and enabled, and you can enter the ip a command in the main controller to view the results.

Description: Motor zero calibration usually only needs to be performed once during the first use; if the motor has been overhauled, replaced, or the zero point is lost, zero calibration also needs to be re-performed.

Two zero calibration methods are provided in the warehouse, suitable for different scenarios:

• ros2 service call /set_zeros std_srvs/srv/Trigger Used to write the current joint position to the motor zero point when the robot software has been started, the motor has been initialized, and inference is not running.

• python3 scripts/set_zero.py It is used for manual positioning and zero calibration of each motor, making it more suitable for scenarios such as initial installation, recalibration after maintenance, or when only partial motors need to be recalibrated.

When using the /set_zeros service, it is recommended to follow the following sequence of operations:

1. First source the ROS2 environment and workspace environment in the current terminal.

2. Run ./tools/start_robot.sh to start the software.

3. Call /init_motors to initialize the motors.

4. Confirm that the robot is at the target zero position and is not currently running inference.

5. Call /set_zeros to write the current zero point.

When using the script scripts/set_zero.py:

1. First, complete the workspace compilation and ensure that install/setup.bash has been generated.

2. Source the ROS2 environment and workspace environment in the current terminal.

3. Confirm that the CAN interface and udev mapping have taken effect normally.

4. Check or modify as needed scripts/config/set_zero.yaml, and confirm that the motor ID, CAN interface, and motor model are consistent with the actual hardware.

5. After running the script in the interactive terminal, manually move the current motor to the zero position as prompted.

6. Press Enter to write the zero point of this motor, press Space to skip the current motor.

scripts/set_zero.py will calibrate each motor in the order specified in scripts/config/set_zero.yaml, and switch the motors to damping mode during the calibration process to facilitate manual adjustment of the attitude.

Warning: Before starting the robot, ensure that the robot has completed zero calibration,please be sure to read the Safety Operation Manual !

In addition, please pay special attention to the zero offset configuration in src/inference/config/robot.yaml:

• If the waist yaw is turned to the limit block for calibration: keep 2.093 .

• If using a printed part to fix the waist yaw for calibration: change 2.093 to 0.0 .

After everything is ready, run the script to start the software:

./tools/start_robot.sh will automatically execute colcon build --symlink-install to compile the workspace and start the following two screen sessions in the background:

• inference_session: Inference Node

• joy_session: Handle Node

You can use the following command to view the background output:

You can use the following command to stop the corresponding background component:

If you need to switch between different strategy models, you can first modify the configuration file loaded in src/inference/launch/inference.launch.py:

Simply replace the inference.yaml with the target configuration file name, for example:

• inference_amp.yaml

• inference_attn_enc.yaml

• inference_beyondmimic.yaml

• inference_getup.yaml

• inference_interrupt.yaml

After the modification is completed, re-run ./tools/start_robot.sh , and the corresponding configuration will be loaded during startup, thus using different strategies.

• X Key: Enable / Disable Motor

• Key A: Reset Motor

• Key B: Start / Pause Inference

• Y Key: Switch between joystick control / cmd_vel command control

• LB Key: Switch strategy mode (available in beyondmimic / interrupt mode)

• RB Key: Switch motion sequence (available in beyondmimic mode)

• Right Joystick: Controls forward, backward, left, and right movement

• LT/RT: Control steering (left/right rotation)

ROS2 services can be invoked via the command line to control the robot:

• Initialize the motor:

• Deinitialize the motor:

• Start reasoning:

• Stop Inference:

• Clear Error:

• Set Zero Point:

This service will write the current posture of the robot to the motor zero point. Before calling, please ensure that the current terminal has sourced the ROS2 and workspace environments, the motor has been initialized, the robot has been positioned at the target zero position, and no inference is currently running.

• Reset Joint:

• Refresh Joint Status:

• Read joint state:

• Read IMU Status:

This repository provides a Python SDK to facilitate users in controlling hardware using Python scripts.

Note: imu_py, motors_py, robot_py these three modules come from the workspace compilation products. Before running any Python SDK examples or scripts, please first complete the workspace compilation, and source the ROS2 environment and the install/setup.bash of this workspace.

Hint: For detailed Python script examples, please refer to the scripts/ directory.

Static Method

• create_imu(imu_id: int, interface_type: str, interface: str, imu_type: str, baudrate: int = 0) -> IMUDriver: Create an IMU driver instance。

Member Method

• get_imu_id() -> int: Get the IMU ID.

• get_ang_vel() -> List[float]: Get the angular velocity [x, y, z].

• get_quat() -> List[float]: Get the quaternion [w, x, y, z].

• get_lin_acc() -> List[float]: Get the linear acceleration [x, y, z].

• get_temperature() -> float: Get the temperature.

Usage Example

provides MotorControlMode enumeration: NONE , MIT , POS , SPD .

Static Method

• create_motor(motor_id: int, interface_type: str, interface: str, motor_type: str, motor_model: int, master_id_offset: int = 0, motor_zero_offset: double = 0.0) -> MotorDriver: Create a motor drive instance。

Member Method

• init_motor(): Initialize the motor.

• deinit_motor(): Deinitialize the motor.

• set_motor_control_mode(mode: MotorControlMode): Sets the control mode.

• motor_mit_cmd(pos: float, vel: float, kp: float, kd: float, torque: float): MIT mode control command.

• motor_pos_cmd(pos: float, spd: float, ignore_limit: bool = False): Position mode control command.

• motor_spd_cmd(spd: float): Speed mode control command.

• lock_motor() / unlock_motor(): Lock/Unlock the motor.

• set_motor_zero(): Sets the current position as the zero point.

• clear_motor_error(): Clears errors.

• get_motor_pos() -> float: Get position (rad).

• get_motor_spd() -> float: Get speed (rad/s).

• get_motor_current() -> float: Get current (A).

• get_motor_temperature() -> float: Get temperature (°C).

• get_error_id() -> int: Get the error code.

• get_motor_id() -> int: Get the motor ID.

• get_motor_control_mode() -> int: Get the control mode.

• get_response_count() -> int: Get the response count.

• refresh_motor_status(): Refresh motor status.

Usage Example

RobotInterface class is used to uniformly control the entire robot, reading the configuration file to automatically load motors and IMUs.

constructor function

• RobotInterface(config_file: str): Creates an instance based on the configuration file path.

Member Method

• init_motors(): Initialize all motors.

• deinit_motors(): Deinitialize all motors.

• reset_joints(joint_default_angle: List[float]): Reset all joints to their default angles.

• apply_action(action: List[float]): Apply control actions (joint target positions/torques, etc., depending on the internal implementation).

• refresh_joints(): Refresh the status of all joints.

• set_zeros(): Sets all current joint positions to zero.

• clear_errors(): Clears all motor errors.

• get_joint_q() -> List[float]: Get all joint positions.

• get_joint_vel() -> List[float]: Get the velocities of all joints.

• get_joint_tau() -> List[float]: Get all joint torques.

• get_quat() -> List[float]: Get IMU quaternion [w, x, y, z]。

• get_ang_vel() -> List[float]: Get the angular velocity of the IMU.

Attribute

• is_init: (Read-only) Whether the robot has been initialized.

Usage Example