Merge pull request #29 from raunakab/master

integrate github workflows on self-hosted runner, format code using clippy

.github/workflows/main.yml

@@ -0,0 +1,51 @@
+on: [push]
+
+# pi is the UBC Bionics Raspberry Pi
+# mb is raunakab's personal Macbook Pro
+# both are self-hosted runners, and may not be available to accept jobs at all times
+name: Raestro (pi/mb)-Split CI
+
+jobs:
+  job-rpi-1:
+    name: Check (rpi)
+    runs-on: raspberrypi
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          command: check
+
+  job-rpi-2:
+    name: Test Suite (rpi)
+    runs-on: raspberrypi
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          command: test
+
+  job-mb-1:
+    name: Nightly Format (mb)
+    runs-on: macbook
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: nightly
+          override: true
+      - run: rustup component add rustfmt
+      - uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: --all -- --check

CHANGELOG.md

@@ -16,6 +16,12 @@ Note that all dates are in DD/MM/YYYY form.
 * finished documentation for all public modules and exports
 * formatted library using rustfmt (all formatting rules can be found in rustfmt.toml)
 * fixed implementation for raestro::constants::Errors
-	* when an error or errors are encountered, the Maestro returns a 2-byte (u16) integer in which each of the first 9 positions (i.e., bit 0 to bit 8) represent an error
-	* if the bit in position i (where i = 0..=8) is set, then the according error was thrown by the Maestro
-	* previous implementation of constants::Errors assumed that each error had a specific number attached to it (i.e., SER_SIGNAL_ERR was 0, SER_BUFFER_ERR was 1, etc.), which is incorrect
+	* when an error or errors are encountered, the Maestro returns a 2-byte (`u16`) integer in which each of the first 9 positions (i.e., bit 0 to bit 8) represent an error
+	* if the bit in position i (where i = `0..=8`) is set, then the according error was thrown by the Maestro
+	* previous implementation of `constants::Errors` assumed that each error had a specific number attached to it (i.e., `SER\_SIGNAL\_ERR` was `0`, `SER\_BUFFER\_ERR` was `1`, etc.), which is incorrect
+
+### 05/06/2021
+* the underlying `uart` instance was incorrectly configured to wait indefinitely if no bytes were read on the `UART` lines
+* this was updated so that `Maestro::read` would only block for 2 seconds, max  (default configuration)
+* `Maestro::set_target` was updated to take in values in units of quarter-us, not us, since all other `raestro` APIs expect values in units of quarter-us
+	* docs were updated to reflect this change

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "raestro"
-version = "0.2.0"
+version = "0.3.0"
 authors = ["nathan-n-poon <nathannpoon@gmail.com>", "raunakab <rabhagat31@gmail.com>", "KelvinKCLee <leekachunkelvin@gmail.com>", "bzhou64 <billzhou64@gmail.com>", "panchalmaharshi8 <panchalmaharshi8@gmail.com>"]
 edition = "2018"
 license = "MIT"

README.md

