Documentation and API cleanup

Author: wjakobczyk

Cargo.toml

@@ -1,12 +1,12 @@
 [package]
+name = "st7920"
+description = "SPI driver for the ST7920 LCD display controller"
 authors = ["Wojciech Jakóbczyk <[email protected]>"]
 categories = ["embedded", "no-std"]
-description = "SPI driver for the ST7920 LCD display controller"
 documentation = "https://docs.rs/st7920"
 exclude = [".gitignore"]
 keywords = ["no-std", "st7920", "lcd", "embedded", "embedded-hal-driver"]
 license = "MIT"
-name = "st7920"
 readme = "README.md"
 repository = "https://github.com/wjakobczyk/st7920"
 version = "0.1.0"

README.md

@@ -1,129 +1,30 @@
-# `cortex-m-quickstart`
+# `ST7920`
 
-> A template for building applications for ARM Cortex-M microcontrollers
+This is a Rust driver library for LCD displays using the [ST7920] controller. It supports graphics mode of the controller, 128x64 in 1bpp. SPI connection to MCU is supported.
 
-This project is developed and maintained by the [Cortex-M team][team].
+It implements [embedded-graphics] driver API.
 
-## Dependencies
+It is platform independent as it uses [embedded-hal] APIs to access hardware.
 
-To build embedded programs using this template you'll need:
+The examples are based on the [stm32f4xx_hal] implementation of embedded-hal.
 
-- Rust 1.31, 1.30-beta, nightly-2018-09-13 or a newer toolchain. e.g. `rustup
-  default beta`
 
