Skip to content

API guide

The driver's API by task, with code that compiles: initialise, find servos, move and read them by register name, read many at once, stop safely, handle errors and shut down.

Datasheet sections this page relies on
  • Status packet, error byte and alert bit: ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark, 3 Status Packet; 3.2 Error, p. 1
  • Ping, Read, Write, Reg Write, Action: ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark, 5.1 Ping to 5.5 Action, p. 1
  • Factory Reset, Reboot, Clear, Control Table Backup: ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark, 5.6 Factory Reset to 5.9 Control Table Backup, p. 1
  • Sync Read, Sync Write, Fast Sync Read: ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark, 5.10 Sync Read; 5.11 Sync Write; 5.12 Fast Sync Read, p. 1
  • Bulk Read, Bulk Write, Fast Bulk Read: ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark, 5.13 Bulk Read; 5.14 Bulk Write; 5.15 Fast Bulk Read, p. 1
  • Protocol 1.0 instructions: ROBOTIS e-Manual, DYNAMIXEL Protocol 1.0 web page, no revision mark, 4 Instruction Details (Ping to Bulk Read), 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
  • Control table, AX / RX / DX series (protocol 1.0): ROBOTIS e-Manual, AX-12A web page, no revision mark, 2 Control Table; 2.2 EEPROM Area; 2.3 RAM Area, p. 1

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

The shape of the API

Group Calls
Lifecycle EnsureInitialized(), IsInitialized(), Deinitialize(), Resync(), ApplyConfig(), GetConfig()
Discovery Ping(), Identify(), BroadcastPing(), ScanIds()
Raw registers Read(), Write(), RegWrite(), Action()
Typed registers ReadRegister(), WriteRegister(), ReadFeedback(), SetTorque(), SetGoalPosition()
Many servos SyncRead(), FastSyncRead(), BulkRead(), FastBulkRead(), SyncWrite(), BulkWrite()
The safe stop DisableTorque(), DisableTorqueAll(), DisableTorqueEach(), DisableTorqueAt()
Setup of a servo SetId(), SetServoBaudRate(), ChangeBusBaud(), SetStatusReturnLevel()
Destructive FactoryReset(), Reboot(), Clear(), Backup()
Diagnostics GetLastReply(), GetLatchedAlert(), ClearLatchedAlert(), GetStats(), ResetStats(), GetLastRequest()
Tables Info(), FindModel(), FamilyOf(), Indirect(), BaudValueFor() (free functions)

Every call that uses the bus returns Result<T>: check ok() (or the bool conversion) and read value, or read error. Result is [[nodiscard]], so an unchecked call is a compiler warning. Every call blocks until its reply is complete or its deadlines have passed (why).

Initialise

dynamixel::Error BringUp(Servos& servos) {
  // The one entry point: starts the UART on the first call, then returns Ok with no I/O. After a
  // failure the next call starts again from the beginning.
  const auto r = servos.EnsureInitialized();
  if (!r) {
    std::printf("DYNAMIXEL init: %s\n", dynamixel::ToString(r.error));
  }
  return r.error;
}

The constructor stores the port and the configuration (Config{} unless you pass one) and does no I/O. EnsureInitialized() is the one way to start the driver: it checks the configuration, brings the UART up through your port and applies Config::baud. It sends nothing on the bus, so it succeeds with no servo connected.

Once it has succeeded, EnsureInitialized() returns Ok at once with no I/O, so a caller can call it before every use. After a failure the driver stays uninitialised and the next call starts again from the beginning. Before it succeeds every call that uses the bus returns NotInitialized and sends nothing; argument and permission errors (InvalidArgument, Unsupported, NotPermitted) come first, and the torque-off calls are never refused (Contract).

Find the servos

dynamixel::Result<uint32_t> FindServos(Servos& servos, std::span<dynamixel::PingInfo> found) {
  // Protocol 2.0: one broadcast ping, every servo answers in ID order.
  const auto all = servos.BroadcastPing(found);
  if (all.ok() && (all.value > 0U)) {
    return all;
  }
  // Protocol 1.0 has no broadcast answers: ping the IDs one by one.
  return servos.ScanIds(1, 20, found);
}

Ping(id) answers with the model number and firmware; PingInfo::family is the control table that model uses (Family::Generic for a model the catalogue does not list). BroadcastPing() asks every servo at once in protocol 2.0; the servos answer in ID order, each within Config::broadcast_timeout_us. Protocol 1.0 has no broadcast answers: ScanIds(first, last, found) pings each ID in turn and takes a missing one as absent. A protocol 1.0 ping does not return the model; Identify(id) pings and then reads the model number and firmware.

Move and read by register name

dynamixel::Error GoTo(Servos& servos, dynamixel::ServoRef servo, int32_t counts) {
  if (auto r = servos.SetTorque(servo, true); !r) {
    return r.error;
  }
  if (auto r = servos.SetGoalPosition(servo, counts); !r) {
    return r.error;
  }
  const auto feedback =
      servos.ReadFeedback(servo); // position, velocity, load, voltage, temperature
  return feedback.error;
}

