DYNAMIXEL Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Concepts | Enumerations | Functions | Variables
dynamixel Namespace Reference

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

Namespaces

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

Classes

struct  BulkReadItem
 One device of a Bulk Read request. More...
 
struct  BulkWriteItem
 One device of a Bulk Write request. More...
 
class  CheckedConfig
 A configuration proven valid at build time. More...
 
struct  Config
 Everything the driver needs to know about the bus. More...
 
struct  DeviceReply
 The per-device outcome of a Sync Read, Bulk Read or Fast read. More...
 
class  DYNAMIXEL
 Master of one DYNAMIXEL bus on a platform port. More...
 
struct  FamilyInfo
 Static facts of a family (e-Manual "Control Table" and "Specifications" pages). More...
 
struct  Feedback
 Position, velocity, effort, voltage and temperature of a servo, read in one transfer. More...
 
struct  IndirectPair
 The area an indirect pair lives in. More...
 
struct  ModelInfo
 One known model number: its family, name and the facts that differ per model. More...
 
struct  PingInfo
 The identity a ping returns. More...
 
struct  RegInfo
 One register of a family's control table. More...
 
struct  ReplyInfo
 An error byte, decoded. More...
 
struct  Result
 The value of a call, or why there is none. More...
 
struct  Result< void >
 The result of a call that returns no value. More...
 
struct  ServoRef
 A servo on the bus: its ID and its control-table family. More...
 
struct  Stats
 What the driver counted since ResetStats(). More...
 
class  UartInterface
 CRTP base of the platform UART port. More...
 

Concepts

concept  UartPort
 Satisfied by a class that derives from UartInterface<Port> and implements the required hooks with exactly the types above and noexcept.
 

Enumerations

enum class  Family : uint8_t {
  Generic = 0 , AxRxDx , Mx28 , Mx64 ,
  Mx106 , Mx28v2 , Mx64v2 , Xl320 ,
  X330 , X430Basic , X430 , X540 ,
  Xw
}
 A servo family: one control table layout (several models share it). More...
 
enum class  Access : uint8_t { ReadOnly = 0 , ReadWrite = 1 }
 Whether a register can be written. More...
 
enum class  Area : uint8_t { Eeprom = 0 , Ram = 1 }
 The memory a register lives in. More...
 
enum class  Kind : uint8_t { Unsigned = 0 , Signed = 1 , SignMag10 = 2 , Offset2048 = 3 }
 How the raw bytes of a register are read as a number. More...
 
enum class  Reg : uint8_t {
  ModelNumber = 0 , FirmwareVersion = 1 , Id = 2 , BaudRate = 3 ,
  ReturnDelayTime = 4 , CwAngleLimit = 5 , CcwAngleLimit = 6 , TemperatureLimit = 7 ,
  MinVoltageLimit = 8 , MaxVoltageLimit = 9 , MaxTorque = 10 , StatusReturnLevel = 11 ,
  AlarmLed = 12 , Shutdown = 13 , TorqueEnable = 14 , Led = 15 ,
  CwComplianceMargin = 16 , CcwComplianceMargin = 17 , CwComplianceSlope = 18 , CcwComplianceSlope = 19 ,
  GoalPosition = 20 , MovingSpeed = 21 , TorqueLimit = 22 , PresentPosition = 23 ,
  PresentVelocity = 24 , PresentLoad = 25 , PresentVoltage = 26 , PresentTemperature = 27 ,
  RegisteredInstruction = 28 , Moving = 29 , Lock = 30 , Punch = 31 ,
  MultiTurnOffset = 32 , ResolutionDivider = 33 , DGain = 34 , IGain = 35 ,
  PGain = 36 , RealtimeTick = 37 , GoalAcceleration = 38 , Current = 39 ,
  TorqueControlModeEnable = 40 , GoalTorque = 41 , DriveMode = 42 , ModelInformation = 43 ,
  OperatingMode = 44 , SecondaryId = 45 , ProtocolType = 46 , HomingOffset = 47 ,
  MovingThreshold = 48 , PwmLimit = 49 , AccelerationLimit = 50 , VelocityLimit = 51 ,
  MaxPositionLimit = 52 , MinPositionLimit = 53 , HardwareErrorStatus = 54 , VelocityIGain = 55 ,
  VelocityPGain = 56 , PositionDGain = 57 , PositionIGain = 58 , PositionPGain = 59 ,
  Feedforward2ndGain = 60 , Feedforward1stGain = 61 , BusWatchdog = 62 , GoalPwm = 63 ,
  GoalVelocity = 64 , ProfileAcceleration = 65 , ProfileVelocity = 66 , MovingStatus = 67 ,
  PresentPwm = 68 , VelocityTrajectory = 69 , PositionTrajectory = 70 , CurrentLimit = 71 ,
  GoalCurrent = 72 , PresentCurrent = 73 , ControlMode = 74 , StartupConfiguration = 75 ,
  PwmSlope = 76 , BackupReady = 77 , ExternalPortMode1 = 78 , ExternalPortMode2 = 79 ,
  ExternalPortMode3 = 80 , ExternalPortData1 = 81 , ExternalPortData2 = 82 , ExternalPortData3 = 83
}
 Family-neutral register names.
 
