4 releases (breaking)
0.5.0 | Dec 4, 2022 |
---|---|
0.4.1 |
|
0.3.0 | May 6, 2021 |
0.2.0 | Apr 14, 2021 |
0.1.0 | Feb 13, 2021 |
#897 in Hardware support
44KB
490 lines
raestro
- A Rust-flavoured API Interface for the Pololu Micro-Maestro (6-Channel) Servo Controller Board
raestro
provides an easy-to-use interface to communicate with the 6-Channel Maestro.
It is developed and maintained by UBC Bionics, Ltd., a design team based in the University of British Columbia, Vancouver, Canada.
Table of Contents
Prelude
Before continuing, please take note of the following points:
- This library is developed specifically for the Raspberry Pi.
- Please take caution in wiring the Pololu Micro Maestro to the Raspberry Pi. Incorrect wiring may lead to permanent hardware damage.
Documentation
All public exports have been properly documented with examples for usage of critical APIs.
A complete version of the documentation can be found here.
Included below is a minimal example of how to setup your environment and build a project using raestro
.
Getting Started
Hardware Setup
- Connect the power and ground lines from the Raspberry Pi to the Maestro.
- Connect the Raspberry Pi's TX and RX pins to the Maestro's RX and TX pins, respectively. Please note the order in which the pins need to be connected (the Pi's TX connected to the Maestro's RX and the Pi's RX connected to the Maestro's TX).
- Connect the power lines for the servos. Documentation on which line is which is available readily online.
- Connect up to 6 servos to one of the pin-triples available (the backside of the board has more info on each pin-type).
Software Setup
The Rust crate rppal
provides user-level APIs for protocols such as PWM
, I2C
, and UART
.
In order to configure UART
for the Raspberry Pi, do the following:
- Remove
console=serial0,11520
from/boot/cmdline.txt
- Disable the Bluetooth by:
- Adding
dtoverlay=pi3-disable-bt
to/boot/config.txt
- For the RPi4 models, do this by adding
dtoverlay=disable-bt
instead - Rebooting the Pi (by powering it off and then on again)
- For the RPi4 models, do this by adding
- Running the command
sudo systemctl disable hciuart
- Adding
Trouble-shooting
If permission denied errors are being observed, please inspect your user's permissions.
More specifically, your user must be added to group dialout
.
If cargo build
or cargo test
do not work because of the rppal
dependency, check the rppal
documentations on how to set up UART
.
The link is here.
Usage
Add the following to your Cargo.toml
file:
[dependencies]
raestro = "0.3.0"
Finally, create a new maestro
instance and initialize it by calling Maestro::start
.
This initialized struct can now be utilized to perform reads and writes to and from the Micro-Maestro 6-Channel.
use std::convert::TryInto;
use std::thread;
use std::time::Duration;
use raestro::maestro::builder::Builder;
use raestro::maestro::constants::Baudrate;
use raestro::maestro::constants::Channel
use raestro::maestro::constants::MAX_QTR_PWM;
use raestro::maestro::constants::MIN_QTR_PWM;
use raestro::maestro::Maestro;
fn main() -> ! {
// Create a new `Maestro` instance by configuring a `Builder`.
let mut maestro: Maestro = Builder::default()
.baudrate(Baudrate::Baudrate11520)
.block_duration(Duration::from_millis(100))
.try_into()
.expect("Failed to build a `maestro` instance.");
let channel = Channel::Channel0;
let pos_min = MIN_QTR_PWM;
let pos_max = MAX_QTR_PWM;
let sleep_duration = Duration::from_secs(1);
// Set the initial position of the servo at the specified channel to the specified location!
maestro.set_target(channel, pos_min).unwrap();
let position = maestro.get_position(channel).unwrap();
// Assert that the requested position is truly being broadcast on the requested channel.
assert_eq!(position, pos_min);
thread::sleep(sleep_duration);
// Move the servo back!
maestro.set_target(channel, pos_max).unwrap();
let position = maestro.get_position(channel).unwrap();
// Once again, assert that the requested position is truly being broadcast on the requested channel.
assert_eq!(position, pos_max);
thread::sleep(sleep_duration);
}
More examples of API usage are provided in the examples
folder.
Dependencies
~0.6–1.1MB
~24K SLoC