A ServoRef is an ID and a Family. The typed calls look up the register in the family's table, check that the value fits and that the register is writable, encode it (little-endian, two's complement or sign-magnitude as the family does) and send it; reads decode the same way. ReadFeedback() returns position, velocity, load or current, voltage and temperature in one transfer. A family without the register returns Unsupported; a value that does not fit returns InvalidArgument. Nothing is sent in either case.

For a register the table does not name, use the raw Read() and Write() with an address and bytes, on any family including Generic. RegWrite() stores the write in the servo and Action() executes the stored writes of every servo together, so a group of servos starts moving on the same packet.

Read many servos at once

dynamixel::Error ReadAllPositions(Servos& servos, std::span<int32_t> positions) {
  const std::array<uint8_t, 3> ids{1, 2, 3};
  std::array<uint8_t, 12> raw{};
  std::array<dynamixel::DeviceReply, 3> replies{};
  // Present Position of the X430 family: address 132, four bytes. Fast Sync Read answers in one
  // packet.
  const auto r = servos.FastSyncRead(132, 4, ids, raw, replies);
  for (std::size_t i = 0; (i < replies.size()) && (i < positions.size()); ++i) {
    if (replies[i].result == dynamixel::Error::Ok) { // each servo has its own outcome
      positions[i] = static_cast<int32_t>(static_cast<uint32_t>(raw[4U * i]) |
                                          (static_cast<uint32_t>(raw[(4U * i) + 1U]) << 8U) |
                                          (static_cast<uint32_t>(raw[(4U * i) + 2U]) << 16U) |
                                          (static_cast<uint32_t>(raw[(4U * i) + 3U]) << 24U));
    }
  }
  return r.error;
}

SyncRead() asks a list of servos for the same registers; they answer one after another. FastSyncRead() (protocol 2.0, firmware that lists it: SupportsFastRead()) has them answer inside one packet. BulkRead() and FastBulkRead() take a different address and length per servo. All four fill the caller's buffer, one slice per servo in request order, and one DeviceReply per servo:

DeviceReply Meaning
result Ok, or why this servo's data is not valid: Timeout (silent, or its part did not arrive), Crc, DeviceIdMismatch, DeviceError, DeviceFault
error_byte The raw error byte, when a packet arrived
alert The hardware alert flag of that servo

The call's own Result says whether the exchange worked; it can be Ok while a servo is Timeout, and a damaged packet still delivers the servos whose part was whole. Read the data only of the servos that are Ok.

SyncWrite() and BulkWrite() send one packet to many servos and get no answer; Ok means sent.

Stop safely

void EmergencyStop(Servos& servos) {
  // Never refused: no initialisation needed, no consent flag, three attempts per servo.
  // One broadcast packet; the servos do not answer a broadcast, so confirm with a read afterwards.
  static_cast<void>(servos.DisableTorqueAll(dynamixel::Family::X430));
}

DisableTorque(servo), DisableTorqueAll(family), DisableTorqueEach(servos) and DisableTorqueAt(id, address) write Torque Enable to 0. They are never refused for the driver's state: no initialisation is needed (they start the port themselves and set the bus baud rate), no consent flag is checked, and a failing input flush does not stop the write (the call then reports Bus after sending). Each servo gets up to three attempts: one is enough when a trusted answer confirms it; when no answer can (status return level below 2, or the broadcast form, which no servo answers) all three are sent, because one lost packet would leave the torque on, and Ok then means "sent", so confirm with a read if the stop matters.

The only refusals, which send nothing, are an argument the bus protocol does not have (an ID out of range, an address above 255 in protocol 1.0, a family that does not speak the bus protocol) and a port that cannot start. DisableTorqueEach() tries every servo and returns only the first error; call DisableTorque() for each servo when you need to know which one failed. A family with no torque register (Generic, a model the catalogue does not list) is refused by DisableTorque() and DisableTorqueAll(), because the driver cannot know the address: use DisableTorqueAt(id, address) with the Torque Enable address from that servo's own control table (64 on the X series, 24 on AX/RX/DX); it is the same stop path, so a Generic servo has the same safety stop. Take the address from the e-Manual's control table for the exact model and firmware. The call writes one byte, 0, at whatever address you give, and with ID 254 it does so to every servo on the bus: a wrong address can set every ID to 0, change the baud rate or silence the servos (on an X-series servo, address 7 is the ID, 8 the baud rate and 68 the status return level), and 24 is a different register on protocol 2.0 X-series servos than on AX/RX/DX. Safe uses are a torque address read from the table of the servo in hand, one servo ID at a time, tested once on the bench. Reboot() is sent the same way.

