RobotGeek I2C LCD Library

The RobotGeek I2C LCD library is available as a part of the RobotGeek Tools and Libraries (see the Geekduino Getting Started Guide for installation instructions). This Arduino Library is used to control the RobotGeek I2C LCD

The library and examples for the I2C LCD are based off the original Arduino LiquidCrystal library. The original library interfaces the Geekduino directly to the HD44780 chip using 4 digital I/O lines. This library extends the original by interfacing with the PCF8574 on the I2C bus to control the HD44780 chip. This means that the orignal examples and functions are almost identical to the ones in this library.

Basic Operation

The RobotGeekLCD library needs to be included in the sketch like any other library. The Wire library also needs to be included to enable I2C communication.

//include the I2C Wire library - needed for communication with the I2C chip attached to the LCD manual 
#include <Wire.h> 
// include the RobotGeekLCD library
#include <RobotGeekLCD.h>

Once the libraries have been included, an RobotGeekLCD object must be created.

// create a robotgeekLCD object named 'lcd'
RobotGeekLCD lcd;

Before any other functions can be called the LCD must be initialized using the init() function. This function should be called from within the setup() function.

void setup() 
{
  // initialize the lcd object - this sets up all the variables and IIC setup for the LCD object to work
  lcd.init();
}

Now functions can be issued to send data to the display.

void loop() 
{
  lcd.print("Hello, World!");
}

Functions

lcd.init()

Initialize the LCD object. This function will take care of opening an I2C channel to the LCDs address (0x27) as well as initializing the HD44780 chip to control the LCD.

File->Examples->robotgeekLCD->HelloWorld

lcd.clear()

Clears the display and sets the cursor to the (0,0) top left corner.

Example:
File->Examples->robotgeekLCD->AutoScroll

lcd.home()

Moves the cursor to the (0,0) top left corner. This function does not clear or alter the current display.

Example:
File->Examples->robotgeekLCD->TextDirection

lcd.setCursor(int column, int row)

This function allows the user to manually move the cursor. The cursor is where the LCD will start printing characters from. The column and row is zero indexed, meaning the first row will be '0', and the second row will be '1'.

Examples:

lcd.setCursor(0,0); //sets the cursor to the upper left corner - the first row, first column
lcd.setCursor(15,0); //sets the cursor to the upper right corner - the first row, 16th column
lcd.setCursor(0,1); //sets the cursor to the lower left corner - the second row, first column
lcd.setCursor(15,1); //sets the cursor to the lower right corner - the second row, 16th column

File->Examples->robotgeekLCD->Hello World

lcd.display()

Turns the LCD on - any characters previously written to the LCD will appear. The LCD is on by default. NOTE: This does not affect the backlight

Example:
File->Examples->robotgeekLCD->Display

lcd.noDisplay()

Turns the LCD off - all characters will turn blank NOTE: This does not affect the backlight

Example:
File->Examples->robotgeekLCD->Display

lcd.write(data)

Used to write single characters to the display. data can be of type byte or a char.

This function makes it easy to display a variety of custom characters offered by the LCD. Using the decimal numbers from the LCD Special Character Table you can print a variety of symbols and characters beyond the normal ASCII character set.

Additionally, this function can be used to display a character created withcreateChar().

Example:
//two equivalent lines to write a single 'A' ot the display
lcd.write('A');
lcd.write(65);
File->Examples->robotgeekLCD->CustomCharacter
Example:
File->Examples->robotgeekLCD->HelloWorld

lcd.print(data)

Displays data to the LCD. data can be a char, byte, int, long or string.

By default, any message longer than 16 characters will not be displayed, but they will be stored in the display's RAM. Functions like autoscroll() and scrollDisplayLeft() can be used to show these characters.

setCursor() must be used to write data to the second line of display.

Example:
File->Examples->robotgeekLCD->Display

lcd.print(data, BASE)

Displays data to the LCD in base BASE. data can be a char, byte, int, long or string.

  • BIN - Base 2 (binary) display
  • OCT - Base 8 (octal) display
  • DEC - Base 10 (decimal) display - Default
  • HEX - Base 16 (hexadecimal) display

lcd.cursor()

Shows the cursor. The cursor as a underline

Example:
File->Examples->robotgeekLCD->Cursor

lcd.noCursor()

Hides the cursor

Example:
File->Examples->robotgeekLCD->Cursor

lcd.blink()

Blinks the cursor

Example:
File->Examples->robotgeekLCD->Blink

lcd.noBlink()

Stops the cursor from blinking

Example:
File->Examples->robotgeekLCD->Blink

lcd.scrollDisplayRight()

Scrolls the current display to the right. Each character is shifted 1 to the right.

Example:
File->Examples->robotgeekLCD->Scroll

lcd.scrollDisplayLeft()

Scrolls the current display to the right. Each character is shifted 1 to the left.

Example:
File->Examples->robotgeekLCD->Scroll

lcd.leftToRight()

Controls the text flow - each new character is to the right of the last one, makin the text move from left to right. This is the LCD's default behavior

Example:
File->Examples->robotgeekLCD->TextDirection

lcd.rightToLeft()

Controls the text flow - each new character is to the left of the last one, making the text move from right to left.

Example:
File->Examples->robotgeekLCD->TextDirection

lcd.autoscroll()

Enables autoscroll. When autoscroll is enabled, text that goes past the LCD's 16 solums causes the text to automatically shift (as if scrollDisplayLeft() was called)

Example:
File->Examples->robotgeekLCD->Autoscroll

lcd.noAutoscroll()

Disables autoscroll. This is the LCD's default behavior

Example:
File->Examples->robotgeekLCD->Autoscroll

lcd.backlight()

Turns on the LCD's backlight. The backlight is on by default

Example:
File->Examples->robotgeekLCD->Backlight

lcd.noBacklight()

Turns off the LCD's backlight

Example:
File->Examples->robotgeekLCD->Backlight

lcd.createChar(int location, byte[] characterMap)

Loads the byte array characterMap into the custom character slot at location

The Hitachi HD44780 that runs the display is capable of storing up to 8 custom 5*8 bitmap characters. Using the creatChar() function the controller can load a byte array into the HD44780 and then later call it for display.

Only 8 custom characters can be stored at a time (locations - 7), however individual characters can be overwritten.

characterMap is an array of 8-bytes. Each individual byte represents a new row in the character (characterMap[0] is the top row and characterMap[7] is the bottom row).

The lowest 5 bits of each byte represent column in the row(the lowest bit is the right most pixel).

If the bit is set to '1' then the pixel will be active.
If the bit is set to '0' then the pixel will be inactive

The individual bytes can be written in and base (decimal, hex, binary) but binary lends itself nicely to a custom character, as it is possible to visualize what the character will look like.

Below are some examples. A blue square represents a '0', where pixel is off and a white square represents a '1' where the pixel is on, just like the LCD Display
byte blankCharacter[8] = {
  0b00000,
  0b00000,
  0b00000,
  0b00000,
  0b00000,
  0b00000,
  0b00000,
  0b00000
};
b_130_0_16777215_00__images_tutorials_rglcd_blank.png
byte fullCharacter[8] = {
  0b11111,
  0b11111,
  0b11111,
  0b11111,
  0b11111,
  0b11111,
  0b11111,
  0b11111
};
full.png
byte boxCharacter[8] = {
  0b11111,
  0b10001,
  0b10001,
  0b10001,
  0b10001,
  0b10001,
  0b10001,
  0b11111
};
box.png
Example:
File->Examples->robotgeekLCD->CustomCharacter
Custom Character Tools and Resources: