DYNAMIXEL Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Namespaces | Enumerations | Functions | Variables
dynamixel_protocol.hpp File Reference

The packet layer of DYNAMIXEL protocols 1.0 and 2.0: CRC-16, checksum, byte stuffing, the frame writer, the receive scanner and register value coding. Pure functions, no I/O. More...

#include <array>
#include <cstddef>
#include <cstdint>
#include <span>
#include "dynamixel_detail.hpp"
#include "dynamixel_tables.hpp"
#include "dynamixel_types.hpp"

Go to the source code of this file.

Classes

class  dynamixel::protocol::FrameWriter
 Builds one instruction packet in a caller buffer, with byte stuffing for protocol 2.0. More...
 
struct  dynamixel::protocol::ScanResult
 What Scan() found in the receive buffer. More...
 
struct  dynamixel::protocol::StatusView
 The fields of a located status packet; the spans point into the receive buffer. More...
 

Namespaces

namespace  dynamixel
 The DYNAMIXEL driver: everything it declares lives here; internals in detail.
 

Enumerations

enum class  dynamixel::protocol::Instruction : uint8_t {
  Ping = 0x01 , Read = 0x02 , Write = 0x03 , RegWrite = 0x04 ,
  Action = 0x05 , FactoryReset = 0x06 , Reboot = 0x08 , Clear = 0x10 ,
  Backup = 0x20 , Status = 0x55 , SyncRead = 0x82 , SyncWrite = 0x83 ,
  FastSyncRead = 0x8A , BulkRead = 0x92 , BulkWrite = 0x93 , FastBulkRead = 0x9A
}
 Instruction codes of both protocols (the e-Manual instruction tables). More...
 

Functions

constexpr std::array< uint16_t, 256 > dynamixel::protocol::detail_crc::MakeTable () noexcept
 The CRC-16 lookup table, generated at build time from the polynomial 0x8005.
 
constexpr uint16_t dynamixel::protocol::Crc16 (uint16_t crc, std::span< const uint8_t > data) noexcept
 Continue a protocol 2.0 CRC-16 over more bytes.
 
constexpr uint8_t dynamixel::protocol::Checksum1 (std::span< const uint8_t > data) noexcept
 The protocol 1.0 checksum of the bytes from the ID to the last parameter.
 
constexpr std::size_t dynamixel::protocol::Destuff (std::span< uint8_t > params) noexcept
 Remove the stuffed bytes of received protocol 2.0 parameters, in place.
 
constexpr bool dynamixel::protocol::detail_scan::MatchesV2 (std::span< const uint8_t > b, std::size_t i) noexcept
 Whether the four bytes at i are the protocol 2.0 header FF FF FD 00.
 
constexpr bool dynamixel::protocol::detail_scan::IsPartialHeader (Protocol protocol, std::span< const uint8_t > bytes, std::size_t pos, std::size_t left) noexcept
 Whether the left bytes at pos (fewer than a header) are the start of one.
 
constexpr bool dynamixel::protocol::detail_scan::IsCandidate (Protocol protocol, std::span< const uint8_t > bytes, std::size_t pos, std::size_t left) noexcept
 Whether a full header starts at pos.
 
constexpr bool dynamixel::protocol::detail_scan::IsPlausible (Protocol protocol, std::span< const uint8_t > bytes, std::size_t pos, std::size_t left, std::size_t max_frame, std::size_t &total) noexcept
 The size a candidate packet claims, and whether that claim is plausible.
 
constexpr bool dynamixel::protocol::detail_scan::IsChecked (Protocol protocol, std::span< const uint8_t > frame) noexcept
 Whether the CRC-16 or checksum of a complete packet matches.
 
constexpr ScanResult dynamixel::protocol::Scan (Protocol protocol, std::span< const uint8_t > bytes, std::size_t max_frame) noexcept
 Find the first valid status packet in received bytes, skipping garbage and resynchronising after a damaged packet.
 
constexpr StatusView dynamixel::protocol::Split (Protocol protocol, std::span< uint8_t > frame) noexcept
 Split a valid status packet found by Scan().
 
constexpr uint32_t dynamixel::protocol::LoadLe (std::span< const uint8_t > data) noexcept
 Read a little-endian unsigned value of 1 to 4 bytes.
 
constexpr int32_t dynamixel::protocol::DecodeValue (Kind kind, std::span< const uint8_t > data) noexcept
 Decode a register's raw bytes.
 
constexpr bool dynamixel::protocol::EncodeValue (Kind kind, std::size_t size, int32_t value, std::span< uint8_t, 4 > out) noexcept
 Encode a value into a register's raw bytes.
 

Variables

constexpr std::array< uint8_t, 4 > dynamixel::protocol::kHeaderV2 {0xFF, 0xFF, 0xFD, 0x00}
 First three bytes of a protocol 2.0 header (the fourth is the reserved 0x00).
 
