Added support for ST7032i controller (#6)

Added support for the ST7032i LCD display controller. In doing so, refactored code to improve ability to add support for more controllers.

Author: michaelkamprath

.gitignore

@@ -4,3 +4,6 @@ Cargo.lock
 
 # MacOS
 .DS_Store
+
+# local dev
+documentation/

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2025-02-16
+* Refactored code base to make it easier to add support for new character display controllers which minmal duplication of code.
+* Added support for the ST7032i conrtroller
+
 ## [0.4.0] - 2024-11-24
 * Completely refactored code to enable different controller types.
 * Improved error handling and test coverage.
@@ -23,7 +27,8 @@
 ## 0.1.0
 Initial release. Support for both Generic PCF8574T I2C and Adafruit Backpack character display adapters.
 
-[Unreleased]: https://github.com/michaelkamprath/bespokeasm/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/michaelkamprath/bespokeasm/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/michaelkamprath/bespokeasm/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/michaelkamprath/bespokeasm/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/michaelkamprath/bespokeasm/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/michaelkamprath/bespokeasm/compare/v0.2.0...v0.2.1

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "i2c-character-display"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 description = "Driver for HD44780-based character displays connected via a I2C adapter"
 license = "MIT"
@@ -23,10 +23,9 @@ bitfield = "0.17"
 defmt = { version = "0.3", optional = true }
 ufmt = {version = "0.2", optional = true}
 
-
 [features]
 defmt = ["dep:defmt", "embedded-hal/defmt-03"]
 ufmt = ["dep:ufmt"]
 
 [dev-dependencies]
-embedded-hal-mock = "0.11"
+embedded-hal-mock = "0.11"

README.md

@@ -14,6 +14,8 @@ in an embedded, `no_std` environment. A number of I2C interfaces are supported:
   This library supports that configuration, though it would be straightforward to add support for other pin configurations.
 - **AiP31068** - This is a character display controller with a built-in I2C support. The command set is similar to the HD44780, but the controller
   operates in 8-bit mode and is initialized differently.  Examples of displays that use this controller include the [Surenoo SLC1602O](https://www.surenoo.com/products/8109143).
+- **ST7032i** - This is an I2C character display controller used with LCD displays. It is similar to the HD44780, but with some differences in the command set.
+  Examples of displays that use this controller include the [Surenoo SLC1602K3](https://www.surenoo.com/collections/81733622/products/8131705).
 
 Key features include:
 - Convenient high-level API for controlling many types of character display
@@ -55,6 +57,8 @@ let mut lcd = CharacterDisplayPCF8574T::new(i2c, LcdDisplayType::Lcd16x2, delay)
 let mut lcd = CharacterDisplayDualHD44780::new(i2c, LcdDisplayType::Lcd40x4, delay);
 // Character display with the AiP31068 controller
 let mut lcd = CharacterDisplayAIP31068::new(i2c, LcdDisplayType::Lcd16x2, delay);
+// Character display with the ST7032i controller
+let mut lcd = CharacterDisplayST7032i::new(i2c, LcdDisplayType::Lcd16x2, delay);
 ```
 When creating the display object, you can choose the display type from the `LcdDisplayType` enum. The display type should match the physical
 display you are using. This display type configures the number of rows and columns, and the internal row offsets for the display.

src/driver.rs

@@ -1,134 +1,170 @@
-pub mod hd44780;
 pub mod aip31068;
+pub mod hd44780;
+pub mod st7032i;
+pub mod standard;
 
 use embedded_hal::{delay::DelayNs, i2c};
 
-use crate::{CharacterDisplayError, DeviceSetupConfig};
+use crate::{CharacterDisplayError, DeviceSetupConfig, LcdDisplayType};
 
-pub trait DriverTrait<I2C, DELAY>: Default
+/// Trait for device hardware implementations. Embodies the hardware-specific
+/// functionality of the device driver IC. The trait is intended to be implemented
+/// for the specific device driver ICs.
+pub trait DeviceHardwareTrait<I2C, DELAY>
 where
     I2C: i2c::I2c,
     DELAY: DelayNs,
 {
+    fn new(config: DeviceSetupConfig<I2C, DELAY>) -> Self;
     /// returns the default I2C address for the device
     fn default_i2c_address() -> u8;
 
     /// returns whether reads are supported by the device
     fn supports_reads() -> bool;
 
-    /// Initialize the display
-    fn init(
+    /// returns LCD type
+    fn lcd_type(&self) -> LcdDisplayType;
+
+    /// returns configured i2c address
+    fn i2c_address(&self) -> u8;
+
+    /// return a immutable reference to the delay object
+    fn delay(&mut self) -> &mut DELAY;
+
+    /// returns the i2c object. mostly used for testing
+    fn i2c(&mut self) -> &mut I2C;
+
+    /// initializes the device hardware. On `Ok`, returns the initial configuration
+    /// of the device. The configuration is a tuple of three bytes:
+    /// (display_function, display_control, display_mode)
+    fn init(&mut self) -> Result<(u8, u8, u8), CharacterDisplayError<I2C>>;
+
+    fn write_bytes(
         &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
+        rs_setting: bool,
+        data: &[u8],
+    ) -> Result<(), CharacterDisplayError<I2C>>;
+}
+
+/// Trait for display actions. Embodies the display commnands that can be performed on the device.
+/// Works with the `DeviceHardwareTrait` to perform the actions on the device to effect the desire
+/// display operation.
+pub trait DisplayActionsTrait<I2C, DELAY, DEVICE>: Default
+where
+    I2C: i2c::I2c,
+    DELAY: DelayNs,
+    DEVICE: DeviceHardwareTrait<I2C, DELAY>,
+{
+    /// Initialize the display state. Intended to be called once after the device is initialized
+    /// and before any other operations are performed. The three parameters are the initial values
+    /// and are recieved from the `DeviceHardwareTrait::init` method of the device.
+    fn init_display_state(
+        &mut self,
+        display_function: u8,
+        display_control: u8,
+        display_mode: u8,
     ) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Clear the display
-    fn clear(
-        &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
-    ) -> Result<(), CharacterDisplayError<I2C>>;
+    fn clear(&mut self, device: &mut DEVICE) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Set the cursor to the home position.
-    fn home(
-        &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
-    ) -> Result<(), CharacterDisplayError<I2C>>;
+    fn home(&mut self, device: &mut DEVICE) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Set the cursor position at specified column and row. Columns and rows are zero-indexed.
     fn set_cursor(
         &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
+        device: &mut DEVICE,
         col: u8,
         row: u8,
     ) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Set the cursor visibility.
     fn show_cursor(
         &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
+        device: &mut DEVICE,
         show_cursor: bool,
     ) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Set the cursor blinking.
     fn blink_cursor(
         &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
+        device: &mut DEVICE,
         blink_cursor: bool,
     ) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Set the display visibility.
     fn show_display(
         &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
+        device: &mut DEVICE,
         show_display: bool,
     ) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Scroll display left.
-    fn scroll_left(
-        &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
-    ) -> Result<(), CharacterDisplayError<I2C>>;
+    fn scroll_left(&mut self, device: &mut DEVICE) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Scroll display right.
-    fn scroll_right(
-        &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
-    ) -> Result<(), CharacterDisplayError<I2C>>;
+    fn scroll_right(&mut self, device: &mut DEVICE) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Set the text flow direction to left to right.
-    fn left_to_right(
-        &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
-    ) -> Result<(), CharacterDisplayError<I2C>>;
+    fn left_to_right(&mut self, device: &mut DEVICE) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Set the text flow direction to right to left.
-    fn right_to_left(
-        &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
-    ) -> Result<(), CharacterDisplayError<I2C>>;
+    fn right_to_left(&mut self, device: &mut DEVICE) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Set the auto scroll mode.
     fn autoscroll(
         &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
+        device: &mut DEVICE,
         autoscroll: bool,
     ) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Prints a string to the LCD at the current cursor position of the active device.
-    fn print(
-        &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
-        text: &str,
-    ) -> Result<(), CharacterDisplayError<I2C>>;
+    fn print(&mut self, device: &mut DEVICE, text: &str) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// Sets the backlight on or off
     fn backlight(
         &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
+        device: &mut DEVICE,
         on: bool,
     ) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// creates a new custom character
     fn create_char(
         &mut self,
-        device: &mut DeviceSetupConfig<I2C, DELAY>,
+        device: &mut DEVICE,
         location: u8,
         charmap: [u8; 8],
     ) -> Result<(), CharacterDisplayError<I2C>>;
 
     /// read bytes from the active controller of the device. The size of the buffer is the number of bytes to read.
     fn read_device_data(
         &self,
-        _device: &mut DeviceSetupConfig<I2C, DELAY>,
+        _device: &mut DEVICE,
         _buffer: &mut [u8],
     ) -> Result<(), CharacterDisplayError<I2C>> {
-        unimplemented!("Reads are not supported for device");
+        #[cfg(feature = "defmt")]
+        defmt::warn!("Reading data is not supported on this display");
+        Err(CharacterDisplayError::UnsupportedOperation)
     }
 
     fn read_address_counter(
         &mut self,
-        _device: &mut DeviceSetupConfig<I2C, DELAY>,
+        _device: &mut DEVICE,
     ) -> Result<u8, CharacterDisplayError<I2C>> {
-        unimplemented!("Reads are not supported for device");
+        #[cfg(feature = "defmt")]
+        defmt::warn!("Reading the address counter is not supported on this display");
+        Err(CharacterDisplayError::UnsupportedOperation)
+    }
+
+    /// Set the contrast of the display. This is not supported by all devices.
+    fn set_contrast(
+        &mut self,
+        _device: &mut DEVICE,
+        _contrast: u8,
+    ) -> Result<(), CharacterDisplayError<I2C>> {
+        #[cfg(feature = "defmt")]
+        defmt::warn!("Setting contrast is not supported on this display");
+        Err(CharacterDisplayError::UnsupportedOperation)
     }
 }