LCD Display Tutorial for Raspberry Pi

After I posted my Raspberry Pi server room rack temperature monitor project, I received many questions on how to integrate LCD displays with the Pi. This video is the first in a series of tutorials:

Here is the wiring that I used to connect the 16×2 display in 4 bit mode to the Pi. Please note that you can use any 6 GPIO pins.
LCD display wiring
The pin outs of LCD displays can vary as well as the power requirements  for the back light so please check your datasheets.
Some LED back lights can be damaged by running them at 5 V without a resistor.

Here is the formula to determine the proper resistor:  R = (Vdd – VLED) / ILED
R is the resistor value in ohms and Vdd is the supply voltage.  VLED and ILED are the typical LED voltage and current respectively as specified in the LCD display datasheet.  Even if you display supports 5 V you might want to add a resistor or variable resistor to control the brightness.  The same holds true for the contrast pin.  I normally use variable resistors for both (see below).

I’ll demonstrate 2 different Python modules for controlling the LCD display.  The first is a modified version of by Raspberry Pi Spy which can be downloaded below.

Chick UPDATE: super-user privileges are no longer required for GPIO access with the latest version of Raspbian. Therefore, GKSU is unnecessary.  Also Thonny is now the default Python editor instead of Idle.

Here is code to test the module:

import sys
# make sure module is in the path
import lcd
# set cursor to line 1
lcd.lcd_byte(lcd.LCD_LINE_1, lcd.LCD_CMD)
# display text centered on line 1
lcd.lcd_string("Raspberry Pi", 2)
# set cursor to line 2
lcd.lcd_byte(lcd.LCD_LINE_2, lcd.LCD_CMD)
# display additional text on line 2
lcd.lcd_string("Model B+", 2)

You can use any GPIO pins for the LCD RS, E, & D1 – D4. The GPIO to LCD pin mappings are specified in the file.  If you change from the default below then you have to update the file with your new selections.

# Define GPIO to LCD mapping
LCD_RS = 26
LCD_E  = 19
LCD_D4 = 13 
LCD_D5 = 6
LCD_D6 = 5
LCD_D7 = 11

The 2nd Python LCD library is Char_LCD by Adafruit

MegaMan UPDATE:  the Adafruit library is now installed using pip. It is no longer necessary to use git and the paths are automatically set up.

sudo pip install adafruit-charlcd

The Adafruit library has several additional methods.  Please note that their syntax has changed since the video.

# turn display on or off

# turn cursor underline on or off

# turn blinking cursor on or off

# scroll text left or right
move_left()	move_right()

# move cursor to row 1, column 1

# move cursor (zero based, ex: 7,1 would be column 8, row 2)

Here is some sample code (updated 4/23/16) to demonstrate the Adafruit library.  As with the module, you can use any GPIO pins.  You specify the GPIO to LCD pin mappings when you instantiate the Adafruit_CharLCD class.  Please note that super-user privileges are no longer required for GPIO access with the latest version of Raspbian

from time import sleep
from Adafruit_CharLCD import Adafruit_CharLCD

# instantiate lcd and specify pins
lcd = Adafruit_CharLCD(rs=26, en=19,
                       d4=13, d5=6, d6=5, d7=11,
                       cols=16, lines=2)
# display text on LCD display \n = new line
lcd.message('Adafruit CharLCD\n  Raspberry Pi')
# scroll text off display
for x in range(0, 16):
# scroll text on display
for x in range(0, 16):

Contast & Brightness:

A potentiometer can be added to the LCD display C pin to control the contrast.  The pin is connected to the wiper of the pot which is usually the middle pin.  One of the outside pins is connected to ground and the other to Vcc.  It doesn’t matter which outside pin goes to Vcc or ground because the pot is acting as a voltage divider either way.  As the dial is turned the wiper’s pin voltage will vary from 0 to 5 V and this will cause the contrast to change.  10 KΩ is a good value for the pot.  This same wiring will also work to control the LCD display brightness.  Instead of of the contrast pin, the wiper would be connected to the LED back light anode.  Most LCD display back lights will tolerate 5 V but please double check so you don’t damage the LED.  You can alter the 0 – 5 V range by adding a resistor in series with one of the outside pins.  This can help fine tune the amount of range provided by the pot.  You can use a multimeter to measure the voltage on the wiper and determine how different resistors affect the range.  Here is a simple schematic:
LCD Contrast Wiring

IP Clock Example:

The Adafruit IP clock example from the video is no longer compatible with the latest version of the Adafruit LCD_Char library. Here is an updated version of the IP clock program. Please note that sudo is no longer necessary to run the program with the latest version of Raspbian, but you still need the shebang line and chmod +x to give the file executable permissions, if you run it from the command line.

from Adafruit_CharLCD import Adafruit_CharLCD
from time import sleep, strftime
from datetime import datetime
import socket

#  Initialize LCD (must specify pinout and dimensions)
lcd = Adafruit_CharLCD(rs=26, en=19,
                       d4=13, d5=6, d6=5, d7=11,
                       cols=16, lines=2)

def get_ip_address():
    return [
             (s.connect(('', 53)),
              s.close()) for s in
                  [socket.socket(socket.AF_INET, socket.SOCK_DGRAM)]

    while 1:
        ip = get_ip_address()
        lcd.message('%b %d  %H:%M:%S\n'))
        lcd.message('IP {}'.format(ip))
except KeyboardInterrupt:
    print('CTRL-C pressed.  Program exiting...')


IP Clock Example