Configuration¶
Every field of dynamixel::Config, the presets, how a configuration is checked, and the optional Kconfig layer.
Datasheet sections this page relies on
From ROBOTIS e-Manual, DYNAMIXEL Protocol 2.0 web page, no revision mark:
- Byte to byte time and the packet gap: 1.6 Byte to Byte Time, p. 1
- Response policy and the broadcast ID: 3.4 Response Policy, p. 1
All of them, with the driver API for each: Datasheet map.
Fields¶
Config{} suits a protocol 2.0 bus of X-series servos at their factory settings. The timing fields are driver side:
the e-Manual gives no reply deadline, so these are the driver's own choices (see the
Contract). Fields with a unit carry it in the name.
| Field | Default | Range | What it does |
|---|---|---|---|
protocol |
Protocol::V2 |
V1, V2 |
Packet format of every servo on the bus |
baud |
57 600 | 9 600 to 10 500 000 | UART rate; applied through the port's SetBaudRate() when it has one |
reply_timeout_us |
20 000 | 100 to 1 000 000 | Longest wait for the first byte of a reply |
gap_timeout_us |
5 000 | 100 to 1 000 000 | Longest wait for the next bytes of a packet that has started |
reboot_wait_us |
500 000 | 0 to 10 000 000 | Wait after a Reboot, Restore or Factory Reset reply |
baud_change_wait_us |
10 000 | 0 to 10 000 000 | Wait after a servo's baud rate changed |
retries |
1 | 0 to 5 | Repeats of a ping or read after a missing, corrupted or invalid reply; writes are never repeated |
echo |
EchoMode::None |
None, Loopback |
Verify the echo of every sent byte on a single-wire bus |
alert_policy |
AlertPolicy::Report |
Report, Fail |
A hardware alert in a reply: succeed and latch it, or return DeviceFault |
status_return |
StatusReturn::All |
PingOnly, ReadOnly, All |
How much the servos answer; calls that need an answer the level does not give return Unsupported |
broadcast_timeout_us |
100 000 | 100 to 1 000 000 | Wait for each reply of a broadcast ping |
allow_destructive |
false |
Permit Factory Reset, Control Table Restore, Clear and ID writes to every servo |
Choose reply_timeout_us longer than the servos' Return Delay Time (500 microseconds at the factory value) plus the
time the longest reply takes on the line. At 57 600 bit/s a byte takes 174 microseconds, so a 100-byte reply needs
about 17 ms; the default 20 ms covers the reads of a few registers, and a Fast Sync Read of many servos at a low
rate needs more. gap_timeout_us has to cover a pause inside a packet, such as the latency timer of a USB adapter.
allow_destructive is never set from Kconfig: it is a decision made in code, where the consequence is visible.
Presets¶
| Preset | What it sets | Use it for |
|---|---|---|
FastBusPreset() |
Reply wait 10 ms, gap 2 ms | A short bus of servos that all answer, at a high rate |
UsbAdapterPreset() |
Reply wait 60 ms, gap 40 ms | A bus behind a USB adapter with a 16 ms latency timer |
LegacyBusPreset() |
Protocol 1.0 at 1 Mbit/s | AX, RX, DX and MX (1.0) servos at their factory rate |
Start from a preset or from Config{} and change fields:
dynamixel::Config LegacyConfig() {
dynamixel::Config c = dynamixel::LegacyBusPreset(); // protocol 1.0 at 1 Mbit/s
c.retries = 2; // repeat a lost ping or read twice
c.reply_timeout_us = 5'000; // a short bus answers quickly
return c; // dynamixel::Validate(c) checks it without the bus
}
dynamixel::Error StartLegacy(MyPort& port) {
static dynamixel::DYNAMIXEL<MyPort> servos(port, LegacyConfig()); // stored, no I/O
return servos.EnsureInitialized().error; // InvalidArgument if the config is out of range
}
Validation¶
dynamixel::Validate(config) checks a configuration without touching the bus, and EnsureInitialized() and
ApplyConfig() call it before any I/O. It returns Error::InvalidArgument when an enum holds a value that is not
an enumerator, the baud rate or a timeout is outside its range, a wait is above ten seconds, or retries is above 5.
A configuration fixed at build time can be checked by the compiler instead:
// A configuration fixed at build time: an invalid value stops the build instead of the first call.
inline constexpr dynamixel::CheckedConfig kBoard{
dynamixel::Config{.baud = 1'000'000, .retries = 2}};
CheckedConfig does not compile for an invalid value, so a wrong number stops the build and not the first call.
Kconfig¶
Under ESP-IDF, idf.py menuconfig shows DYNAMIXEL servo bus when the driver is a component of the project
(Installation); the menu is _config/Kconfig. The options reach the code
only through inc/dynamixel_kconfig.hpp, never through a driver signature:
dynamixel::Error StartFromMenuconfig(MyPort& port) {
static dynamixel::DYNAMIXEL<MyPort> servos(port, dynamixel::KconfigDefaults());
return servos.EnsureInitialized().error;
}
| Option | Default | Config field |
|---|---|---|
CONFIG_DYNAMIXEL_PROTOCOL_1 or _2 |
protocol 2.0 | protocol |
CONFIG_DYNAMIXEL_BAUD |
57 600 | baud |
CONFIG_DYNAMIXEL_REPLY_TIMEOUT_US |
20 000 | reply_timeout_us |
CONFIG_DYNAMIXEL_RETRIES |
1 | retries |
CONFIG_DYNAMIXEL_ECHO_LOOPBACK |
n | echo |
Without Kconfig (plain CMake, other platforms) KconfigDefaults() returns Config{}. Both cases are host tests.
Changing the configuration later¶
ApplyConfig() stores a new, valid configuration and applies the baud rate at once when the driver is up. To move
a running bus to a new rate, set the servo first and then the port: SetServoBaudRate() writes the servo's Baud Rate
register, ChangeBusBaud() moves the UART, waits baud_change_wait_us and resynchronises:
dynamixel::Error MoveBusTo1Mbit(dynamixel::DYNAMIXEL<FullPort>& servos, dynamixel::ServoRef servo) {
// First the servo, at the old rate; then the port, followed by a resynchronisation.
if (auto r = servos.SetServoBaudRate(servo, 1'000'000); !r) {
return r.error;
}
return servos.ChangeBusBaud(1'000'000).error;
}
Next: Porting.