LCD API 1.0

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.

Background

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.

• 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

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
  Keypad page

• printstr(Str)
  Print a string without delay.

Only Supported on the Web4Robot.com display

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

  LCDI2C_VERTICAL_BAR_GRAPH 1

  LCDI2C_HORIZONTAL_BAR_GRAPH 2

  LCDI2C_HORIZONTAL_LINE_GRAPH 3

• 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

• LCD i2c Libraries
• LCD Keypad function description
• Main Arduino LCD page