Skip to content

Implementation of the embedded-hal traits for the HD44780.

License

Notifications You must be signed in to change notification settings

JohnDoneth/hd44780-driver

Repository files navigation

hd44780-driver

crates.io crates.io travis-ci.org Rust API

Implementation of the embedded-hal traits for the HD44780.

Examples

Examples for several different boards can be found here

Any platform that implements the embedded-hal traits is supported by this library! See awesome-embedded-rust for a list of supported platforms.

Getting Started

This library aims to keep it simple in that to get started all you will have to do is supply the HD44780::new function a bunch of pins from your platform that implement the OutputPin trait for embedded-hal as well as a struct that implements the delay traits DelayUs<u16> and DelayMs<u8>.

// Pseudo-code: check the HAL crate for your specific device for exact code to get pins / delay
// It is recommended to use push/pull output pins, but if your specific LCD device has pull-up resistors
// an open/drain output pin should work too

let mut delay = Delay::new();

let mut lcd = HD44780::new(
    DisplayOptions8Bit::new(MemoryMap1602::new())
        .with_pins(FourBitBusPins {
            rs: d4.into_push_pull_output(&mut port), // Register Select pin,
            en: d3.into_push_pull_output(&mut port), // Enable pin,

            d4: d9.into_push_pull_output(&mut port),  // d4,
            d5: d10.into_push_pull_output(&mut port), // d5,
            d6: d11.into_push_pull_output(&mut port), // d6,
            d7: d12.into_push_pull_output(&mut port), // d7,
        }),
    &mut delay,
)
.unwrap();

// Unshift display and set cursor to 0
lcd.reset(&mut delay);

// Clear existing characters
lcd.clear(&mut delay);

// Display the following string
lcd.write_str("Hello, world!", &mut delay);

// Move the cursor to the second line
lcd.set_cursor_xy((0, 1), &mut delay);

// Display the following string on the second line
lcd.write_str("I'm on line 2!", &mut delay);

Async API

The async API is similar to the sync API. The the major differences are that:

  • The async API requires the async feature to use.
  • The async API requires the nightly compiler because of use of unstable features.
  • The async API uses embedded-hal-async rather than embedded-hal traits.

Embassy provides some implementations of these traits for some MCUs, and provides an executor that can execute futures. However, projects implementing embedded-hal-async traits, including this project, can run on any executor with any driver, provided such executor and driver also implement embedded-async-traits.

use hd44780_driver::non_blocking::HD44780;
use hd44780_driver::setup::DisplayOptions8Bit;
use hd44780_driver::memory_map::MemoryMap1602;
use hd44780_driver::bus::FourBitBusPins;

let mut delay = embassy::time::Delay::new();
pin_mut!(delay);

let mut display = HD44780::new(
    DisplayOptions8Bit::new(MemoryMap1602::new())
        .with_pins(FourBitBusPins {
            rs,
            en,
            d4,
            d5,
            d6,
            d7,
        }),
    delay.as_mut(),
)
.await
.unwrap();

display.clear(delay.as_mut()).await;
display.write_str(msg, delay.as_mut()).await;

Features

  • 4-bit & 8-bit modes are supported
  • Support for i2c backpacks
  • Non-blocking API

Todo

  • Busy flag support
  • A more user-friendly API with additional features
  • Custom characters

Contributing

  • Additional issues as well as pull-requests are welcome.

  • If you have a platform not yet covered in this repository that is supported by embedded-hal, a pull-request of an example would be awesome!

License

This project is licensed under MIT license (LICENSE or https://opensource.org/licenses/MIT)