Enhanced library for Freetronics 16x2 LCD shields. More...

#include <LCD.h>

Inheritance diagram for LCD:

Public Types
enum	ScreenSaverMode { DisplayOff, BacklightOff, BacklightOnSelect }
	Screen saver mode that controls the display and back light. More...

Public Member Functions
	LCD ()
	Initialize the Freetronics LCD display with the default pin assignment. More...

	LCD (uint8_t pin9)
	Initialize the Freetronics LCD display for USBDroid. More...

	LCD (uint8_t rs, uint8_t enable, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3)
	Initialize the Freetronics LCD display with custom pins. More...

uint8_t	backlightPin () const
	Returns the pin that is being used to control the back light. The default is 3. More...

void	setBacklightPin (uint8_t pin)
	Sets the back light pin for the LCD shield. More...

void	display ()
	Turns on the display of text on the LCD and the back light. More...

void	noDisplay ()
	Turns off the display of text on the LCD and the back light. More...

ScreenSaverMode	screenSaverMode () const
	Returns the current screen saver mode; default is DisplayOff. More...

void	setScreenSaverMode (ScreenSaverMode mode)
	Sets the current screen saver mode. More...

void	enableScreenSaver (int timeoutSecs=10)
	Enables the screen saver and causes it to activate after timeoutSecs of inactivity on the buttons. More...

void	disableScreenSaver ()
	Disables the screen saver. More...

bool	isScreenSaved () const
	Returns true if the screen has been saved; false otherwise. More...

int	getButton ()
	Gets the next button press, release, or idle event. More...

Detailed Description

Enhanced library for Freetronics 16x2 LCD shields.

This class extends the standard Arduino LiquidCrystal library with extra functionality for the Freetronics 16x2 LCD shield:

http://www.freetronics.com/pages/16x2-lcd-shield-quickstart-guide

The Freetronics LCD has an additional back light, which is turned on and off with the display() and noDisplay() functions. The user can also call enableScreenSaver() to cause the display and back light to automatically turn off after a specific timeout. The setScreenSaverMode() function controls which of the display and back light are disabled when the screen saver activates.

The Freetronics LCD also has 5 push buttons for Left, Right, Up, Down, and Select, to assist with the creation of interactive sketches. The user can call getButton() to get the current button state. One of the following values may be returned:

LCD_BUTTON_NONE - No button has been pressed, or a button has been pressed but not yet released.
LCD_BUTTON_LEFT - Left button was pressed.
LCD_BUTTON_RIGHT - Right button was pressed.
LCD_BUTTON_UP - Up button was pressed.
LCD_BUTTON_DOWN - Down button was pressed.
LCD_BUTTON_SELECT - Select button was pressed.
LCD_BUTTON_LEFT_RELEASED - Left button was released.
LCD_BUTTON_RIGHT_RELEASED - Right button was released.
LCD_BUTTON_UP_RELEASED - Up button was released.
LCD_BUTTON_DOWN_RELEASED - Down button was released.
LCD_BUTTON_SELECT_RELEASED - Select button was released.

For convenience, all RELEASED button codes are the negation of their pressed counterparts. That is, LCD_BUTTON_LEFT_RELEASED == -LCD_BUTTON_LEFT. LCD_BUTTON_NONE is defined to be zero. Thus, you can check if a generic button has been pressed with button > 0 and if a generic button has been released with button < 0.

Support for DFRobot LCD Shield

The DFRobot LCD Shield is almost identical to the Freetronics shield, except it uses pin 10 for the back light instead of pin 3. This can be specified in the application's setup() function:

LCD lcd;
void setup() {
    lcd.setBacklightPin(10);
}

The back light pin is configured for output the first time the application calls getButton().

See Also: Form, Hello World Example

Definition at line 48 of file LCD.h.

Member Enumeration Documentation

enum LCD::ScreenSaverMode

Screen saver mode that controls the display and back light.

Enumerator
DisplayOff	Turn off both the display and the backlight when the screen saver is activated.
BacklightOff	Turn off the back light but leave the display on when the screen saver is activated.
BacklightOnSelect	Same as BacklightOff but the screen saver is only deactivated when Select is pressed; other buttons have no effect.

Definition at line 62 of file LCD.h.

Constructor & Destructor Documentation

LCD::LCD ( )

inline

Initialize the Freetronics LCD display with the default pin assignment.

The following example shows how to initialize the Freetronics LCD shield:

LCD lcd;

Definition at line 50 of file LCD.h.

LCD::LCD ( uint8_t pin9 )

inline

Initialize the Freetronics LCD display for USBDroid.

On the USBDroid, the D9 pin is used for USB Host functionality. Either the USB Host's use of D9 must be reassigned to another pin, or the Freetronics LCD shield must be modified. The following Web page describes the modifications that are necessary: http://www.freetronics.com/pages/combining-the-lcd-keypad-shield-and-the-usbdroid

