Struct Bus

pub struct Bus<ReadBuffer, WriteBuffer> { /* private fields */ }

Dynamixel Protocol 2 communication bus.

Implementations

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn action(&mut self, motor_id: u8) -> Result<Response<()>, TransferError>

Send an action command to trigger a previously registered instruction.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

If you want to broadcast this instruction, it may be more convenient to use Self::broadcast_action() instead.

pub fn broadcast_action(&mut self) -> Result<(), WriteError>

Broadcast an action command to all connected motors to trigger a previously registered instruction.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn bulk_read_cb<Read, F>( &mut self, reads: &[Read], on_response: F, ) -> Result<(), WriteError>

where Read: AsRef<BulkReadData>, F: FnMut(&BulkReadData, Result<Response<&[u8]>, ReadError>),

Synchronously read arbitrary data ranges from multiple motors in one command.

Unlike the sync read instruction, a bulk read can be used to read a different amount of data from a different address for each motor.

The data for multi-byte registers is received in little-endian format.

The on_response function is called for the reply from each motor. If the function fails to write the instruction, an error is returned and the function is not called.

Panics

The protocol forbids specifying the same motor ID multiple times. This function panics if the same motor ID is used for more than one read.

pub fn bulk_read<Read>( &mut self, reads: &[Read], ) -> Result<Vec<Response<Vec<u8>>>, TransferError>

where Read: AsRef<BulkReadData>,

Synchronously read arbitrary data ranges from multiple motors in one command.

Unlike the sync read instruction, a bulk read can be used to read a different amount of data from a different address for each motor.

If this function fails to get the data from any of the motors, the entire function retrns an error. If you need access to the data from other motors, or if you want acces to the error for each motor, see Self::bulk_read_cb.

Panics

The protocol forbids specifying the same motor ID multiple times. This function panics if the same motor ID is used for more than one read.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn bulk_write<'a, I, T>(&mut self, writes: &'a I) -> Result<(), WriteError>

where &'a I: IntoIterator, <&'a I as IntoIterator>::IntoIter: Clone, <&'a I as IntoIterator>::Item: Borrow<BulkWriteData<T>>, T: AsRef<[u8]>,

Synchronously write arbitrary data ranges to multiple motors.

Each motor will perform the write as soon as it receives the command. This gives much shorter delays than executing a regular Self::write for each motor individually. Unlike the sync write instruction, a bulk write allows you to write a different amount of data to a different address for each motor.

The data for multi-byte registers should serialized as little-endian.

Panics

The protocol forbids specifying the same motor ID multiple times. This function panics if the same motor ID is used for more than one write.

This function also panics if the data length for a motor exceeds the capacity of a u16.

Example

use dynamixel2::Bus;
use dynamixel2::instructions::BulkWriteData;
use std::time::Duration;

let mut bus = Bus::open("/dev/ttyUSB0", 57600)?;
bus.bulk_write(&[
  // Write a u32 value of 2000 to register 116 of motor 1.
  BulkWriteData {
    motor_id: 1,
    address: 116,
    data: 2000u32.to_le_bytes().as_slice(),
  },
  // Write a u16 value of 300 to register 102 of motor 2.
  BulkWriteData {
    motor_id: 2,
    address: 102,
    data: 300u16.to_le_bytes().as_slice(),
  },
])?;

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn clear_revolution_counter( &mut self, motor_id: u8, ) -> Result<Response<()>, TransferError>

Clear the multi-revolution counter of a motor.

This will reset the “present position” register to a value between 0 and a whole revolution. It is not possible to clear the revolution counter of a motor while it is moving. Doing so will cause the motor to return an error, and the revolution counter will not be reset.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

If you want to broadcast this instruction, it may be more convenient to use Self::broadcast_clear_revolution_counter() instead.

pub fn broadcast_clear_revolution_counter(&mut self) -> Result<(), WriteError>

Clear the revolution counter of all connected motors.