The time a stop can take is bounded, not short: in each attempt the first read waits the reply timeout and every later read the gap timeout, for at most 4 * FrameBytes + 16 reads, and there are three attempts. A line that gives one byte per read can therefore hold a stop for up to 3 * (Config::reply_timeout_us + (4 * FrameBytes + 15) * Config::gap_timeout_us) (the timeouts are held inside 100 microseconds to 1 second on this path). A test pins this formula. Use short timeouts when the stop must return quickly.

Alerts

void CheckAlerts(Servos& servos) {
  const auto temperature =
      servos.ReadRegister({1, dynamixel::Family::X430}, dynamixel::Reg::PresentTemperature);
  if (temperature.ok() && servos.GetLastReply().alert) {
    // Bit 7 of the error byte: the servo reports a hardware error. The data is valid.
    std::printf("servo 1 alert, error byte 0x%02X\n",
                static_cast<unsigned>(servos.GetLatchedAlert().error_byte));
    servos.ClearLatchedAlert();
  }
}

A servo with a hardware error pending sets the alert flag in its reply (bit 7 of the error byte in protocol 2.0; the voltage, temperature and overload flags in protocol 1.0). With AlertPolicy::Report (the default) the call succeeds with valid data and the alert is latched until ClearLatchedAlert(); with AlertPolicy::Fail the call returns DeviceFault and no data. Read Reg::HardwareErrorStatus for the cause.

Handle errors

const char* Describe(dynamixel::Error e) {
  switch (e) {
  case dynamixel::Error::Timeout:
    return "no answer: ID, baud rate, protocol or wiring";
  case dynamixel::Error::LineFault:
    return "the line is stuck or floating: check power and the direction control";
  case dynamixel::Error::EchoMismatch:
    return "the echo differs: another talker on the bus, or the loopback setting is wrong";
  case dynamixel::Error::DeviceError:
    return "the servo refused the instruction: see GetLastReply().error_byte";
  case dynamixel::Error::NotPermitted:
    return "destructive instruction: set Config::allow_destructive on purpose";
  default:
    return dynamixel::ToString(e);
  }
}
Signal Meaning What to do
Error::Timeout No complete reply The servo's power, ID, rate, protocol, the direction control; raise reply_timeout_us
Error::LineFault The line is stuck or floating Power, ground, the half-duplex stage; then Resync()
Error::EchoMismatch The echo differs from the request Another talker, or Config::echo is wrong
Error::Crc, InvalidReply A damaged or malformed reply The rate, the ground, the cable; Resync()
Error::DeviceError The servo refused the instruction GetLastReply().error_byte; often an EEPROM write with the torque on
Error::DeviceFault A hardware alert with AlertPolicy::Fail Reg::HardwareErrorStatus
Error::NotPermitted A destructive call without consent Config::allow_destructive, on purpose
Error::Bus Your port reported a failure The port and the UART

Every value, with the calls that return it, is on the Contract page, and Troubleshooting goes through each. dynamixel::ToString() names an error for a log.

Reset a servo

dynamixel::Error ResetToFactory(MyPort& port, dynamixel::Config config) {
  config.allow_destructive =
      true; // the one switch that unlocks reset, restore and broadcast ID writes
  static Servos servos(port, config);
  return servos.FactoryReset(1, dynamixel::ResetOption::KeepIdAndBaud).error;
}

Factory Reset, Control Table Restore (Backup() with BackupOption::Restore), Clear() and an ID write to every servo (SetId() with the broadcast ID) change or erase what a servo keeps, so they return NotPermitted unless Config::allow_destructive is set. A reset can change the ID and baud rate: ResetOption::KeepIdAndBaud keeps them. After a reset or a reboot the driver waits Config::reboot_wait_us before the next call. Backup() with BackupOption::Store is not behind that flag: it overwrites the servo's backup area but nothing the servo runs on.

SetStatusReturnLevel() adopts a lower level when the answer to its write is silent, because the servo stops answering at the new level. A lost write looks the same, so the driver logs a warning in that case: read the register back to verify.

Diagnostics

For bring-up and fault finding the driver keeps what it saw (handbook KB-CPP-119, KB-CPP-129), with no I/O:

Call What it gives
GetLastRequest() The bytes of the last instruction packet, as put on the line
GetLastReply() The decoded error byte of the last status packet
GetLatchedAlert(), ClearLatchedAlert() The first alert since the last clear
GetStats(), ResetStats() Transactions, retries, timeouts, CRC errors, garbage bytes, line faults

Shut down

void PowerDown(Servos& servos) {
  // No bus traffic: the servos keep their state. Stop them first when they must not move.
  static_cast<void>(servos.DisableTorqueAll(dynamixel::Family::X430));
  static_cast<void>(servos.Deinitialize());
}

After Deinitialize() every call that uses the bus returns NotInitialized until the next EnsureInitialized(). Deinitialize() sends nothing: the servos keep their state, so stop them first when they must not move.

Next: Configuration.