Skip to content

Quickstart

Run the driver on your PC first, with no hardware; then move a servo from your MCU: wire the bus, write a small port class, call four driver functions.

Datasheet sections this page relies on
  • Byte to byte time and the packet gap: ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark, 1.6 Byte to Byte Time, p. 1
  • Control table, X series (addresses, sizes, units): ROBOTIS e-Manual, XM430-W350 web page, no revision mark, 2 Control Table; 2.1 Control Table of EEPROM Area; 2.2 Control Table of RAM Area, p. 1

All of them, with the driver API for each: Datasheet map.

Try it on your PC

examples/host/ runs the real driver against a simulated bus of two XM430 servos, through a host port. From the repository root, with CMake and a C++20 compiler:

cmake -S examples/host -B build-example
cmake --build build-example
./build-example/dynamixel_host_example
DYNAMIXEL driver 0.1.0 on the host
dynamixel: initialised
servo 1: model 1020, firmware 46
servo 2: model 1020, firmware 46
servo 1: 31 C
servo 2: 25 C
torque off

The calls in main.cpp are the ones below; only the port differs on an MCU. CI builds and runs this example on every pull request.

1. Wire it

MCU Servo bus Notes
UART TX and RX DATA, through a half-duplex stage 57 600 8N1 for an X-series servo at the factory settings
A GPIO or the UART's RTS The stage's direction input High while the MCU sends
GND GND Common with the servo supply
VDD 10.0 V to 14.8 V from its own supply (XM430-W350), never from the MCU board

The Hardware page has the pins, the circuit, the bus settings and the timing. Check the servo's ID, bit rate and protocol first (the Dynamixel Wizard of ROBOTIS shows them); the driver defaults are protocol 2.0, 57 600 bit/s and ID 1.

2. Add the driver

Add the repository as a submodule and link the dynamixel::dynamixel CMake target. Installation covers CMake on any MCU, the installed package and ESP-IDF.

git submodule add https://github.com/kokeb-labs-drivers/driver-dynamixel.git external/driver-dynamixel

3. Write the port

The port is the only platform code: it brings the UART up and moves bytes. Replace the platform_* calls with your SDK's.

my_port.hpp
class MyPort : public dynamixel::UartInterface<MyPort> {
public:
  // Bring the UART up once; later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_uart_init();
    }
    return ready_;
  }

  // Transmit the whole packet in one go, wait for the last stop bit, then listen again.
  bool Write(const uint8_t* data, std::size_t len) noexcept {
    return platform_uart_send(data, len);
  }

  // One to `max` bytes as soon as one has arrived, or 0 after `timeout_us` without a byte.
  std::size_t Read(uint8_t* data, std::size_t max, uint32_t timeout_us) noexcept {
    return platform_uart_receive(data, max, timeout_us);
  }

  // Drop whatever has been received and not yet read.
  bool FlushInput() noexcept {
    return platform_uart_discard_input();
  }

  // Wait at least `us` microseconds (the settle times after a reboot or a baud rate change).
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

Porting explains each method, the optional hooks and the half-duplex rules.

4. Move the servo

main.cpp
#include "dynamixel.hpp"

int move_first_servo(MyPort& port) {
  dynamixel::DYNAMIXEL<MyPort> servos(port); // protocol 2.0, 57 600 bit/s; no I/O yet

  if (auto r = servos.EnsureInitialized(); !r) { // 1. UART up
    return static_cast<int>(r.error);            //    Bus: check the UART and the wiring
  }
  const auto found = servos.Ping(1); // 2. who is there? model, firmware, family
  if (!found) {
    return static_cast<int>(found.error); //    Timeout: wrong ID, baud rate or protocol
  }
  const dynamixel::ServoRef servo{found.value.id, found.value.family};
  if (auto r = servos.SetTorque(servo, true); !r) { // 3. torque on
    return static_cast<int>(r.error);
  }
  return static_cast<int>(servos.SetGoalPosition(servo, 2048).error); // 4. half a turn
}

What each step does:

  1. EnsureInitialized() brings the UART up through your port and applies Config::baud. It sends nothing on the bus.
  2. Ping(1) asks servo 1 for its model number and firmware. The model number selects the control table (PingInfo::family) that the typed calls below use.
  3. SetTorque() writes the Torque Enable register of the servo's family.
  4. SetGoalPosition() writes the Goal Position register. The torque must be on first; position 2048 is the middle of the 4096 counts of an X-series servo.

This example is built by the host CI, so it compiles against the current headers.

If it does not work

Symptom First thing to check
EnsureInitialized() returns Bus Your port's EnsureInitialized(): the UART did not come up
Ping() returns Timeout The servo's supply, its ID, bit rate and protocol; the direction pin
Ping() returns LineFault The line is stuck low, high or floating: power, ground, the half-duplex stage
Ping() returns EchoMismatch Single-wire loopback is on and the echo differs: another talker, or Config::echo is wrong
A call returns DeviceError The servo refused the instruction; GetLastReply().error_byte says why

Troubleshooting goes through each.

Next

  • API guide: discover servos, typed registers, Sync and Fast reads, the safe stop, errors.
  • Configuration: presets, every Config field, Kconfig.
  • Examples: the host example and the ESP32 example.
  • Platforms: which MCUs have a port and an example.