This will reset the “present position” register to a value between 0 and a whole revolution. It is not possible to clear the mutli-revolution counter of a motor while it is moving. Doing so will cause the motor to return an error, and the revolution counter will not be reset.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn factory_reset( &mut self, motor_id: u8, kind: FactoryResetKind, ) -> Result<Response<()>, TransferError>

Reset the settings of a motor to the factory defaults.

This will reset all registers to the factory default, including the EEPROM registers. The only exceptions are the ID and baud rate settings, which may be kept depending on the kind argument.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

If you want to broadcast this instruction, it may be more convenient to use Self::broadcast_factory_reset() instead.

Starting with version 42 of the firmware for the MX-series and X-series, motors ignore a broadcast reset command with FactoryResetKind::ResetAll. Motors with older firmware may still execute the command, which would cause multiple motors on the bus to have the same ID. At that point, communication with those motors is not possible anymore. The only way to restore communication is to physically disconnect all but one motor at a time and re-assign unique IDs. Or use the ID Inspection Tool in the Dynamixel Wizard 2.0

pub fn broadcast_factory_reset( &mut self, kind: FactoryResetKind, ) -> Result<(), WriteError>

Reset the settings of all connected motors to the factory defaults.

This will reset all registers to the factory default, including the EEPROM registers. The only exceptions are the ID and baud rate settings, which may be kept depending on the kind argument.

Starting with version 42 of the firmware for the MX-series and X-series, motors ignore a broadcast reset command with FactoryResetKind::ResetAll. Motors with older firmware may still execute the command, which would cause multiple motors on the bus to have the same ID. At that point, communication with those motors is not possible anymore. The only way to restore communication is to physically disconnect all but one motor at a time and re-assign unique IDs.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn ping(&mut self, motor_id: u8) -> Result<Response<Ping>, TransferError>

Ping a specific motor by ID.

This will not work correctly if the motor ID is packet_id::BROADCAST. Use Self::scan or Self::scan_cb instead.

pub fn scan( &mut self, ) -> Result<Vec<Result<Response<Ping>, ReadError>>, WriteError>

Scan a bus for motors with a broadcast ping, returning the responses in a Vec.

Only timeouts are filtered out since they indicate a lack of response. All other responses (including errors) are collected.

pub fn scan_cb<F>(&mut self, on_response: F) -> Result<(), TransferError>

where F: FnMut(Response<Ping>),

Scan a bus for motors with a broadcast ping, calling an FnMut for each response.

Only timeouts are filtered out since they indicate a lack of response. All other responses (including errors) are passed to the handler.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn read( &mut self, motor_id: u8, address: u16, count: u16, ) -> Result<Response<Vec<u8>>, TransferError>

Read an arbitrary number of bytes from a specific motor.

This function will not work correctly if the motor ID is set to packet_id::BROADCAST. Use Self::sync_read to read from multiple motors with one command.

pub fn read_u8( &mut self, motor_id: u8, address: u16, ) -> Result<Response<u8>, TransferError>

Read an 8 bit register from a specific motor.

This function will not work correctly if the motor ID is set to packet_id::BROADCAST. Use Self::sync_read to read from multiple motors with one command.

pub fn read_u16( &mut self, motor_id: u8, address: u16, ) -> Result<Response<u16>, TransferError>

Read 16 bit register from a specific motor.

This function will not work correctly if the motor ID is set to packet_id::BROADCAST. Use Self::sync_read to read from multiple motors with one command.

pub fn read_u32( &mut self, motor_id: u8, address: u16, ) -> Result<Response<u32>, TransferError>

Read 32 bit register from a specific motor.

This function will not work correctly if the motor ID is set to packet_id::BROADCAST. Use Self::sync_read to read from multiple motors with one command.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn reboot(&mut self, motor_id: u8) -> Result<Response<()>, TransferError>

Send a reboot command to a specific motor.

