Big cleanup/updates (#1)

* Package upgrades, fix lib code

* Fix/update all examples

* Simplify crate structure a bunch

Need to update/populate docs but this compiles at least

* Fix examples

* Test lib/doc examples in CI

* Check doc links in CI

* Nicer message when TARGET is undefined

* Check formatting in CI

* Add nightly rustfmt config for doc formatting

* Fix doc tests

* Move module docs onto structs

Makes things much more discoverable when browsing

* Update docs to be more accurate

* Update and test README example in CI

* Add changelog

* fixup! Check doc links in CI

* Add custom error type for more flexibility

* Remove builder, consolidate properties/display.rs

* Add basic migration guide to changelog/readme

* Ignore README examples, fix copypasta

* Fix bugs in command definitions

* Improve display init procedure

* Fix rotation example

* Polish BMP and rotation examples

* Use e-g Triangle primitive instead of lines

* Bump changelog

* Run nightly cargo format

* Remove debugging/dev examples

* Update README example

Author: jamwaffles

.travis.yml

@@ -38,15 +38,18 @@ matrix:
     - rust: nightly
 
 install:
+  - pip install linkchecker --user
   - rustup component add rust-src
+  - rustup component add rustfmt
+  - rustup target add thumbv7m-none-eabi
   - |
-      SYSROOT=$(rustc --print sysroot)
+    SYSROOT=$(rustc --print sysroot)
 
-      if [[ ! "$SYSROOT" =~ "$TARGET" ]]; then
-        rustup target add $TARGET
-      else
-        echo "Target $TARGET is already installed"
-      fi
+    if [[ ! "$SYSROOT" =~ "$TARGET" ]]; then
+      rustup target add $TARGET
+    else
+      echo "Target $TARGET is already installed"
+    fi
   - source ~/.cargo/env || true
 
 script:

CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+`ssd1331` is a Rust driver for the SSD1331 OLED display driver/module. It implements the
+`embedded-hal` traits to allow easy integration with embedded Rust projects using an SPI interface.
+
+## Unreleased
+
+- None
+
+### Added
+
+- None
+
+### Changed
+
+- None
+
+### Fixed
+
+- None
+
+### Security
+
+- None
+
+## 0.2.0-alpha.1
+
+The driver has been drastically simplified with removal of the `RawMode` and `GraphicsMode` structs, as well as the `Builder`.
+
+[embedded-graphics](https://crates.io/crates/embedded-graphics) is also upgraded to version `0.6.0-alpha.2`, so there may be breaking changes around uses of embedded-graphics.
+
+### Migrating from 0.1 to 0.2
+
+Version 0.1.x
+
+```rust
+use ssd1331::{prelude::*, Builder};
+
+let mut disp: GraphicsMode<_> = Builder::new().connect_spi(spi, dc).into();
+
+disp.reset(&mut rst, &mut delay);
+disp.init().unwrap();
+disp.flush().unwrap();
+
+disp.get_dimensions();
+disp.get_rotation();
+```
+
+Version 0.2.x
+
+```rust
+use ssd1331::{Ssd1331, DisplayRotation};
+
+let mut disp = Ssd1331::new(spi, dc, DisplayRotation::Rotate0);
+
+disp.reset(&mut rst, &mut delay).unwrap();
+disp.init().unwrap();
+disp.flush().unwrap();
+
+disp.dimensions();
+disp.rotation();
+```
+
+### Added
+
+- Added `ssd1331::Error` enum with pin (if DC pin fails to set) and communication error (if SPI write fails) variants. The return type of fallible methods has changed from `Result<(), ()>` to `Result<(), ssd1331::Error<CommE, PinE>>`. `CommE` and `PinE` default to `()` so no user code changes should be required.
+
+### Changed
+
+- Upgraded [embedded-graphics](https://crates.io/crates/embedded-graphics) to 0.6.0-alpha.2
+- **(breaking)** `display.get_dimensions()` is renamed to `display.dimensions()`
+- **(breaking)** The `Builder` struct has been removed. Use `Ssd1331::new()` instead. Code that looked like this:
+
+  ```rust
+  use ssd1331::{prelude::*, Builder};
+
+  let mut disp: GraphicsMode<_> = Builder::new().connect_spi(spi, dc).into();
+
+  disp.reset(&mut rst, &mut delay);
+  disp.init().unwrap();
+  disp.flush().unwrap();
+  ```
+
+  Should now look like this:
+
+  ```rust
+  use ssd1331::{Ssd1331, DisplayRotation};
+
+  let mut disp = Ssd1331::new(spi, dc, DisplayRotation::Rotate0);
+
+  disp.reset(&mut rst, &mut delay).unwrap();
+  disp.init().unwrap();
+  disp.flush().unwrap();
+  ```
+
+- **(breaking)** Crate import structure has been simplified. Imports that looked like this:
+
+  ```rust
+  use ssd1331::prelude::*;
+  use ssd1331::Builder;
+  ```
+
+  Should now look like this:
+
+  ```rust
+  use ssd1331::{Ssd1331, DisplayRotation};
+  ```
+
+  See above items about removal of `Builder` struct.
+
+### Deprecated
+
+- None
+
+### Removed
+
+- **(breaking)** Removed `RawMode` and `GraphicsMode` traits. The `.set_pixel()` and `.draw()` methods can now be used directly on the `Ssd1331` struct.
+- **(breaking)** Removed `Builder` struct.
+
+### Fixed
+
+- None
+
+### Security
+
+- None

Cargo.toml

@@ -16,19 +16,24 @@ branch = "master"
 repository = "jamwaffles/ssd1331"
 
 [dependencies]
-embedded-hal = "0.2.2"
+embedded-hal = "0.2.3"
 
 [dependencies.embedded-graphics]
 optional = true
-version = "0.4.5"
+version = "0.6.0-alpha.2"
+
+# Turns `bmp` feature on in examples to enable `ImageBmp`
+[dev-dependencies.embedded-graphics]
+version = "0.6.0-alpha.2"
+features = ["bmp"]
 
 [dev-dependencies]
-cortex-m = "0.5.8"
-cortex-m-rt = "0.6.7"
-panic-semihosting = "0.5.1"
+cortex-m = "0.6.1"
+cortex-m-rt = "0.6.11"
+panic-semihosting = "0.5.3"
 
 [dev-dependencies.stm32f1xx-hal]
-version = "0.2.0"
+version = "0.5.2"
 features = [ "rt", "stm32f103" ]
 
 [features]

README.md

@@ -23,26 +23,22 @@ You can also export images directly from The GIMP by saving as `.bmp` and choosi
 
 ## [Examples](examples)
 
-Load a BMP and display it in the center of the display. From [`examples/bmp.rs`](examples/bmp.rs):
+Load a BMP image of the Rust logo and display it in the center of the display. From
+[`examples/bmp.rs`](examples/bmp.rs):
 
-```rust
+```rust,ignore
 #![no_std]
 #![no_main]
 
-extern crate cortex_m;
-extern crate cortex_m_rt as rt;
-extern crate panic_semihosting;
-extern crate stm32f1xx_hal as hal;
-
 use cortex_m_rt::ExceptionFrame;
 use cortex_m_rt::{entry, exception};
-use embedded_graphics::image::Image1BPP;
-use embedded_graphics::prelude::*;
-use hal::i2c::{BlockingI2c, DutyCycle, Mode};
-use hal::prelude::*;
-use hal::stm32;
-use ssd1331::prelude::*;
-use ssd1331::Builder;
+use embedded_graphics::{geometry::Point, image::ImageBmp, prelude::*};
+use panic_semihosting as _;
+use ssd1331::{Ssd1331, DisplayRotation::Rotate0};
+use stm32f1xx_hal::delay::Delay;
+use stm32f1xx_hal::prelude::*;
+use stm32f1xx_hal::spi::{Mode, Phase, Polarity, Spi};
+use stm32f1xx_hal::stm32;
 
 #[entry]
 fn main() -> ! {
@@ -59,6 +55,8 @@ fn main() -> ! {
     let sck = gpioa.pa5.into_alternate_push_pull(&mut gpioa.crl);
     let miso = gpioa.pa6;
     let mosi = gpioa.pa7.into_alternate_push_pull(&mut gpioa.crl);
+    let mut delay = Delay::new(cp.SYST, clocks);
+    let mut rst = gpiob.pb0.into_push_pull_output(&mut gpiob.crl);
     let dc = gpiob.pb1.into_push_pull_output(&mut gpiob.crl);
 
     let spi = Spi::spi1(
@@ -74,19 +72,24 @@ fn main() -> ! {
         &mut rcc.apb2,
     );
 
-    let mut disp: GraphicsMode<_> = Builder::new().connect_spi(spi, dc).into();
+    let mut disp = Ssd1331::new(spi, dc, DisplayRotation::Rotate0);
 
+    disp.reset(&mut rst, &mut delay).unwrap();
     disp.init().unwrap();
     disp.flush().unwrap();
 
-    // 16BPP, RGB565-format BMP image
+    let (w, h) = disp.dimensions();
+
     let im = ImageBmp::new(include_bytes!("./rust-pride.bmp")).unwrap();
 
-    let centered = im.translate(Coord::new((96 - im.width() as i32) / 2, 0));
+    // Position image in the center of the display
+    let moved = im.translate(Point::new(
+        (w as u32 - im.width()) as i32 / 2,
+        (h as u32 - im.height()) as i32 / 2,
+    ));
 
-    disp.draw(centered.into_iter());
+    disp.draw(moved.into_iter());
 
-    disp.draw(im.into_iter());
     disp.flush().unwrap();
 
     loop {}
@@ -96,18 +99,51 @@ fn main() -> ! {
 fn HardFault(ef: &ExceptionFrame) -> ! {
     panic!("{:#?}", ef);
 }
-
 ```
 
 ![Rust rainbow demo image.](readme_pride.jpg?raw=true)
 
+## Migrating from 0.1 to 0.2
+
+The full changelog can be found [here](CHANGELOG.md). A tl;dr version is shown below.
+
+Version 0.1.x
+
+```rust,ignore
+use ssd1331::{prelude::*, Builder};
+
+let mut disp: GraphicsMode<_> = Builder::new().connect_spi(spi, dc).into();
+
+disp.reset(&mut rst, &mut delay);
+disp.init().unwrap();
+disp.flush().unwrap();
+
+disp.get_dimensions();
+disp.get_rotation();
+```
+
+Version 0.2.x
+
+```rust,ignore
+use ssd1331::{Ssd1331, DisplayRotation};
+
+let mut disp = Ssd1331::new(spi, dc, DisplayRotation::Rotate0);
+
+disp.reset(&mut rst, &mut delay).unwrap();
+disp.init().unwrap();
+disp.flush().unwrap();
+
+disp.dimensions();
+disp.rotation();
+```
+
 ## License
 
 Licensed under either of
 
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
-  http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+-   Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+    http://www.apache.org/licenses/LICENSE-2.0)
+-   MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.
 

build.rs

@@ -1,7 +1,4 @@
-use std::env;
-use std::fs::File;
-use std::io::Write;
-use std::path::PathBuf;
+use std::{env, fs::File, io::Write, path::PathBuf};
 
 pub fn main() {
     // Put the linker script somewhere the linker can find it

build.sh

@@ -1,9 +1,30 @@
 #!/bin/sh
 
+# Exit early on error
 set -e
 
+# Print commands as they're run
+set -x
+
+if [ -z $TARGET ]; then
+    echo "TARGET environment variable required but not set"
+
+    exit 1
+fi
+
+cargo fmt --all -- --check
+
 cargo build --target $TARGET --all-features --release
 
+cargo test --lib --target x86_64-unknown-linux-gnu
+
+# Always test docs against thumbv7m target as the complete readme example needs to compile against it
+cargo test --doc --target thumbv7m-none-eabi
+
 if [ -z $DISABLE_EXAMPLES ]; then
 	cargo build --target $TARGET --all-features --examples
-fi
+fi
+
+cargo doc --all-features --target $TARGET
+
+linkchecker target/$TARGET/doc/ssd1331/index.html