Protocol¶
The two DYNAMIXEL packet protocols as the driver implements them: the packet layout, the byte stuffing, the CRC, how a reply is found in the receive bytes and which instruction each protocol has.
Datasheet sections this page relies on
- Instruction packet layout: ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark, 2 Instruction Packet, p. 1
- 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
- Response policy and the broadcast ID: ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark, 3.4 Response Policy, p. 1
- Packet process, header and byte stuffing: ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark, 4 Packet Process, 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 packets and checksum: ROBOTIS e-Manual, DYNAMIXEL Protocol 1.0 web page, no revision mark, 2 Instruction Packet; 2.6 Checksum; 3 Status Packet; 3.2 Checksum, 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
- Protocol 1.0 error byte: ROBOTIS e-Manual, DYNAMIXEL Protocol 1.0 web page, no revision mark, 3.1 Error, p. 1
- CRC-16 of protocol 2.0 packets: ROBOTIS e-Manual, CRC Calculation web page, no revision mark, CRC Calculation, p. 1
All of them, with the driver API for each: Datasheet map.
One bus, one protocol¶
Every servo on a bus speaks the same protocol, chosen by Config::protocol. Protocol 2.0 is the one of the X
series, the MX(2.0) servos and the XL-320; protocol 1.0 is the one of the AX, RX, DX and MX (1.0 firmware)
servos. The X330, XL430, XM, XH, XD and XW servos can be set to either (their Protocol Type register). The driver
does not detect the protocol: a wrong choice shows as Error::Timeout on every call, because a servo drops a packet
it cannot parse.
Protocol 2.0 packets¶
| Field | Bytes | Value |
|---|---|---|
| Header | 4 | FF FF FD 00 |
| ID | 1 | 0 to 252; 254 is the broadcast ID |
| Length | 2 | The bytes after this field: instruction, parameters, CRC |
| Instruction | 1 | See the table below; 55 in a status packet |
| Parameters | n | Stuffed |
| CRC | 2 | CRC-16, polynomial 0x8005, initial value 0, low byte first, over everything before it |
A status packet carries the error byte and then the parameters. Bit 7 of the error byte is the alert (the servo has
a hardware error pending, see its Hardware Error Status register); bits 6 to 0 are the error number
(Protocol2Error).
Byte stuffing. The header must not occur inside a packet, so the sender inserts one FD after every FF FF FD
in the parameters, and the Length counts the inserted byte. protocol::FrameWriter stuffs while it builds a packet
and protocol::Destuff() removes it from a reply; an FF FF FD not followed by FD is a bad packet
(Error::InvalidReply). The driver sizes its buffer for the worst case: every third parameter byte stuffed.
Protocol 1.0 packets¶
| Field | Bytes | Value |
|---|---|---|
| Header | 2 | FF FF |
| ID | 1 | 0 to 253; 254 is the broadcast ID |
| Length | 1 | Parameters plus 2 |
| Instruction | 1 | In a status packet, the error byte |
| Parameters | n | 0 to 253 |
| Checksum | 1 | The complement of the low byte of the sum from the ID to the last parameter |
The error byte is a set of flags (p1_error). The driver splits them in two: the command faults (angle limit,
range, checksum, instruction) mean the servo did not carry out the instruction and give Error::DeviceError; the
conditions (input voltage, overheating, overload) report the servo's state next to valid data and are handled by
Config::alert_policy.
Instructions¶
| Instruction | Code | Protocol | Driver call |
|---|---|---|---|
| Ping | 01 |
1.0, 2.0 | Ping(), Identify(), BroadcastPing(), ScanIds() |
| Read | 02 |
1.0, 2.0 | Read(), ReadRegister(), ReadFeedback() |
| Write | 03 |
1.0, 2.0 | Write(), WriteRegister(), SetTorque(), SetGoalPosition() |
| Reg Write | 04 |
1.0, 2.0 | RegWrite() |
| Action | 05 |
1.0, 2.0 | Action() |
| Factory Reset | 06 |
1.0, 2.0 | FactoryReset() |
| Reboot | 08 |
1.0, 2.0 | Reboot() |
| Clear | 10 |
2.0 | Clear() |
| Control Table Backup | 20 |
2.0 | Backup() |
| Sync Read | 82 |
2.0 | SyncRead() |
| Sync Write | 83 |
1.0, 2.0 | SyncWrite() |
| Fast Sync Read | 8A |
2.0 | FastSyncRead() |
| Bulk Read | 92 |
1.0 (MX and X servos), 2.0 | BulkRead() |
| Bulk Write | 93 |
2.0 | BulkWrite() |
| Fast Bulk Read | 9A |
2.0 | FastBulkRead() |
A call for an instruction the configured protocol does not have returns Error::Unsupported before anything is sent.
Who answers¶
A servo answers according to its Status Return Level register (StatusReturn): a ping always, a read at level 1 and
2, every other instruction at level 2 only. Config::status_return is what the driver expects of the whole bus; a
call that needs an answer the level does not give returns Unsupported instead of waiting for a timeout. The
broadcast ID is answered only for a ping, a sync read and a bulk read (and by each servo in turn: the answers come in
ID order, one reply timeout apart for a broadcast ping, Config::broadcast_timeout_us). A write or an action on
the broadcast ID is sent and Ok means "sent".
Finding the reply¶
The receive bytes can hold garbage, the echo of the request, or a late reply. protocol::Scan() looks for the first
valid status packet:
- It skips bytes until a header. A partial header at the end is kept, because the next read may complete it.
- A candidate needs a plausible length (it must fit the receive buffer) and, in protocol 2.0, the status
instruction
55. - A candidate whose CRC or checksum does not match is dropped by one byte, and the search goes on inside it, so a
real packet that starts within damaged bytes is still found. Each such drop is counted in
Stats::crc_errors. - A packet shorter than its length says is waited for, bounded by
Config::gap_timeout_usper read.
A line that carries only 00 or only FF for a whole candidate is a stuck or floating line: Error::LineFault
(counted in Stats::line_faults), not a timeout, so the wiring is blamed and not the servo.
Fast Sync Read and Fast Bulk Read¶
The servos answer back to back inside one status packet: the first one sends the header, its own part and a CRC,
and each following servo continues the same packet with its part (error byte, ID, data, CRC). The driver parses the
parts one by one, checks each CRC, and fills DeviceReply per ID. A packet that ends early still delivers the parts
that arrived whole and checked; the rest are Timeout. The e-Manual gives the layout of the parts, not what the
first servo puts in the packet header's ID field or the length when a listed servo is silent; the driver accepts
the header of any ID and re-reads the parts it can verify (see Troubleshooting and the
open points in the Contract). Use the plain SyncRead() where the servos' firmware does not list Fast
Sync Read (SupportsFastRead() is advice built from the e-Manual's firmware notes).