Certain error conditions can only be cleared by rebooting a motor. When a motor reboots, all volatile (non-EEPROM) registers are reset to their initial value. This also has the effect of disabling motor torque and resetting the multi-revolution information.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

If you want to broadcast this instruction, it may be more convenient to use Self::broadcast_reboot() instead.

pub fn broadcast_reboot(&mut self) -> Result<(), WriteError>

Broadcast an reboot command to all connected motors to trigger a previously registered instruction.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn reg_write( &mut self, motor_id: u8, address: u16, data: &[u8], ) -> Result<Response<()>, TransferError>

Register a write of an arbitrary number of bytes, to be triggered later by an action command.

Only one write command can be registered per motor.

You can have all connected motors execute their registered write using Self::broadcast_action, or a single motor using Self::action.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

pub fn reg_write_u8( &mut self, motor_id: u8, address: u16, value: u8, ) -> Result<Response<()>, TransferError>

Register a write command for a 8 bit value to a specific motor.

Only one write command can be registered per motor.

You can have all connected motors execute their registered write using Self::broadcast_action, or a single motor using Self::action.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

pub fn reg_write_u16( &mut self, motor_id: u8, address: u16, value: u16, ) -> Result<Response<()>, TransferError>

Register a write command for a 16 bit value to a specific motor.

Only one write command can be registered per motor.

You can have all connected motors execute their registered write using Self::broadcast_action, or a single motor using Self::action.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

pub fn reg_write_u32( &mut self, motor_id: u8, address: u16, value: u32, ) -> Result<Response<()>, TransferError>

Register a write command for a 32 bit value to a specific motor.

Only one write command can be registered per motor.

You can have all connected motors execute their registered write using Self::broadcast_action, or a single motor using Self::action.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn sync_read_cb<'a, F>( &'a mut self, motor_ids: &'a [u8], address: u16, count: u16, on_response: F, ) -> Result<(), WriteError>

where F: FnMut(Result<Response<&[u8]>, ReadError>),

Synchronously read an arbitrary number of bytes from multiple motors in one command.

The on_response function is called for the reply from each motor. If the function fails to write the instruction, an error is returned and the function is not called.

pub fn sync_read_u8_cb<'a, F>( &'a mut self, motor_ids: &'a [u8], address: u16, on_response: F, ) -> Result<(), WriteError>

where F: FnMut(Result<Response<u8>, ReadError>),

Synchronously read an 8 bit value from multiple motors in one command.

The on_response function is called for the reply from each motor. If the function fails to write the instruction, an error is returned and the function is not called.

pub fn sync_read_u16_cb<'a, F>( &'a mut self, motor_ids: &'a [u8], address: u16, on_response: F, ) -> Result<(), WriteError>

where F: FnMut(Result<Response<u16>, ReadError>),

Synchronously read a 16 bit value from multiple motors in one command.

The on_response function is called for the reply from each motor. If the function fails to write the instruction, an error is returned and the function is not called.

pub fn sync_read_u32_cb<'a, F>( &'a mut self, motor_ids: &'a [u8], address: u16, on_response: F, ) -> Result<(), WriteError>

where F: FnMut(Result<Response<u32>, ReadError>),

Synchronously read a 32 bit value from multiple motors in one command.

The on_response function is called for the reply from each motor. If the function fails to write the instruction, an error is returned and the function is not called.

pub fn sync_read<'a>( &'a mut self, motor_ids: &'a [u8], address: u16, count: u16, ) -> Result<Vec<Response<Vec<u8>>>, TransferError>

Synchronously read an arbitrary number of bytes from multiple motors in one command.

If this function fails to get the data from any of the motors, the entire function retrns an error. If you need access to the data from other motors, or if you want acces to the error for each motor, see Self::sync_read_cb.

pub fn sync_read_u8<'a>( &'a mut self, motor_ids: &'a [u8], address: u16, ) -> Result<Vec<Response<u8>>, TransferError>

Synchronously read an 8 bit value from multiple motors in one command.