If you choose to modify the LCD shield, then you must use this version of the constructor to initialize the shield, passing the alternative pin as the pin9 parameter. Using the recommended pin from the above Web page of A1, you would initialize the LCD as follows:

LCD lcd(A1);

Definition at line 51 of file LCD.h.

LCD::LCD	(	uint8_t	rs,
		uint8_t	enable,
		uint8_t	d0,
		uint8_t	d1,
		uint8_t	d2,
		uint8_t	d3
	)

inline

Initialize the Freetronics LCD display with custom pins.

For compatibility with other shields, it may be desirable to rewire some of the pins entirely. This version of the constructor allows any pins to be reassigned from the defaults (which are rs = 8, enable = 9, d0 = 4, d1 = 5, d2 = 6, d3 = 7.)

LCD lcd(8,9,4,5,10,11);

Definition at line 52 of file LCD.h.

Member Function Documentation

uint8_t LCD::backlightPin ( ) const

inline

Returns the pin that is being used to control the back light. The default is 3.

See Also: setBacklightPin()

Definition at line 56 of file LCD.h.

void LCD::disableScreenSaver ( )

Disables the screen saver.

See Also: enableScreenSaver(), display(), isScreenSaved()

Definition at line 323 of file LCD.cpp.

void LCD::display ( )

Turns on the display of text on the LCD and the back light.

If the screen saver is active, then calling this function will deactivate the screen saver and reset the timeout. Thus, this function can be called for force the screen to restore.

See Also: noDisplay(), enableScreenSaver(), setScreenSaverMode()

Definition at line 221 of file LCD.cpp.

void LCD::enableScreenSaver ( int timeoutSecs = 10 )

Enables the screen saver and causes it to activate after timeoutSecs of inactivity on the buttons.

If timeoutSecs is less than or equal to zero, then the call is equivalent to calling disableScreenSaver().

For the screen saver to work, the application must regularly call getButton() to fetch the LCD's button state even if no buttons are pressed.

If the timeoutSecs parameter is not supplied, the default is 10 seconds.

See Also: disableScreenSaver(), display(), getButton(), isScreenSaved()

Definition at line 309 of file LCD.cpp.

int LCD::getButton ( )

Gets the next button press, release, or idle event.

If no buttons are pressed, this function will return LCD_BUTTON_NONE.

When a button is pressed, this function will return one of LCD_BUTTON_LEFT, LCD_BUTTON_RIGHT, LCD_BUTTON_UP, LCD_BUTTON_DOWN, or LCD_BUTTON_SELECT. While the button is pressed, this function will return LCD_BUTTON_NONE until the button is released. When the button is released, this function will return one of LCD_BUTTON_LEFT_RELEASED, LCD_BUTTON_RIGHT_RELEASED, LCD_BUTTON_UP_RELEAED, LCD_BUTTON_DOWN_RELEASED, or LCD_BUTTON_SELECT_RELEASED.

If the screen saver is currently active, then it will be deactivated by this function whenever a button is pressed. If screenSaverMode() is DisplayOff, the function will "eat" the button press and return LCD_BUTTON_NONE. The scrren saver can also be deactivated under program control by calling display().

This function debounces the button state automatically so there is no need for the caller to worry about spurious button events.

See Also: enableScreenSaver(), display(), Form::dispatch()

Definition at line 368 of file LCD.cpp.

bool LCD::isScreenSaved ( ) const

inline

Returns true if the screen has been saved; false otherwise.

See Also: enableScreenSaver()

Definition at line 74 of file LCD.h.

void LCD::noDisplay ( )

Turns off the display of text on the LCD and the back light.

This function can be called to force the screen saver to activate.

See Also: display(), enableScreenSaver(), setScreenSaverMode()

Definition at line 238 of file LCD.cpp.

ScreenSaverMode LCD::screenSaverMode ( ) const

inline

Returns the current screen saver mode; default is DisplayOff.

See Also: setScreenSaverMode(), enableScreenSaver()

Definition at line 69 of file LCD.h.

void LCD::setBacklightPin ( uint8_t pin )

Sets the back light pin for the LCD shield.

The DFRobot LCD Shield uses pin 10 for the back light instead of pin 3:

LCD lcd;
void setup() {
    lcd.setBacklightPin(10);
}

The back light pin is configured for output the next time the application calls getButton().

See Also: backlightPin()

Definition at line 197 of file LCD.cpp.

void LCD::setScreenSaverMode ( ScreenSaverMode mode )

Sets the current screen saver mode.

See Also: screenSaverMode(), enableScreenSaver()

Definition at line 283 of file LCD.cpp.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Detailed Description

Support for DFRobot LCD Shield

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation