robot_hardware_interface

A ROS2 hardware interface plugin library for humanoid robots, built on top of ros2_control. It provides production-ready, real-time-safe hardware interface implementations for multiple robot platforms, along with shared utilities that make adding new robots straightforward.

Supported Robots

Robot	Vendor	Communication	Plugin Name
G1	Unitree	DDS (unitree_sdk2)	unitree/G1HardwareInterface
X2	Agibot	ROS2 Topic (aimdk_msgs)	agibot/X2HardwareInterface
PM01	EngineAI	ROS2 Topic (interface_protocol)	engineai/PM01HardwareInterface

Features

• Real-time safe — zero heap allocation in read(), write(), and SDK callbacks
• Lock-free data exchange — SPSC triple-buffer (DataBuffer<T>) between the SDK thread and the ros2_control thread
• Safe startup — three-layer protection ensures commands are never sent before the first valid state is received
• Configurable decimation — reduce CPU load by processing state at a fraction of the SDK publish rate
• Performance monitoring — latency warnings for read(), write(), state callbacks, and command send jitter; silent during normal operation

Dependencies

Package	Role
rclcpp, rclcpp_lifecycle	ROS2 node and lifecycle
hardware_interface	ros2_control plugin base
pluginlib	Plugin registration
unitree_sdk2_ament	Unitree DDS SDK
aimdk_msgs	Agibot ROS2 message types
interface_protocol	EngineAI ROS2 message types
Eigen3	Linear algebra utilities

Build

# Clone into your ROS2 workspace
cd ~/ros2_ws/src
git clone <repo-url> robot_hardware_interface

# Install ROS2 dependencies
rosdep install --from-paths . --ignore-src -r -y

# Build
cd ~/ros2_ws
colcon build --packages-select robot_hardware_interface

Usage

Load the plugin in your robot's URDF <ros2_control> block:

<ros2_control name="g1_hardware" type="system">
    <hardware>
        <plugin>unitree/G1HardwareInterface</plugin>
        <param name="network_interface">eth0</param>
        <param name="enable_monitor">true</param>
        <param name="command_writer_period_us">2000</param>  <!-- 500 Hz -->
        <param name="state_decimation">1</param>
    </hardware>
    <joint name="left_hip_pitch_joint">
        <command_interface name="position"/>
        <command_interface name="velocity"/>
        <command_interface name="stiffness"/>
        <command_interface name="damping"/>
        <command_interface name="effort"/>
        <state_interface name="position"/>
        <state_interface name="velocity"/>
        <state_interface name="effort"/>
    </joint>
    <!-- ... remaining joints ... -->
</ros2_control>

URDF Parameters

Parameter	Type	Default	Description
network_interface	string	lo	Network interface name (DDS mode)
enable_monitor	bool	true	Enable latency / jitter monitoring
command_writer_period_us	uint64	2000	Command send period in microseconds
state_decimation	uint32	1	Process 1 out of every N state frames

Common Rate Combinations

Controller Rate	command_writer_period_us	state_decimation	Effective State Rate
500 Hz	2000 (default)	1 (default)	1000 Hz
200 Hz	4000 – 5000	4	250 Hz
100 Hz	8000 – 10000	10	100 Hz

Architecture

[SDK / Topic Callback Thread]
    │
    ▼  setData()
┌─────────────────────────┐
│  DataBuffer<T>          │  lock-free SPSC triple buffer
│  (motor state / IMU)    │
└─────────────────────────┘
    │  getData()
    ▼
[ros2_control main thread]
    ├── read()   →  copy state into jointData_ / imuData_
    └── write()  →  pack jointData_ into command → setData()
                                                        │
                                              [Command Writer Thread]
                                                        │
                                              getData() → send to SDK / Topic

Shared Components (common/)

Header	Provides
data_buffer.hpp	DataBuffer<T> — lock-free SPSC triple buffer
types.hpp	MotorData, ImuData, ImuState, CallbackReturn, return_type
motor_types.hpp	MotorCommand<N,T>, MotorState<N,T>
monitor.hpp	MonitorThresholds constants

Adding a New Robot

1. Create include/robot_hardware_interface/{vendor}/{robot}.hpp and src/{vendor}/{robot}.cpp following the templates in CLAUDE.md.
2. Register the plugin in robot_hardware_interface.xml:

<class name="{vendor}/{Robot}HardwareInterface"
       type="{vendor}::{Robot}HardwareInterface"
       base_class_type="hardware_interface::SystemInterface">
    <description>Hardware interface for {Vendor} {Robot}</description>
</class>

3. Rebuild the package — ament_auto_add_library will pick up the new source file automatically.

License

MIT — see LICENSE.