will be read-only starting December 31st, 2018. For more info please look at this Forum Post


This API is for character based LCD displays.

This is a recommended API to allow a sketch to use any available connected character based LCD display no matter how it is connected, or who manufactured it, if the library conforms the the base API.

After taking a look at the current state of the LCD displays for the Arduino it quickly became apparent that this is one of the most widely used devices that is commonly connected to the Arduino. They may be connected in many ways: By a 8 bit or 4 bit bus, a shift register, the I2C or SPI bus as well as serially.

Not only are there multiple ways to connect an LCD display to the Arduino, but there are many different libraries to choose from.

The problem arises when you want to share code with someone and they do not have the exact same LCD as you have, or it is wired up to their Arduino differently. The Liquid Crystal library kind of solves this, but that is only for hardwired displays. If you have an I2C or serial display your are out of luck, or have many lines of code to change.

The API is broken down into 3 parts.

  • Mandatory Functions:
    Those functions that must be supported by the display.

  • Optional Functions:
    Those functions that should be supported by the library.
    Not all functions can be supported by all displays.
    Although included in the function they might not do anything.

  • Extend Functions:
    Those functions that are very specific to a display.
    Examples are custom character generation,graphing,keypad, etc.

Current libraries that support the API

LibraryDisplays SupportedVerified APIConnection
hd44780PCF8574/MCP23008 driving hd44780, Raystar RC1602B5-LLH-JWV, Noritake CU165ECBP-T2J, Noritake CU-U Series VFDsY4bit, SPI, i2c
LiquidCrystalGeneric Hitachi HD44780P4, 8 bit
LiquidCrystal_I2CPCF8574 driving HD44780YI2C
LCDi2cNHDNewHaven Display I2C ModeYi2c
ST7036 LibGeneric ST7036 LCD controllerYi2c

If you are converting or creating a library for a display, please download this skeleton library. It has all the commands that need to be supported included.

LCD API 1.0 Specification

Mandatory Functions:

  • LibraryName
    Creates a variable of type LibraryName
    Library specific, as it sets display size, address, pins used, etc
    This is the line that will need to be changed in a sketch as well as the include to switch from one library to the other.

  • init()
    Initializes the display.
    Clears the screen and puts the cursor at 0,0

  • setDelay(Cmd,Char)
    Lets you override the static delays in the library.
    Some displays require delays to allow command to complete
    Typically there are two different delays.
    One for LCD commands, and one when sending characters to the display.
    The library should set the default for the display.

  • print(value)
    Print a value decimal, or string, uses inherited print command
    So things like print(i, DEC) or print(i, BIN) work

  • println(value)
    Same as print, but adds a carriage return

  • write(value)
    Raw Write a value to the display

  • command(value)
    Send a command to the display, for commands not supported by the library

  • clear()
    Clear the display and place cursor at 0,0

  • home()
    Home the cursor to 0,0 and leave displayed characters

  • setCursor(Row,Col)
    Where Row 0-MAXLINEs, and Col 0-MAXCOLUMNS

  • cursor_on()
    Turn the block cursor on

  • cursor_off()
    Turn the block cursor off

  • blink_on()
    Turn on the blinking underline cursor

  • blink_off()
    Turn off the blinking underline cursor

Optional Functions:

Should be included in the library, but might not be functional

  • setBacklight(val)
    Set the backlight off/on, or set Backlight brightness (0-255)
    If the display only has the option to turn the backlight on and off: 0 = off, >0 = on

  • setContrast(val)
    Set the contrast value of the display (0-255)

  • on()
    Turn the LCD display on
    If the display does not have an option to turn on/off just turn backlight on/off

  • off()
    Turn the LCD display off

  • status()
    Return the status of the display
    Returns the FIFO buffer on the robot-electronics display
    Can be used to get r/w status of hardwired displays

Extend Functions:

Things that are specific to a particular display

  • load_custom_character(Char_Num,*Rows)
    Load up a custom character [0-7]
    *Rows is an array of 7 bytes that contain bitmap
    To send custom character to display use lcd.write(0-7);
    See sample sketch on how to implement this.

  • keypad()
    Read value from keypad

  • printstr(Str)
    Print a string without delay.

Only Supported on the display

  • init_bargraph(GraphType)
    Initialize display for a particular type of graph. Where graph type is one of

  • draw_horizontal_graph(Row, Col, Len, End)
  • draw_vertical_graph(Row, Col, Len, End)
    Row, Col = start of graph
    Len is length of graph
    End is bit position of end of graph

Please make comments and suggestion on the forum

See Also