Architecture of the library =========================== .. highlight:: C++ 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 :cpp: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: * :cpp:class:`Ping\ `: check availability of an actuator with given ID * :cpp:class:`Read\ `: read some data in the RAM or ROM of an actuator * :cpp:class:`Write\ `: write some data in the RAM or ROM of an actuator * :cpp:class:`RegWrite\ `: register a write instruction to be performed later (on receival of the *action* instruction) * :cpp:class:`Action\ `: trigger the registered write instruction * :cpp:class:`FactoryReset\ `: reset the ROM of the actuator to factory defaults * :cpp:class:`SyncWrite\ `: simultaneously write data for several servos (one memory address, many servos, many data) * :cpp:class:`Reboot\ ` (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 :cpp:class:`StatusPacket\ ` 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 :menuselection:`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 :cpp:class:`ModelTraits\ `, templated by the servo. This makes a unified yet extensible interface to all actuators. Along the control table, the :code:`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 :cpp:class:`BaseServo\ ` abstract class declares all possible methods to interact with an actuator. They all throw a "not implemented" exception. Then, :cpp:class:`Servo ` inherits of :cpp:class:`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 :code:`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 :cpp:class:`ProtocolSpecificPackets\ ` is for these operations: * convert the speed from unit-less integer to radians per second