Struct ag_lcd::LcdDisplay

pub struct LcdDisplay<T, D>
where
    T: OutputPin + Sized,
    D: DelayNs + Sized,
{ /* private fields */ }

The LCD display

Methods called on this struct will fail silently if the system or screen is misconfigured.

Implementations

impl<T, D> LcdDisplay<T, D>

where T: OutputPin + Sized, D: DelayNs + Sized,

pub fn new(rs: T, en: T, delay: D) -> Self

Create a new instance of the LcdDisplay

Examples

let peripherals = arduino_hal::Peripherals::take().unwrap();
let pins = arduino_hal::pins!(peripherals);
let delay = arduino_hal::Delay::new();

let rs = pins.d12.into_output().downgrade();
let rw = pins.d11.into_output().downgrade();
let en = pins.d10.into_output().downgrade();
let d4 = pins.d5.into_output().downgrade();
let d5 = pins.d4.into_output().downgrade();
let d6 = pins.d3.into_output().downgrade();
let d7 = pins.d2.into_output().downgrade();

let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_blink(Blink::On)
    .with_cursor(Cursor::Off)
    .with_rw(d10) // optional (set lcd pin to GND if not provided)
    .build();

pub fn with_cols(self, cols: u8) -> Self

Set amount of columns this lcd has

pub fn with_half_bus(self, d4: T, d5: T, d6: T, d7: T) -> Self

Set four pins that connect to the lcd screen and configure the display for four-pin mode.

The parameters below (d4-d7) are labeled in the order that you should see on the LCD itself. Regardless of how the display is connected to the arduino, ‘D4’ on the LCD should map to ‘d4’ when calling this function.

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .build();

pub fn with_full_bus( self, d0: T, d1: T, d2: T, d3: T, d4: T, d5: T, d6: T, d7: T, ) -> Self

Set eight pins that connect to the lcd screen and configure the display for eight-pin mode.

The parameters below (d0-d7) are labeled in the order that you should see on the LCD itself. Regardless of how the display is connected to the arduino, ‘D4’ on the LCD should map to ‘d4’ when calling this function.

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_full_bus(d0, d1, d4, d5, d6, d7, d6, d7)
    .build();

pub fn with_rw(self, rw: T) -> Self

Set an RW (Read/Write) pin to use (This is optional and can normally be connected directly to GND, leaving the display permanently in Write mode)

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_rw(d10)
    .build();

pub fn with_size(self, value: Size) -> Self

Set the character size of the LCD display. (Defaults to Size::Dots5x8)

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_size(Size::Dots5x8)
    .build();

pub fn with_lines(self, value: Lines) -> Self

Set the number of lines on the LCD display. (Default is Lines::OneLine)

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_lines(Lines::OneLine)
    .build();

pub fn with_layout(self, value: Layout) -> Self

Set the text direction layout of the LCD display. (Default is Layout::LeftToRight)

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_layout(Layout::LeftToRight)
    .build();

pub fn with_display(self, value: Display) -> Self

Set the LCD display on or off initially. (Default is Display::On)

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_display(Display::On)
    .build();

pub fn with_cursor(self, value: Cursor) -> Self

Set the cursor on or off initially. (Default is Cursor::Off)

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_cursor(Cursor::Off)
    .build();

pub fn with_blink(self, value: Blink) -> Self

Set the cursor background to blink on and off. (Default is Blink::Off)

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_blink(Blink::Off)
    .build();

pub fn with_backlight(self, backlight_pin: T) -> Self

Set a pin for controlling backlight state

pub fn with_autoscroll(self, value: AutoScroll) -> Self

Set autoscroll on or off. (Default is AutoScroll::Off)

Examples

...
let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_autoscroll(AutoScroll::Off)
    .build();

pub fn with_reliable_init(self, delay_toggle: u32) -> Self

Increase reliability of initialization of LCD.

Some users experience unreliable initialization of the LCD, where the LCD sometimes is unable to display symbols after running .build(). This method toggles the LCD off and on with some delay in between, 3 times. A higher delay_toggle tends to make this method more reliable, and a value of 10 000 is recommended. Note that this method should be run as close as possible to .build().

Examples

let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_reliable_init(10000)
    .build();

pub fn build(self) -> Self

Finish construction of the LcdDisplay and initialized the display to the provided settings.

Examples

use ag_lcd::{Display, Blink, Cursor, LcdDisplay};

let peripherals = arduino_hal::Peripherals::take().unwrap();
let pins = arduino_hal::pins!(peripherals);
let delay = arduino_hal::Delay::new();

let rs = pins.d12.into_output().downgrade();
let rw = pins.d11.into_output().downgrade();
let en = pins.d10.into_output().downgrade();

// left-side names refer to lcd pinout (e.g. 'd4' = D4 on lcd)
let d4 = pins.d5.into_output().downgrade();
let d5 = pins.d4.into_output().downgrade();
let d6 = pins.d3.into_output().downgrade();
let d7 = pins.d2.into_output().downgrade();

let mut lcd: LcdDisplay<_,_> = LcdDisplay::new(rs, en, delay)
    .with_half_bus(d4, d5, d6, d7)
    .with_display(Display::On)
    .with_blink(Blink::On)
    .with_cursor(Cursor::On)
    .with_rw(rw) // optional (set lcd pin to GND if not provided)
    .build();

lcd.print("Test message!");

pub fn set_position(&mut self, col: u8, row: u8)

