Struct raestro::Maestro

pub struct Maestro { /* fields omitted */ }

The main wrapper around the Maestro communications interface.

The impl blocks for this struct are split into three sections, two of which are included below, with the remaining being private and hidden from documentation: 1. Basic public APIs; contains the standard APIs to create, initailize, and close a Maestro instance 2. Pololu Micro Maestro Protocols; all the protocols supported by the Maestro, sendable over the UART pins on the Raspberry Pi

Implementations

impl Maestro

Basic public APIs

This section contains all the APIs required to get a maestro instance up and running.

Definitions

An initialized maestro instance is defined as an instance in which struct fields are the Some(_) variant.

An uninitialized maestro instance is an instance in which all fields are the None variant.

An invalid maestro instance is an instance which does not fit the above definitions.

All valid maestro instances must either uninitialized or initialized. An invalid maestro instance will result in undefined behaviour. All methods below are proved to either only transition a maestro instance to uninitialized and initialized states only. Therefore, invalid states are impossible to reach. This is an invariant which must (and will) be guaranteed for all provided APIs.

pub fn new() -> Self

Creates a new maestro instance in the uninitialized state.

pub fn start(&mut self, baud_rate: BaudRates) -> Result<()>

Transitions the given maestro instance to the initialized state with default configuration values.

Default block duration is set to 2seconds.

Returns an error if any fields were unable to be initialized. In the case of this failure, this instance will be closed and will be transitioned back into the uninitialized state. This is done to prevent any leakage of maestro instances into the invalid state.

pub fn close(&mut self)

Closes the maestro instance (i.e., transitions the maestro instance back into the uninitialized state).

This instance is no longer usable to communicate with the Maestro, unless until Maestro::start() is called again.

pub fn set_block_duration(&mut self, duration: Duration) -> Result<()>

Configures the block duration to the passed in value.

Default block duration is set to 2seconds.

Note

Reading from the Maestro is implemented as a blocking read. Given that the Maestro only writes back when requested to do so, and that writes coming from the Maestro happen immediately after requests sent to it, (implying that waiting times are minimal), a blocking read is sufficient (and probably more efficient than implementing any sort of asynchronous functionality).

Returns an error if the maestro instance has not been initialized by calling Maestro::start().

impl Maestro

Pololu Micro Maestro Protocols

These protocols are officially supported by the Pololu Micro Maestro 6-Channel.

For interacting with the Pololu, the official “Pololu-Protocol” is being utilized.

More information on the Pololu-Protocol can be found at the official Pololu Micro Maestro documentation pages, available here. Information on the available serial commands, as well as the specific protocols officially supported (for each type of Maestro), is available in section 5.e.

pub fn set_target(&mut self, channel: Channels, target: u16) -> Result<()>

Sets the target of the servo motor at the given channel with the given microseconds.

Microsecond ranges can only be between 992us and 2000us. However, the input to set_target is in quarter microseconds. Thus, the accepted range to set_target is between 3968 and 8000. Any values outside of this range will return an error.

The units to set_target are in: target * (0.25) [us]

Example Usage

use raestro::prelude::*;

let mut m = Maestro::new();
m.start(BaudRates::BR_115200).unwrap();

let channel: Channels = Channels::C_0; // can be any arbitrary channel in the Channels enum
let qtr_microsec = 4000u16; // can be any value between 3968 and 8000
// 4000 quarter microsecs would be 1000us, thus this example sets a target of 1000us

m.set_target(channel, qtr_microsec);

pub fn set_speed(&mut self, channel: Channels, speed: u16) -> Result<()>

Sets the rotational speed of the servo motor at the given channel with the given speed.

The units to set_speed are in: speed * (0.025) [us / ms]

Example Usage

use raestro::prelude::*;

let mut m = Maestro::new();
m.start(BaudRates::BR_115200).unwrap();

let channel: Channels = Channels::C_0; // can be any arbitrary channel in the Channels enum
let speed = 10u16;

m.set_speed(channel, speed);

pub fn set_acceleration(
    &mut self,
    channel: Channels,
    acceleration: u8
) -> Result<()>

Sets the rotational acceleration limit of the servo motor at the given channel with the given value.

The acceleration can be any usigned 8-bit integer from 1u8 to 255u8. An acceleration of 0u8 will command the Maestro to not set any acceleration limit.

Note that an acceleration limit causes the servo to speed up and the slow down as it approaches the target. By having no acceleration limit, this behaviour is disabled.

The units to set_acceleration are in: acceleration * 0.0003125 [us / ((ms)^2)]

Example Usage

use raestro::prelude::*;

let mut m = Maestro::new();
m.start(BaudRates::BR_115200).unwrap();

let channel: Channels = Channels::C_0; // can be any arbitrary channel in the Channels enum
let acceleration = 10u8;

m.set_acceleration(channel, acceleration);

pub fn go_home(&mut self) -> Result<()>

Sends all servos to home position.

Home position is defined as 992us.

Example Usage

use raestro::prelude::*;

let mut m = Maestro::new();
m.start(BaudRates::BR_115200).unwrap();

m.go_home();

pub fn stop_script(&mut self) -> Result<()>

Stops all requested actions sent to the Maestro to be stopped immediately.

Example Usage

use raestro::prelude::*;

let mut m = Maestro::new();
m.start(BaudRates::BR_115200).unwrap();

m.stop_script();

pub fn get_position(&mut self, channel: Channels) -> Result<u16>

Gets the PWM signal being broadcasted to the servo at the given channel.

Important

In order to rotate the servos, the Maestro sends a PWM signal over the corresponding channel. This is, in essence, what is happening when set_target is called. However, this signal can still be sent even if a servo motor is not connected to the pins; the only difference here being that no servo is connected to execute the rotation, but the signal is still sent, regardless.

The get_position request will only return the PWM that is being broadcasted on the channel. Using this method will NOT help you in determining servo failures, incorrect servo positions, etc. This method will only return the PWM that is being broadcasted on the given channel.

The Maestro, in and of itself, cannot possibly know if a servo is or is not at the location that was encoded in the request (i.e., if the servo failed half-way through exectution). As such, raestro cannot support this functionality either. If this functionality is required for your project, you will need to develop additional hardware.

get_position returns the PWM being broadcasted in quarter microsec. If get_position returns 4000, the servo is currently broadcasting 1000us to the respective channel.

Example Usage

use raestro::prelude::*;

let mut m = Maestro::new();
m.start(BaudRates::BR_115200).unwrap();

let channel: Channels = Channels::C_0; // can be any arbitrary channel in the Channels enum
let target = 4000u16; // can be any value between 3968u16 and 8000u16

m.set_target(channel, target);

let actual_position = m.get_position(channel).unwrap();

assert_eq!(target, actual_position);

pub fn get_errors(&mut self) -> Result<Vec<Errors>>

Gets any errors encountered by the Maestro during execution.

Important

This method will not inform you of any failures with the servo hardware. The Maestro, in and of itself, is not capable of determining external hardware malfunctions. If your project requires this feature, you will need to develop additional hardware to implement it.

Example Usage

use raestro::prelude::*;

let mut m = Maestro::new();
m.start(BaudRates::BR_115200).unwrap();

let errors = m.get_errors().unwrap();

Trait Implementations

impl Debug for Maestro

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

Formats the value using the given formatter.

impl Default for Maestro

fn default() -> Self

Returns the “default value” for a type.