If this function fails to get the data from any of the motors, the entire function retrns an error. If you need access to the data from other motors, or if you want acces to the error for each motor, see Self::sync_read_u8_cb.

pub fn sync_read_u16<'a>( &'a mut self, motor_ids: &'a [u8], address: u16, ) -> Result<Vec<Response<u16>>, TransferError>

Synchronously read a 16 bit value from multiple motors in one command.

If this function fails to get the data from any of the motors, the entire function retrns an error. If you need access to the data from other motors, or if you want acces to the error for each motor, see Self::sync_read_u16_cb.

pub fn sync_read_u32<'a>( &'a mut self, motor_ids: &'a [u8], address: u16, ) -> Result<Vec<Response<u32>>, TransferError>

Synchronously read a 32 bit value from multiple motors in one command.

If this function fails to get the data from any of the motors, the entire function retrns an error. If you need access to the data from other motors, or if you want acces to the error for each motor, see Self::sync_read_u32_cb.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn sync_write<'a, Iter, Data, Buf>( &mut self, address: u16, count: u16, data: Iter, ) -> Result<(), WriteError>

where Iter: IntoIterator<Item = Data>, Iter::IntoIter: ExactSizeIterator, Data: AsRef<SyncWriteData<Buf>>, Buf: AsRef<[u8]> + 'a,

Synchronously write an arbitrary number of bytes to multiple motors.

Each motor will perform the write as soon as it receives the command. This gives much shorter delays than executing a regular Self::write for each motor individually.

Panics

The amount of data to write for each motor must be exactly count bytes. This function panics if that is not the case.

Example

use dynamixel2::Bus;
use dynamixel2::instructions::SyncWriteData;
use std::time::Duration;

let mut bus = Bus::open("/dev/ttyUSB0", 57600)?;
// Write to register 116 of motor 1 and and 2 at the same time.
bus.sync_write(116, 4, &[
  SyncWriteData {
    motor_id: 1,
    data: 2000u32.to_le_bytes(),
  },
  SyncWriteData {
    motor_id: 2,
    data: 1600u32.to_le_bytes(),
  },
])?;

pub fn sync_write_u8<Iter, Data>( &mut self, address: u16, data: Iter, ) -> Result<(), WriteError>

where Iter: IntoIterator<Item = Data>, Iter::IntoIter: ExactSizeIterator, Data: AsRef<SyncWriteData<u8>>,

Synchronously write a 8 bit value to multiple motors.

Each motor will perform the write as soon as it receives the command. This gives much shorter delays than executing a regular Self::write for each motor individually.

pub fn sync_write_u16<Iter, Data>( &mut self, address: u16, data: Iter, ) -> Result<(), WriteError>

where Iter: IntoIterator<Item = Data>, Iter::IntoIter: ExactSizeIterator, Data: AsRef<SyncWriteData<u16>>,

Synchronously write a 16 bit value to multiple motors.

Each motor will perform the write as soon as it receives the command. This gives much shorter delays than executing a regular Self::write for each motor individually.

pub fn sync_write_u32<Iter, Data>( &mut self, address: u16, data: Iter, ) -> Result<(), WriteError>

where Iter: IntoIterator<Item = Data>, Iter::IntoIter: ExactSizeIterator, Data: AsRef<SyncWriteData<u32>>,

Synchronously write a 32 bit value to multiple motors.

Each motor will perform the write as soon as it receives the command. This gives much shorter delays than executing a regular Self::write for each motor individually.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn write( &mut self, motor_id: u8, address: u16, data: &[u8], ) -> Result<Response<()>, TransferError>

Write an arbitrary number of bytes to a specific motor.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

pub fn write_u8( &mut self, motor_id: u8, address: u16, value: u8, ) -> Result<Response<()>, TransferError>

Write an 8 bit value to a specific motor.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

pub fn write_u16( &mut self, motor_id: u8, address: u16, value: u16, ) -> Result<Response<()>, TransferError>

Write an 16 bit value to a specific motor.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