Set the position of the cursor.

Examples

let mut lcd: LcdDisplay<_,_> = ...;

let row = 0;
let col = 2;

lcd.set_position(col,row);

pub fn set_scroll(&mut self, direction: Scroll, distance: u8)

Scroll the display right or left.

Examples

let mut lcd: LcdDisplay<_,_> = ...;

let direction = Scroll::Left;
let distance = 2;

lcd.set_scroll(direction,distance);

pub fn set_layout(&mut self, layout: Layout)

Set the text direction layout.

Examples

let mut lcd: LcdDisplay<_,_> = ...;

lcd.set_layout(Layout::LeftToRight);

pub fn set_display(&mut self, display: Display)

Turn the display on or off.

Examples

let mut lcd: LcdDisplay<_,_> = ...;

lcd.set_display(Display::Off);

pub fn set_cursor(&mut self, cursor: Cursor)

Turn the cursor on or off.

Examples

let mut lcd: LcdDisplay<_,_> = ...;

lcd.set_cursor(Cursor::On);

pub fn set_blink(&mut self, blink: Blink)

Make the background of the cursor blink or stop blinking.

Examples

let mut lcd: LcdDisplay<_,_> = ...;

lcd.set_blink(Blink::On);

pub fn set_backlight(&mut self, backlight: Backlight)

Enable or disable LCD backlight

pub fn set_autoscroll(&mut self, scroll: AutoScroll)

Turn auto scroll on or off.

Examples

let mut lcd: LcdDisplay<_,_> = ...;

lcd.set_autoscroll(AutoScroll::On);

pub fn set_character(&mut self, location: u8, map: [u8; 8])

Add a new character map to the LCD memory (CGRAM) at a particular location. There are eight locations available at positions 0-7, and location values outside of this range will be bitwise masked to fall within the range, possibly overwriting an existing custom character.

Examples

let mut lcd: LcdDisplay<_,_> = ...;

// set a sideways smiley face in CGRAM at location 0.
lcd.set_character(0u8,[
    0b00110,
    0b00001,
    0b11001,
    0b00001,
    0b00001,
    0b11001,
    0b00001,
    0b00110
]);

// write the character code for the custom character.
lcd.home();
lcd.write(0u8);

pub fn clear(&mut self)

Clear the display.

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.clear();

pub fn home(&mut self)

Move the cursor to the home position.

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.home(); // cursor should be top-left

pub fn scroll_right(&mut self, value: u8)

Scroll the display to the right. (See set_scroll)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.scroll_right(2); // display scrolls 2 positions to the right.

pub fn scroll_left(&mut self, value: u8)

Scroll the display to the left. (See set_scroll)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.scroll_left(2); // display scrolls 2 positions to the left.

pub fn layout_left_to_right(&mut self)

Set the text direction layout left-to-right. (See set_layout)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.layout_left_to_right();

pub fn layout_right_to_left(&mut self)

Set the text direction layout right-to-left. (See set_layout)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.layout_right_to_left();

pub fn display_on(&mut self)

Turn the display on. (See set_display)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.display_on();

pub fn display_off(&mut self)

Turn the display off. (See set_display)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.display_off();

pub fn cursor_on(&mut self)

Turn the cursor on. (See set_cursor)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.cursor_on();

pub fn cursor_off(&mut self)

Turn the cursor off. (See set_cursor)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.cursor_off();

pub fn blink_on(&mut self)

Set the background of the cursor to blink. (See set_blink)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.blink_on();

pub fn blink_off(&mut self)

Set the background of the cursor to stop blinking. (See set_blink)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.blink_off();

pub fn backlight_on(&mut self)

Turn backlight on

pub fn backlight_off(&mut self)

Turn backlight off

pub fn autoscroll_on(&mut self)

Turn autoscroll on. (See set_autoscroll)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.autoscroll_on();

pub fn autoscroll_off(&mut self)

Turn autoscroll off. (See set_autoscroll)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.autoscroll_off();

pub fn mode(&self) -> Mode

Get the current bus mode. (See with_half_bus and with_full_bus)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
let mode = lcd.mode();

pub fn layout(&self) -> Layout

Get the current text direction layout. (See set_layout)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
let layout = lcd.layout();

pub fn display(&self) -> Display

Get the current state of the display (on or off). (See set_display)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
let display = lcd.display();

pub fn cursor(&self) -> Cursor

Get the current cursor state (on or off). (See set_cursor)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
let cursor = lcd.cursor();

pub fn blink(&self) -> Blink

Get the current blink state (on or off). (See set_blink)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
let blink = lcd.blink();

pub fn autoscroll(&self) -> AutoScroll

Get the current autoscroll state (on or off). (See set_autoscroll)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
let autoscroll = lcd.autoscroll();

pub fn lines(&self) -> Lines

Get the number of lines. (See with_lines)

Examples

let mut lcd: LcdDisplay<_,_> = ...;
let lines = lcd.lines();

pub fn error(&self) -> Error

Get the current error code. If an error occurs, the internal code will be set to a value other than Error::None (11u8).

Examples

let mut lcd: LcdDisplay<_,_> = ...;
let code = lcd.error();

pub fn print(&mut self, text: &str)

Print a message to the LCD display.

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.print("TEST MESSAGE");

pub fn write(&mut self, value: u8)

Write a single character to the LCD display.

Examples

let mut lcd: LcdDisplay<_,_> = ...;
lcd.write('A' as u8);