Struct dynamixel2::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<(), TransferError>

Send an action command to trigger a previously registered instruction.

The motor_id parameter may be set to packet_id::BROADCAST, although the Self::broadcast_action is generally easier to use.

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<BulkRead>,
    F: FnMut(Result<BulkData<&[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<BulkData<Vec<u8>>>, TransferError>where
    Read: AsRef<BulkRead>,

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<Write, T>(
    &mut self,
    writes: &[Write]
) -> Result<(), WriteError>where
    Write: Borrow<BulkData<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.

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<(), 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.

The motor_id parameter may be set to packet_id::BROADCAST, although the Self::broadcast_clear_revolution_counter is generally easier to use.

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<(), 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.

The motor_id parameter may be set to packet_id::BROADCAST, although the Self::broadcast_factory_reset is generally easier to use.

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.

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<PingResponse, 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<PingResponse, 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<(), WriteError>where
    F: FnMut(Result<PingResponse, ReadError>),

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<ReadResponse<'_, ReadBuffer, WriteBuffer>, 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<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<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<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<(), 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.

The motor_id parameter may be set to packet_id::BROADCAST, although the Self::broadcast_reboot is generally easier to use.

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<(), 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.

pub fn reg_write_u8(
    &mut self,
    motor_id: u8,
    address: u16,
    value: u8
) -> Result<(), 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.

pub fn reg_write_u16(
    &mut self,
    motor_id: u8,
    address: u16,
    value: u16
) -> Result<(), 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.

pub fn reg_write_u32(
    &mut self,
    motor_id: u8,
    address: u16,
    value: u32
) -> Result<(), 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.

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<SyncData<&[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<SyncData<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<SyncData<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<SyncData<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, F>(
    &'a mut self,
    motor_ids: &'a [u8],
    address: u16,
    count: u16
) -> Result<Vec<SyncData<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, F>(
    &'a mut self,
    motor_ids: &'a [u8],
    address: u16
) -> Result<Vec<SyncData<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, F>(
    &'a mut self,
    motor_ids: &'a [u8],
    address: u16
) -> Result<Vec<SyncData<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, F>(
    &'a mut self,
    motor_ids: &'a [u8],
    address: u16
) -> Result<Vec<SyncData<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>(
    &mut self,
    address: u16,
    count: u16,
    data: Iter
) -> Result<(), WriteError>where
    Iter: IntoIterator<Item = Data>,
    Iter::IntoIter: ExactSizeIterator,
    Data: AsRef<SyncData<&'a [u8]>>,

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.

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<SyncData<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<SyncData<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<SyncData<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<(), TransferError>

Write an arbitrary number of bytes to a specific motor.

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

Write an 8 bit value to a specific motor.

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

Write an 16 bit value to a specific motor.

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

Write an 32 bit value to a specific motor.

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

pub fn open(
    path: impl AsRef<Path>,
    baud_rate: u32,
    read_timeout: Duration
) -> 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(stream: SerialPort, read_timeout: Duration) -> Self

Create a new bus for an open serial port.

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_timeout: Duration,
    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_timeout: Duration,
    read_buffer: ReadBuffer,
    write_buffer: WriteBuffer
) -> Self

Create a new bus using pre-allocated buffers.

pub fn transfer_single<F>(
    &mut self,
    packet_id: u8,
    instruction_id: u8,
    parameter_count: usize,
    encode_parameters: F
) -> Result<Response<'_, ReadBuffer, WriteBuffer>, 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(
    &mut self
) -> Result<Response<'_, ReadBuffer, WriteBuffer>, ReadError>

Read a raw status response from the bus.