1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
|
mod codes;
pub mod custom_char;
mod of_node;
pub mod special_char;
use std::fs::{File, OpenOptions};
use std::path::Path;
use std::io::BufWriter;
use std::io::Result;
use std::io::Write;
use codes::SpecialCode;
use codes::WriteInto;
// Increment this number when appropriate:
//
// NUMBER_OF_LCD_SCREENS_DESTROYED_DURING_TESTING: 1
/// A screen that allows you to send commands to a charlcd driver (or whatever
/// that implements the [`Write`] trait).
///
/// # Simple example
///
/// ```rust
/// use charlcd::Screen;
///
/// fn main() -> std::io::Result<()> {
/// let mut screen = Screen::default(); // will use "/dev/lcd" charlcd driver
///
/// screen.clear()?;
/// screen.write(b"hello, world!")?;
/// screen.flash_backlight()?;
/// screen.flush()?; // send all the previous commands to the driver at once
/// }
/// ```
pub struct Screen<T> {
writer: T,
}
macro_rules! write_simple_code {
($self:expr, $code:expr) => {{
$code.write_into(&mut $self.writer)?;
Ok(())
}};
}
impl<T> Screen<T>
where
T: Write,
{
/// Create a new [`Screen`] instance that will use the provided [`Write`]
/// under the hood to send commands.
pub fn new(writer: T) -> Screen<T> {
Screen { writer }
}
/// Clean the rest of the current line, from current cursor position.
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn kill_eol(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::KillEndOfLine)
}
/// Reinitialize the display to its default hardware values.
///
/// # Live footage (before and after)
/// 
/// 
///
/// Note: we observe that the cursor *and* blink are activated after a call
/// to [`Screen::reinit()`], although the [`Screen::blink_on()`] and
/// [`Screen::cursor_on()`] methods are *not* called in this function. We
/// can deduce it is a hardware default to put back the blink and cursor on
/// at initialization.
///
/// You may want to disable them after a call to this function by using the
/// [`Screen::blink_off()`] and [`Screen::cursor_off()`] functions.
pub fn reinit(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::ReinitializeDisplay)
}
/// Disable the display.
///
/// The displayed content is not lost and kept into the screen buffer. Call
/// [`Screen::display_on()`] to display back what was printed to the screen.
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn display_off(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::DisplayOff)
}
/// Enable the display.
///
/// The content of the screen buffer will be displayed back with no change.
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn display_on(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::DisplayOn)
}
/// Enable the underscore cursor (independent of blinking cursor).
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn cursor_on(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::CursorOn)
}
/// Disable the underscore cursor (independent of blinking cursor).
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn cursor_off(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::CursorOff)
}
/// Enable the blinking cursor (independent of underscore cursor).
///
/// # Live footage (before and after)
/// 
/// 
///
/// Note: due to long exposure duration of the camera (1 second), the
/// blinking cursor appears dim in the footage.
///
pub fn blink_on(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::BlinkOn)
}
/// Disable the blinking cursor (independent of underscore cursor).
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn blink_off(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::BlinkOff)
}
/// Enable the backlight.
pub fn backlight_on(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::BacklightOn)
}
/// Disable the backlight.
pub fn backlight_off(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::BacklightOff)
}
/// Flash the backlight during a small duration.
///
/// The exact duration is specified in the driver. As of today, the default
/// value is set to 4 seconds (`LCD_BL_TEMPO_PERIOD` define in `charlcd.c`).
pub fn flash_backlight(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::FlashBacklight)
}
/// Clear the screen and return the cursor at original (0, 0) XY position.
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn clear(&mut self) -> std::io::Result<()> {
self.write(&[0x0c])?; // '\f' escape not defined in Rust
Ok(())
}
/// Move the cursor back one character, and delete the character at this
/// position.
///
/// This is an utility function that will send the raw byte value for the
/// `'\b'` escape sequence. This sequence is valid in C, but is not
/// available in Rust.
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn back(&mut self) -> std::io::Result<()> {
self.write(&[0x08])?; // '\b' escape not defined in Rust
Ok(())
}
// Less-used (and some non-working?) methods below
/// Shift cursor left.
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn shift_cursor_left(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::ShiftCursorLeft)
}
/// Shift cursor right.
///
/// # Live footage (before and after)
/// 
/// 
///
pub fn shift_cursor_right(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::ShiftCursorRight)
}
/// Shift display left.
///
/// # Live footage (before and after)
/// 
/// 
///
/// Note: we can observe that the shift will create an artefact on the n+2
/// line, as the extra characters will be shifted there.
pub fn shift_display_left(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::ShiftDisplayLeft)
}
/// Shift display right.
///
/// # Live footage (before and after)
/// 
/// 
///
/// Note: we can observe that the shift will create an artefact on the n+2
/// line, as the extra characters will be shifted there.
pub fn shift_display_right(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::ShiftDisplayRight)
}
/// Enable one line mode.
///
/// # Live footage (before and after)
/// 
/// 
///
/// We can see that the screen seems to disable power for the second and
/// fourth line of the display (in case of a 4 lines one). Cutting the
/// power for half the screen means that the contrast adjustment will not
/// be correct anymore, as the screen uses less power by managing only half
/// of the characters.
///
/// A manual recalibration of the contrast will be necessary if you change
/// between [`Screen::one_line()`] and [`Screen::two_lines()`] modes.
pub fn one_line(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::OneLine)
}
/// Enable two lines mode.
///
/// # Live footage (before and after)
/// 
/// 
///
/// This will mess up the screen if coming from [`Screen::one_line()`] mode.
///
/// A manual recalibration of the contrast will be necessary if you change
/// between [`Screen::one_line()`] and [`Screen::two_lines()`] modes.
pub fn two_lines(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::TwoLines)
}
/// Enable small font mode.
///
/// Note: this function seems to have no effect on the screen after tests
/// with multiple screen variants. No relevant footage available.
pub fn small_font(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::SmallFont)
}
/// Enable big font mode.
///
/// Note: this function seems to have no effect on the screen after tests
/// with multiple screen variants. No relevant footage available.
pub fn large_font(&mut self) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::LargeFont)
}
/// Custom character create
pub fn custom_char(&mut self, code: u8, value: [u8; 8]) -> std::io::Result<()> {
let mut res = 0u64;
let mut i = 0;
for b in value.iter().rev() {
res |= (*b as u64) << i;
i += 8;
}
write_simple_code!(self, SpecialCode::Generator(code, res))
}
pub fn gotoxy(&mut self, x: u32, y: u32) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::GotoXY(Some(x), Some(y)))
}
pub fn gotox(&mut self, x: u32) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::GotoXY(Some(x), None))
}
pub fn gotoy(&mut self, y: u32) -> std::io::Result<()> {
write_simple_code!(self, SpecialCode::GotoXY(None, Some(y)))
}
}
// Reimplement Write trait for Screen, so that user can call the write and
// flush methods of the inner writer.
impl<T> Write for Screen<T>
where
T: Write,
{
fn write(&mut self, buf: &[u8]) -> Result<usize> {
self.writer.write(buf)
}
fn flush(&mut self) -> Result<()> {
self.writer.flush()
}
}
// Concrete screen based on a File, to write to the real charlcd driver (or to
// another file).
type FileScreen = Screen<BufWriter<File>>;
const DEFAULT_SCREEN_DEV_PATH: &str = "/dev/lcd";
impl FileScreen {
/// Create a Screen instance based on the passed path to the device.
pub fn from_dev_path(path: &Path) -> std::io::Result<FileScreen> {
let file = OpenOptions::new().write(true).open(path)?;
let buf = BufWriter::new(file);
Ok(Screen::new(buf))
}
/// Create a default Screen instance based on `/dev/lcd` device driver
/// path.
pub fn default() -> std::io::Result<FileScreen> {
Screen::from_dev_path(&Path::new(DEFAULT_SCREEN_DEV_PATH))
}
/// Get the width of the screen, in number of characters it can display.
///
/// # Example
///
/// ```rust
/// let screen = Screen::default()?; // the screen is 20x4 in this test
/// let width = screen.width()?;
/// assert_eq!(width, 20);
/// ```
///
/// # Important note
///
/// The implementation behind this function is currently a hack that will
/// go find the value in the `auxdisplay` platform device tree node in
/// `/sys/devices/platform/auxdisplay/of_node/*`. This is because the
/// `charlcd` driver does not export the `width` nor `height` fields to
/// userspace.
///
/// In the future, this function may be able to read the value directly
/// from the `/dev/lcd` device if a proper `ioctl` or `read` call is
/// implemented for this purpose.
///
pub fn width(&self) -> std::io::Result<u32> {
of_node::display_width_chars()
}
/// Get the height of the screen, in number of characters it can display.
///
/// # Example
///
/// ```rust
/// let screen = Screen::default()?; // the screen is 20x4 in this test
/// let width = screen.height()?;
/// assert_eq!(width, 4);
/// ```
///
/// # Important note
///
/// The implementation behind this function is currently a hack that will
/// go find the value in the `auxdisplay` platform device tree node in
/// `/sys/devices/platform/auxdisplay/of_node/*`. This is because the
/// `charlcd` driver does not export the `width` nor `height` fields to
/// userspace.
///
/// In the future, this function may be able to read the value directly
/// from the `/dev/lcd` device if a proper `ioctl` or `read` call is
/// implemented for this purpose.
///
pub fn height(&self) -> std::io::Result<u32> {
of_node::display_height_chars()
}
}
|
