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 then you may wish to take a diversion to this Adafruit tutorial:

If you're using Occidentalis, you can skip this next step, but for Raspbian users, edit /etc/modules (sudo nano /etc/modules) and add:

to the end of the file. Then save and reboot to enable the hardware I2C driver.

Before you can get started with I2C on the Pi, you'll need to run through a couple quick steps from the console.  Just enter the following commands to add SMBus support (which includes I2C) to Python:

Copy Code
sudo apt-get install python-smbus
sudo apt-get install 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:
Copy Code
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"):

Copy Code
sudo apt-get install git
git clone
cd Adafruit-Raspberry-Pi-Python-Code
cd Adafruit_CharLCDPlate
You will also need to install RPi.GPIO, the python library for Pi that allows easy GPIO access. On Raspbian, just run
sudo apt-get install python-dev
sudo apt-get install python-rpi.gpio

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 library file:
Copy Code
sudo python
If you have a rev 2 (512MB) Pi, or if you're not getting anything displaying, it might be due to the I2C bus number change in the Pi hardware. Edit using a command like "nano". Find the "Test code" section near the end of the file, and change the line

lcd = Adafruit_CharLCDPlate()

lcd = Adafruit_CharLCDPlate(busnum = 0)
for a Rev 1 Pi, or to

lcd = Adafruit_CharLCDPlate(busnum = 1)
for a Rev 2 Pi.

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.

Press some buttons!

Now you can press the buttons to see text and color change.

If you have a blue/white monochrome display the backlight will 'turn off' when pressing some buttons because it does not have the other LEDs installed. This is normal! (The library assumes you have an RGB LCD, there's no way for it to detect that it's actually monochrome)

Using the library code

Interfacing with the python example code is fairly easy! Inside the Adafruit_CharLCDPlate folder you'll find a python script. The script does a few things, at the top it imports all the sub-modules. You'll need to have the, and python files to be in the same directory so be sure to copy them to your final destination.

Next it initializes the plate with lcd = Adafruit_CharLCDPlate() - this creates the lcd object and starts communicating with the plate to set up the LCD and buttons

After initialization, you can clear the display with lcd.clear() and write text with lcd.message("text goes here") don't forget that its only 16 characters per line, and it does not automatically wrap lines. To insert a newline use the special '\n' character such as shown in the command: lcd.message("Adafruit RGB LCD\nPlate w/Keypad!")

Next you can set the backlight with lcd.backlight(lcd.COLORNAME) where COLORNAME is RED, YELLOW, GREEN, TEAL, BLUE, VIOLET for RGB LCD's or for monochrome LCDs, just use ON and OFF

Finally, you can ask the plate which buttons are pressed with buttonPressed(lcd.BUTTONNAME) where BUTTONNAME is LEFT RIGHT UP DOWN or SELECT. This is not an interrupt-driven library so you can't have an interrupt go off when a button in pressed, instead you'll have to query the button in a loop.

That's it! If you want to make detailed messages, use the python string formatting commands to create a string and then write that string with message()

Last updated on 2014-04-23 at 06.04.58 PM Published on 2012-11-21 at 07.51.59 PM