enum class  BaudScheme : uint8_t {
  None = 0 , Divider = 1 , Table4 = 2 , Table7 = 3 ,
  Table8 = 4
}
 How a family encodes its Baud Rate register. More...
 
enum class  Error : uint8_t {
  Error::Ok = 0 , Error::NotInitialized = 1 , Error::InvalidArgument = 2 , Error::Bus = 3 ,
  Error::Timeout = 4 , Error::DeviceIdMismatch , Error::Crc = 6 , Error::Busy = 7 ,
  Error::DeviceFault = 8 , Error::Unsupported = 9 , Error::DeviceError , Error::InvalidReply ,
  Error::EchoMismatch = 18 , Error::LineFault = 19 , Error::NotPermitted = 22
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  LogLevel : uint8_t { LogLevel::Error = 0 , LogLevel::Warning , LogLevel::Info , LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  Protocol : uint8_t { Protocol::V1 = 0 , Protocol::V2 = 1 }
 The packet format of the bus: one per DYNAMIXEL object, because every servo on a bus shares it. More...
 
enum class  EchoMode : uint8_t { EchoMode::None = 0 , EchoMode::Loopback = 1 }
 Whether the transmitted bytes come back on the receive line (a single-wire loopback). More...
 
enum class  AlertPolicy : uint8_t { AlertPolicy::Report = 0 , AlertPolicy::Fail = 1 }
 What a reply with a hardware alert means for the call. More...
 
enum class  StatusReturn : uint8_t { StatusReturn::PingOnly = 0 , StatusReturn::ReadOnly = 1 , StatusReturn::All = 2 }
 How much a servo answers (the Status Return Level register, values 0 to 2). More...
 
enum class  ResetOption : uint8_t { ResetOption::KeepIdAndBaud = 0x02 , ResetOption::KeepId = 0x01 , ResetOption::All = 0xFF }
 The option byte of a Factory Reset instruction (protocol 2.0). More...
 
enum class  ClearOption : uint8_t { ClearOption::MultiTurn = 0x01 , ClearOption::Errors = 0x02 }
 The option of a Clear instruction (protocol 2.0). More...
 
enum class  BackupOption : uint8_t { BackupOption::Store = 0x01 , BackupOption::Restore = 0x02 }
 The option of a Control Table Backup instruction (protocol 2.0). More...
 
enum class  Protocol2Error : uint8_t {
  Protocol2Error::None = 0 , Protocol2Error::ResultFail = 1 , Protocol2Error::InstructionError = 2 , Protocol2Error::CrcError = 3 ,
  Protocol2Error::DataRangeError = 4 , Protocol2Error::DataLengthError = 5 , Protocol2Error::DataLimitError = 6 , Protocol2Error::AccessError
}
 Protocol 2.0 error numbers (bits 6..0 of the error byte of a status packet). More...
 

Functions

constexpr Config KconfigDefaults () noexcept
 The configuration menuconfig selected, on top of the defaults.
 
constexpr std::span< const RegInfo > Table (Family family) noexcept
 The control table of a family.
 
constexpr const FamilyInfo & Info (Family family) noexcept
 The facts of a family.
 
constexpr const RegInfo * Lookup (Family family, Reg reg) noexcept
 Find a register of a family.
 
constexpr IndirectPair Indirect (Family family, uint32_t index) noexcept
 The registers of indirect pair index (1-based): the indirect address (2 bytes) that points at any control-table address, and the data byte that reads or writes through it (X330: 1..28; others 1..56, where 29..56 lie above address 255 and need protocol 2.0).
 
constexpr bool BaudValueFor (Family family, uint32_t bits_per_second, uint8_t &value) noexcept
 The Baud Rate register value for a bit rate.
 
constexpr uint32_t BaudRateOf (Family family, uint8_t value) noexcept
 The bit rate a Baud Rate register value selects.
 
constexpr const ModelInfo * FindModel (uint16_t number) noexcept
 Look a model number up in the catalogue.
 
constexpr Family FamilyOf (uint16_t number) noexcept
 The family of a model number.
 
constexpr bool SupportsFastRead (uint16_t number, uint8_t firmware) noexcept
 Whether the e-Manual lists Fast Sync Read, Fast Bulk Read and Control Table Backup for a model at a firmware version. Advice only: the driver never refuses an instruction because of it.
 
constexpr const char * ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Config FastBusPreset () noexcept
 Calls on a bus of servos that all answer: the shortest sensible setup for a first test.
 
constexpr Config UsbAdapterPreset () noexcept
 A bus on a USB adapter whose receive buffer is flushed in 16 ms steps.
 
constexpr Config LegacyBusPreset () noexcept
 The legacy bus: protocol 1.0 at 1 Mbit/s with the single-wire loopback of a half-duplex adapter.
 
constexpr Error Validate (const Config &config) noexcept
 Check a configuration without touching the bus.
 
constexpr ReplyInfo Classify (Protocol protocol, uint8_t id, uint8_t error_byte) noexcept
 Decode the error byte of a status packet.
 
constexpr Protocol2Error ErrorNumber (uint8_t error_byte) noexcept
 The protocol 2.0 error number of an error byte.
 
void 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 * GetDriverVersion () noexcept
 
constexpr uint32_t GetDriverVersionMajor () noexcept
 
constexpr uint32_t GetDriverVersionMinor () noexcept
 
constexpr uint32_t GetDriverVersionPatch () noexcept
 

Variables

constexpr uint8_t kProtocolBit1 = 0x01U
 Protocol bits of FamilyInfo::protocols.
 
constexpr uint8_t kProtocolBit2 = 0x02U
 The family speaks protocol 2.0.
 
constexpr std::array< uint32_t, 8 > kRates
 Rates of the table baud scheme (X and similar families), indexed by the register value.
 
constexpr uint8_t kAlertBit = 0x80
 Protocol 2.0 alert bit of the error byte.
 
constexpr uint8_t kBroadcastId = 0xFE
 The broadcast ID: an instruction to it reaches every servo and none answers.
 
constexpr uint8_t kMaxIdV2 = 252
 The largest valid servo ID of protocol 2.0.
 
constexpr uint8_t kMaxIdV1 = 253
 The largest valid servo ID of protocol 1.0.
 
constexpr uint32_t kMinTimeoutUs = 100
 Shortest and longest reply wait the driver accepts, microseconds (KB-CPP20-058).
 
constexpr uint32_t kMaxTimeoutUs = 1'000'000
 Longest timeout the driver accepts: one second.
 
constexpr uint32_t kMaxSettleUs = 10'000'000
 Longest settle time after a reboot or factory reset the driver accepts: 10 seconds.
 
constexpr uint32_t kMinBaud = 9'600
 Lowest and highest bit rate the driver accepts for Config::baud.
 
constexpr uint32_t 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 kMaxRetries = 5
 The most repeats of an idempotent instruction Config::retries allows.
 
Bus requirements

What the servos need from the UART (e-Manual, protocol 1.0 and 2.0, "DYNAMIXEL Protocol"). A port and a board configuration check their settings against these with static_assert (handbook KB-CPP-123).

constexpr uint32_t kMaxBaudRate = 4'500'000
 
constexpr uint32_t kFactoryBaudRate = 57'600
 Factory rate of the X series (Baud Rate register value 1).
 
constexpr uint32_t kTurnaroundUs = 500
 
constexpr uint32_t kMaxTurnaroundUs = 508
 Largest Return Delay Time (254 counts of 2 microseconds).
 
constexpr uint32_t kInstructionByteGapMaxUsV2 = 1500
 Longest pause between two bytes of a protocol 2.0 instruction packet that the servo accepts.
 
constexpr uint32_t kInstructionByteGapMaxUsV1 = 100'000
 Longest pause between two bytes of a protocol 1.0 instruction packet that the servo accepts.
 

Detailed Description

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

Enumeration Type Documentation

◆ Access

enum class dynamixel::Access : uint8_t
strong

Whether a register can be written.

Enumerator
ReadOnly 

R: a write is an access error.

ReadWrite 

RW.

◆ Area

enum class dynamixel::Area : uint8_t
strong

The memory a register lives in.

Enumerator
Eeprom 

Kept at power-off; written only while torque is off.

Ram 

Reset at power-on.

◆ BaudScheme

enum class dynamixel::BaudScheme : uint8_t
strong

How a family encodes its Baud Rate register.

Enumerator
None 

No baud register in the table (generic).

Divider 

Protocol 1.0 families: 2 000 000 / (value + 1) bit/s.

Table4 

XL-320: values 0..3 for 9 600, 57 600, 115 200 and 1 000 000.

Table7 

X330: values 0..6 up to 4 000 000.

Table8 

X430, X540, XW, MX(2.0): values 0..7 up to 4 500 000.

◆ Family

enum class dynamixel::Family : uint8_t
strong

A servo family: one control table layout (several models share it).

Enumerator
Generic 

Unknown or unlisted model: raw addresses only.

AxRxDx 

AX-12A/12W, RX-10/24F/28/64, DX-113/116/117 (protocol 1.0).

Mx28 

MX-28 and MX-12W (protocol 1.0 firmware).

Mx64 

MX-64 (protocol 1.0 firmware).

Mx106 

MX-106 (protocol 1.0 firmware).

Mx28v2 

MX-28(2.0) (protocol 2.0 firmware).

Mx64v2 

MX-64(2.0) and MX-106(2.0).

Xl320 

XL-320 (protocol 2.0 only, its own table).

X330 

XL330, XC330, XM335.

X430Basic 

XL430, XC430, 2XL430, 2XC430 (no current registers).

X430 

XM430, XH430, XD430.

X540 

XM540, XH540, XD540 (adds the external ports).

Xw 

XW430, XW540 (X430 table without LED).

◆ Kind

enum class dynamixel::Kind : uint8_t
strong

How the raw bytes of a register are read as a number.

Enumerator
Unsigned 

Little-endian unsigned.

Signed 

Little-endian two's complement of the register width.

SignMag10 

Protocol 1.0 speed, load, torque: bits 9..0 magnitude, bit 10 direction (CW).

Offset2048 

MX-64/106 current: value - 2048 counts.

Function Documentation

◆ BaudRateOf()

constexpr uint32_t dynamixel::BaudRateOf ( Family  family,
uint8_t  value 
)
constexprnoexcept

The bit rate a Baud Rate register value selects.

Parameters
familyThe family.
valueThe register value.
Returns
The rate in bit/s, or 0 when the scheme has no such value.

◆ BaudValueFor()

constexpr bool dynamixel::BaudValueFor ( Family  family,
uint32_t  bits_per_second,
uint8_t &  value 
)
constexprnoexcept

The Baud Rate register value for a bit rate.

Parameters
familyThe family.
bits_per_secondThe wanted rate.
valueSet to the register value on success.
Returns
true when the family's baud scheme offers exactly that rate (protocol 1.0 families: any 2 000 000 / (n + 1) that is exact, n 0 to 254).

◆ FamilyOf()

constexpr Family dynamixel::FamilyOf ( uint16_t  number)
constexprnoexcept

The family of a model number.

Parameters
numberThe Model Number register value.
Returns
The family, or Family::Generic for an unlisted number.

◆ FindModel()

constexpr const ModelInfo * dynamixel::FindModel ( uint16_t  number)
constexprnoexcept

Look a model number up in the catalogue.

Parameters
numberThe Model Number register value (from a ping reply or a read of address 0).
Returns
The catalogue entry, or nullptr for a number the catalogue does not list.

◆ Indirect()

constexpr IndirectPair dynamixel::Indirect ( Family  family,
uint32_t  index 
)
constexprnoexcept

The registers of indirect pair index (1-based): the indirect address (2 bytes) that points at any control-table address, and the data byte that reads or writes through it (X330: 1..28; others 1..56, where 29..56 lie above address 255 and need protocol 2.0).

Parameters
familyThe family.
index1 to 28 (X330) or 56.
Returns
The two addresses, or {0, 0} when the family has no such pair.

◆ Info()

constexpr const FamilyInfo & dynamixel::Info ( Family  family)
constexprnoexcept

The facts of a family.

Parameters
familyThe family; a value that is not a family gives Generic.
Returns
Its FamilyInfo.

◆ KconfigDefaults()

constexpr Config dynamixel::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected, on top of the defaults.

Returns
Config{} with the protocol, bit rate, reply timeout, retries and echo mode from Kconfig. allow_destructive is never a Kconfig option: it is decided in code, call by call.

◆ Lookup()

constexpr const RegInfo * dynamixel::Lookup ( Family  family,
Reg  reg 
)
constexprnoexcept

Find a register of a family.

Parameters
familyThe family.
regThe register name.
Returns
A pointer into the family's table, or nullptr when the family has no such register.

◆ SupportsFastRead()

constexpr bool dynamixel::SupportsFastRead ( uint16_t  number,
uint8_t  firmware 
)
constexprnoexcept

Whether the e-Manual lists Fast Sync Read, Fast Bulk Read and Control Table Backup for a model at a firmware version. Advice only: the driver never refuses an instruction because of it.

Parameters
numberThe Model Number register value.
firmwareThe Firmware Version register value.
Returns
true when the model is listed and firmware reaches the first documented version.

◆ Table()

constexpr std::span< const RegInfo > dynamixel::Table ( Family  family)
constexprnoexcept

The control table of a family.

Parameters
familyThe family.
Returns
Its registers in address order; empty for Family::Generic and for a value that is not a family.

Variable Documentation

◆ kMaxBaudRate

constexpr uint32_t dynamixel::kMaxBaudRate = 4'500'000
inlineconstexpr

Highest rate of the families in the catalogue (X series: 4.5 Mbit/s); the P series goes to 10.5 Mbit/s.

◆ kProtocolBit1

constexpr uint8_t dynamixel::kProtocolBit1 = 0x01U
inlineconstexpr

Protocol bits of FamilyInfo::protocols.

The family speaks protocol 1.0.

◆ kRates

constexpr std::array<uint32_t, 8> dynamixel::kRates
inlineconstexpr
Initial value:
{9'600U, 57'600U, 115'200U, 1'000'000U,
2'000'000U, 3'000'000U, 4'000'000U, 4'500'000U}

Rates of the table baud scheme (X and similar families), indexed by the register value.

◆ kTurnaroundUs

constexpr uint32_t dynamixel::kTurnaroundUs = 500
inlineconstexpr

Return Delay Time factory value 250 counts of 2 microseconds: the servo answers after 500 microseconds.