DYNAMIXEL Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Enumerations | Functions | Variables
Driver types

Errors, results, replies, statistics and configuration. More...

Namespaces

namespace  dynamixel::p1_error
 Protocol 1.0 error flags (the error byte of a status packet).
 
namespace  dynamixel::hw_error
 Bits of the X-series Hardware Error Status register (address 70) and the Shutdown register.
 

Classes

struct  dynamixel::Result< T >
 The value of a call, or why there is none. More...
 
struct  dynamixel::Result< void >
 The result of a call that returns no value. More...
 
struct  dynamixel::ReplyInfo
 An error byte, decoded. More...
 
struct  dynamixel::PingInfo
 The identity a ping returns. More...
 
struct  dynamixel::ServoRef
 A servo on the bus: its ID and its control-table family. More...
 
struct  dynamixel::DeviceReply
 The per-device outcome of a Sync Read, Bulk Read or Fast read. More...
 
struct  dynamixel::BulkReadItem
 One device of a Bulk Read request. More...
 
struct  dynamixel::BulkWriteItem
 One device of a Bulk Write request. More...
 
struct  dynamixel::Feedback
 Position, velocity, effort, voltage and temperature of a servo, read in one transfer. More...
 
struct  dynamixel::Stats
 What the driver counted since ResetStats(). More...
 
struct  dynamixel::Config
 Everything the driver needs to know about the bus. More...
 
class  dynamixel::CheckedConfig
 A configuration proven valid at build time. More...
 

Enumerations