pub fn write_u32( &mut self, motor_id: u8, address: u16, value: u32, ) -> Result<Response<()>, TransferError>

Write an 32 bit value to a specific motor.

You may specify crate::instructions::packet_id::BROADCAST as motor ID. If you do, none of the devices will reply with a response, and this function will not wait for any.

impl Bus<Vec<u8>, Vec<u8>>

pub fn open(path: impl AsRef<Path>, baud_rate: u32) -> Result<Self>

Open a serial port with the given baud rate.

This will allocate a new read and write buffer of 128 bytes each. Use Self::open_with_buffers() if you want to use a custom buffers.

pub fn new(serial_port: SerialPort) -> Result<Self, InitializeError>

Create a new bus for an open serial port.

The serial port must already be configured in raw mode with the correct baud rate, character size (8), parity (disabled) and stop bits (1).

This will allocate a new read and write buffer of 128 bytes each. Use Self::with_buffers() if you want to use a custom buffers.

impl<ReadBuffer, WriteBuffer> Bus<ReadBuffer, WriteBuffer>

where ReadBuffer: AsRef<[u8]> + AsMut<[u8]>, WriteBuffer: AsRef<[u8]> + AsMut<[u8]>,

pub fn open_with_buffers( path: impl AsRef<Path>, baud_rate: u32, read_buffer: ReadBuffer, write_buffer: WriteBuffer, ) -> Result<Self>

Open a serial port with the given baud rate.

This will allocate a new read and write buffer of 128 bytes each.

pub fn with_buffers( serial_port: SerialPort, read_buffer: ReadBuffer, write_buffer: WriteBuffer, ) -> Result<Self, InitializeError>

Create a new bus using pre-allocated buffers.

The serial port must already be configured in raw mode with the correct baud rate, character size (8), parity (disabled) and stop bits (1).

pub fn serial_port(&self) -> &SerialPort

Get a reference to the underlying SerialPort.

Note that performing any read or write with the SerialPort bypasses the read/write buffer of the bus, and may disrupt the communication with the motors. In general, it should be safe to read and write to the bus manually in between instructions, if the response from the motors has already been received.

pub fn into_serial_port(self) -> SerialPort

Consume this bus object to get ownership of the serial port.

This discards any data in internal the read buffer of the bus object. This is normally not a problem, since all data in the read buffer is also discarded when transmitting a new command.

pub fn baud_rate(&self) -> u32

Get the baud rate of the bus.

pub fn set_baud_rate(&mut self, baud_rate: u32) -> Result<(), Error>

Set the baud rate of the underlying serial port.

pub fn transfer_single<F>( &mut self, packet_id: u8, instruction_id: u8, parameter_count: usize, expected_response_parameters: u16, encode_parameters: F, ) -> Result<StatusPacket<'_>, TransferError>

where F: FnOnce(&mut [u8]),

Write a raw instruction to a stream, and read a single raw response.

This function also checks that the packet ID of the status response matches the one from the instruction.

This is not suitable for broadcast instructions. For broadcast instructions, each motor sends an individual response or no response is send at all. Instead, use Self::write_instruction and Self::read_status_response.

pub fn write_instruction<F>( &mut self, packet_id: u8, instruction_id: u8, parameter_count: usize, encode_parameters: F, ) -> Result<(), WriteError>

where F: FnOnce(&mut [u8]),

Write an instruction message to the bus.

pub fn read_status_response_deadline( &mut self, deadline: Instant, ) -> Result<StatusPacket<'_>, ReadError>

Read a raw status response from the bus with the given deadline.

pub fn read_status_response( &mut self, expected_parameters: u16, ) -> Result<StatusPacket<'_>, ReadError>

Read a raw status response with an automatically calculated timeout.

The read timeout is determined by the expected number of response parameters and the baud rate of the bus.

Trait Implementations

impl<ReadBuffer, WriteBuffer> Debug for Bus<ReadBuffer, WriteBuffer>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.