pwr_hd44780/
lib.rs

1/// A convenient, high-level driver for the HD44780 display.
2/// Supports both the `I2C` and `GPIO` buses + has a buffered implementation.
3///
4/// # License
5///
6/// Copyright (c) 2018, Patryk Wychowaniec <wychowaniec.patryk@gmail.com>.
7/// Licensed under the MIT license.
8
9extern crate i2cdev;
10extern crate rppal;
11
12pub(crate) use buses::Bus;
13pub use buses::Gpio4 as Gpio4Bus;
14pub use buses::I2C as I2CBus;
15pub use frontends::Buffered as BufferedLcd;
16pub use frontends::Direct as DirectLcd;
17
18pub mod buses;
19pub mod frontends;
20
21pub type Result<T> = ::std::result::Result<T, Box<std::error::Error>>;
22pub type UnitResult = Result<()>;
23
24pub trait Hd44780 {
25    /// Clears the screen and moves cursor at (0, 0).
26    fn clear(&mut self) -> UnitResult;
27
28    /// Moves the cursor at (0, 0).
29    fn home(&mut self) -> UnitResult;
30
31    /// Moves the cursor at given position.
32    ///
33    /// # Example
34    ///
35    /// ```rust
36    /// lcd.move_at(2, 2);
37    /// ```
38    ///
39    /// # Errors
40    ///
41    /// When passed an invalid coordinates (eg. beyond the screen), returns an error and does not
42    /// update the cursor position.
43    fn move_at(&mut self, y: usize, x: usize) -> UnitResult;
44
45    /// Prints a single ASCII character at current cursor's position and moves the cursor.
46    /// Can be used to print custom-made characters (ie. the ones created by `create_char`).
47    ///
48    /// # Example
49    ///
50    /// ```rust
51    /// lcd.print_char(2);
52    /// ```
53    fn print_char(&mut self, ch: u8) -> UnitResult;
54
55    /// Prints a single ASCII character at given position and moves the cursor.
56    /// Can be used to print custom-made characters (ie. the ones created by `create_char`).
57    ///
58    /// # Example
59    ///
60    /// ```rust
61    /// lcd.print_char_at(1, 0, 2);
62    /// ```
63    ///
64    /// # Errors
65    ///
66    /// 1. Returns an error when passed an invalid coordinates.
67    ///
68    /// 2. When given character requires overflowing current line, the behaviour is undefined.
69    fn print_char_at(&mut self, y: usize, x: usize, ch: u8) -> UnitResult {
70        self.move_at(y, x)?;
71        self.print_char(ch)
72    }
73
74    /// Prints a string at current cursor's position and moves the cursor.
75    ///
76    /// # Example
77    ///
78    /// ```rust
79    /// lcd.print("Hello World!");
80    /// lcd.print(format!("Hello, {}!", someone));
81    /// ```
82    ///
83    /// # Errors
84    ///
85    /// When given character requires overflowing current line, the behaviour is undefined.
86    fn print<T: Into<String>>(&mut self, str: T) -> UnitResult {
87        for ch in str.into().chars() {
88            self.print_char(ch as u8)?;
89        }
90
91        Ok(())
92    }
93
94    /// Prints a string at given position.
95    ///
96    /// # Example
97    ///
98    /// ```rust
99    /// lcd.print_at(1, 0, "Hello World!");
100    /// lcd.print_at(2, 0, format!("Hello, {}!", someone));
101    /// ```
102    ///
103    /// # Errors
104    ///
105    /// 1. Returns an error when passed an invalid coordinates.
106    ///
107    /// 2. When given string requires overflowing current line, the behaviour is undefined.
108    fn print_at<T: Into<String>>(&mut self, y: usize, x: usize, str: T) -> UnitResult {
109        self.move_at(y, x)?;
110        self.print(str)
111    }
112
113    /// Enables / disables the backlight.
114    fn set_backlight(&mut self, enabled: bool) -> UnitResult;
115
116    /// Enables / disables blinking the cursor.
117    /// `Blinking` means that the whole character box is blinking (a whole 5x8 or 5x10 box),
118    fn set_cursor_blinking(&mut self, enabled: bool) -> UnitResult;
119
120    /// Enables / disables the cursor.
121    /// `Visible` means that only bottom of the character box is blinking (a single line).
122    fn set_cursor_visible(&mut self, enabled: bool) -> UnitResult;
123
124    /// Shows / hides the text.
125    fn set_text_visible(&mut self, enabled: bool) -> UnitResult;
126
127    /// Creates a custom character from given bitmap.
128    ///
129    /// Each array item in given bitmap represents a single line, of which only the last 5 bits are
130    /// important - rest is ignored.
131    ///
132    /// `idx` must be from range `<0, 7>` (that is: only 8 custom characters are possible, that's a
133    /// limit imposed by the designers of the HD44780).
134    ///
135    /// When passed an invalid `idx`, does nothing.
136    ///
137    /// # Example
138    ///
139    /// ```rust
140    /// lcd.create_char(1, [
141    ///   0b00000000,
142    ///   0b10000000,
143    ///   0b01000000,
144    ///   0b00100000,
145    ///   0b00010000,
146    ///   0b00001000,
147    ///   0b00000100,
148    ///   0b00000010,
149    /// ]);
150    ///
151    /// lcd.print_char(1);
152    /// ```
153    ///
154    /// # Errors
155    ///
156    /// Returns an error when passed an invalid index.
157    fn create_char(&mut self, idx: u8, lines: [u8; 8]) -> UnitResult;
158
159    /// Returns screen's height (number of lines).
160    fn height(&self) -> usize;
161
162    /// Returns screen's width (number of characters per line).
163    fn width(&self) -> usize;
164}
165
166#[derive(Copy, Clone, PartialEq)]
167pub enum Font {
168    Font5x8,
169    Font5x10,
170}
171
172#[derive(Copy, Clone)]
173pub struct Properties {
174    // number of lines
175    pub height: usize,
176
177    // number of characters per line
178    pub width: usize,
179
180    // LCD's font
181    pub font: Font,
182}
pwr_hd44780/lib.rs

pwr_hd44780/
lib.rs
