chipKIT® Development Platform

Inspired by Arduino™

Last edit: 2021-03-21 22:34 by Majenko

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.

  1. Detailed Introduction

  2. Wiring

    1. LCD Pin Definitions

  3. Introductory Programs

    1. HelloWorld

    2. Scroll

  4. Full library usage

    1. LiquidCrystal

      1. Constructors

        1. LiquidCrystal(uint8_t rs, uint8_t enable, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3);

        2. LiquidCrystal(uint8_t rs, uint8_t rw, uint8_t enable, uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3);

        3. 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)

        4. 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)

      2. Constants

        1. Commands

        2. Flags for Display Entry Mode

        3. Flags for Display On/Off Control

        4. Flags for Display/Cursor Shift

        5. Flags for Function Set

      3. Public Functions

        1. 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)

        2. begin(uint8_t cols, uint8_t rows, uint8_t charsize = LCD_5x8DOTS)

        3. clear()

        4. home()

        5. noDisplay()

        6. display()

        7. noBlink()

        8. blink()

        9. noCursor()

        10. cursor()

        11. scrollDisplayLeft()

        12. scrollDisplayRight()

        13. leftToRight()

        14. rightToLeft()

        15. autoscroll()

        16. noAutoscroll()

        17. setRowOffsets(int row1, int row2, int row3, int row4)

        18. createChar(uint8_t, uint8_t[])

          1. Example Use

        19. setCursor(uint8_t, uint8_t)

        20. write(uint8_t)

        21. command(uint8_t)

  5. External Links

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

400px

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

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