@@ -1,10 +1,10 @@
-# Raestro - A Rust-flavoured API Interface for the Pololu Micro-Maestro (6-Channel) Servo Controller Board
-[![Build Status](https://travis-ci.com/raunakab/raestro.svg?branch=master)](https://travis-ci.com/github/raunakab/raestro)
+# `raestro` - A Rust-flavoured API Interface for the Pololu Micro-Maestro (6-Channel) Servo Controller Board
+[![build\_status](https://github.com/raunakab/raestro/actions/workflows/main.yml/badge.svg)](https://github.com/raunakab/raestro/actions/workflows/main.yml)
 [![crates.io](https://meritbadge.herokuapp.com/raestro)](https://crates.io/crates/raestro)
 [![docs](https://docs.rs/raestro/badge.svg)](https://docs.rs/crate/raestro)
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
 
-Raestro is developed and maintained by [UBC Bionics, Ltd.](https://ubcbionics.com/), a design team based in the University of British Columbia, Vancouver, Canada.
+`raestro` is developed and maintained by [UBC Bionics, Ltd.](https://ubcbionics.com/), a design team based in the University of British Columbia, Vancouver, Canada.
 
 ## Table of Contents
 - [Prelude](#Prelude)
@@ -19,39 +19,40 @@ Raestro is developed and maintained by [UBC Bionics, Ltd.](https://ubcbionics.co
 This library is developed specifically for the Raspberry Pi, which acts as the main computer system on our bionic arm. Builds on different architectures will not be guaranteed to work.
 
 ## Documentation
-As of current, documentation for this library and all of its APIs is still being worked on. However, design decisions on Raestro are now finally starting to stabilize, and as such, documentation will soon be available as part of the next incremental release.
+All public exports have been properly documented with examples for usage of critical APIs.
+A complete version of the documentation can be found [here](https://docs.rs/raestro).
+Included below is a minimal example of how to setup your environment and build a project using `raestro`.
 
 ## Getting Started
 
 ### Hardware Setup
-1. Connect the power+ground lines from the RPi to the Maestro.
-2. Connect the RPI'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 (RPi TX connected to Maestro RX; RPi RX connected to Maestro TX).
-3. Connect the power lines for the servos (holding the board such that the pins are facing you and are on the right side of the board,these are the 2 pins on the top right). The left one of the pair is the power; the right one is ground.
-4. Connect up to 6 servos on one of the pin-triples available (the backside of the board has more info on each pin-type).
+1. Connect the power and ground lines from the Raspberry Pi to the Maestro.
+2. 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).
+3. Connect the power lines for the servos. Documentation on which line is which is available readily online.
+4. 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:
-1. Remove "console=serial0,11520" from /boot/cmdline.txt
+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:
+1. Remove `console=serial0,11520` from `/boot/cmdline.txt`
 2. Disable the Bluetooth by:
-	* Adding "dtoverlay=pi3-disable-bt" to /boot/config.txt (without the quotation marks)
-		* For the RPi4 models, add "dtoverlay=disable-bt" instead
-		* Once this is done, reboot the Pi (by powering it off and then on again)
-		* Connecting GPIO Pin-14 (physical pin 08) to an LED, this LED should be LIT
-	* Running the command "sudo systemctl disable hciuart"
+	* 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)
+	* Running the command `sudo systemctl disable hciuart`
 
 ### Trouble-shooting
-If "cargo build" or "cargo test" do not work because of the rppal dependency, check the rppal documentations on how to set up UART.
+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](https://docs.rs/rppal/0.11.3/rppal/uart/index.html).
 
 ## Usage
-Add the following to your Cargo.toml file:
+Add the following to your `Cargo.toml` file:
 ```toml
 [dependencies]
-raestro = "0.2.0"
+raestro = "0.3.0"
 ```
-In the main function, create a new Maestro instance and initialize it by calling start.
-This initialized struct can now be utilized to perform writes and reads to and from the Maestro.
+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.
 ```rust
 use raestro::prelude::*;
 
@@ -62,14 +63,15 @@ fn main() -> () {
 	let channel = Channels::C_0;
 
 	// the position is in microseconds and can only be between 992 and 2000
+	// the set_target method takes in a target in quarter microseconds, so multiply the desired value by 4
 	// (specifically for the Pololu Micro-Maestro 6-Channel Board)
-	let position = 992u16;
+	let target = 3968u16;
 
-	maestro.set_target(channel, position).unwrap();
+	maestro.set_target(channel, target).unwrap();
 
 	let actual_position = maestro.get_position(channel).unwrap();
 
-	assert_eq!(position, actual_position);
+	assert_eq!(target, actual_position);
 }
 ```
-More examples of API usage are provided in the examples folder.
+More examples of API usage are provided in the `examples` folder.

examples/get_position.rs

@@ -25,23 +25,23 @@ fn main() -> () {
 
     let channel: Channels = Channels::C_0;
 
-    let pos_min = 992u16;
-    let pos_max = 2000u16;
+    let target_min = 3968u16;
+    let target_max = 8000u16;
 
     let sleep_time = Duration::from_millis(1000u64);
 
     #[allow(unused_assignments)]
     let mut current_position: Option<u16> = None;
 
     loop {
-        maestro.set_target(channel, pos_min).unwrap();
+        maestro.set_target(channel, target_min).unwrap();
         current_position = Some(maestro.get_position(channel).unwrap());
-        println!("current position: {:?}", current_position.unwrap());
+        assert_eq!(current_position.unwrap(), target_min);
         thread::sleep(sleep_time);
 
-        maestro.set_target(channel, pos_max).unwrap();
+        maestro.set_target(channel, target_max).unwrap();
         current_position = Some(maestro.get_position(channel).unwrap());
-        println!("current position: {:?}", current_position.unwrap());
+        assert_eq!(current_position.unwrap(), target_max);
         thread::sleep(sleep_time);
     }
 }

examples/set_acceleration.rs

@@ -25,21 +25,21 @@ fn main() -> () {
 
     let channel: Channels = Channels::C_0;
 
-    let accel0 = 1u8;
-    let accel1 = 255u8;
+    let accel_min = 1u8;
+    let accel_max = 255u8;
 
-    let pos0 = 992u16;
-    let pos1 = 2000u16;
+    let target_min = 3968u16;
+    let target_max = 8000u16;
 
     let sleep_time = Duration::from_millis(5000u64);
 
     loop {
-        maestro.set_acceleration(channel, accel0).unwrap();
-        maestro.set_target(channel, pos0).unwrap();
+        maestro.set_acceleration(channel, accel_min).unwrap();
+        maestro.set_target(channel, target_min).unwrap();
         thread::sleep(sleep_time);
 
-        maestro.set_acceleration(channel, accel1).unwrap();
-        maestro.set_target(channel, pos1).unwrap();
+        maestro.set_acceleration(channel, accel_max).unwrap();
+        maestro.set_target(channel, target_max).unwrap();
         thread::sleep(sleep_time);
     }
 }

examples/set_speed.rs

@@ -28,18 +28,18 @@ fn main() -> () {
     let speed0 = 10u16;
     let speed1 = 140u16;
 
-    let pos0 = 992u16;
-    let pos1 = 2000u16;
+    let target_min = 3968u16;
+    let target_max = 8000u16;
 
     let sleep_time = Duration::from_millis(1000u64);
 
     loop {
         maestro.set_speed(channel, speed0).unwrap();
-        maestro.set_target(channel, pos0).unwrap();
+        maestro.set_target(channel, target_min).unwrap();
         thread::sleep(sleep_time);
 
         maestro.set_speed(channel, speed1).unwrap();
-        maestro.set_target(channel, pos1).unwrap();
+        maestro.set_target(channel, target_max).unwrap();
         thread::sleep(sleep_time);
     }
 }

examples/set_target.rs

@@ -27,8 +27,8 @@ fn main() -> () {
     let channel1: Channels = Channels::C_1;
     let channel2: Channels = Channels::C_2;
 
-    let pos_min = 992u16;
-    let pos_max = 2000u16;
+    let pos_min = 3968u16;
+    let pos_max = 8000u16;
 
     let sleep_time = Duration::from_millis(1000u64);
 

examples/stop_script.rs

@@ -25,17 +25,17 @@ fn main() -> () {
 
     let channel: Channels = Channels::C_0;
 
-    let pos0 = 992u16;
-    let pos1 = 2000u16;
+    let target_min = 3968u16;
+    let target_max = 8000u16;
 
     let sleep_time = Duration::from_millis(1000u64);
 
     loop {
-        maestro.set_target(channel, pos0).unwrap();
+        maestro.set_target(channel, target_min).unwrap();
         maestro.stop_script().unwrap();
         thread::sleep(sleep_time);
 
-        maestro.set_target(channel, pos1).unwrap();
+        maestro.set_target(channel, target_max).unwrap();
         maestro.stop_script().unwrap();
         thread::sleep(sleep_time);
     }