The backlights will not turn on until you have the code running so don't be alarmed if nothing lights up when you plug in the plate! If you have a 'positive' style LCD, you may see some squares on the first line, that's normal

Setting up your Pi for I2C

For a more basic introduction to setting up I2C on your Pi, take a diversion to this Adafruit tutorial:

It is required to install kernel I2C support before continuing!

You'll also want to run:

sudo apt-get install -y python-smbus
sudo apt-get install -y i2c-tools
i2c-tools isn't strictly required, but it's a useful package since you can use it to scan for any I2C or SMBus devices connected to your board.  If you know something is connected, but you don't know it's 7-bit I2C address, this library has a great little tool to help you find it:
sudo i2cdetect -y 0 #(if you are using a version 1 Raspberry Pi)
sudo i2cdetect -y 1 #(if you are using a version 2 Raspberry Pi)

This will search /dev/i2c-0 or /dev/i2c-1 for all address, and if an Adafruit LCD Plate is connected, it should show up at 0x20

Once both of these packages have been installed, you have everything you need to get started accessing I2C and SMBus devices in Python.

Using the example Python code

The LCD Pi Plate Python code for Pi is available on Github at:

The easiest way to get the code onto your Pi is to hook up an Ethernet cable, and clone it directly using git, which is installed by default on most distros. Simply run the following commands from an appropriate location (ex. /home/pi):

sudo apt-get update
sudo apt-get install -y build-essential python-dev python-smbus python-pip git
sudo pip install RPi.GPIO
git clone
cd Adafruit_Python_CharLCD
sudo python install

Testing the Library

Once the code has be downloaded to an appropriate folder, and you have your LCD Plate properly connected, you can start with the basic demo display, which is run by simply executing the script in the examples folder:
cd examples
sudo python
The example will turn the backlight on to different RGB colors (don't worry if you're using a monochrome backlight LCD, it is normal to see the backlight turn on and off) and then ask you to press buttons. As you press different buttons the button name should be printed and the backlight color changed. Try pressing different buttons to see what happens on the display.

Press Ctrl-C to quit the program.

Adjusting Contrast

The plate uses a character LCD with an external contrast potentiometer. The first time you use it, adjust the potentiometer in the bottom right until you see the text clearly. If you don't upload code to the Pi, some boxes may appear instead, or you may see nothing at all.

Using the library code

Look at the contents of the file to see the basic usage of the character LCD plate class. The basic usage is to import the library and create an instance of the Adafruit_CharLCDPlate class. The char LCD plate class is smart enough to know how to talk to the character LCD plate without any configuration or parameters.

Once you have an instance of the Adafruit_CharLCDPlate class there are a few functions you can call to interact with the display:
  • message(text)
    • Print the provided string message to the display. The text string can include linebreak characters ('\n') and will move to the next line when found in the string.
  • clear()
    • Clear the display and reset the position of message printing to the first column and first line.
  • set_color(red, green, blue)
    • Set the color of the red, green, and blue backlight LEDs. Each color value should be a 1 for on or 0 for off. For example to set a red backlight call set_color(1,0,0) or to set a purple color call set_color(1,0,1).
You can find a more detailed write-up of the library in this character LCD guide (see the Usage and Raspberry Pi Char LCD Plate pages).
This guide was first published on Nov 21, 2012. It was last updated on Oct 16, 2018. This page (Usage) was last updated on Jun 07, 2018.