dynamixel_hardware

⚠️ This package is deprecated

Use ROBOTIS’s officially maintained dynamixel_hardware_interface instead. It fills the same role, is released for humble, jazzy, kilted, lyrical, and rolling, and has capabilities this package never had.

Read the migration guide. It maps every parameter and interface, and is honest about the four things you lose — runtime control-mode switching, use_dummy, Protocol 1.0 servos, and lifecycle-based reconnection — with a workaround for each.

No further releases will be made; the last one was 0.6.1. This repository will be archived (read-only) once the end-of-life status lands in ros/rosdistro. Published binaries stay published and keep working. If you cannot migrate, pin this package.

The ros2_control hardware interface for any kind of ROBOTIS Dynamixel robot.

The package builds one pluginlib plugin, dynamixel_hardware/DynamixelHardware: a SystemInterface implementation that drives any number of ROBOTIS Dynamixel servos sharing a single serial bus. It is hopefully compatible with any configuration of Dynamixel servos, thanks to ros2_control’s flexible architecture.

Features

• All eight Dynamixel operating modes – position, extended_position, multi_turn, current_based_position, velocity, current, torque and pwm – selected per joint with the control_mode parameter.
• Per-joint mode switching at runtime: the mode a joint runs in follows the command interfaces the active controller claims, so a position-controlled arm and a velocity-controlled wheel can share one bus and one control cycle.
• A pwm command interface next to position, velocity and effort, for direct duty-ratio control.
• Joint-side units: per-joint gear_ratio, offset and torque_constant convert between the servo and the joint, so controllers command joint radians and Nm rather than motor revolutions and milliamps.
• Hardware-free operation: use_dummy swaps the serial driver for a built-in dummy that emulates every operating mode through the same plugin logic, so a robot description can be brought up with no servos attached.
• Bounded error handling: write() sends nothing until the first successful read() after activation, and each direction of the bus tolerates a configurable burst of consecutive failures before it reports an error to the controller manager.
• Protocol 1.0 and 2.0 servos, through automatic control-table name fallbacks (Goal_Velocity to Moving_Speed, Present_Velocity to Present_Speed, Present_Current to Present_Load).
• One codebase for every supported distro: the version differences live in compat.hpp and a single CMake standard check, not in diverging branches.

Supported distros

Each distro branch is built and tested by its own workflow, and a nightly matrix rebuilds all four plus the examples repository downstream. The older branches (foxy, galactic, iron) are frozen and unsupported.

Kilted is not part of this line: it has no branch here and receives no backports. Kilted users stay on the released ros-kilted-dynamixel-hardware 0.6.0 binary, which predates everything documented below.

Installation

Binary packages are published for jazzy, kilted, lyrical and rolling, and carry the older 0.5.x/0.6.x line:

$ sudo apt install ros-$ROS_DISTRO-dynamixel-hardware

There is no humble binary – dynamixel_hardware has never been released into humble – so humble users build from source, as does anyone who wants what this README documents:

$ export ROS_DISTRO=rolling  # humble, jazzy, lyrical or rolling
$ source /opt/ros/$ROS_DISTRO/setup.bash
$ mkdir -p ~/ws/src && cd ~/ws/src
$ git clone https://github.com/dynamixel-community/dynamixel_hardware.git
$ git clone https://github.com/dynamixel-community/dynamixel_hardware_examples.git
$ cd ~/ws
$ rosdep install --from-paths src --ignore-src -r -y
$ colcon build --symlink-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
$ . install/setup.bash

Clone the default rolling branch whichever distro you build against. It is the only branch that carries what this README describes, and the same codebase builds on humble, jazzy, lyrical and rolling – that is what the compat.hpp shim is for. The distro branches receive this content by backport once 1.0.0 is released; until then -b humble and -b jazzy would give you the 0.6.x line instead, and -b lyrical would fail, because that branch is cut as part of the 1.0.0 release.

The examples repository is optional; it is what the walkthrough further down uses.

Configuration

A minimal <ros2_control> section:

<ros2_control name="DynamixelHardware" type="system">
  <hardware>
    <plugin>dynamixel_hardware/DynamixelHardware</plugin>
    <param name="port_name">/dev/ttyUSB0</param>
    <param name="baud_rate">1000000</param>
    <!-- <param name="use_dummy">true</param> -->
  </hardware>
  <joint name="joint1">
    <param name="id">1</param>
    <command_interface name="position"/>
    <state_interface name="position"/>
    <state_interface name="velocity"/>
    <state_interface name="effort"/>
  </joint>
</ros2_control>

Every parameter below is a <param> element inside that tag. These tables are the reference; the OpenManipulator-X walkthrough further down shows the same parameters in context.

Hardware parameters

Parameters of the <hardware> tag:

File truncated at 100 lines see the full file