chipKIT® Development Platform
Inspired by Arduino™
- Get Started
- Learning
- Products
- Blog
- Beginner
For first time users of chipKIT modules. - Intermediate
For users who have a moderate exposure with chipKIT modules. - Advanced
For users who are experts with chipKIT modules. - Developers
- About Us
- Support
LiquidCrystal
| LiquidCrystal | |
|---|---|
| Quick Look | |
| Hardware | (External hardware) |
| Include | LiquidCrystal.h |
The LiquidCrystal library is used for interfacing with a LCD (Liquid Crystal Display) based on the Hitachi HD44780 or a compatible) chipset.
Detailed Introduction
Liquid Crystal Displays are a common way to provide a visual interface for an end user. The HD44780 is a dot matrix controller capable of individual pixle control. To take advantage of this feature library provides a createChar function which allows you to create 8 custom characters which are stored in RAM. Each character is either 5x8 or 5x10 pixles depeding on your display.
The controller also has a large set of built in characters stored in ROM. When you print a character it's binary ascii equivalent is sent through the data lines and the proper character is retrieved from the equivalent address location in ROM. The characters displayed may vary depending on the part number of the controller.
The controllers come with 4 and 8 bit data line options. You'll need to select the correct constructor for the number of data lines you are using.
Lastly, note that the LiquidCrystal library inherits from the Print class. Therfore functions such as print() from the print class may be used.
Wiring
To wire a LCD to a chipKIT you will need at least 1 resistor for the LED back light and an optional potentiomenter to control the contrast.
Although many of the common displays come with 8 (0-7) data lines only the upper 4 (4 - 7) are required. You can save the extra pins on your chipKIT for something else. The reason you can get away wth this is because the LiquidCrystal library takes care of sending 2 packets of data for you when the appropiate 4 bit constructor is used. If you need speed, which most applications don't, then you'll want to connect up lines 0-3 of the LCD as well and chose an appropriate 8 bit constructor when creating your LiquidCrystal library object.
In our examples we have selected chipKIT pins D12 (RS) and D11 (Enable) for our control lines and chipKIT pins D5, D4, D3, and D2 for our Data line. It's important to note that the PIC32 microcontroller output 3.3V logic levels. Some LCD modules will treat 3.3V as a logic high. However, if your display does not then you may need some additional circuitry.
Below is a list of the pin definitions of a classic Hitachi HD44780 compatible LCD display and the description of the pins function. Take special note of the control pins as the'll help you understand how the library work and will assist you in troubleshooting faulty circuits.
LCD Pin Definitions
| Pin No. | Name | Description |
|---|---|---|
| 1 | GND | Ground |
| 2 | VCC | Power (Typically +5V but check your datasheet) |
| 3 | VEE | Contrast Control |
| 4 | RS | Register Select (RS), used to select whether data or an instruction is being transferred between the microcontroller and the LCD. It is 0 for a command and 1 for data. |
| 5 | R/W | Read/Write, Selects the data direction. High = Write, Low = Read. Typically tied to Ground. |
| 6 | E | Enable, used to synchronize data transfer. Pulsing the Enable pin causes data at the pins to be latched. |
| 7 | D0 | Data line 0 |
| 8 | D1 | Data line 1 |
| 9 | D2 | Data line 2 |
| 10 | D3 | Data line 3 |
| 11 | D4 | Data line 4 |
| 12 | D5 | Data line 5 |
| 13 | D6 | Data line 6 |
| 14 | D7 | Data line 7 |
| 15 | LED+ | Anode, Backlight |
| 16 | LED- | Cathode, Backlight (A current limiting resistor is required to prevent burning out the LED) |
Introductory Programs
HelloWorld
This sketch example demonstrates how print Hello World on a a 16x2 LCD display.
/*
LiquidCrystal Library - Hello World
Demonstrates the use a 16x2 LCD display. The LiquidCrystal
library works with all LCD displays that are compatible with the
Hitachi HD44780 driver. There are many of them out there, and you
can usually tell them by the 16-pin interface.
This sketch prints "Hello World!" to the LCD
and shows the time.
The circuit:
* LCD RS pin to digital pin 12
* LCD Enable pin to digital pin 11
* LCD D4 pin to digital pin 5
* LCD D5 pin to digital pin 4
* LCD D6 pin to digital pin 3
* LCD D7 pin to digital pin 2
* LCD R/W pin to ground
* 10K resistor:
* ends to +5V and ground
* wiper to LCD VO pin (pin 3)
Library originally added 18 Apr 2008
by David A. Mellis
library modified 5 Jul 2009
by Limor Fried (http://www.ladyada.net)
example added 9 Jul 2009
by Tom Igoe
modified 22 Nov 2010
by Tom Igoe
This example code is in the public domain.
http://www.arduino.cc/en/Tutorial/LiquidCrystal
*/
// include the library code:
#include <LiquidCrystal.h>
// initialize the library with the numbers of the interface pins
LiquidCrystal lcd(12, 11, 5, 4, 3, 2);
void setup() {
// set up the LCD's number of columns and rows:
lcd.begin(16, 2);
// Print a message to the LCD.
lcd.print("hello, world!");
}
void loop() {
// set the cursor to column 0, line 1
// (note: line 1 is the second row, since counting begins with 0):
lcd.setCursor(0, 1);
// print the number of seconds since reset:
lcd.print(millis()/1000);
}
Scroll
This sketch example prints hello world to a 16x2 LCD display and then scrolls the text offscreen to the left, then offscreen to the right, and finally back to center.
/*
LiquidCrystal Library - scrollDisplayLeft() and scrollDisplayRight()
Demonstrates the use a 16x2 LCD display. The LiquidCrystal
library works with all LCD displays that are compatible with the
Hitachi HD44780 driver. There are many of them out there, and you
can usually tell them by the 16-pin interface.
This sketch prints "Hello World!" to the LCD and uses the
scrollDisplayLeft() and scrollDisplayRight() methods to scroll
the text.
The circuit:
* LCD RS pin to digital pin 12
* LCD Enable pin to digital pin 11
* LCD D4 pin to digital pin 5
* LCD D5 pin to digital pin 4
* LCD D6 pin to digital pin 3
* LCD D7 pin to digital pin 2
* LCD R/W pin to ground
* 10K resistor:
* ends to +5V and ground
* wiper to LCD VO pin (pin 3)
Library originally added 18 Apr 2008
by David A. Mellis
library modified 5 Jul 2009
by Limor Fried (http://www.ladyada.net)
example added 9 Jul 2009
by Tom Igoe
modified 22 Nov 2010
by Tom Igoe
This example code is in the public domain.
http://www.arduino.cc/en/Tutorial/LiquidCrystal
*/
// include the library code:
#include <LiquidCrystal.h>
// initialize the library with the numbers of the interface pins
LiquidCrystal lcd(12, 11, 5, 4, 3, 2);
void setup() {
// set up the LCD's number of columns and rows:
lcd.begin(16, 2);
// Print a message to the LCD.
lcd.print("hello, world!");
delay(1000);
}
void loop() {
// scroll 13 positions (string length) to the left
// to move it offscreen left:
for (int positionCounter = 0; positionCounter < 13; positionCounter++) {
// scroll one position left:
lcd.scrollDisplayLeft();
// wait a bit:
delay(150);
}
// scroll 29 positions (string length + display length) to the right
// to move it offscreen right:
for (int positionCounter = 0; positionCounter < 29; positionCounter++) {
// scroll one position right:
lcd.scrollDisplayRight();
// wait a bit:
delay(150);
}
// scroll 16 positions (display length + string length) to the left
// to move it back to center:
for (int positionCounter = 0; positionCounter < 16; positionCounter++) {
// scroll one position left:
lcd.scrollDisplayLeft();
// wait a bit:
delay(150);
}
// delay at the end of the full loop:
delay(1000);
}
Full library usage
LiquidCrystal
- Parent class: Print
Constructors
LiquidCrystal(uint8_t rs, uint8_t enable, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3);
LiquidCrystal(uint8_t rs, uint8_t enable,
uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3);
4 bit constructor, no r/w control, saves a pin
LiquidCrystal(uint8_t rs, uint8_t rw, uint8_t enable, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3);
LiquidCrystal(uint8_t rs, uint8_t rw, uint8_t enable,
uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3);
4 bit constructor with r/w control pin set.
LiquidCrystal(uint8_t rs, uint8_t enable, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3, uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7)
LiquidCrystal(uint8_t rs, uint8_t enable,
uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3,
uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7);
8 bit constructor, no r/w control, saves a pin
LiquidCrystal(uint8_t rs, uint8_t rw, uint8_t enable, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3, uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7)
LiquidCrystal(uint8_t rs, uint8_t rw, uint8_t enable,
uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3,
uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7);
8 bit constructor with r/w control pin set.
Constants
Commands
| Name | Default Value |
|---|---|
| LCD_CLEARDISPLAY | 0x01 |
| LCD_RETURNHOME | 0x02 |
| LCD_ENTRYMODESET | 0x04 |
| LCD_DISPLAYCONTROL | 0x08 |
| LCD_CURSORSHIFT | 0x10 |
| LCD_FUNCTIONSET | 0x20 |
| LCD_SETCGRAMADDR | 0x40 |
| LCD_SETDDRAMADDR | 0x80 |
Flags for Display Entry Mode
| Name | Default Value |
|---|---|
| LCD_ENTRYRIGHT | 0x00 |
| LCD_ENTRYLEFT | 0x02 |
| LCD_ENTRYSHIFTINCREMENT | 0x01 |
| LCD_ENTRYSHIFTDECREMENT | 0x00 |
Flags for Display On/Off Control
| Name | Default Value |
|---|---|
| LCD_DISPLAYON | 0x04 |
| LCD_DISPLAYOFF | 0x00 |
| LCD_CURSORON | 0x02 |
| LCD_CURSOROFF | 0x00 |
| LCD_BLINKON | 0x01 |
| LCD_BLINKOFF | 0x00 |
Flags for Display/Cursor Shift
| Name | Default Value |
|---|---|
| LCD_DISPLAYMOVE | 0x08 |
| LCD_CURSORMOVE | 0x00 |
| LCD_MOVERIGHT | 0x04 |
| LCD_MOVELEFT | 0x00 |
Flags for Function Set
| Name | Default Value |
|---|---|
| LCD_8BITMODE | 0x10 |
| LCD_4BITMODE | 0x00 |
| LCD_2LINE | 0x08 |
| LCD_1LINE | 0x00 |
| LCD_5x10DOTS | 0x04 |
| LCD_5x8DOTS | 0x00 |
Public Functions
init(uint8_t fourbitmode, uint8_t rs, uint8_t rw, uint8_t enable, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3, uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7)
void init(uint8_t fourbitmode, uint8_t rs, uint8_t rw, uint8_t enable,
uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3,
uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7);
Called from the LiquidCrystal constructors. Typically would not be used in your arduino sketch. However, it is a public function and could be used to change the configuration of the LiquidCrystal object.
begin(uint8_t cols, uint8_t rows, uint8_t charsize = LCD_5x8DOTS)
void begin(uint8_t cols, uint8_t rows, uint8_t charsize = LCD_5x8DOTS);
Sets the number of columns, rows, and character size for a display.
clear()
void clear();
Clear display, set cursor position to zero, and delay for 2000 uS.
home()
void home();
Set cursor position to zero and delays for 2000 uS.
noDisplay()
void noDisplay();
Turn the display off.
display()
void display();
Turn the display on.
noBlink()
void noBlink();
Turn off the blinking cursor.
blink()
void blink();
Turn on the blinking cursor.
noCursor()
void noCursor();
Turns the underline cursor off.
cursor()
void cursor();
Turns the underline cursor on.
scrollDisplayLeft()
void scrollDisplayLeft();
Scroll the display left without changing the RAM.
scrollDisplayRight()
void scrollDisplayRight();
Scroll the display right without changing the RAM.
leftToRight()
void leftToRight();
Sets the direction for text to be written to the LCD to left-to-right (default).
rightToLeft()
void rightToLeft();
Sets the direction for text to be written to the LCD to right-to-left.
autoscroll()
void autoscroll();
noAutoscroll()
void noAutoscroll();
Causes each character entered to appear in the same location. All existing characters are shifted in the direction defined by setting leftToRight() or rightToLeft().
setRowOffsets(int row1, int row2, int row3, int row4)
void setRowOffsets(int row1, int row2, int row3, int row4);
Allows support for non standard LCD displays. Sets the address offset of DDRAM.
createChar(uint8_t, uint8_t[])
void createChar(uint8_t, uint8_t[]);
Allows us to fill the first 8 CGRAM locations with custom characters.
Example Use
#include <LiquidCrystal.h>
LiquidCrystal lcd(12, 11, 5, 4, 3, 2);
// 5x8 Character
byte smiley[8] = {
B00000,
B10001,
B00000,
B00000,
B10001,
B01110,
B00000,
B00000
};
void setup()
{
lcd.createChar(0, smiley);
lcd.begin(16, 2);
lcd.write(0);
}
void loop()
{
}
setCursor(uint8_t, uint8_t)
void setCursor(uint8_t, uint8_t);
write(uint8_t)
virtual size_t write(uint8_t);
command(uint8_t)
void command(uint8_t);
External Links
- github.com/chipKIT32/chipKIT-core/tree/master/pic32/libraries/LiquidCrystal - The github repository for the chipKIT LiquidCrystal Library.
- www.sparkfun.com/datasheets/LCD/HD44780.pdf - HD44780 Controller Manual