enum class  dynamixel::Error : uint8_t {
  dynamixel::Error::Ok = 0 , dynamixel::Error::NotInitialized = 1 , dynamixel::Error::InvalidArgument = 2 , dynamixel::Error::Bus = 3 ,
  dynamixel::Error::Timeout = 4 , dynamixel::Error::DeviceIdMismatch , dynamixel::Error::Crc = 6 , dynamixel::Error::Busy = 7 ,
  dynamixel::Error::DeviceFault = 8 , dynamixel::Error::Unsupported = 9 , dynamixel::Error::DeviceError , dynamixel::Error::InvalidReply ,
  dynamixel::Error::EchoMismatch = 18 , dynamixel::Error::LineFault = 19 , dynamixel::Error::NotPermitted = 22
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  dynamixel::LogLevel : uint8_t { dynamixel::LogLevel::Error = 0 , dynamixel::LogLevel::Warning , dynamixel::LogLevel::Info , dynamixel::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  dynamixel::Protocol : uint8_t { dynamixel::Protocol::V1 = 0 , dynamixel::Protocol::V2 = 1 }
 The packet format of the bus: one per DYNAMIXEL object, because every servo on a bus shares it. More...
 
enum class  dynamixel::EchoMode : uint8_t { dynamixel::EchoMode::None = 0 , dynamixel::EchoMode::Loopback = 1 }
 Whether the transmitted bytes come back on the receive line (a single-wire loopback). More...
 
enum class  dynamixel::AlertPolicy : uint8_t { dynamixel::AlertPolicy::Report = 0 , dynamixel::AlertPolicy::Fail = 1 }
 What a reply with a hardware alert means for the call. More...
 
enum class  dynamixel::StatusReturn : uint8_t { dynamixel::StatusReturn::PingOnly = 0 , dynamixel::StatusReturn::ReadOnly = 1 , dynamixel::StatusReturn::All = 2 }
 How much a servo answers (the Status Return Level register, values 0 to 2). More...
 
enum class  dynamixel::ResetOption : uint8_t { dynamixel::ResetOption::KeepIdAndBaud = 0x02 , dynamixel::ResetOption::KeepId = 0x01 , dynamixel::ResetOption::All = 0xFF }
 The option byte of a Factory Reset instruction (protocol 2.0). More...
 
enum class  dynamixel::ClearOption : uint8_t { dynamixel::ClearOption::MultiTurn = 0x01 , dynamixel::ClearOption::Errors = 0x02 }
 The option of a Clear instruction (protocol 2.0). More...
 
enum class  dynamixel::BackupOption : uint8_t { dynamixel::BackupOption::Store = 0x01 , dynamixel::BackupOption::Restore = 0x02 }
 The option of a Control Table Backup instruction (protocol 2.0). More...
 
enum class  dynamixel::Protocol2Error : uint8_t {
  dynamixel::Protocol2Error::None = 0 , dynamixel::Protocol2Error::ResultFail = 1 , dynamixel::Protocol2Error::InstructionError = 2 , dynamixel::Protocol2Error::CrcError = 3 ,
  dynamixel::Protocol2Error::DataRangeError = 4 , dynamixel::Protocol2Error::DataLengthError = 5 , dynamixel::Protocol2Error::DataLimitError = 6 , dynamixel::Protocol2Error::AccessError
}
 Protocol 2.0 error numbers (bits 6..0 of the error byte of a status packet). More...
 

Functions

constexpr const char * dynamixel::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Config dynamixel::FastBusPreset () noexcept
 Calls on a bus of servos that all answer: the shortest sensible setup for a first test.
 
constexpr Config dynamixel::UsbAdapterPreset () noexcept
 A bus on a USB adapter whose receive buffer is flushed in 16 ms steps.
 
constexpr Config dynamixel::LegacyBusPreset () noexcept
 The legacy bus: protocol 1.0 at 1 Mbit/s with the single-wire loopback of a half-duplex adapter.
 
constexpr Error dynamixel::Validate (const Config &config) noexcept
 Check a configuration without touching the bus.
 
constexpr ReplyInfo dynamixel::Classify (Protocol protocol, uint8_t id, uint8_t error_byte) noexcept
 Decode the error byte of a status packet.
 
constexpr Protocol2Error dynamixel::ErrorNumber (uint8_t error_byte) noexcept
 The protocol 2.0 error number of an error byte.
 
void dynamixel::ConfigIsInvalid () noexcept
 Reached only when a CheckedConfig is built from an invalid configuration: it is never defined, so the build fails and names it (KB-CPP20-013).
 
constexpr const char * dynamixel::GetDriverVersion () noexcept
 
constexpr uint32_t dynamixel::GetDriverVersionMajor () noexcept
 
constexpr uint32_t dynamixel::GetDriverVersionMinor () noexcept
 
constexpr uint32_t dynamixel::GetDriverVersionPatch () noexcept
 

Variables

constexpr uint8_t dynamixel::kAlertBit = 0x80
 Protocol 2.0 alert bit of the error byte.
 
constexpr uint8_t dynamixel::kBroadcastId = 0xFE
 The broadcast ID: an instruction to it reaches every servo and none answers.
 
constexpr uint8_t dynamixel::kMaxIdV2 = 252
 The largest valid servo ID of protocol 2.0.
 
constexpr uint8_t dynamixel::kMaxIdV1 = 253
 The largest valid servo ID of protocol 1.0.
 
constexpr uint32_t dynamixel::kMinTimeoutUs = 100
 Shortest and longest reply wait the driver accepts, microseconds (KB-CPP20-058).
 
constexpr uint32_t dynamixel::kMaxTimeoutUs = 1'000'000
 Longest timeout the driver accepts: one second.
 
constexpr uint32_t dynamixel::kMaxSettleUs = 10'000'000
 Longest settle time after a reboot or factory reset the driver accepts: 10 seconds.
 
constexpr uint32_t dynamixel::kMinBaud = 9'600
 Lowest and highest bit rate the driver accepts for Config::baud.
 
constexpr uint32_t dynamixel::kMaxBaud = 10'500'000
 Highest bit rate the driver accepts (the e-Manual lists up to 4.5 Mbit/s, the P series 10.5).
 
constexpr uint8_t dynamixel::kMaxRetries = 5
 The most repeats of an idempotent instruction Config::retries allows.
 

Detailed Description

Errors, results, replies, statistics and configuration.

Enumeration Type Documentation

◆ AlertPolicy

enum class dynamixel::AlertPolicy : uint8_t
strong

What a reply with a hardware alert means for the call.

Enumerator
Report 

The call succeeds, the data is returned and the alert is latched (GetLatchedAlert()).

Fail 

The call returns DeviceFault and discards the data; the alert is latched too.

◆ BackupOption

enum class dynamixel::BackupOption : uint8_t
strong

The option of a Control Table Backup instruction (protocol 2.0).

Enumerator
Store 

Store the control table in the backup area (torque must be off).

Restore 

Restore the EEPROM from the backup; the servo reboots.

◆ ClearOption

enum class dynamixel::ClearOption : uint8_t
strong

The option of a Clear instruction (protocol 2.0).

Enumerator
MultiTurn 

Reset the present position to one turn (0 to 4095); only while stopped.

Errors 

Clear registered errors (Y series only in the e-Manual).

◆ EchoMode

enum class dynamixel::EchoMode : uint8_t
strong

Whether the transmitted bytes come back on the receive line (a single-wire loopback).

Enumerator
None 

Separate lines or a direction-controlled transceiver: nothing is echoed.

Loopback 

TX and RX are tied: every sent byte is read back and compared.

◆ Error

enum class dynamixel::Error : uint8_t
strong

Why a call failed. Every call of the driver returns one of these in its Result.

Values 0 to 9 are the shared base set; bus-specific values start at 16. [[nodiscard]] on the type: a function that returns a bare Error cannot have it ignored either (KB-CPP20-037).

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded, or Deinitialize() ran since.

InvalidArgument 

An argument or a Config field is out of range; nothing was sent.

Bus 

A port hook returned false.

Timeout 

No complete reply within the deadline (nothing, or a truncated packet).

DeviceIdMismatch 

The reply came from another ID than the one addressed, or the model differs.

Crc 

The CRC-16 (protocol 2.0) or checksum (protocol 1.0) of a reply did not match.

Busy 

Reserved by the shared set; this driver has no pending state.

DeviceFault 

The servo reported a hardware alert and AlertPolicy::Fail is set.

Unsupported 

The hook, protocol or family does not offer this call.

DeviceError 

The servo rejected the instruction: see GetLastReply() for the error number.

InvalidReply 

A reply the protocol refuses: header, length, instruction or parameter count.

EchoMismatch 

The transmitted bytes were not read back as sent (collision or wiring).

LineFault 

The line carried only 0x00 or only 0xFF: stuck low, stuck high or floating.

NotPermitted 

A destructive instruction without Config::allow_destructive.

◆ LogLevel

enum class dynamixel::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events: initialised, resynchronised.

Debug 

Detail for bring-up.

◆ Protocol

enum class dynamixel::Protocol : uint8_t
strong

The packet format of the bus: one per DYNAMIXEL object, because every servo on a bus shares it.

Enumerator
V1 

Protocol 1.0: header FF FF, one-byte length, additive checksum, error flags.

V2 

Protocol 2.0: header FF FF FD 00, two-byte length, CRC-16, byte stuffing, error number.

◆ Protocol2Error

enum class dynamixel::Protocol2Error : uint8_t
strong

Protocol 2.0 error numbers (bits 6..0 of the error byte of a status packet).

Enumerator
None 

No error.

ResultFail 

The instruction could not be processed.

InstructionError 

Undefined instruction, or Action without a Reg Write.

CrcError 

The servo's CRC check of the instruction failed.

DataRangeError 

The value is outside the register's range.

DataLengthError 

The data is shorter than the register.

DataLimitError 

The value is outside a configured limit.

AccessError 

Read-only, write-only or undefined address, or an EEPROM write with torque on.

◆ ResetOption

enum class dynamixel::ResetOption : uint8_t
strong

The option byte of a Factory Reset instruction (protocol 2.0).

Enumerator
KeepIdAndBaud 

Reset all except ID and baud rate.

KeepId 

Reset all except ID.

All 

Reset all; the servo returns to ID 1 and 57 600 bit/s.

◆ StatusReturn

enum class dynamixel::StatusReturn : uint8_t
strong

How much a servo answers (the Status Return Level register, values 0 to 2).

Enumerator
PingOnly 

Only ping instructions are answered.

ReadOnly 

Ping and read instructions are answered.

All 

Every instruction addressed to one servo is answered. Factory default.

Function Documentation

◆ Classify()

constexpr ReplyInfo dynamixel::Classify ( Protocol  protocol,
uint8_t  id,
uint8_t  error_byte 
)
constexprnoexcept

Decode the error byte of a status packet.

Parameters
protocolThe protocol the packet used.
idThe ID the packet came from.
error_byteThe raw error byte.
Returns
The decoded ReplyInfo.

◆ ErrorNumber()

constexpr Protocol2Error dynamixel::ErrorNumber ( uint8_t  error_byte)
constexprnoexcept

The protocol 2.0 error number of an error byte.

Parameters
error_byteThe raw error byte.
Returns
The number, or Protocol2Error::None; a number the e-Manual does not define maps to ResultFail.

◆ FastBusPreset()

constexpr Config dynamixel::FastBusPreset ( )
constexprnoexcept

Calls on a bus of servos that all answer: the shortest sensible setup for a first test.

Returns
A configuration with a 10 ms reply timeout.

◆ GetDriverVersion()

constexpr const char * dynamixel::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0", from the generated dynamixel_version.h. No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t dynamixel::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t dynamixel::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t dynamixel::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ LegacyBusPreset()

constexpr Config dynamixel::LegacyBusPreset ( )
constexprnoexcept

The legacy bus: protocol 1.0 at 1 Mbit/s with the single-wire loopback of a half-duplex adapter.

Returns
A protocol 1.0 configuration.

◆ ToString()

constexpr const char * dynamixel::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string such as "Timeout"; "Unknown" for a value that is not an enumerator.

◆ UsbAdapterPreset()

constexpr Config dynamixel::UsbAdapterPreset ( )
constexprnoexcept

A bus on a USB adapter whose receive buffer is flushed in 16 ms steps.

Returns
A configuration with long timeouts that tolerate the adapter's latency timer.

◆ Validate()

constexpr Error dynamixel::Validate ( const Config &  config)
constexprnoexcept

Check a configuration without touching the bus.

Fails when an enum holds a value that is not an enumerator, the baud rate is outside kMinBaud to kMaxBaud, a timeout is outside kMinTimeoutUs to kMaxTimeoutUs, a wait is above kMaxSettleUs, or retries exceeds kMaxRetries.

Parameters
configThe configuration.
Returns
Error::Ok or Error::InvalidArgument.