|
DYNAMIXEL Driver 0.1.0
API reference
|
Master of one DYNAMIXEL bus on a platform port. More...
#include <dynamixel.hpp>
Public Member Functions | |
| DYNAMIXEL (Port &port, const Config &config={}) noexcept | |
| Bind the driver to a port and store the configuration. No I/O, cannot fail. | |
| DYNAMIXEL (const DYNAMIXEL &)=delete | |
| One driver object per bus. | |
| DYNAMIXEL & | operator= (const DYNAMIXEL &)=delete |
| One driver object per bus. | |
Lifecycle | |
| Result< void > | EnsureInitialized () noexcept |
| Start the driver, once: validate the configuration, bring the port up and set its rate. | |
| bool | IsInitialized () const noexcept |
| Result< void > | Deinitialize () noexcept |
Mark the driver uninitialised. No bus traffic: the servos keep their state (torque stays on; call DisableTorqueAll() first when the servos must stop). | |
| Result< void > | Resync () noexcept |
| Resynchronise: drop everything received and wait until the line has been quiet for one reply timeout, so that a late status packet cannot be taken for the answer to the next instruction. | |
| Result< void > | ApplyConfig (const Config &config) noexcept |
Change the whole configuration; the UART rate follows through SetBaudRate() when the port has it. | |
| const Config & | GetConfig () const &noexcept |
| void | GetConfig () const &&=delete |
| Not on a temporary driver: the reference would dangle (KB-CPP20-044). | |
Discovery | |
| Result< PingInfo > | Ping (uint8_t id) noexcept |
| Ping one servo (always answered, whatever the Status Return Level). | |
| Result< PingInfo > | Identify (uint8_t id) noexcept |
| Ping and learn the model: protocol 2.0 is one ping, protocol 1.0 a ping and a read of the Model Number and Firmware Version registers. | |
| Result< uint32_t > | BroadcastPing (std::span< PingInfo > found) noexcept |
| Ping the broadcast ID and collect the answers (protocol 2.0): every servo answers, in ID order. | |
| Result< uint32_t > | ScanIds (uint8_t first, uint8_t last, std::span< PingInfo > found) noexcept |
Ping every ID from first to last one after another. | |
Raw control-table access | |
| Result< void > | Read (uint8_t id, uint16_t address, std::span< uint8_t > out) noexcept |
| Read bytes of one servo's control table. | |
| Result< void > | Write (uint8_t id, uint16_t address, std::span< const uint8_t > data) noexcept |
| Write bytes to the control table. | |
| Result< void > | RegWrite (uint8_t id, uint16_t address, std::span< const uint8_t > data) noexcept |
| Store a write to be executed by the next Action instruction (Reg Write). | |
| Result< void > | Action (uint8_t id) noexcept |
| Execute the stored Reg Write (all servos at once with the broadcast ID). | |
Reset, reboot, clear, backup | |
| Result< void > | FactoryReset (uint8_t id, ResetOption option) noexcept |
| Reset a servo's control table to the factory values. | |
| Result< void > | Reboot (uint8_t id) noexcept |
Reboot a servo; waits Config::reboot_wait_us after the reply. Sent like the stop: it needs no EnsureInitialized() and is written even when the input flush fails (the call then returns Bus after the write). | |
| Result< void > | Clear (uint8_t id, ClearOption option) noexcept |
Clear the multi-turn count or registered errors (protocol 2.0). Needs Config::allow_destructive. | |
| Result< void > | Backup (uint8_t id, BackupOption option) noexcept |
| Store the control table in the backup area, or restore the EEPROM from it (protocol 2.0). | |
Sync and bulk instructions | |
| Result< void > | SyncWrite (uint16_t address, uint16_t length, std::span< const uint8_t > ids, std::span< const uint8_t > data) noexcept |
| Write the same address and length to several servos with one packet (both protocols). No answer. | |
| Result< void > | BulkWrite (std::span< const BulkWriteItem > items) noexcept |
| Write different addresses and lengths to several servos with one packet (protocol 2.0). No answer. | |
| Result< void > | SyncRead (uint16_t address, uint16_t length, std::span< const uint8_t > ids, std::span< uint8_t > out, std::span< DeviceReply > replies) noexcept |
Read the same address and length from several servos (protocol 2.0): each one answers with its own packet, in the order of ids. | |
| Result< void > | FastSyncRead (uint16_t address, uint16_t length, std::span< const uint8_t > ids, std::span< uint8_t > out, std::span< DeviceReply > replies) noexcept |
| Sync Read with one combined answer packet (Fast Sync Read, protocol 2.0): the servos answer back to back inside one packet, every part with its own error byte, ID and CRC. | |
| Result< void > | BulkRead (std::span< const BulkReadItem > items, std::span< uint8_t > out, std::span< DeviceReply > replies) noexcept |
| Read different addresses and lengths from several servos (protocol 1.0 for MX and X servos, and 2.0). | |
| Result< void > | FastBulkRead (std::span< const BulkReadItem > items, std::span< uint8_t > out, std::span< DeviceReply > replies) noexcept |
| Bulk Read with one combined answer packet (Fast Bulk Read, protocol 2.0). | |
Typed register access | |
| Result< int32_t > | ReadRegister (ServoRef servo, Reg reg) noexcept |
| Read one register by its family-neutral name and decode it. | |
| Result< void > | WriteRegister (ServoRef servo, Reg reg, int32_t value) noexcept |
| Encode and write one register. | |
| Result< void > | SetTorque (ServoRef servo, bool enable) noexcept |
Turn the torque on or off. Use DisableTorque() to stop: it is never refused. | |
| Result< void > | DisableTorque (ServoRef servo) noexcept |
Turn one servo's torque off. Never refused for the driver's state: it needs no EnsureInitialized() (it starts the port and sets the bus baud rate), ignores any earlier failure and asks for no consent, and writes even when the input flush fails. The write is idempotent: it is repeated (up to three times) until a trusted answer confirms it, and sent all three times when no answer can (status return level below 2, or a broadcast). | |
| Result< void > | DisableTorqueAll (Family family) noexcept |
Turn the torque of every servo of a family off with one broadcast. Never refused for the driver's state. Nothing is answered, so the broadcast is sent three times and Ok means sent. | |
| Result< void > | DisableTorqueAt (uint8_t id, uint16_t torque_address) noexcept |
Turn the torque off at an explicit address: the stop for a servo whose family is Generic (a model the catalogue does not list) or one that has no Reg::TorqueEnable. It shares the stop path of DisableTorque(): never refused for the driver's state, written even when the input flush fails, up to three attempts. The caller supplies the address from the servo's own control table (64 on the X series in protocol 2.0, 24 on AX/RX/DX). | |
| Result< void > | DisableTorqueEach (std::span< const ServoRef > servos) noexcept |
DisableTorque() for each servo of a list, whatever one of them does. | |
| Result< Feedback > | ReadFeedback (ServoRef servo) noexcept |
| Read position, velocity, load or current, voltage and temperature in one transfer. | |
| Result< void > | SetGoalPosition (ServoRef servo, int32_t counts) noexcept |
| Write the Goal Position. | |
| Result< void > | SetId (ServoRef servo, uint8_t new_id) noexcept |
Change a servo's ID. Needs Config::allow_destructive when servo.id is the broadcast ID. | |
| Result< void > | SetServoBaudRate (ServoRef servo, uint32_t bits_per_second) noexcept |
Write a servo's Baud Rate register; the new rate applies after the reply. The port keeps its rate: follow with ChangeBusBaud(). | |
| Result< void > | ChangeBusBaud (uint32_t bits_per_second) noexcept |
Change the UART rate of the port (after SetServoBaudRate()), wait Config::baud_change_wait_us and resynchronise. | |
| Result< void > | SetStatusReturnLevel (ServoRef servo, StatusReturn level) noexcept |
Write the Status Return Level and adopt it as the bus's expectation. A write that lowers the level may go unanswered: silence is then accepted as success and the level is adopted, with a warning in the log. A lost write and a lost answer look the same: when it matters, read the register back (at the old level, with Read()) to verify. | |
Diagnostics | |
| const ReplyInfo & | GetLastReply () const &noexcept |
| void | GetLastReply () const &&=delete |
| Not on a temporary driver (KB-CPP20-044). | |
| const ReplyInfo & | GetLatchedAlert () const &noexcept |
| void | GetLatchedAlert () const &&=delete |
| Not on a temporary driver (KB-CPP20-044). | |
| void | ClearLatchedAlert () noexcept |
| Forget the latched alert. No I/O. | |
| const Stats & | GetStats () const &noexcept |
| void | GetStats () const &&=delete |
| Not on a temporary driver (KB-CPP20-044). | |
| void | ResetStats () noexcept |
| Zero the counters. No I/O. | |
| std::span< const uint8_t > | GetLastRequest () const &noexcept |
| void | GetLastRequest () const &&=delete |
| Not on a temporary driver (KB-CPP20-044). | |
Master of one DYNAMIXEL bus on a platform port.
Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), use, optionally Deinitialize(). Every call that touches the bus returns Error::NotInitialized until EnsureInitialized() has succeeded, with one exception: the torque-off calls (DisableTorque(), DisableTorqueAll(), DisableTorqueEach(), DisableTorqueAt()) and Reboot() are never refused for the driver's state; they bring the port up themselves (and set the bus baud rate) and write even when the input flush fails.
Optional port hooks, found at compile time:
| Hook | Used for | Without it |
|---|---|---|
bool SetBaudRate(uint32_t baud) noexcept | EnsureInitialized(), ApplyConfig() and ChangeBusBaud() set the UART rate | The port's own rate stays; ChangeBusBaud() returns Unsupported |
void Log(LogLevel, const char* message) noexcept | One line per lifecycle event or failure | Nothing is logged |
A hook declared with the wrong signature is a compile error.
| Port | Your class derived from UartInterface<Port>. |
| FrameBytes | Size of the transmit and of the receive buffer, 64 to 4096 bytes (default 512). A transfer that does not fit returns InvalidArgument before anything is sent. |
|
inlineexplicitnoexcept |
Bind the driver to a port and store the configuration. No I/O, cannot fail.
| port | The port; it must outlive the driver. |
| config | What EnsureInitialized() will apply; checked there, before any I/O. |
|
noexcept |
Execute the stored Reg Write (all servos at once with the broadcast ID).
| id | The servo ID or 254. |
Write().
|
noexcept |
Change the whole configuration; the UART rate follows through SetBaudRate() when the port has it.
| config | Checked with Validate() before any I/O. |
Ok, InvalidArgument or Bus.
|
noexcept |
Store the control table in the backup area, or restore the EEPROM from it (protocol 2.0).
Restore needs Config::allow_destructive, makes the servo reboot and waits Config::reboot_wait_us. Torque must be off or the servo answers with a result fail error. Store is not behind allow_destructive, although it overwrites the previous backup in the servo's backup area: it changes nothing the servo runs on, and a restore still needs consent.
| id | The servo ID or 254. |
| option | Store or restore. |
NotPermitted, Unsupported (protocol 1.0), InvalidArgument or the errors of Write().
|
noexcept |
Ping the broadcast ID and collect the answers (protocol 2.0): every servo answers, in ID order.
Waits Config::broadcast_timeout_us for each answer and stops at the first silence, at a damaged answer or when found is full (the remaining answers are dropped by the next call's flush).
| found | Receives one entry per distinct ID that answered validly. |
NotInitialized, InvalidArgument (empty found), Unsupported (protocol 1.0 has no broadcast ping answers), Bus, or the error of the first answer when none was valid.
|
noexcept |
Read different addresses and lengths from several servos (protocol 1.0 for MX and X servos, and 2.0).
| items | One entry per servo, each ID once. |
| out | The sum of all lengths in bytes; the data of servo k follows that of servo k - 1. |
| replies | One entry per item. |
SyncRead().
|
noexcept |
Write different addresses and lengths to several servos with one packet (protocol 2.0). No answer.
| items | One entry per servo, each ID once, each with at least one byte. |
Ok, NotInitialized, Unsupported (protocol 1.0), InvalidArgument or Bus.
|
noexcept |
Change the UART rate of the port (after SetServoBaudRate()), wait Config::baud_change_wait_us and resynchronise.
| bits_per_second | The new rate, kMinBaud to kMaxBaud. |
NotInitialized, InvalidArgument, Unsupported (the port has no SetBaudRate()), Bus.
|
noexcept |
Clear the multi-turn count or registered errors (protocol 2.0). Needs Config::allow_destructive.
| id | The servo ID or 254. |
| option | What to clear. |
NotPermitted, Unsupported (protocol 1.0), InvalidArgument or the errors of Write().
|
noexcept |
Mark the driver uninitialised. No bus traffic: the servos keep their state (torque stays on; call DisableTorqueAll() first when the servos must stop).
Ok.
|
noexcept |
Turn one servo's torque off. Never refused for the driver's state: it needs no EnsureInitialized() (it starts the port and sets the bus baud rate), ignores any earlier failure and asks for no consent, and writes even when the input flush fails. The write is idempotent: it is repeated (up to three times) until a trusted answer confirms it, and sent all three times when no answer can (status return level below 2, or a broadcast).
| servo | The servo; its family must have a torque register and speak the bus protocol (not Generic: use DisableTorqueAt()). |
Ok when confirmed (or sent, without answers), InvalidArgument (the ID, or a family with no torque register on this protocol; nothing is sent), Bus (the port did not start, or the flush failed: the packets were sent all the same), or the last error of the attempts.
|
noexcept |
Turn the torque of every servo of a family off with one broadcast. Never refused for the driver's state. Nothing is answered, so the broadcast is sent three times and Ok means sent.
| family | The family whose torque register is written. |
Ok (sent), InvalidArgument (Generic, or a family that does not speak the bus protocol) or Bus.
|
noexcept |
Turn the torque off at an explicit address: the stop for a servo whose family is Generic (a model the catalogue does not list) or one that has no Reg::TorqueEnable. It shares the stop path of DisableTorque(): never refused for the driver's state, written even when the input flush fails, up to three attempts. The caller supplies the address from the servo's own control table (64 on the X series in protocol 2.0, 24 on AX/RX/DX).
| id | The servo ID, or 254 for every servo. |
| torque_address | The Torque Enable address (at most 255 in protocol 1.0). |
DisableTorque(); InvalidArgument for an ID or address the protocol does not have (nothing is sent).Warning: this writes one byte 0 at the address given, with ID 254 to every servo. A wrong address can set IDs to 0, change the baud rate or silence the servos. Take the address from the e-Manual's control table for the exact model and firmware (64 on the X series, 24 on AX/RX/DX, MX 1.0 and XL-320; the Pro series differ).
|
noexcept |
DisableTorque() for each servo of a list, whatever one of them does.
| servos | The servos. |
Ok, or only the first error after all of them were tried: to know which servo failed, call DisableTorque() for each one.
|
noexcept |
Start the driver, once: validate the configuration, bring the port up and set its rate.
After it succeeds, later calls return Ok at once with no I/O. After it fails, the driver stays uninitialised and the next call starts again. No servo is addressed.
Ok, InvalidArgument (the stored configuration fails Validate(); no I/O) or Bus.
|
noexcept |
Reset a servo's control table to the factory values.
Needs Config::allow_destructive. Reset all (ResetOption::All) also resets the ID to 1 and the baud rate to 57 600 bit/s: the servo then answers at another ID and rate than the bus uses. Protocol 1.0 has no option byte (it resets everything: only ResetOption::All is accepted) and cannot use the broadcast ID; protocol 2.0 refuses reset all on the broadcast ID (the firmware does too). Waits Config::reboot_wait_us afterwards.
| id | The servo ID (broadcast only protocol 2.0 with a keep option). |
| option | What to keep. |
NotPermitted, InvalidArgument or the errors of Write().
|
noexcept |
Bulk Read with one combined answer packet (Fast Bulk Read, protocol 2.0).
| items | One entry per servo, each ID once. |
| out | The sum of all lengths in bytes. |
| replies | One entry per item. |
FastSyncRead().
|
noexcept |
Sync Read with one combined answer packet (Fast Sync Read, protocol 2.0): the servos answer back to back inside one packet, every part with its own error byte, ID and CRC.
| address | First address. |
| length | Bytes per servo. |
| ids | The servo IDs. |
| out | ids.size() * length bytes. |
| replies | One entry per ID. A packet that ends early still delivers the parts that arrived whole and checked; the rest is Timeout. |
SyncRead(). The combined packet must fit the receive buffer (InvalidArgument otherwise).
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
ClearLatchedAlert(); all zero when none. No I/O.
|
inlinenoexcept |
ResetStats(). No I/O.
|
noexcept |
|
inlinenoexcept |
EnsureInitialized() and before Deinitialize(). No I/O.
|
noexcept |
Ping one servo (always answered, whatever the Status Return Level).
| id | 0 to 252 (protocol 2.0) or 253 (protocol 1.0); not the broadcast ID. |
id is set (Identify() reads the rest). Errors: NotInitialized, InvalidArgument, Bus, Timeout, Crc, InvalidReply, LineFault, EchoMismatch, DeviceIdMismatch, DeviceError, DeviceFault.
|
noexcept |
Read bytes of one servo's control table.
| id | The servo ID (not the broadcast ID: reads are not executed on it). |
| address | First address (0 to 255 in protocol 1.0). |
| out | Receives out.size() bytes, 1 or more; the reply must fit the receive buffer even with byte stuffing. |
Ok, NotInitialized, InvalidArgument (nothing sent), Unsupported (the status return level is ping only), Bus, Timeout, Crc, InvalidReply, LineFault, EchoMismatch, DeviceIdMismatch, DeviceError (the servo's error number is in GetLastReply()) or DeviceFault. Retried Config::retries times.
|
noexcept |
Read position, velocity, load or current, voltage and temperature in one transfer.
| servo | The servo; its family needs these registers (not Generic). |
Read() and Unsupported.
|
noexcept |
Read one register by its family-neutral name and decode it.
| servo | The servo: ID and family (FamilyOf() of a ping's model number). |
| reg | The register. |
Unsupported (the family has no such register, or does not speak the bus protocol: nothing is sent), or the errors of Read().
|
noexcept |
Reboot a servo; waits Config::reboot_wait_us after the reply. Sent like the stop: it needs no EnsureInitialized() and is written even when the input flush fails (the call then returns Bus after the write).
| id | The servo ID or 254. |
InvalidArgument, Bus, or as Write().
|
noexcept |
Store a write to be executed by the next Action instruction (Reg Write).
| id | The servo ID or 254. |
| address | First address. |
| data | The bytes, 1 or more. |
Write().
|
noexcept |
Resynchronise: drop everything received and wait until the line has been quiet for one reply timeout, so that a late status packet cannot be taken for the answer to the next instruction.
Ok, NotInitialized, Bus, or LineFault when the line never went quiet.
|
noexcept |
Ping every ID from first to last one after another.
| first | First ID. |
| last | Last ID, not below first, within the protocol's ID range. |
| found | Receives the IDs that answered; InvalidArgument when it is empty. |
NotInitialized, InvalidArgument or Bus. A full found stops the scan.
|
noexcept |
Write the Goal Position.
| servo | The servo. |
| counts | Position in counts. |
WriteRegister().
|
noexcept |
Change a servo's ID. Needs Config::allow_destructive when servo.id is the broadcast ID.
| servo | The servo (current ID). |
| new_id | 0 to 252 (253 in protocol 1.0). |
NotPermitted, InvalidArgument or the errors of WriteRegister().
|
noexcept |
Write a servo's Baud Rate register; the new rate applies after the reply. The port keeps its rate: follow with ChangeBusBaud().
| servo | The servo. |
| bits_per_second | A rate the family's baud scheme offers. |
InvalidArgument (not offered) or the errors of WriteRegister().
|
noexcept |
Write the Status Return Level and adopt it as the bus's expectation. A write that lowers the level may go unanswered: silence is then accepted as success and the level is adopted, with a warning in the log. A lost write and a lost answer look the same: when it matters, read the register back (at the old level, with Read()) to verify.
| servo | The servo (or {254, family}). |
| level | The new level. |
InvalidArgument or the errors of WriteRegister().
|
noexcept |
Turn the torque on or off. Use DisableTorque() to stop: it is never refused.
| servo | The servo. |
| enable | true to enable. |
WriteRegister().
|
noexcept |
Read the same address and length from several servos (protocol 2.0): each one answers with its own packet, in the order of ids.
| address | First address. |
| length | Bytes per servo, 1 or more. |
| ids | The servo IDs, 1 to many, none the broadcast ID. |
| out | ids.size() * length bytes; entry k holds servo k's data when replies[k].result is Ok. |
| replies | One entry per ID: its outcome. |
Ok when every servo answered validly, else the first failing outcome; NotInitialized, Unsupported (protocol 1.0, or the status return level is ping only), InvalidArgument or Bus. Not retried as a whole: re-read the failed servos.
|
noexcept |
Write the same address and length to several servos with one packet (both protocols). No answer.
| address | First address (0 to 255 in protocol 1.0). |
| length | Bytes per servo, 1 or more. |
| ids | The servo IDs (1 to many, not 254). |
| data | ids.size() * length bytes, the bytes of the first servo first. |
Ok (sent), NotInitialized, InvalidArgument (nothing sent, also when the packet does not fit the transmit buffer) or Bus.
|
noexcept |
Write bytes to the control table.
Not retried: a lost reply does not tell whether the servo applied the write. With the broadcast ID nothing is answered and Ok only means "sent".
| id | The servo ID or 254 (every servo). |
| address | First address. |
| data | The bytes, 1 or more. |
Read(), plus Ok for a sent broadcast.
|
noexcept |
Encode and write one register.
| servo | The servo (or {254, family} for every servo of a family). |
| reg | The register. |
| value | The value in the register's unit. |
InvalidArgument (the register is read-only, or the value does not fit its size; nothing sent), Unsupported (the family has no such register, or does not speak the bus protocol) or the errors of Write().