constexpr std::size_t dynamixel::protocol::kPrefixV2 = 8
 
constexpr std::size_t dynamixel::protocol::kPrefixV1 = 5
 
constexpr std::size_t dynamixel::protocol::kOverheadV2 = kPrefixV2 + 2U
 Fixed bytes of a protocol 2.0 packet around its parameters (prefix and CRC).
 
constexpr std::size_t dynamixel::protocol::kOverheadV1 = kPrefixV1 + 1U
 Fixed bytes of a protocol 1.0 packet around its parameters (prefix and checksum).
 
constexpr std::size_t dynamixel::protocol::kMaxParamsV1 = 253
 
constexpr std::array< uint16_t, 256 > dynamixel::protocol::detail_crc::kTable = MakeTable()
 The table MakeTable() built.
 
constexpr std::size_t dynamixel::protocol::kBadStuffing = static_cast<std::size_t>(-1)
 Returned by Destuff() for parameters that are not validly stuffed.
 

Detailed Description

The packet layer of DYNAMIXEL protocols 1.0 and 2.0: CRC-16, checksum, byte stuffing, the frame writer, the receive scanner and register value coding. Pure functions, no I/O.

Protocol 2.0 packet: FF FF FD 00 | ID | LEN_L LEN_H | INST | PARAM... | CRC_L CRC_H; LEN counts the instruction, the parameters and the CRC; a status packet carries the error byte as its first parameter. Byte stuffing inserts FD after every FF FF FD of the parameters (e-Manual, protocol 2.0, "Packet Process"). CRC-16 is polynomial 0x8005, initial value 0, no reflection (e-Manual, "CRC Calculation"), computed over the stuffed packet from the header to the last parameter. Protocol 1.0 packet: FF FF | ID | LEN | INST | PARAM... | CHK, LEN = parameters + 2, CHK = ~(ID + LEN + INST + PARAM...) (e-Manual, protocol 1.0).

Enumeration Type Documentation

◆ Instruction

enum class dynamixel::protocol::Instruction : uint8_t
strong

Instruction codes of both protocols (the e-Manual instruction tables).

Enumerator
Ping 

Ping (both).

Read 

Read (both).

Write 

Write (both).

RegWrite 

Reg Write (both).

Action 

Action (both).

FactoryReset 

Factory Reset (both; protocol 2.0 has an option byte).

Reboot 

Reboot (both).

Clear 

Clear (protocol 2.0).

Backup 

Control Table Backup (protocol 2.0).

Status 

Status (return) packet (protocol 2.0).

SyncRead 

Sync Read (protocol 2.0).

SyncWrite 

Sync Write (both).

FastSyncRead 

Fast Sync Read (protocol 2.0).

BulkRead 

Bulk Read (both, different parameter layouts).

BulkWrite 

Bulk Write (protocol 2.0).

FastBulkRead 

Fast Bulk Read (protocol 2.0).

Function Documentation

◆ Checksum1()

constexpr uint8_t dynamixel::protocol::Checksum1 ( std::span< const uint8_t >  data)
constexprnoexcept

The protocol 1.0 checksum of the bytes from the ID to the last parameter.

Parameters
dataID, length, instruction or error byte, parameters.
Returns
The bitwise complement of the low byte of their sum.

◆ Crc16()

constexpr uint16_t dynamixel::protocol::Crc16 ( uint16_t  crc,
std::span< const uint8_t >  data 
)
constexprnoexcept

Continue a protocol 2.0 CRC-16 over more bytes.

Parameters
crcThe CRC so far (0 at the start).
dataThe bytes.
Returns
The new CRC.

◆ DecodeValue()

constexpr int32_t dynamixel::protocol::DecodeValue ( Kind  kind,
std::span< const uint8_t >  data 
)
constexprnoexcept

Decode a register's raw bytes.

Parameters
kindThe decoding of the register.
dataThe raw bytes, 1, 2 or 4.
Returns
The value as a signed 32-bit number.

◆ Destuff()

constexpr std::size_t dynamixel::protocol::Destuff ( std::span< uint8_t >  params)
constexprnoexcept

Remove the stuffed bytes of received protocol 2.0 parameters, in place.

Parameters
paramsThe parameters as received (CRC already checked).
Returns
The unstuffed length, or kBadStuffing when an FF FF FD is not followed by FD.

◆ EncodeValue()

constexpr bool dynamixel::protocol::EncodeValue ( Kind  kind,
std::size_t  size,
int32_t  value,
std::span< uint8_t, 4 >  out 
)
constexprnoexcept

Encode a value into a register's raw bytes.

