|
154
|
1 // ---------------------------------------------------------------------------
|
|
|
2 // Created by Francisco Malpartida on 20/08/11.
|
|
|
3 // Copyright 2011 - Under creative commons license 3.0:
|
|
|
4 // Attribution-ShareAlike CC BY-SA
|
|
|
5 //
|
|
|
6 // This software is furnished "as is", without technical support, and with no
|
|
|
7 // warranty, express or implied, as to its usefulness for any purpose.
|
|
|
8 //
|
|
|
9 // Thread Safe: No
|
|
|
10 // Extendable: Yes
|
|
|
11 //
|
|
|
12 // @file LCD.h
|
|
|
13 // This file implements a basic liquid crystal library that comes as standard
|
|
|
14 // in the Arduino SDK.
|
|
|
15 //
|
|
|
16 // @brief
|
|
|
17 // This is a basic implementation of the LiquidCrystal library of the
|
|
|
18 // Arduino SDK. This library is a refactored version of the one supplied
|
|
|
19 // in the Arduino SDK in such a way that it simplifies its extension
|
|
|
20 // to support other mechanism to communicate to LCDs such as I2C, Serial, SR,
|
|
|
21 // The original library has been reworked in such a way that this will be
|
|
|
22 // the base class implementing all generic methods to command an LCD based
|
|
|
23 // on the Hitachi HD44780 and compatible chipsets.
|
|
|
24 //
|
|
|
25 // This base class is a pure abstract class and needs to be extended. As reference,
|
|
|
26 // it has been extended to drive 4 and 8 bit mode control, LCDs and I2C extension
|
|
|
27 // backpacks such as the I2CLCDextraIO using the PCF8574* I2C IO Expander ASIC.
|
|
|
28 //
|
|
|
29 // The functionality provided by this class and its base class is identical
|
|
|
30 // to the original functionality of the Arduino LiquidCrystal library.
|
|
|
31 //
|
|
|
32 // @version API 1.1.0
|
|
|
33 //
|
|
|
34 //
|
|
|
35 // @author F. Malpartida - fmalpartida@gmail.com
|
|
|
36 // ---------------------------------------------------------------------------
|
|
|
37 #ifndef _LCD_H_
|
|
|
38 #define _LCD_H_
|
|
|
39
|
|
|
40 #if (ARDUINO < 100)
|
|
|
41 #include <WProgram.h>
|
|
|
42 #else
|
|
|
43 #include <Arduino.h>
|
|
|
44 #endif
|
|
|
45
|
|
|
46 #include <inttypes.h>
|
|
|
47 #include <Print.h>
|
|
|
48
|
|
|
49
|
|
|
50 /*!
|
|
|
51 @defined
|
|
|
52 @abstract Enables disables fast waits for write operations for LCD
|
|
|
53 @discussion If defined, the library will avoid doing un-necessary waits.
|
|
|
54 this can be done, because the time taken by Arduino's slow digitalWrite
|
|
|
55 operations. If fast digitalIO operations, comment this line out or undefine
|
|
|
56 the mode.
|
|
|
57 */
|
|
|
58 #ifdef __AVR__
|
|
|
59 #define FAST_MODE
|
|
|
60 #endif
|
|
|
61
|
|
|
62 /*!
|
|
|
63 @function
|
|
|
64 @abstract waits for a given time in microseconds (compilation dependent).
|
|
|
65 @discussion Waits for a given time defined in microseconds depending on
|
|
|
66 the FAST_MODE define. If the FAST_MODE is defined the call will return
|
|
|
67 inmediatelly.
|
|
|
68 @param uSec[in] time in microseconds.
|
|
|
69 @result None
|
|
|
70 */
|
|
|
71 inline static void waitUsec ( uint16_t uSec )
|
|
|
72 {
|
|
|
73 #ifndef FAST_MODE
|
|
|
74 delayMicroseconds ( uSec );
|
|
|
75 #endif // FAST_MODE
|
|
|
76 }
|
|
|
77
|
|
|
78
|
|
|
79 /*!
|
|
|
80 @defined
|
|
|
81 @abstract All these definitions shouldn't be used unless you are writing
|
|
|
82 a driver.
|
|
|
83 @discussion All these definitions are for driver implementation only and
|
|
|
84 shouldn't be used by applications.
|
|
|
85 */
|
|
|
86 // LCD Commands
|
|
|
87 // ---------------------------------------------------------------------------
|
|
|
88 #define LCD_CLEARDISPLAY 0x01
|
|
|
89 #define LCD_RETURNHOME 0x02
|
|
|
90 #define LCD_ENTRYMODESET 0x04
|
|
|
91 #define LCD_DISPLAYCONTROL 0x08
|
|
|
92 #define LCD_CURSORSHIFT 0x10
|
|
|
93 #define LCD_FUNCTIONSET 0x20
|
|
|
94 #define LCD_SETCGRAMADDR 0x40
|
|
|
95 #define LCD_SETDDRAMADDR 0x80
|
|
|
96
|
|
|
97 // flags for display entry mode
|
|
|
98 // ---------------------------------------------------------------------------
|
|
|
99 #define LCD_ENTRYRIGHT 0x00
|
|
|
100 #define LCD_ENTRYLEFT 0x02
|
|
|
101 #define LCD_ENTRYSHIFTINCREMENT 0x01
|
|
|
102 #define LCD_ENTRYSHIFTDECREMENT 0x00
|
|
|
103
|
|
|
104 // flags for display on/off and cursor control
|
|
|
105 // ---------------------------------------------------------------------------
|
|
|
106 #define LCD_DISPLAYON 0x04
|
|
|
107 #define LCD_DISPLAYOFF 0x00
|
|
|
108 #define LCD_CURSORON 0x02
|
|
|
109 #define LCD_CURSOROFF 0x00
|
|
|
110 #define LCD_BLINKON 0x01
|
|
|
111 #define LCD_BLINKOFF 0x00
|
|
|
112
|
|
|
113 // flags for display/cursor shift
|
|
|
114 // ---------------------------------------------------------------------------
|
|
|
115 #define LCD_DISPLAYMOVE 0x08
|
|
|
116 #define LCD_CURSORMOVE 0x00
|
|
|
117 #define LCD_MOVERIGHT 0x04
|
|
|
118 #define LCD_MOVELEFT 0x00
|
|
|
119
|
|
|
120 // flags for function set
|
|
|
121 // ---------------------------------------------------------------------------
|
|
|
122 #define LCD_8BITMODE 0x10
|
|
|
123 #define LCD_4BITMODE 0x00
|
|
|
124 #define LCD_2LINE 0x08
|
|
|
125 #define LCD_1LINE 0x00
|
|
|
126 #define LCD_5x10DOTS 0x04
|
|
|
127 #define LCD_5x8DOTS 0x00
|
|
|
128
|
|
|
129
|
|
|
130 // Define COMMAND and DATA LCD Rs (used by send method).
|
|
|
131 // ---------------------------------------------------------------------------
|
|
|
132 #define COMMAND 0
|
|
|
133 #define DATA 1
|
|
|
134 #define FOUR_BITS 2
|
|
|
135
|
|
|
136
|
|
|
137 /*!
|
|
|
138 @defined
|
|
|
139 @abstract Defines the duration of the home and clear commands
|
|
|
140 @discussion This constant defines the time it takes for the home and clear
|
|
|
141 commands in the LCD - Time in microseconds.
|
|
|
142 */
|
|
|
143 #define HOME_CLEAR_EXEC 2000
|
|
|
144
|
|
|
145 /*!
|
|
|
146 @defined
|
|
|
147 @abstract Backlight off constant declaration
|
|
|
148 @discussion Used in combination with the setBacklight to swith off the
|
|
|
149 LCD backlight. @set setBacklight
|
|
|
150 */
|
|
|
151 #define BACKLIGHT_OFF 0
|
|
|
152
|
|
|
153 /*!
|
|
|
154 @defined
|
|
|
155 @abstract Backlight on constant declaration
|
|
|
156 @discussion Used in combination with the setBacklight to swith on the
|
|
|
157 LCD backlight. @set setBacklight
|
|
|
158 */
|
|
|
159 #define BACKLIGHT_ON 255
|
|
|
160
|
|
|
161
|
|
|
162 /*!
|
|
|
163 @typedef
|
|
|
164 @abstract Define backlight control polarity
|
|
|
165 @discussion Backlight control polarity. @see setBacklightPin.
|
|
|
166 */
|
|
|
167 typedef enum { POSITIVE, NEGATIVE } t_backlighPol;
|
|
|
168
|
|
|
169 class LCD : public Print
|
|
|
170 {
|
|
|
171 public:
|
|
|
172
|
|
|
173 /*!
|
|
|
174 @method
|
|
|
175 @abstract LiquidCrystal abstract constructor.
|
|
|
176 @discussion LiquidCrystal class abstract constructor needed to create
|
|
|
177 the base abstract class.
|
|
|
178 */
|
|
|
179 LCD ( );
|
|
|
180
|
|
|
181 /*!
|
|
|
182 @function
|
|
|
183 @abstract LCD initialization.
|
|
|
184 @discussion Initializes the LCD to a given size (col, row). This methods
|
|
|
185 initializes the LCD, therefore, it MUST be called prior to using any other
|
|
|
186 method from this class.
|
|
|
187
|
|
|
188 This method is abstract, a base implementation is available common to all LCD
|
|
|
189 drivers. Should it not be compatible with some other LCD driver, a derived
|
|
|
190 implementation should be done on the driver specif class.
|
|
|
191
|
|
|
192 @param cols[in] the number of columns that the display has
|
|
|
193 @param rows[in] the number of rows that the display has
|
|
|
194 @param charsize[in] character size, default==LCD_5x8DOTS
|
|
|
195 */
|
|
|
196 virtual void begin(uint8_t cols, uint8_t rows, uint8_t charsize = LCD_5x8DOTS);
|
|
|
197
|
|
|
198 /*!
|
|
|
199 @function
|
|
|
200 @abstract Clears the LCD.
|
|
|
201 @discussion Clears the LCD screen and positions the cursor in the upper-left
|
|
|
202 corner.
|
|
|
203
|
|
|
204 This operation is time consuming for the LCD.
|
|
|
205
|
|
|
206 @param none
|
|
|
207 */
|
|
|
208 void clear();
|
|
|
209
|
|
|
210 /*!
|
|
|
211 @function
|
|
|
212 @abstract Sets the cursor to the upper-left corner.
|
|
|
213 @discussion Positions the cursor in the upper-left of the LCD.
|
|
|
214 That is, use that location in outputting subsequent text to the display.
|
|
|
215 To also clear the display, use the clear() function instead.
|
|
|
216
|
|
|
217 This operation is time consuming for the LCD.
|
|
|
218
|
|
|
219 @param none
|
|
|
220 */
|
|
|
221 void home();
|
|
|
222
|
|
|
223 /*!
|
|
|
224 @function
|
|
|
225 @abstract Turns off the LCD display.
|
|
|
226 @discussion Turns off the LCD display, without losing the text currently
|
|
|
227 being displayed on it.
|
|
|
228
|
|
|
229 @param none
|
|
|
230 */
|
|
|
231 void noDisplay();
|
|
|
232
|
|
|
233 /*!
|
|
|
234 @function
|
|
|
235 @abstract Turns on the LCD display.
|
|
|
236 @discussion Turns on the LCD display, after it's been turned off with
|
|
|
237 noDisplay(). This will restore the text (and cursor location) that was on
|
|
|
238 the display prior to calling noDisplay().
|
|
|
239
|
|
|
240 @param none
|
|
|
241 */
|
|
|
242 void display();
|
|
|
243
|
|
|
244 /*!
|
|
|
245 @function
|
|
|
246 @abstract Turns off the blinking of the LCD cursor.
|
|
|
247
|
|
|
248 @param none
|
|
|
249 */
|
|
|
250 void noBlink();
|
|
|
251
|
|
|
252 /*!
|
|
|
253 @function
|
|
|
254 @abstract Display the cursor of the LCD.
|
|
|
255 @discussion Display the blinking LCD cursor. If used in combination with
|
|
|
256 the cursor() function, the result will depend on the particular display.
|
|
|
257
|
|
|
258 @param none
|
|
|
259 */
|
|
|
260 void blink();
|
|
|
261
|
|
|
262 /*!
|
|
|
263 @function
|
|
|
264 @abstract Hides the LCD cursor.
|
|
|
265
|
|
|
266 @param none
|
|
|
267 */
|
|
|
268 void noCursor();
|
|
|
269
|
|
|
270 /*!
|
|
|
271 @function
|
|
|
272 @abstract Display the LCD cursor.
|
|
|
273 @discussion Display the LCD cursor: an underscore (line) at the location
|
|
|
274 where the next character will be written.
|
|
|
275
|
|
|
276 @param none
|
|
|
277 */
|
|
|
278 void cursor();
|
|
|
279
|
|
|
280 /*!
|
|
|
281 @function
|
|
|
282 @abstract Scrolls the contents of the display (text and cursor) one space
|
|
|
283 to the left.
|
|
|
284
|
|
|
285 @param none
|
|
|
286 */
|
|
|
287 void scrollDisplayLeft();
|
|
|
288
|
|
|
289 /*!
|
|
|
290 @function
|
|
|
291 @abstract Scrolls the contents of the display (text and cursor) one space
|
|
|
292 to the right.
|
|
|
293
|
|
|
294 @param none
|
|
|
295 */
|
|
|
296 void scrollDisplayRight();
|
|
|
297
|
|
|
298 /*!
|
|
|
299 @function
|
|
|
300 @abstract Set the direction for text written to the LCD to left-to-right.
|
|
|
301 @discussion Set the direction for text written to the LCD to left-to-right.
|
|
|
302 All subsequent characters written to the display will go from left to right,
|
|
|
303 but does not affect previously-output text.
|
|
|
304
|
|
|
305 This is the default configuration.
|
|
|
306
|
|
|
307 @param none
|
|
|
308 */
|
|
|
309 void leftToRight();
|
|
|
310
|
|
|
311 /*!
|
|
|
312 @function
|
|
|
313 @abstract Set the direction for text written to the LCD to right-to-left.
|
|
|
314 @discussion Set the direction for text written to the LCD to right-to-left.
|
|
|
315 All subsequent characters written to the display will go from right to left,
|
|
|
316 but does not affect previously-output text.
|
|
|
317
|
|
|
318 left-to-right is the default configuration.
|
|
|
319
|
|
|
320 @param none
|
|
|
321 */
|
|
|
322 void rightToLeft();
|
|
|
323
|
|
|
324 /*!
|
|
|
325 @function
|
|
|
326 @abstract Moves the cursor one space to the left.
|
|
|
327 @discussion
|
|
|
328 @param none
|
|
|
329 */
|
|
|
330 void moveCursorLeft();
|
|
|
331
|
|
|
332
|
|
|
333 /*!
|
|
|
334 @function
|
|
|
335 @abstract Moves the cursor one space to the right.
|
|
|
336
|
|
|
337 @param none
|
|
|
338 */
|
|
|
339 void moveCursorRight();
|
|
|
340
|
|
|
341 /*!
|
|
|
342 @function
|
|
|
343 @abstract Turns on automatic scrolling of the LCD.
|
|
|
344 @discussion Turns on automatic scrolling of the LCD. This causes each
|
|
|
345 character output to the display to push previous characters over by one
|
|
|
346 space. If the current text direction is left-to-right (the default),
|
|
|
347 the display scrolls to the left; if the current direction is right-to-left,
|
|
|
348 the display scrolls to the right.
|
|
|
349 This has the effect of outputting each new character to the same location on
|
|
|
350 the LCD.
|
|
|
351
|
|
|
352 @param none
|
|
|
353 */
|
|
|
354 void autoscroll();
|
|
|
355
|
|
|
356 /*!
|
|
|
357 @function
|
|
|
358 @abstract Turns off automatic scrolling of the LCD.
|
|
|
359 @discussion Turns off automatic scrolling of the LCD, this is the default
|
|
|
360 configuration of the LCD.
|
|
|
361
|
|
|
362 @param none
|
|
|
363 */
|
|
|
364 void noAutoscroll();
|
|
|
365
|
|
|
366 /*!
|
|
|
367 @function
|
|
|
368 @abstract Creates a custom character for use on the LCD.
|
|
|
369 @discussion Create a custom character (glyph) for use on the LCD.
|
|
|
370 Most chipsets only support up to eight characters of 5x8 pixels. Therefore,
|
|
|
371 this methods has been limited to locations (numbered 0 to 7).
|
|
|
372
|
|
|
373 The appearance of each custom character is specified by an array of eight
|
|
|
374 bytes, one for each row. The five least significant bits of each byte
|
|
|
375 determine the pixels in that row. To display a custom character on screen,
|
|
|
376 write()/print() its number, i.e. lcd.print (char(x)); // Where x is 0..7.
|
|
|
377
|
|
|
378 @param location[in] LCD memory location of the character to create
|
|
|
379 (0 to 7)
|
|
|
380 @param charmap[in] the bitmap array representing each row of the character.
|
|
|
381 */
|
|
|
382 void createChar(uint8_t location, uint8_t charmap[]);
|
|
|
383
|
|
|
384 /*!
|
|
|
385 @function
|
|
|
386 @abstract Position the LCD cursor.
|
|
|
387 @discussion Sets the position of the LCD cursor. Set the location at which
|
|
|
388 subsequent text written to the LCD will be displayed.
|
|
|
389
|
|
|
390 @param col[in] LCD column
|
|
|
391 @param row[in] LCD row - line.
|
|
|
392 */
|
|
|
393 void setCursor(uint8_t col, uint8_t row);
|
|
|
394
|
|
|
395 /*!
|
|
|
396 @function
|
|
|
397 @abstract Switch-on the LCD backlight.
|
|
|
398 @discussion Switch-on the LCD backlight.
|
|
|
399 The setBacklightPin has to be called before setting the backlight for
|
|
|
400 this method to work. @see setBacklightPin.
|
|
|
401 */
|
|
|
402 void backlight ( void );
|
|
|
403
|
|
|
404 /*!
|
|
|
405 @function
|
|
|
406 @abstract Switch-off the LCD backlight.
|
|
|
407 @discussion Switch-off the LCD backlight.
|
|
|
408 The setBacklightPin has to be called before setting the backlight for
|
|
|
409 this method to work. @see setBacklightPin.
|
|
|
410 */
|
|
|
411 void noBacklight ( void );
|
|
|
412
|
|
|
413 /*!
|
|
|
414 @function
|
|
|
415 @abstract Switch on the LCD module.
|
|
|
416 @discussion Switch on the LCD module, it will switch on the LCD controller
|
|
|
417 and the backlight. This method has the same effect of calling display and
|
|
|
418 backlight. @see display, @see backlight
|
|
|
419 */
|
|
|
420 void on ( void );
|
|
|
421
|
|
|
422 /*!
|
|
|
423 @function
|
|
|
424 @abstract Switch off the LCD module.
|
|
|
425 @discussion Switch off the LCD module, it will switch off the LCD controller
|
|
|
426 and the backlight. This method has the same effect of calling noDisplay and
|
|
|
427 noBacklight. @see display, @see backlight
|
|
|
428 */
|
|
|
429 void off ( void );
|
|
|
430
|
|
|
431 //
|
|
|
432 // virtual class methods
|
|
|
433 // --------------------------------------------------------------------------
|
|
|
434 /*!
|
|
|
435 @function
|
|
|
436 @abstract Sets the pin to control the backlight.
|
|
|
437 @discussion Sets the pin in the device to control the backlight.
|
|
|
438 This method is device dependent and can be programmed on each subclass. An
|
|
|
439 empty function call is provided that does nothing.
|
|
|
440
|
|
|
441 @param value: pin associated to backlight control.
|
|
|
442 @param pol: backlight polarity control (POSITIVE, NEGATIVE)
|
|
|
443 */
|
|
|
444 virtual void setBacklightPin ( uint8_t value, t_backlighPol pol ) { };
|
|
|
445
|
|
|
446 /*!
|
|
|
447 @function
|
|
|
448 @abstract Sets the pin to control the backlight.
|
|
|
449 @discussion Sets the pin in the device to control the backlight. The behaviour
|
|
|
450 of this method is very dependent on the device. Some controllers support
|
|
|
451 dimming some don't. Please read the actual header file for each individual
|
|
|
452 device. The setBacklightPin method has to be called before setting the backlight
|
|
|
453 or the adequate backlight control constructor.
|
|
|
454 @see setBacklightPin.
|
|
|
455
|
|
|
456 NOTE: The prefered methods to control the backlight are "backlight" and
|
|
|
457 "noBacklight".
|
|
|
458
|
|
|
459 @param 0..255 - the value is very dependent on the LCD. However,
|
|
|
460 BACKLIGHT_OFF will be interpreted as off and BACKLIGHT_ON will drive the
|
|
|
461 backlight on.
|
|
|
462 */
|
|
|
463 virtual void setBacklight ( uint8_t value ) { };
|
|
|
464
|
|
|
465 /*!
|
|
|
466 @function
|
|
|
467 @abstract Writes to the LCD.
|
|
|
468 @discussion This method writes character to the LCD in the current cursor
|
|
|
469 position.
|
|
|
470
|
|
|
471 This is the virtual write method, implemented in the Print class, therefore
|
|
|
472 all Print class methods will end up calling this method.
|
|
|
473
|
|
|
474 @param value[in] Value to write to the LCD.
|
|
|
475 */
|
|
|
476 #if (ARDUINO < 100)
|
|
|
477 virtual void write(uint8_t value);
|
|
|
478 #else
|
|
|
479 virtual size_t write(uint8_t value);
|
|
|
480 #endif
|
|
|
481
|
|
|
482 #if (ARDUINO < 100)
|
|
|
483 using Print::write;
|
|
|
484 #else
|
|
|
485 using Print::write;
|
|
|
486 #endif
|
|
|
487
|
|
|
488 protected:
|
|
|
489 // Internal LCD variables to control the LCD shared between all derived
|
|
|
490 // classes.
|
|
|
491 uint8_t _displayfunction; // LCD_5x10DOTS or LCD_5x8DOTS, LCD_4BITMODE or
|
|
|
492 // LCD_8BITMODE, LCD_1LINE or LCD_2LINE
|
|
|
493 uint8_t _displaycontrol; // LCD base control command LCD on/off, blink, cursor
|
|
|
494 // all commands are "ored" to its contents.
|
|
|
495 uint8_t _displaymode; // Text entry mode to the LCD
|
|
|
496 uint8_t _numlines; // Number of lines of the LCD, initialized with begin()
|
|
|
497 uint8_t _cols; // Number of columns in the LCD
|
|
|
498 t_backlighPol _polarity; // Backlight polarity
|
|
|
499
|
|
|
500 private:
|
|
|
501 /*!
|
|
|
502 @function
|
|
|
503 @abstract Send a command to the LCD.
|
|
|
504 @discussion This method sends a command to the LCD by setting the Register
|
|
|
505 select line of the LCD.
|
|
|
506
|
|
|
507 This command shouldn't be used to drive the LCD, only to implement any other
|
|
|
508 feature that is not available on this library.
|
|
|
509
|
|
|
510 @param value[in] Command value to send to the LCD (COMMAND, DATA or
|
|
|
511 FOUR_BITS).
|
|
|
512 */
|
|
|
513 void command(uint8_t value);
|
|
|
514
|
|
|
515 /*!
|
|
|
516 @function
|
|
|
517 @abstract Send a particular value to the LCD.
|
|
|
518 @discussion Sends a particular value to the LCD. This is a pure abstract
|
|
|
519 method, therefore, it is implementation dependent of each derived class how
|
|
|
520 to physically write to the LCD.
|
|
|
521
|
|
|
522 Users should never call this method.
|
|
|
523
|
|
|
524 @param value[in] Value to send to the LCD.
|
|
|
525 @result mode LOW - write to the LCD CGRAM, HIGH - write a command to
|
|
|
526 the LCD.
|
|
|
527 */
|
|
|
528 #if (ARDUINO < 100)
|
|
|
529 virtual void send(uint8_t value, uint8_t mode) { };
|
|
|
530 #else
|
|
|
531 virtual void send(uint8_t value, uint8_t mode) = 0;
|
|
|
532 #endif
|
|
|
533
|
|
|
534 };
|
|
|
535
|
|
|
536 #endif
|
