Restructure crate to simplify usage/contributing (#150)

* First passing build

* Only allow reset() for SPI interfaces

* Fix default addressing mode to Horizontal

* Upgrade example deps

* Tidy CI config

* Get rid of linkchecker

* Fix doc formatting

* Attempt to fix cast issue

* Changelog entry

* Remove I2C builder, replace with static methods

* Add some more docs

* More restructuring

* Update to new pattern using into_* methods

* Fix changelog

* Remove pinned version hack

* Use bools for pixel color values

* Rename some methods

* Fix potential underflow error

* Rename get_position to position

* Remove panics from set area methods

* Add clear() method to basic mode

* Update README example

Author: jamwaffles

.cargo/config

@@ -23,4 +23,4 @@ rustflags = [
 ]
 
 [build]
-target = "thumbv7m-none-eabi"
+target = "thumbv7m-none-eabi"

.circleci/config.yml

@@ -1,12 +1,11 @@
 target_steps: &target_steps
   docker:
-    - image: circleci/rust:1.41.0
+    - image: cimg/rust:1.51.0
   steps:
     - checkout
     - restore_cache:
-        key: v2-ssd1306-{{ .Environment.CIRCLE_JOB }}-{{ checksum "Cargo.toml" }}
+        key: v3-ssd1306-{{ .Environment.CIRCLE_JOB }}-{{ checksum "Cargo.toml" }}
     - run: rustup self update
-    - run: sudo apt install -qq linkchecker
     - run: rustup default ${RUST_VERSION:-stable}
     - run: rustup component add rustfmt
     - run: cargo update
@@ -20,10 +19,10 @@ target_steps: &target_steps
         fi
     - run: ./build.sh
     - save_cache:
-        key: v2-ssd1306-{{ .Environment.CIRCLE_JOB }}-{{ checksum "Cargo.toml" }}
+        key: v3-ssd1306-{{ .Environment.CIRCLE_JOB }}-{{ checksum "Cargo.toml" }}
         paths:
           - ./target
-          - /usr/local/cargo/registry
+          - /home/circleci/.cargo/registry
 
 version: 2
 jobs:

CHANGELOG.md

@@ -6,6 +6,24 @@
 
 ## [Unreleased] - ReleaseDate
 
+- **(breaking)** [#150](https://github.com/jamwaffles/ssd1306/pull/150) `BufferedGraphicsMode::set_pixel` now accepts a `bool` instead of a `u8` for the pixel color value.
+- **(breaking)** [#150](https://github.com/jamwaffles/ssd1306/pull/150) `display_on` is now called `set_display_on`.
+- **(breaking)** [#150](https://github.com/jamwaffles/ssd1306/pull/150) `TerminalMode::get_position` is now called `position` to conform with Rust API guidelines.
+- **(breaking)** [#150](https://github.com/jamwaffles/ssd1306/pull/150) Refactor the crate API to be more versatile and to make code clearer to understand.
+
+  A graphics mode initialisation now looks like this:
+
+  ```rust
+  use ssd1306::{prelude::*, I2CDisplayInterface, Ssd1306};
+
+  let interface = I2CDisplayInterface::new(i2c);
+
+  let mut display = Ssd1306::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
+      .into_buffered_graphics_mode();
+
+  display.init().unwrap();
+  ```
+
 ## [0.5.2] - 2021-04-19
 
 - [#145](https://github.com/jamwaffles/ssd1306/pull/145) Fixed rotation for 96x16 and 72x40 displays.
@@ -135,10 +153,10 @@
 - Builder docs clarify the order of method calls (#89)
 
 <!-- next-url -->
+
 [unreleased]: https://github.com/jamwaffles/ssd1306/compare/v0.5.2...HEAD
 [0.5.2]: https://github.com/jamwaffles/ssd1306/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/jamwaffles/ssd1306/compare/v0.5.0...v0.5.1
-
 [0.5.0]: https://github.com/jamwaffles/ssd1306/compare/v0.4.2...v0.5.0
 [0.4.2]: https://github.com/jamwaffles/ssd1306/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/jamwaffles/ssd1306/compare/v0.4.0...v0.4.1

Cargo.toml

@@ -10,7 +10,6 @@ readme = "README.md"
 repository = "https://github.com/jamwaffles/ssd1306"
 version = "0.5.2"
 edition = "2018"
-
 exclude = [ "build.rs", "build.sh", "memory.x", "doc", "*.jpg", "*.png", "*.bmp" ]
 
 [badges]
@@ -31,10 +30,11 @@ optional = true
 version = "0.6.0"
 
 [dev-dependencies]
-cortex-m = "0.6.2"
+cortex-m = "0.7.2"
 cortex-m-rt = "0.6.12"
 cortex-m-rtic = "0.5.3"
 panic-halt = "0.2.0"
+cast = { version = "0.2.6", default-features = false }
 
 # Used to load BMP images in various examples
 [dev-dependencies.tinybmp]
@@ -44,12 +44,12 @@ features = [ "graphics" ]
 
 # Used by the noise_i2c examples
 [dev-dependencies.rand]
-version = "0.7.3"
+version = "0.8.3"
 default-features = false
 features = [ "small_rng" ]
 
 [dev-dependencies.stm32f1xx-hal]
-version = "0.5.3"
+version = "0.7.0"
 features = [ "rt", "stm32f103" ]
 
 [features]

README.md

@@ -8,8 +8,6 @@
 
 I2C and SPI (4 wire) driver for the SSD1306 OLED display.
 
-See the [announcement blog post](https://wapl.es/electronics/rust/2018/04/30/ssd1306-driver.html) for more information.
-
 Please consider [becoming a sponsor](https://github.com/sponsors/jamwaffles/) so I may continue to maintain this crate in my spare time!
 
 ## [Documentation](https://docs.rs/ssd1306)
@@ -31,7 +29,7 @@ use embedded_graphics::{
     prelude::*,
 };
 use panic_halt as _;
-use ssd1306::{prelude::*, Builder, I2CDIBuilder};
+use ssd1306::{prelude::*, I2CDisplayInterface, Ssd1306};
 use stm32f1xx_hal::{
     i2c::{BlockingI2c, DutyCycle, Mode},
     prelude::*,
@@ -70,18 +68,18 @@ fn main() -> ! {
         1000,
     );
 
-    let interface = I2CDIBuilder::new().init(i2c);
-    let mut disp: GraphicsMode<_, _> = Builder::new().connect(interface).into();
-
-    disp.init().unwrap();
+    let interface = I2CDisplayInterface::new(i2c);
+    let mut display = Ssd1306::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
+        .into_buffered_graphics_mode();
+    display.init().unwrap();
 
     let raw: ImageRaw<BinaryColor> = ImageRaw::new(include_bytes!("./rust.raw"), 64, 64);
 
     let im = Image::new(&raw, Point::new(32, 0));
 
-    im.draw(&mut disp).unwrap();
+    im.draw(&mut display).unwrap();
 
-    disp.flush().unwrap();
+    display.flush().unwrap();
 
     loop {}
 }

build.sh

@@ -28,5 +28,3 @@ cargo clean --doc
 cargo clean --doc --target $TARGET
 
 cargo doc --all-features --target $TARGET
-
-linkchecker target/$TARGET/doc/ssd1306/index.html

examples/bmp_i2c.rs

@@ -28,7 +28,7 @@ use embedded_graphics::{
     prelude::*,
 };
 use panic_halt as _;
-use ssd1306::{prelude::*, Builder, I2CDIBuilder};
+use ssd1306::{prelude::*, I2CDisplayInterface, Ssd1306};
 use stm32f1xx_hal::{
     i2c::{BlockingI2c, DutyCycle, Mode},
     prelude::*,
@@ -68,9 +68,10 @@ fn main() -> ! {
         1000,
     );
 
-    let interface = I2CDIBuilder::new().init(i2c);
-    let mut disp: GraphicsMode<_, _> = Builder::new().connect(interface).into();
-    disp.init().unwrap();
+    let interface = I2CDisplayInterface::new(i2c);
+    let mut display = Ssd1306::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
+        .into_buffered_graphics_mode();
+    display.init().unwrap();
 
     let bmp =
         Bmp::from_slice(include_bytes!("./rust-pride.bmp")).expect("Failed to load BMP image");
@@ -93,10 +94,10 @@ fn main() -> ! {
                 },
             )
         })
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
-    disp.flush().unwrap();
+    display.flush().unwrap();
 
     loop {}
 }

examples/graphics.rs

@@ -28,7 +28,7 @@ use embedded_graphics::{
     style::PrimitiveStyleBuilder,
 };
 use panic_halt as _;
-use ssd1306::{prelude::*, Builder};
+use ssd1306::{prelude::*, Ssd1306};
 use stm32f1xx_hal::{
     delay::Delay,
     prelude::*,
@@ -75,10 +75,11 @@ fn main() -> ! {
     );
 
     let interface = display_interface_spi::SPIInterfaceNoCS::new(spi, dc);
-    let mut disp: GraphicsMode<_, _> = Builder::new().connect(interface).into();
+    let mut display = Ssd1306::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
+        .into_buffered_graphics_mode();
 
-    disp.reset(&mut rst, &mut delay).unwrap();
-    disp.init().unwrap();
+    display.reset(&mut rst, &mut delay).unwrap();
+    display.init().unwrap();
 
     let yoffset = 20;
 
@@ -92,7 +93,7 @@ fn main() -> ! {
     // enum to the _Builder_ struct
     Rectangle::new(Point::new(0, 0), Point::new(127, 63))
         .into_styled(style)
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
     // triangle
@@ -102,22 +103,22 @@ fn main() -> ! {
         Point::new(16 + 8, yoffset),
     )
     .into_styled(style)
-    .draw(&mut disp)
+    .draw(&mut display)
     .unwrap();
 
     // square
     Rectangle::new(Point::new(52, yoffset), Point::new(52 + 16, 16 + yoffset))
         .into_styled(style)
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
     // circle
     Circle::new(Point::new(96, yoffset + 8), 8)
         .into_styled(style)
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
-    disp.flush().unwrap();
+    display.flush().unwrap();
 
     loop {}
 }

examples/graphics_i2c.rs

@@ -25,7 +25,7 @@ use embedded_graphics::{
     style::PrimitiveStyleBuilder,
 };
 use panic_halt as _;
-use ssd1306::{prelude::*, Builder, I2CDIBuilder};
+use ssd1306::{prelude::*, I2CDisplayInterface, Ssd1306};
 use stm32f1xx_hal::{
     i2c::{BlockingI2c, DutyCycle, Mode},
     prelude::*,
@@ -64,9 +64,10 @@ fn main() -> ! {
         1000,
     );
 
-    let interface = I2CDIBuilder::new().init(i2c);
-    let mut disp: GraphicsMode<_, _> = Builder::new().connect(interface).into();
-    disp.init().unwrap();
+    let interface = I2CDisplayInterface::new(i2c);
+    let mut display = Ssd1306::new(interface, DisplaySize128x64, DisplayRotation::Rotate0)
+        .into_buffered_graphics_mode();
+    display.init().unwrap();
 
     let yoffset = 20;
 
@@ -80,7 +81,7 @@ fn main() -> ! {
     // enum to the _Builder_ struct
     Rectangle::new(Point::new(0, 0), Point::new(127, 63))
         .into_styled(style)
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
     // triangle
@@ -90,22 +91,22 @@ fn main() -> ! {
         Point::new(16 + 8, yoffset),
     )
     .into_styled(style)
-    .draw(&mut disp)
+    .draw(&mut display)
     .unwrap();
 
     // square
     Rectangle::new(Point::new(52, yoffset), Point::new(52 + 16, 16 + yoffset))
         .into_styled(style)
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
     // circle
     Circle::new(Point::new(96, yoffset + 8), 8)
         .into_styled(style)
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
-    disp.flush().unwrap();
+    display.flush().unwrap();
 
     loop {}
 }

examples/graphics_i2c_128x32.rs

@@ -25,7 +25,7 @@ use embedded_graphics::{
     style::PrimitiveStyleBuilder,
 };
 use panic_halt as _;
-use ssd1306::{prelude::*, Builder, I2CDIBuilder};
+use ssd1306::{prelude::*, I2CDisplayInterface, Ssd1306};
 use stm32f1xx_hal::{
     i2c::{BlockingI2c, DutyCycle, Mode},
     prelude::*,
@@ -64,12 +64,10 @@ fn main() -> ! {
         1000,
     );
 
-    let interface = I2CDIBuilder::new().init(i2c);
-    let mut disp: GraphicsMode<_, _> = Builder::new()
-        .size(DisplaySize128x32)
-        .connect(interface)
-        .into();
-    disp.init().unwrap();
+    let interface = I2CDisplayInterface::new(i2c);
+    let mut display = Ssd1306::new(interface, DisplaySize128x32, DisplayRotation::Rotate0)
+        .into_buffered_graphics_mode();
+    display.init().unwrap();
 
     let yoffset = 8;
 
@@ -83,7 +81,7 @@ fn main() -> ! {
     // enum to the _Builder_ struct
     Rectangle::new(Point::new(0, 0), Point::new(127, 31))
         .into_styled(style)
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
     // triangle
@@ -93,22 +91,22 @@ fn main() -> ! {
         Point::new(16 + 8, yoffset),
     )
     .into_styled(style)
-    .draw(&mut disp)
+    .draw(&mut display)
     .unwrap();
 
     // square
     Rectangle::new(Point::new(52, yoffset), Point::new(52 + 16, 16 + yoffset))
         .into_styled(style)
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
     // circle
     Circle::new(Point::new(96, yoffset + 8), 8)
         .into_styled(style)
-        .draw(&mut disp)
+        .draw(&mut display)
         .unwrap();
 
-    disp.flush().unwrap();
+    display.flush().unwrap();
 
     loop {}
 }