Adafruit 16x2 Character LCD + Keypad for
Raspberry Pi
Created by lady ada
https://learn.adafruit.com/adafruit-16x2-character-lcd-plus-keypad-for-raspberry-pi
Last updated on 2021-11-15 05:53:18 PM EST
©Adafruit Industries
Page 1 of 27
Table of Contents
Overview
3
Parts List
4
•
•
•
•
•
•
•
•
•
5
5
5
6
6
6
6
6
6
1) Resistors
2) Potentiometer
3) Pushbuttons
4) i2c Port Expander Chip
5) Male Header Pins
6) Printed Circuit Board
7) Raspberry Pi Plate Header
8) Bumper
Additional
Assembly
7
• Model B+ Protection
21
Python Usage
• Python Installation of CharLCD Library
• Python Code
• Full Example Code
23
23
24
25
Python Docs
26
Download
26
©Adafruit Industries
Page 2 of 27
Overview
This new Adafruit plate makes it easy to use a 16x2 Character LCD. We really like the
range of LCDs we stock in the shop, such as our classic blue & white (http://adafru.it/
181) as well as the fancy RGB negative (http://adafru.it/399) and RGB positive (http://
adafru.it/398). Unfortunately, these LCDs do require quite a few digital pins, 6 to
control the LCD and then perhaps another 3 to control the RGB backlight for a total of
9 pins. That's nearly all the GPIO available on a Raspberry Pi!
©Adafruit Industries
Page 3 of 27
With this in mind, we wanted to make it easier for people to get these LCD into their
projects so we devised a Pi plate that lets you control a 16x2 Character LCD, up to 3
backlight pins AND 5 keypad pins using only the two I2C pins on the Pi! The best part
is you don't really lose those two pins either, since you can stick i2c-based sensors,
RTCs, etc and have them share the I2C bus. This is a super slick way to add a display
without all the wiring hassle.
WARNING: The new Raspberry Pi model B+ with 4 USB ports overlaps closely
with backlight resistor leads on the char LCD plate. You will need to cover the
USB port and back of resistors with electrical tape to protect them from
touching. See more details and pictures on the assembly page of this guide.
This plate is perfect for when you want to build a stand-alone project with its own
user interface. The 4 directional buttons plus select button allows basic control
without having to attach a bulky computer.
The kit is designed for any Raspberry Pi - version 1 and 2.
If you want plug in a Cobbler or Gertboard at the same time, check out our Stacking
Header, you can fit an IDC cable over it if the Plate is assembled with this part. (http://
adafru.it/1112)
Parts List
Check to make sure your kit comes with the following parts.Sometimes we make
mistakes so double check everything and email support@adafruit.com if you need
©Adafruit Industries
Page 4 of 27
replacements!
We recently adjusted the kit so the buttons are on the RIGHT side instead of the left.
The parts list is otherwise the same, its just a little more stable than before
1) Resistors
There is a total of 3 resistors in this kit. For resistors labeled RED and BLUE on the
PCB, they are 1/4W 5% 220 ohm resistors (Red, Red, Brown, Gold). For the resistor
labeled GREEN on the PCB, it is a 1/4W 5% 330 ohm resistor (Orange Orange Brown
Gold).
2) Potentiometer
There is one 10k trim potentiometer. This part will go in the spot labeled Contrast
3) Pushbuttons
There are a total of 5 x 6mm tactile switch pushbuttons. These will be used in the UP,
DOWN, LEFT, RIGHT and SELECT locations on the PCB.
©Adafruit Industries
Page 5 of 27
4) i2c Port Expander Chip
There is one of these MCP23017 i2c (16 input/output) port expander chips in the kit.
This is how we are able to only use 2 R-Pi pins to run the entire LCD and buttons. Clic
k here for more info on this chip. (http://adafru.it/732)
5) Male Header Pins
There is one strip of 36 male header pins in the kit. These will be used to attach the
LCD to the PCB.
6) Printed Circuit Board
There will be one PCB in the kit as shown above.
7) Raspberry Pi Plate Header
There will be one extra-tall 26 pin female header for plugging into the Pi
8) Bumper
There will be one rubber bumper as shown above
Additional
You'll also need an LCD to place into the shield.
Your LCD may have 16 pins (Monochrome) or 18 pins (RGB) and may have 2 rows of
connectors or one. This is normal and does not affect the display
©Adafruit Industries
Page 6 of 27
You can also use 16x2 LCDs that are the same size that do not have an RGB backlight,
or have no backlight at all.
We carry Negative type (http://adafru.it/399) or Positive type (http://adafru.it/398)
LCDs as well as Blue and White LCDs (http://adafru.it/181)
Assembly
Check the kit against the parts list to
verify you have all the parts necessary
We recently adjusted the kit so the
buttons are on the right side instead of
the left. The parts list is otherwise the
same, its just a little more stable than
before
©Adafruit Industries
Page 7 of 27
Put the printed circuit board into a vise or
board holder, heat up your soldering iron
and make sure you're ready to go!
We'll start with the first resistor GREEN which has orange, orange, brown, gold
bands on it. This resistor acts as the
backlight control resistor for the green
backlight pin.
Bend the resistor into a 'staple' and slide
it into the slot marked GREEN on the
PCB. Resistors do not have a direction so
you can put it in 'either way' and it'll work
find.
©Adafruit Industries
Page 8 of 27
Bend the 'legs' of the resistor out so it
sits flat against the PCB and flip it over.
This way the resistor won't fall out while
soldering.
With your soldering iron heated up and
ready, solder in both leads of the resistor.
To do this, heat up the round ring pad
and the wire lead at the same time for 2
or 3 seconds, then dip the end of the
solder into the heated joint to melt it in.
Then remove the solder and the
soldering iron.
©Adafruit Industries
Page 9 of 27
Once the soldering is complete, we can
clean up by clipping the leads of the
resistor. This keeps them from shorting to
something else. Use diagonal or flush
cutters to clip the wires right above
where the solder joint ends.
Since you did so great with the first
resistor, we'll place all of the rest now at
the same time.
The two 220 ohm
resistors RED and BLUE - named because
they are the backlight series resistors for
the RGB backlights on the LCDs. These
resistors are colored Red Red Brown
Gold.
©Adafruit Industries
Page 10 of 27
Solder the resistors just like you did with
the first one.
Clip all the leads.
©Adafruit Industries
Page 11 of 27
Next up we will place the buttons. These
buttons are useful to send a signal to the
Pi (say if you have a basic menu system).
We have a 4-way 'direction pad' for up/
down/left/right input and a button to the
right called SELECT. These 5 buttons
should be able to make 'talking' back to
your project easy. These are connected
to the I2C port expander chip so they
require no extra pins on the Pi, our library
does the work of reading whether they
are pressed.
All the buttons are the same, and they
should snap nicely into place. Press
down onto each button until it snaps in
and sits flat against the PCB.
We recently adjusted the kit so the
buttons are on the RIGHT side instead of
the left. The buttons snap in the same but
they're on the right
©Adafruit Industries
Page 12 of 27
Flip over the PCB and check that all the
legs for the buttons are sticking out.
Solder each leg, taking care not to
accidentally 'short' two button legs
together. The ones for the directional
pads are very close!
©Adafruit Industries
Page 13 of 27
Next, place the 10K potentiometer (the
orange-faced thing with three legs) into
the spot above the RESET button. It will
only fit one way. This is the contrast
potentiometer which will adjust how dark
the characters appear. All displays are
slightly different so you'll adjust this once
the display is soldered in.
The kit may come with two
potentiometers - a big blue one for
breadboarding the LCD and a smaller
orange one for the shield kit. You can
throw away or recycle the blue one, use
only the orange one here!
We recently adjusted the kit to have the
potentiometer in the center rather than
the right, goes in the same way, just in
the middle!
Flip over the PCB and solder in the three
legs of the potentiometer
©Adafruit Industries
Page 14 of 27
We're nearly done! Now we will place the
I2C port expander chip. Double check
that it has the MCP23017-E/SP marking
on it. This is a 16-pin expander chip, that
uses the i2c bus. That means you can
send it commands using the i2c pins on
an Pi and control 16 more digital pins! 5
of those pins go to the buttons, 6 go to
the LCD control and 3 are used for the
backlight (the remaining 2 are unused).
Unlike buttons or resistors, chips do have
a direction and the must be put in the
right way! First, use a flat table to
carefully bend the legs of the chip so
they are parallel. Then slip it into the
silkscreened outline so that the notch at
the end of the chip is on the right. Click
the image to the left to make absolutely
sure you've got it in the right way. Once
you are sure, press the chip into place
We recently adjusted the kit so the chip
is more to the left, its the same
alignment, just shifted over
©Adafruit Industries
Page 15 of 27
Flip over the PCB and solder in the 28
pins of the port expander.
Next we will attach the header, there is a
standard 'extra tall' header included in
the kit. However, if you want to attach a
cobbler or GertBoard, etc to the plate,
you may want to opt for one of our
stacking headers, they're extra long so
you can plug in an IDC cable on top!
©Adafruit Industries
Page 16 of 27
Before we solder in the header, remove
the bumper from the backing and attach
it on the underneath so its right over the
Ethernet jack when the PCB is plugged
in.
On kits where the buttons are on the left,
put it right below the contrast pot, as
shown. This will keep the pot from
touching the Ethernet jack.
On kits where the buttons are on the
right, put it right next to the buttons (it
shouldnt overlap any button legs) sitting
flat
Place the 2x13 header onto your Pi, and
slide the plate on top, it should fit
perfectly.
©Adafruit Industries
Page 17 of 27
Now we will solder all 26 pins for the
plate - this will send power and data
between the two boards and also provide
a mechanical stability. You may need to
hold the plate down with tape to get it
sitting flat against the Pi.
Solder in one pin, we suggest the top
right, then check if the plate is sitting flat.
If not, heat up the joint with one hand
while stabilizing with the other until its
right.
Then solder the other 25 pins
©Adafruit Industries
Page 18 of 27
Finally, we place the LCD.
Break off a piece of 18 or 16 pin header
from the stick in the kit.
If you have an RGB display, you'll need
18, for a blue&white you'll need 16
Place the header into the remaining slot
with the long ends of the pins sticking
UP. If you have only 16 pins, leave the
two rightmost pads empty
©Adafruit Industries
Page 19 of 27
Slide the LCD over the header so that it
is perfectly centered over the four holes
and the silkscreen.
Your LCD may have two rows of
connectors or one row. If its a two-rowconnector LCD we do not use the bottom
row, just continue using the LCD as it will
fit just fine!
The LCD should 'snap' in against the
buttons
Solder all the pins!
©Adafruit Industries
Page 20 of 27
Flip over the assembly, carefully. Then
solder in the 16 or 18 pins of header
WARNING: If you're using the new Raspberry Pi model B+ with 4 USB ports you
will need to take some extra steps to ensure the backlight resistor leads do not
touch the USB ports and short out. See the steps below for more details.
Model B+ Protection
With the new Raspberry Pi model B+ and its extra USB ports there's a slight problem
with the layout of the character LCD shield. As you can see in the photo below, the
three through-hole backlight resistors have their leads right above one of the metal
USB ports. Unfortunately these leads are quite close and can potentially short against
the metal USB port.
©Adafruit Industries
Page 21 of 27
There is current limiting in the resistor circuit so it shouldn't damage the Pi if there is a
short, but to be sure it is advised to cover the USB port and resistor leads in a few
layers of electrical tape. Be sure to cut the resistor leads as short as possible with
flush cutters and try to ensure there are no sharp edges from the cut leads or solder.
See the photo below with arrows pointing to the two locations you should place
electrical tape.
Note that if you are using a Raspberry Pi model A or B (i.e. Pi with only 1 or 2 USB
ports) you can skip this step and move on. You only need to add this tape if you're
using a Raspberry Pi model B+, the Pi with 4 USB ports.
©Adafruit Industries
Page 22 of 27
That's it! You're done soldering, now you
just have to run the code in the Usage
section next.
Python Usage
It's easy to use the I2C 16x2 RGB LCD Pi plate with Python and the Adafruit
CircuitPython CharLCD (https://adafru.it/C47) library. This library allows you to easily
write Python code that controls the RGB character LCD.
Assemble the plate as shown in the previous pages and attach to your Pi.
You'll need to set up your Raspberry PI to work with I2C before this will work!
Check out the CircuitPython on Raspberry Pi guide for details: https://
learn.adafruit.com/circuitpython-on-raspberrypi-linux
Python Installation of CharLCD Library
You'll need to install the Adafruit_Blinka library that provides the CircuitPython
support in Python. This will also require enabling I2C on your Raspberry Pi and
verifying you are running Python 3.
Once that's done, from your command line run the following command:
• sudo pip3 install adafruit-circuitpython-charlcd
If your default Python is version 3 you may need to run 'pip' instead. Just make sure
you aren't trying to use CircuitPython on Python 2.x, it isn't supported!
©Adafruit Industries
Page 23 of 27
Python Code
To demonstrate the usage of the character LCD we'll initialize it and display text using
CircuitPython code.
First, you'll need to import necessary modules, initialize the I2C bus, and create an
instance of the character LCD class. Paste the following code into your REPL:
import board
import busio
import adafruit_character_lcd.character_lcd_rgb_i2c as character_lcd
lcd_columns = 16
lcd_rows = 2
i2c = busio.I2C(board.SCL, board.SDA)
lcd = character_lcd.Character_LCD_RGB_I2C(i2c, lcd_columns, lcd_rows)
Now you're ready to start writing text and characters on the display! The usage of the
LCD class is exactly the same as shown in the parallel LCD wiring guide (https://
adafru.it/CVQ). Be sure to check out that guide (https://adafru.it/CVQ) for a complete
discussion of LCD usage.
As a quick test though you can run the following code to use the color property to
set the backlight to red and the message property to write text to the display:
lcd.color = [100, 0, 0]
lcd.message = "Hello\nCircuitPython"
See the parallel LCD guide for more functions you can call to control the LCD! (https:/
/adafru.it/CVQ)
If you don't see anything, adjust the potentiometer on the plate until the message
shows up. The potentiometer is located below the LCD on the side opposite the
buttons.
©Adafruit Industries
Page 24 of 27
That's all there is to using the RGB character LCD Pi Plate with Python and the
Adafruit CircuitPython CharLCD library!
Full Example Code
Save the following file to your Pi and run it to see a demo of some of the different
things the character LCD library has to offer!
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
"""Simple test for I2C RGB character LCD shield kit"""
import time
import board
import adafruit_character_lcd.character_lcd_rgb_i2c as character_lcd
# Modify this if you have a different sized Character LCD
lcd_columns = 16
lcd_rows = 2
# Initialise I2C bus.
i2c = board.I2C() # uses board.SCL and board.SDA
# Initialise the LCD class
lcd = character_lcd.Character_LCD_RGB_I2C(i2c, lcd_columns, lcd_rows)
lcd.clear()
# Set LCD color to red
lcd.color = [100, 0, 0]
time.sleep(1)
# Print two line message
lcd.message = "Hello\nCircuitPython"
# Wait 5s
time.sleep(5)
# Set LCD color to blue
lcd.color = [0, 100, 0]
time.sleep(1)
# Set LCD color to green
lcd.color = [0, 0, 100]
time.sleep(1)
# Set LCD color to purple
lcd.color = [50, 0, 50]
time.sleep(1)
lcd.clear()
# Print two line message right to left
lcd.text_direction = lcd.RIGHT_TO_LEFT
lcd.message = "Hello\nCircuitPython"
# Wait 5s
time.sleep(5)
# Return text direction to left to right
lcd.text_direction = lcd.LEFT_TO_RIGHT
# Display cursor
lcd.clear()
lcd.cursor = True
lcd.message = "Cursor! "
# Wait 5s
time.sleep(5)
# Display blinking cursor
lcd.clear()
lcd.blink = True
lcd.message = "Blinky Cursor!"
# Wait 5s
©Adafruit Industries
Page 25 of 27
time.sleep(5)
lcd.blink = False
lcd.clear()
# Create message to scroll
scroll_msg = "