-- The `cargo generate` subcommand. [Installation
-  instructions](https://github.com/ashleygwilliams/cargo-generate#installation).
 
-- `rust-std` components (pre-compiled `core` crate) for the ARM Cortex-M
-  targets. Run:
+# Documentation
 
-``` console
-$ rustup target add thumbv6m-none-eabi thumbv7m-none-eabi thumbv7em-none-eabi thumbv7em-none-eabihf
-```
+See [examples].
 
-## Using this template
+The controller supports 1 bit-per-pixel displays, so an off-screen buffer has to be used to provide random access to pixels.
+Size of the buffer is 1024 bytes.
 
-**NOTE**: This is the very short version that only covers building programs. For
-the long version, which additionally covers flashing, running and debugging
-programs, check [the embedded Rust book][book].
-
-[book]: https://rust-embedded.github.io/book
-
-0. Before we begin you need to identify some characteristics of the target
-  device as these will be used to configure the project:
-
-- The ARM core. e.g. Cortex-M3.
-
-- Does the ARM core include an FPU? Cortex-M4**F** and Cortex-M7**F** cores do.
-
-- How much Flash memory and RAM does the target device has? e.g. 256 KiB of
-  Flash and 32 KiB of RAM.
-
-- Where are Flash memory and RAM mapped in the address space? e.g. RAM is
-  commonly located at address `0x2000_0000`.
-
-You can find this information in the data sheet or the reference manual of your
-device.
-
-In this example we'll be using the STM32F3DISCOVERY. This board contains an
-STM32F303VCT6 microcontroller. This microcontroller has:
-
-- A Cortex-M4F core that includes a single precision FPU
-
-- 256 KiB of Flash located at address 0x0800_0000.
-
-- 40 KiB of RAM located at address 0x2000_0000. (There's another RAM region but
-  for simplicity we'll ignore it).
-
-1. Instantiate the template.
-
-``` console
-$ cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart
- Project Name: app
- Creating project called `app`...
- Done! New project created /tmp/app
-
-$ cd app
-```
-
-2. Set a default compilation target. There are four options as mentioned at the
-   bottom of `.cargo/config`. For the STM32F303VCT6, which has a Cortex-M4F
-   core, we'll pick the `thumbv7em-none-eabihf` target.
-
-``` console
-$ tail -n6 .cargo/config
-```
-
-``` toml
-[build]
-# Pick ONE of these compilation targets
-# target = "thumbv6m-none-eabi"    # Cortex-M0 and Cortex-M0+
-# target = "thumbv7m-none-eabi"    # Cortex-M3
-# target = "thumbv7em-none-eabi"   # Cortex-M4 and Cortex-M7 (no FPU)
-target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)
-```
-
-3. Enter the memory region information into the `memory.x` file.
-
-``` console
-$ cat memory.x
-/* Linker script for the STM32F303VCT6 */
-MEMORY
-{
-  /* NOTE 1 K = 1 KiBi = 1024 bytes */
-  FLASH : ORIGIN = 0x08000000, LENGTH = 256K
-  RAM : ORIGIN = 0x20000000, LENGTH = 40K
-}
-```
-
-4. Build the template application or one of the examples.
-
-``` console
-$ cargo build
-```
+The buffer has to be flushed to update the display after a group of draw calls has been completed. The flush is not part of embedded-graphics API.
 
 # License
 
-This template is 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)
-
-at your option.
-
-## Contribution
-
-Unless you explicitly state otherwise, any contribution intentionally submitted
-for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
-dual licensed as above, without any additional terms or conditions.
-
-## Code of Conduct
-
-Contribution to this crate is organized under the terms of the [Rust Code of
-Conduct][CoC], the maintainer of this crate, the [Cortex-M team][team], promises
-to intervene to uphold that code of conduct.
+This library is licensed under MIT license ([LICENSE](LICENSE) or http://opensource.org/licenses/MIT)
 
-[CoC]: https://www.rust-lang.org/policies/code-of-conduct
-[team]: https://github.com/rust-embedded/wg#the-cortex-m-team
+[embedded-graphics]: https://docs.rs/embedded-graphics/0.6.0-alpha.2/embedded_graphics/
+[embedded-hal]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/
+[stm32f4xx_hal]: https://docs.rs/stm32f4xx-hal/0.5.0/stm32f4xx_hal/
+[examples]: https://github.com/wjakobczyk/st7920/tree/master/examples
+[ST7920]: https://www.lcd-module.de/eng/pdf/zubehoer/st7920_chinese.pdf

examples/graphics.rs

@@ -60,7 +60,7 @@ fn main() -> ! {
                 .into_iter(),
         );
 
-        disp.flush_range(15, 15, 14, 31)
+        disp.flush_region(15, 15, 14, 31)
             .expect("could not flush display");
     }
 

src/lib.rs

@@ -1,3 +1,16 @@
+//! # ST7920
+//!
+//! This is a Rust driver library for LCD displays using the [ST7920] controller.
+//!
+//! It supports graphics mode of the controller, 128x64 in 1bpp. SPI connection to MCU is supported.
+//!
+//! The controller supports 1 bit-per-pixel displays, so an off-screen buffer has to be used to provide random access to pixels.
+//!
+//! Size of the buffer is 1024 bytes.
+//!
+//! The buffer has to be flushed to update the display after a group of draw calls has been completed.
+//! The flush is not part of embedded-graphics API.
+
 #![no_std]
 
 use num_derive::ToPrimitive;
@@ -14,7 +27,7 @@ pub enum Error<CommError, PinError> {
     Pin(PinError),
 }
 
-/// ST7735 instructions.
+/// ST7920 instructions.
 #[derive(ToPrimitive)]
 enum Instruction {
     BasicFunction = 0x30,
@@ -32,19 +45,19 @@ const ROW_SIZE: usize = (WIDTH / 8) as usize;
 const BUFFER_SIZE: usize = ROW_SIZE * HEIGHT as usize;
 const X_ADDR_DIV: u8 = 16;
 
-/// ST7735 driver to connect to TFT displays.
 pub struct ST7920<SPI, RST, CS, DELAY>
 where
     SPI: spi::Write<u8>,
     RST: OutputPin,
     CS: OutputPin,
 {
-    /// SPI
+    /// SPI pin
     spi: SPI,
 
     /// Reset pin.
     rst: RST,
 
+    /// CS pin
     cs: Option<CS>,
 
     delay: DELAY,
@@ -59,10 +72,10 @@ where
     CS: OutputPin<Error = PinError>,
     DELAY: DelayMs<u8> + DelayUs<u8>,
 {
-    /// Creates a new driver instance that uses hardware SPI.
+    /// Create a new driver instance that uses SPI connection.
     pub fn new(
         spi: SPI,
-        rst: RST, //TODO option
+        rst: RST,
         cs: Option<CS>,
         delay: DELAY,
     ) -> Self {
@@ -93,7 +106,7 @@ where
         Ok(())
     }
 
-    /// Runs commands to initialize the display.
+    /// Initialize the display controller
     pub fn init(&mut self) -> Result<(), Error<SPIError, PinError>> {
         self.enable_cs()?;
         self.hard_reset()?;
@@ -167,6 +180,7 @@ where
         Ok(())
     }
 
+    /// Clear whole display area
     pub fn clear(&mut self) -> Result<(), Error<SPIError, PinError>> {
         self.enable_cs()?;
 
@@ -183,6 +197,7 @@ where
         Ok(())
     }
 
+    /// Draw pixel
     pub fn set_pixel(&mut self, x: u8, y: u8, val: u8) {
         let x_mask = 0x80 >> (x % 8);
         if val != 0 {
@@ -192,6 +207,7 @@ where
         }
     }
 
+    /// Flush buffer to update entire display
     pub fn flush(&mut self) -> Result<(), Error<SPIError, PinError>> {
         self.enable_cs()?;
 
@@ -212,10 +228,11 @@ where
         Ok(())
     }
 
-    pub fn flush_range(
+    /// Flush buffer to update region of the display
+    pub fn flush_region(
         &mut self,
-        x1: u8,
-        y1: u8,
+        x: u8,
+        y: u8,
         mut w: u8,
         h: u8,
     ) -> Result<(), Error<SPIError, PinError>> {
@@ -229,13 +246,13 @@ where
             w += 8; //need to send even number of bytes
         }
 
-        let mut row_start = y1 as usize * ROW_SIZE;
-        for y in y1..y1 + h {
-            self.set_address(x1 / 8, y)?;
+        let mut row_start = y as usize * ROW_SIZE;
+        for y in y..y + h {
+            self.set_address(x / 8, y)?;
 
-            for x in x1 / 8..(x1 + w) / 8 {
+            for x in x / 8..(x + w) / 8 {
                 self.write_data(self.buffer[row_start + x as usize])?;
-                //TODO send in one SPI transaction
+                //TODO send in a single SPI transaction
             }
 
             row_start += ROW_SIZE;