Architecture of the library

In this document we will describe how the library communicates with dynamixel actuators.

The two protocols

The client interacts with Dynamixels by sending instructions and receiving status reports, both in forms of packets. Robotis has two versions of its communication protocol defining diferent packet formats and contents. We have a class for each protocol containing:

  • type definitions for protocol-specific data
  • the instructions allowed in the protocol
  • methods to build a packet from data (pack_data) and extract data from incoming packet (unpack_data)

Note

Unless said overwise, everything written bellow is common to versions 1 and 2 of the communication protocols.

Serial interface

All communication with the dynamixel has to go through a serial interface. We support both USB2AX and USB2DYNAMIXEL in the class controllers::Usb2Dynamixel. Other serial interfaces should also work.

Instructions and status report

Instructions are packets sent to the actuators and status reports are the replies that the user may get (not for every instruction). There are different instruction kinds and a class is defined for each instruction.

Supported instructions:

  • Ping<class Protocol>: check availability of an actuator with given ID
  • Read<class Protocol>: read some data in the RAM or ROM of an actuator
  • Write<class Protocol>: write some data in the RAM or ROM of an actuator
  • RegWrite<class Protocol>: register a write instruction to be performed later (on receival of the action instruction)
  • Action<class Protocol>: trigger the registered write instruction
  • FactoryReset<class Protocol>: reset the ROM of the actuator to factory defaults
  • SyncWrite<class Protocol>: simultaneously write data for several servos (one memory address, many servos, many data)
  • Reboot<class Protocol> (only for protocol 2)

Note

The following instructions, specific to protocol 2, are not implemented yet:

  • Sync read: same as sync write but for reading
  • Bulk write: simultaneously write data for several (many addresses, many servos, many data)
  • Bulk read: same as bulk write but for reading

Likewise, the StatusPacket<class Protocol> class is for the status report packet. A status packet can report errors in the communication or related to an actuator. It could be for instance a checksum error or an overheating error. Such packets are sent in response to any packet, unless it was sent to the broadcast ID. Some actuators also allow to configure which instructions trigger a status report.

Note

For more details on how instructions and status packet work, refer to Robotis’ documentation then go to Product Information ‣ Actuator ‣ Communication 1.0/2.0.

Model traits

For a more easy to use client interface, the information specific to each actuator model (including the control table) is stored in the library. We use the trait class ModelTraits<class Model>, templated by the servo. This makes a unified yet extensible interface to all actuators.

Along the control table, the ModelTraits class also defines the protocol version used by each servo.

Todo

give a link to the list of supported actuators

BaseServo, Servo and actuator classes

The BaseServo<class Protocol> abstract class declares all possible methods to interact with an actuator. They all throw a “not implemented” exception. Then, Servo inherits of BaseServo and defines the methods to access the fields common to all actuators. The remainder fields are defined in the actuator secific classes. For instance, the MX 28 actuators have the class Mx28. One such class is defined for every servo model.

Protocol-specific packets

Some operations are common to all actuators that use a given protocol. The templated class ProtocolSpecificPackets<class Model, class Protocol> is for these operations:

  • convert the speed from unit-less integer to radians per second