Parameters
kindThe decoding of the register.
sizeThe register size, 1, 2 or 4.
valueThe value to write.
outReceives size bytes, low byte first.
Returns
false when the value does not fit the register (nothing is written).

◆ IsCandidate()

constexpr bool dynamixel::protocol::detail_scan::IsCandidate ( Protocol  protocol,
std::span< const uint8_t >  bytes,
std::size_t  pos,
std::size_t  left 
)
constexprnoexcept

Whether a full header starts at pos.

Parameters
protocolThe packet format.
bytesThe receive bytes.
posThe offset.
leftHow many bytes there are from pos, at least a header.
Returns
true on a header.

◆ IsChecked()

constexpr bool dynamixel::protocol::detail_scan::IsChecked ( Protocol  protocol,
std::span< const uint8_t >  frame 
)
constexprnoexcept

Whether the CRC-16 or checksum of a complete packet matches.

Parameters
protocolThe packet format.
frameThe whole packet.
Returns
true when it does.

◆ IsPartialHeader()

constexpr bool dynamixel::protocol::detail_scan::IsPartialHeader ( Protocol  protocol,
std::span< const uint8_t >  bytes,
std::size_t  pos,
std::size_t  left 
)
constexprnoexcept

Whether the left bytes at pos (fewer than a header) are the start of one.

Parameters
protocolThe packet format.
bytesThe receive bytes.
posThe offset of the bytes.
leftHow many bytes there are from pos.
Returns
true when every byte matches the header's beginning.

◆ IsPlausible()

constexpr bool dynamixel::protocol::detail_scan::IsPlausible ( Protocol  protocol,
std::span< const uint8_t >  bytes,
std::size_t  pos,
std::size_t  left,
std::size_t  max_frame,
std::size_t &  total 
)
constexprnoexcept

The size a candidate packet claims, and whether that claim is plausible.

Parameters
protocolThe packet format.
bytesThe receive bytes.
posThe offset of the candidate; its length field is inside bytes.
leftHow many bytes there are from pos.
max_frameThe largest packet the receive buffer holds.
totalSet to the claimed packet size.
Returns
true when the length, the size and (where visible) the instruction or ID are acceptable.

◆ LoadLe()

constexpr uint32_t dynamixel::protocol::LoadLe ( std::span< const uint8_t >  data)
constexprnoexcept

Read a little-endian unsigned value of 1 to 4 bytes.

Parameters
dataThe bytes.
Returns
The value; 0 for an empty or over-long span.

◆ MakeTable()

constexpr std::array< uint16_t, 256 > dynamixel::protocol::detail_crc::MakeTable ( )
constexprnoexcept

The CRC-16 lookup table, generated at build time from the polynomial 0x8005.

Returns
The 256 entries of the table.

◆ MatchesV2()

constexpr bool dynamixel::protocol::detail_scan::MatchesV2 ( std::span< const uint8_t >  b,
std::size_t  i 
)
constexprnoexcept

Whether the four bytes at i are the protocol 2.0 header FF FF FD 00.

Parameters
bThe receive bytes; i + 3 must be inside.
iThe offset to test.
Returns
true on a header.

◆ Scan()

constexpr ScanResult dynamixel::protocol::Scan ( Protocol  protocol,
std::span< const uint8_t >  bytes,
std::size_t  max_frame 
)
constexprnoexcept

Find the first valid status packet in received bytes, skipping garbage and resynchronising after a damaged packet.

A candidate is a header followed by an in-range length; it is valid when it fits max_frame, its instruction byte is the status instruction (protocol 2.0) and its CRC or checksum matches. A damaged candidate is dropped by one byte and the search continues inside it, so a real packet that starts within the damaged bytes is still found.

Parameters
protocolThe packet format.
bytesWhat the port returned so far.
max_frameThe largest packet the receive buffer holds.
Returns
The result; see ScanResult.

◆ Split()

constexpr StatusView dynamixel::protocol::Split ( Protocol  protocol,
std::span< uint8_t >  frame 
)
constexprnoexcept

Split a valid status packet found by Scan().

Parameters
protocolThe packet format.
frameThe whole packet.
Returns
The fields.

Variable Documentation

◆ kMaxParamsV1

constexpr std::size_t dynamixel::protocol::kMaxParamsV1 = 253
inlineconstexpr

The most parameters a protocol 1.0 packet holds: the length byte (255) minus instruction and checksum.

◆ kPrefixV1

constexpr std::size_t dynamixel::protocol::kPrefixV1 = 5
inlineconstexpr

Bytes before the parameters of a protocol 1.0 instruction packet: header, ID, length, instruction.

◆ kPrefixV2

constexpr std::size_t dynamixel::protocol::kPrefixV2 = 8
inlineconstexpr

Bytes before the parameters of a protocol 2.0 instruction packet: header, ID, length, instruction.