RPLCD Documentation

Release 1.3.0

Danilo Bargen

Sep 06, 2021

 Contents

1 About 1

2 Features 3

3 Contents 5
3.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.5 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4 Indices and tables 23

i
ii
 CHAPTER 1

About

RPLCD is a Python 2/3 Raspberry PI Character LCD library for the Hitachi HD44780 controller. It supports both
GPIO (parallel) mode as well as boards with an I2 C port expander (e.g. the PCF8574 or the MCP23008). Furthermore
it can use the pigpio library to control the (remote) LCD.
This library is inspired by Adafruit Industries’ CharLCD library as well as by Arduino’s LiquidCrystal library.
For GPIO mode, no external dependencies (except the RPi.GPIO library, which comes preinstalled on Raspbian) are
needed to use this library. If you want to control LCDs via I2 C, then you also need the python-smbus library. If
you want to control the LCD with pigpio, you have to install the pigpio library.

1
RPLCD Documentation, Release 1.3.0

2 Chapter 1. About
 CHAPTER 2

Features

Already implemented
• Simple to use API
• Support for both 4 bit and 8 bit modes
• Support for parallel (GPIO), I2 C and pigpio connections
• Support for custom characters
• Support for backlight control circuits (including PWM dimming when using the pigpio backend)
• Support for contrast control (when using the pigpio backend)
• Built-in support for A00 and A02 and ST0B character tables
• Python 2/3 compatible
• Caching: Only write characters if they changed
• No external dependencies (except RPi.GPIO, and python-smbus if you need I2 C support)
Wishlist
These things may get implemented in the future, depending on my free time and motivation:
• MicroPython port
Supported I2 C Port Expanders
• PCF8574 (used by a lot of I2 C LCD adapters on Ali Express)
• MCP23008 (used in Adafruit I2 C LCD backpack)
• MCP23017

3
RPLCD Documentation, Release 1.3.0

4 Chapter 2. Features
 CHAPTER 3

Contents

3.1 Installation

3.1.1 From PyPI

You can install RPLCD directly from PyPI using pip:

$ sudo pip install RPLCD

If you want to use I2 C, you also either the smbus or smbus2 library:
$ sudo apt install python-smbus
or
$ sudo pip install smbus2

RPLCD will first try to use smbus if available and if not, fall back to smbus2.
If you want to use pigpio, the easiest way is to install the library via your packet manager (select the Python version
you need):
$ sudo apt-get install pigpio python-pigpio python3-pigpio

3.1.2 Manual Installation

You can also install the library manually without pip. Either just copy the scripts to your working directory and import
them, or download the repository and run python setup.py install to install it into your Python package
directory.

3.2 Getting Started

After you’ve installed RPLCD, you need two more steps to get started: Correct wiring and importing the library.

5
RPLCD Documentation, Release 1.3.0

3.2.1 Wiring

Via I2 C

The wiring is much simpler if you have a LCD module with I2 C support. These boards usually have a “backpack
board” and look similar to this:

The board on this photo has a PCF8574 port expander chip on it. There are also boards with other chips, e.g. the
Adafruit I2 C/SPI LCD Backpack which uses an MCP23008 port expander.
First, connect the pins on the right with the Raspberry Pi:
• GND: Pin 6 (GND)
• VCC: Pin 4 (5V)
• SDA: Pin 3 (SDA)
• SCL: Pin 5 (SCL)
To make things clearer, here’s a little visualization:

6 Chapter 3. Contents
 RPLCD Documentation, Release 1.3.0

Via GPIO

If you don’t have an I2 C version of the board, you can also connect the LCD Pins directly to the GPIO header of the
Raspberry Pi.
If you don’t know how to wire up the LCD to the Raspberry Pi, you could use this example wiring configuration in 4
bit mode (BOARD numbering scheme):
• RS: 15
• RW: 18
• E: 16
• Data 4-7: 21, 22, 23, 24
To make things clearer, here’s a little visualization:

3.2. Getting Started 7

RPLCD Documentation, Release 1.3.0

After wiring up the data pins, you have to connect the voltage input for controller and backlight, and set up the contrast
circuit. As there are some differences regarding the hardware between different modules, please refer to the Adafruit
tutorial to learn how to wire up these circuits.

Via pigpio

If you decide to use the pigpio library to control the LCD, follow the instructions set out above. Please keep in mind
that the pigpio can only use the BCM numbering scheme.
The advantage of using the pigpio library is that you could control the backlight and contrast via PWM. You could
also run the program on one computer (there is no need for this computer to be a Raspberry Pi) and control a LCD on
any Raspberry Pi because pigpio follows a server-client approach. The disadvantage is, that it might be a bit slower
when updating compared to using the GPIO library.

3.2.2 Initializing the LCD

Setup: I2 C

To use an i2c device, the user running the Python script needs write permissions to the i2c device. Under Raspbian,
the pi user already has permissions. If using another username created seperately, assign the group “i2c” to your user.
For example assuming logged in as current user and that user has sudo permissions issue:

sudo usermod -aG i2c $USER

For other platforms take a look at permissions for non-root users

First, import the RPLCD library from your Python script.

from RPLCD.i2c import CharLCD

Then create a new instance of the CharLCD class. For that, you need to know the address of your LCD. You can
find it on the command line using the sudo i2cdetect -y 1 command (or sudo i2cdetect -y 0 on the
original Raspberry Pi). In my case the address of the display was 0x27. You also need to provide the name of the I2 C
port expander that your board uses. It should be written on the microchip that’s soldered on to your board. Supported
port expanders are the PCF8574, the MCP23008 and the MCP23017.

lcd = CharLCD('PCF8574', 0x27)

If you want to customize the way the LCD is instantiated (e.g. by changing the number of columns and rows on your
display or the I2 C port), you can change the corresponding parameters. Example:

lcd = CharLCD(i2c_expander='PCF8574', address=0x27, port=1,

cols=20, rows=4, dotsize=8,
charmap='A02',
auto_linebreaks=True,
backlight_enabled=True)

Setup: GPIO

First, import the RPLCD library from your Python script.

from RPLCD.gpio import CharLCD

8 Chapter 3. Contents
 RPLCD Documentation, Release 1.3.0

Then create a new instance of the CharLCD class. If you have a 20x4 LCD, you must at least specify the numbering
mode and the pins you used:

lcd = CharLCD(pin_rs=15, pin_rw=18, pin_e=16, pins_data=[21, 22, 23, 24],

numbering_mode=GPIO.BOARD)

If you want to customize the way the LCD is instantiated (e.g. by changing the pin configuration or the number of
columns and rows on your display), you can change the corresponding parameters. Here’s a full example:

from RPi import GPIO

lcd = CharLCD(pin_rs=15, pin_rw=18, pin_e=16, pins_data=[21, 22, 23, 24],

numbering_mode=GPIO.BOARD,
cols=20, rows=4, dotsize=8,
charmap='A02',
auto_linebreaks=True)

Setup: pigpio

First, import the the pigpio and RPLCD libraries from your Python script.

import pigpio
from RPLCD.pigpio import CharLCD

Then create a connection to the pigpio daemon

pi = pigpio.pi()

and create a new instance of the CharLCD class. If you have a 20x4 LCD, you must at least specify the previously
initiated pigpio connection and the pins you used:

lcd = CharLCD(pi,
pin_rs=15, pin_rw=18, pin_e=16, pins_data=[21, 22, 23, 24])

If you want to customize the way the LCD is instantiated (e.g. by changing the pin configuration or the number of
columns and rows on your display), you can change the corresponding parameters. Here’s a full example:

import pigpio
from RPLCD.pigpio import CharLCD

pi = pigpio.pi()
lcd = CharLCD(pi,
pin_rs=15, pin_rw=18, pin_e=16, pins_data=[21, 22, 23, 24],
cols=20, rows=4, dotsize=8,
charmap='A02',
auto_linebreaks=True)

Writing Data

Now you can write a string to the LCD:

lcd.write_string('Hello world')

To clean the display, use the clear() method:

3.2. Getting Started 9

RPLCD Documentation, Release 1.3.0

lcd.clear()

You can control line breaks with the newline (\n, moves down 1 line) and carriage return (\r, moves to beginning of
line) characters.

lcd.write_string('Hello\r\n World!')

And you can also set the cursor position directly:

lcd.cursor_pos = (2, 0)

3.3 Usage

Make sure to read the Getting Started section if you haven’t done so yet.

3.3.1 Writing To Display

Regular text can be written to the CharLCD instance using the write_string() method. It accepts unicode
strings (str in Python 3).
The cursor position can be set by assigning a (row, col) tuple to cursor_pos. It can be reset to the starting
position with home().
Line feed characters (\n) move down one line and carriage returns (\r) move to the beginning of the current line.

lcd.write_string('Raspberry Pi HD44780')
lcd.cursor_pos = (2, 0)
lcd.write_string('https://github.com/\n\rdbrgn/RPLCD')

10 Chapter 3. Contents
 RPLCD Documentation, Release 1.3.0

You can also use the convenience functions cr(), lf() and crlf() to write line feed (\n) or carriage return (\r)
characters to the display.

lcd.write_string('Hello')
lcd.crlf()
lcd.write_string('world!')

After your script has finished, you may want to close the connection and optionally clear the screen with the close()
method.

lcd.close(clear=True)

When using a GPIO based LCD, this will reset the GPIO configuration. Note that doing this without clearing can lead
to undesired effects on the LCD, because the GPIO pins are floating (not configured as input or output anymore).

3.3.2 Clearing the Display

You can clear the display by using the clear() method. It will overwrite the data with blank characters and reset
the cursor position.
Alternatively, if you want to hide all characters but keep the data in the LCD memory, set the display_enabled
property to False.

3.3. Usage 11
RPLCD Documentation, Release 1.3.0

3.3.3 Character Maps

RPLCD supports the two most commonly used character maps for HD44780 style displays: A00 and A02. You can
find them on pages 17 and 18 of the datasheet.
Additionally it supports the character map 0B of the ST7066 controller chip.
The default character map is A02. If you find that some of the characters you are writing to the display turn out wrong,
then try using the A00 character map:

lcd = CharLCD(..., charmap='A00')

As a rule of thumb, if your display can show Japanese characters, it uses A00, otherwise A02 or ST0B. To show the
entire character map on your LCD, you can use the show_charmap target of the rplcd-tests script.
Should you run into the situation that your character map does not seem to match either the A00 or the A02 tables,
please open an issue on Github.
The same thing counts if you have a character that should be supported by your character map, but which doesn’t get
written correctly to the display. Let me know by opening an issue!
In case you need a character that is not included in the default device character map, there is a possibility to cre-
ate custom characters and write them into the HD44780 CGRAM. For more information, see the Creating Custom
Characters section.

3.3.4 Creating Custom Characters

The HD44780 supports up to 8 user created characters. A character is defined by a 8x5 bitmap. The bitmap should
be a tuple of 8 numbers, each representing a 5 pixel row. Each character is written to a specific location in CGRAM
(numbers 0-7).

>>> lcd = CharLCD(...)

>>> smiley = (
... 0b00000,
... 0b01010,
... 0b01010,
... 0b00000,
... 0b10001,
... 0b10001,
... 0b01110,
... 0b00000,
... )
>>> lcd.create_char(0, smiley)

To actually show a stored character on the display, you can use hex escape codes with the location number you specified
previously. For example, to write the character at location 3:

>>> lcd.write_string('\x03')

The escape code can also be embedded in a longer string:

>>> lcd.write_string('Hello there \x03')

The following tool can help you to create your custom characters: https://omerk.github.io/lcdchargen/

12 Chapter 3. Contents
 RPLCD Documentation, Release 1.3.0

3.3.5 Changing the Cursor Appearance

The cursor appearance can be changed by setting the cursor_mode property to one of the following three values:
• hide – No cursor will be displayed
• line – The cursor will be indicated with an underline
• blink – The cursor will be indicated with a blinking square

3.3.6 Backlight Control

I2 C

If you’re using an LCD connected through the I2 C bus, you can directly turn on the backlight using the boolean
backlight_enabled property.

GPIO

By setting the pin_backlight parameter in the CharLCD constructor, you can control a backlight circuit.
First of all, you need to build an external circuit to control the backlight, most LCD modules don’t support it directly.
You could do this for example by using a transistor and a pull-up resistor. Then connect the transistor to a GPIO pin
and configure that pin using the pin_backlight parameter in the constructor. If you use an active high circuit
instead of active low, you can change that behavior by setting the backlight_mode to either active_high or
active_low. Now you can toggle the backlight_enabled property to turn the backlight on and off.

pigpio

When using the pigpio library, it is also possible to control the backlight with PWM.
The API is compatible to the backlight control of I2 C and GPIO explained above, but the backlight_enabled
property (and parameter) now also accepts a value between 0 and 1 as a backlight level (0 or False turns the
backlight off, 1 or True turns it on). The perceived brightness of the backlight should roughly correspond to the
given value.
The PWM dimming of the backlight has to be enabled explicitly by setting the backlight_pwm parameter to True
during initialization of CharLCD. If this parameter is False (the default value), the interface only switches the
backlight on and off. If this parameter is a number, dimming of the backlight is enabled and the value is interpreted as
the PWM frequency in Hertz.

3.3.7 Contrast Control

This is currently only possible with the pigpio backend.

pigpio

The API is similar to that controlling the backlight. The pin_contrast specifies the pin connected to the LCDs
contrast input. The contrast_mode can be active_high or active_low and the contrast_pwm sets the
PWM frequency.
The contrast property sets the contrast level. It should be a value between 0 and 1. It is also recognized as a
parameter to CharLCD to set the initial contrast level.

3.3. Usage 13
RPLCD Documentation, Release 1.3.0

If you don’t set the pin_contrast parameter, the contrast control stays disabled.

3.3.8 Automatic Line Breaks

By default, RPLCD tries to automatically insert line breaks where appropriate to achieve (hopefully) intuitive line
wrapping.
Part of these rules is that manual linebreaks (either \r\n or \n\r) that immediately follow an automatically issued
line break are ignored.
If you want more control over line breaks, you can disable the automatic system by setting the auto_linebreaks
parameter of the CharLCD constructor to False.

lcd = CharLCD(..., auto_linebreaks=False)

3.3.9 Scrolling Text

I wrote a blogpost on how to implement scrolling text: https://blog.dbrgn.ch/2014/4/20/scrolling-text-with-rplcd/

To see the result, go to https://www.youtube.com/watch?v=49RkQeiVTGU.

3.3.10 Raw Commands

You can send raw commands to the LCD with command() and write a raw byte to the LCD with write(). For
more information, please refer to the Hitachi HD44780 datasheet.

3.4 Troubleshooting

3.4.1 Compatibility Mode

Not all LCDs are made equal. It appears that some devices (especially those with non-original HD44780 controllers)
don’t run at the reference clock, and as such, are out of specification when it comes to timings.
If you’ve been experiencing issues with garbled text occasionally on initialization/use of the display, try enabling the
compatibility mode by passing compat_mode=True to the CharLCD constructor.

3.4.2 TypeError: this constructor takes no arguments

If you’re getting this error, you are probably importing the CharLCD class the wrong way. If you use parallel
(GPIO) mode, you should use from RPLCD.gpio import CharLCD. If you use I2 C mode, you should use
from RPLCD.i2c import CharLCD.

3.4.3 ValueError: Invalid GPIO numbering mode

Since version 1.0.0, you need to explicitly specify the pin numbering mode. So if you’re getting this error:

ValueError: Invalid GPIO numbering mode: numbering_mode=None, must be

either GPIO.BOARD or GPIO.BCM

14 Chapter 3. Contents
 RPLCD Documentation, Release 1.3.0

...then you need to pass in the numbering_mode explicitly:

import RPi.GPIO as GPIO

# For BOARD numbering

lcd = CharLCD(..., numbering_mode=GPIO.BOARD)

# For BCM numbering

lcd = CharLCD(..., numbering_mode=GPIO.BCM)

The numbering mode is important, if you’re unsure which one to use, search on Google/DuckDuckGo to learn about
the differences between the two numbering modes.

3.5 API

3.5.1 CharLCD (I2 C)

The main class for controlling I2 C connected LCDs.

class RPLCD.i2c.CharLCD(i2c_expander, address, expander_params=None, port=1, cols=20, rows=4,
dotsize=8, charmap=’A02’, auto_linebreaks=True, backlight_enabled=True)
CharLCD via PCF8574 I2C port expander:
Pin mapping:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 D7 | D6 | D5 | D4 | BL | EN | RW | RS
CharLCD via MCP23008 and MCP23017 I2C port expanders:
Adafruit I2C/SPI LCD Backback is supported.
Warning: You might need a level shifter (that supports i2c) between the SCL/SDA connections on the
MCP chip / backpack and the Raspberry Pi. Or you might damage the Pi and possibly any other 3.3V
i2c devices connected on the i2c bus. Or cause reliability issues. The SCL/SDA are rated 0.7*VDD
on the MCP23008, so it needs 3.5V on the SCL/SDA when 5V is applied to drive the LCD.
The MCP23008 and MCP23017 needs to be connected exactly the same way as the backpack.
For complete schematics see the adafruit page at: https://learn.adafruit.com/i2c-spi-lcd-backpack/
4-bit operation. I2C only supported.
Pin mapping:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 BL | D7 | D6 | D5 | D4 | E | RS | -

Parameters
• address (int) – The I2C address of your LCD.
• i2c_expander (string) – Set your I2 C chip type. Supported: “PCF8574”,
“MCP23008”, “MCP23017”.
• expander_params (dictionary) – Parameters for expanders, in a dictionary. Only
needed for MCP23017 gpio_bank - This must be either A or B
If you have a HAT, A is usually marked 1 and B is 2
Example: expander_params={‘gpio_bank’: ‘A’}
• port (int) – The I2C port number. Default: 1.

3.5. API 15
RPLCD Documentation, Release 1.3.0

• cols (int) – Number of columns per row (usually 16 or 20). Default: 20.
• rows (int) – Number of display rows (usually 1, 2 or 4). Default: 4.
• dotsize (int) – Some 1 line displays allow a font height of 10px. Allowed: 8 or 10.
Default: 8.
• charmap (str) – The character map used. Depends on your LCD. This must be either
A00 or A02 or ST0B.
• auto_linebreaks (bool) – Whether or not to automatically insert line breaks. Default:
True.
• backlight_enabled (bool) – Whether the backlight is enabled initially. Default:
True.

backlight_enabled
Whether or not to enable the backlight. Either True or False.
clear()
Overwrite display with blank characters and reset cursor position.
close(clear=False)
command(value)
Send a raw command to the LCD.
cr()
Write a carriage return (\r) character to the LCD.
create_char(location, bitmap)
Create a new character.
The HD44780 supports up to 8 custom characters (location 0-7).
Parameters
• location (int) – The place in memory where the character is stored. Values need to
be integers between 0 and 7.
• bitmap (tuple of int) – The bitmap containing the character. This should be a
tuple of 8 numbers, each representing a 5 pixel row.
Raises AssertionError – Raised when an invalid location is passed in or when bitmap has
an incorrect size.
Example:

>>> smiley = (
... 0b00000,
... 0b01010,
... 0b01010,
... 0b00000,
... 0b10001,
... 0b10001,
... 0b01110,
... 0b00000,
... )
>>> lcd.create_char(0, smiley)

crlf()
Write a line feed and a carriage return (\r\n) character to the LCD.

16 Chapter 3. Contents
 RPLCD Documentation, Release 1.3.0

cursor_mode
How the cursor should behave (hide, line or blink).
cursor_pos
The cursor position as a 2-tuple (row, col).
display_enabled
Whether or not to display any characters.
home()
Set cursor to initial position and reset any shifting.
lf()
Write a line feed (\n) character to the LCD.
shift_display(amount)
Shift the display. Use negative amounts to shift left and positive amounts to shift right.
text_align_mode
The text alignment (left or right).
write(value)
Write a raw byte to the LCD.
write_shift_mode
The shift mode when writing (cursor or display).
write_string(value)
Write the specified unicode string to the display.
To control multiline behavior, use newline (\n) and carriage return (\r) characters.
Lines that are too long automatically continue on next line, as long as auto_linebreaks has not been
disabled.
Make sure that you’re only passing unicode objects to this function. The unicode string is then converted
to the correct LCD encoding by using the charmap specified at instantiation time.
If you’re dealing with bytestrings (the default string type in Python 2), convert it to a unicode object using
the .decode(encoding) method and the appropriate encoding. Example for UTF-8 encoded strings:

>>> bstring = 'Temperature: 30°C'

>>> bstring
'Temperature: 30°C'
>>> bstring.decode('utf-8')
u'Temperature: 30°C'

3.5.2 CharLCD (GPIO)

The main class for controlling GPIO (parallel) connected LCDs.

class RPLCD.gpio.CharLCD(numbering_mode=None, pin_rs=None, pin_rw=None, pin_e=None,
pins_data=None, pin_backlight=None, backlight_mode=’active_low’,
backlight_enabled=True, cols=20, rows=4, dotsize=8, charmap=’A02’,
auto_linebreaks=True, compat_mode=False)
Character LCD controller.
The default pin numbers are based on the BOARD numbering scheme (1-26).
You can save 1 pin by not using RW. Set pin_rw to None if you want this.
Parameters

3.5. API 17
RPLCD Documentation, Release 1.3.0

• pin_rs (int) – Pin for register select (RS). Default: 15.

• pin_rw (int) – Pin for selecting read or write mode (R/W). Set this to None for read only
mode. Default: 18.
• pin_e (int) – Pin to start data read or write (E). Default: 16.
• pins_data (list of int) – List of data bus pins in 8 bit mode (DB0-DB7) or in 4 bit
mode (DB4-DB7) in ascending order. Default: [21, 22, 23, 24].
• pin_backlight (int) – Pin for controlling backlight on/off. Set this to None for no
backlight control. Default: None.
• backlight_mode (str) – Set this to either active_high or active_low to con-
figure the operating control for the backlight. Has no effect if pin_backlight is None
• backlight_enabled (bool) – Whether the backlight is enabled initially. Default:
True. Has no effect if pin_backlight is None
• numbering_mode (int) – Which scheme to use for numbering of the GPIO pins, either
GPIO.BOARD or GPIO.BCM. Default: GPIO.BOARD (1-26).
• rows (int) – Number of display rows (usually 1, 2 or 4). Default: 4.
• cols (int) – Number of columns per row (usually 16 or 20). Default 20.
• dotsize (int) – Some 1 line displays allow a font height of 10px. Allowed: 8 or 10.
Default: 8.
• charmap (str) – The character map used. Depends on your LCD. This must be either
A00 or A02 or ST0B. Default: A02.
• auto_linebreaks (bool) – Whether or not to automatically insert line breaks. Default:
True.
• compat_mode (bool) – Whether to run additional checks to support older LCDs that
may not run at the reference clock (or keep up with it).
backlight_enabled
Whether or not to turn on the backlight.
clear()
Overwrite display with blank characters and reset cursor position.
close(clear=False)
command(value)
Send a raw command to the LCD.
cr()
Write a carriage return (\r) character to the LCD.
create_char(location, bitmap)
Create a new character.
The HD44780 supports up to 8 custom characters (location 0-7).
Parameters
• location (int) – The place in memory where the character is stored. Values need to
be integers between 0 and 7.
• bitmap (tuple of int) – The bitmap containing the character. This should be a
tuple of 8 numbers, each representing a 5 pixel row.

18 Chapter 3. Contents
 RPLCD Documentation, Release 1.3.0

Raises AssertionError – Raised when an invalid location is passed in or when bitmap has
an incorrect size.
Example:

>>> smiley = (
... 0b00000,
... 0b01010,
... 0b01010,
... 0b00000,
... 0b10001,
... 0b10001,
... 0b01110,
... 0b00000,
... )
>>> lcd.create_char(0, smiley)

crlf()
Write a line feed and a carriage return (\r\n) character to the LCD.
cursor_mode
How the cursor should behave (hide, line or blink).
cursor_pos
The cursor position as a 2-tuple (row, col).
display_enabled
Whether or not to display any characters.
home()
Set cursor to initial position and reset any shifting.
lf()
Write a line feed (\n) character to the LCD.
shift_display(amount)
Shift the display. Use negative amounts to shift left and positive amounts to shift right.
text_align_mode
The text alignment (left or right).
write(value)
Write a raw byte to the LCD.
write_shift_mode
The shift mode when writing (cursor or display).
write_string(value)
Write the specified unicode string to the display.
To control multiline behavior, use newline (\n) and carriage return (\r) characters.
Lines that are too long automatically continue on next line, as long as auto_linebreaks has not been
disabled.
Make sure that you’re only passing unicode objects to this function. The unicode string is then converted
to the correct LCD encoding by using the charmap specified at instantiation time.
If you’re dealing with bytestrings (the default string type in Python 2), convert it to a unicode object using
the .decode(encoding) method and the appropriate encoding. Example for UTF-8 encoded strings:

3.5. API 19
RPLCD Documentation, Release 1.3.0

>>> bstring = 'Temperature: 30°C'

>>> bstring
'Temperature: 30°C'
>>> bstring.decode('utf-8')
u'Temperature: 30°C'

3.5.3 CharLCD (pigpio)

The main class for controlling LCDs through pigpio.

class RPLCD.pigpio.CharLCD(pi, pin_rs=None, pin_rw=None, pin_e=None, pin_e2=None,
pins_data=None, pin_backlight=None, backlight_mode=’active_low’,
backlight_pwm=False, backlight_enabled=True, pin_contrast=None,
contrast_mode=’active_high’, contrast_pwm=None, contrast=0.5,
cols=20, rows=4, dotsize=8, charmap=’A02’, auto_linebreaks=True)
Character LCD controller.
The pin numbers are based on the BCM numbering scheme!
You can save 1 pin by not using RW. Set pin_rw to None if you want this.
Parameters
• pi (pigpio.pi object) – A pigpio.pi object to access the GPIOs.
• pin_rs (int) – Pin for register select (RS). Default: 15.
• pin_rw (int) – Pin for selecting read or write mode (R/W). Set this to None for read only
mode. Default: 18.
• pin_e (int) – Pin to start data read or write (E). Default: 16.
• pins_data (list of int) – List of data bus pins in 8 bit mode (DB0-DB7) or in 4 bit
mode (DB4-DB7) in ascending order. Default: [21, 22, 23, 24].
• pin_backlight (int) – Pin for controlling backlight on/off. Set this to None for no
backlight control. Default: None.
• backlight_mode (str) – Set this to either active_high or active_low to con-
figure the operating control for the backlight. Has no effect if pin_backlight is None.
• backlight_pwm (bool or int) – Set this to True, if you want to enable PWM for
the backlight with the default PWM frequency. Set this to the frequency (in Hz) of the PWM
for the backlight or to False to disable PWM for the backlight. Default: False. Has no
effect if pin_backlight is None.
• backlight_enabled (bool or float) – Whether the backlight is enabled initially.
If backlight_pwm is True, this can be a value between 0 and 1, specifying the initial back-
light level. Default: True. Has no effect if pin_backlight is None.
• pin_contrast (int) – Pin for controlling LCD contrast. Set this to None for no contrast
control. Default: None.
• contrast_mode (str) – Set this to either active_high or active_low to config-
ure the operating control for the LCD contrast. Has no effect if pin_contrast is None.
• contrast_pwm (int) – Set this to the frequency (in Hz) of the PWM for the LCD con-
trast if you want to change the default value. Has no effect if pin_contrast is None.
• contrast (float) – A value between 0 and 1, specifying the initial LCD contrast. De-
fault: 0.5. Has no effect if pin_contrast is None

20 Chapter 3. Contents
 RPLCD Documentation, Release 1.3.0

• rows (int) – Number of display rows (usually 1, 2 or 4). Default: 4.

• cols (int) – Number of columns per row (usually 16 or 20). Default 20.
• dotsize (int) – Some 1 line displays allow a font height of 10px. Allowed: 8 or 10.
Default: 8.
• charmap (str) – The character map used. Depends on your LCD. This must be either
A00 or A02 or ST0B. Default: A02.
• auto_linebreaks (bool) – Whether or not to automatically insert line breaks. Default:
True.
backlight_enabled
Turn on/off or set the brightness of the backlight.
clear()
Overwrite display with blank characters and reset cursor position.
close(clear=False)
command(value)
Send a raw command to the LCD.
contrast
Set the LCD contrast.
cr()
Write a carriage return (\r) character to the LCD.
create_char(location, bitmap)
Create a new character.
The HD44780 supports up to 8 custom characters (location 0-7).
Parameters
• location (int) – The place in memory where the character is stored. Values need to
be integers between 0 and 7.
• bitmap (tuple of int) – The bitmap containing the character. This should be a
tuple of 8 numbers, each representing a 5 pixel row.
Raises AssertionError – Raised when an invalid location is passed in or when bitmap has
an incorrect size.
Example:

>>> smiley = (
... 0b00000,
... 0b01010,
... 0b01010,
... 0b00000,
... 0b10001,
... 0b10001,
... 0b01110,
... 0b00000,
... )
>>> lcd.create_char(0, smiley)

crlf()
Write a line feed and a carriage return (\r\n) character to the LCD.

3.5. API 21
RPLCD Documentation, Release 1.3.0

cursor_mode
How the cursor should behave (hide, line or blink).
cursor_pos
The cursor position as a 2-tuple (row, col).
display_enabled
Whether or not to display any characters.
home()
Set cursor to initial position and reset any shifting.
lf()
Write a line feed (\n) character to the LCD.
shift_display(amount)
Shift the display. Use negative amounts to shift left and positive amounts to shift right.
text_align_mode
The text alignment (left or right).
write(value)
Write a raw byte to the LCD.
write_shift_mode
The shift mode when writing (cursor or display).
write_string(value)
Write the specified unicode string to the display.
To control multiline behavior, use newline (\n) and carriage return (\r) characters.
Lines that are too long automatically continue on next line, as long as auto_linebreaks has not been
disabled.
Make sure that you’re only passing unicode objects to this function. The unicode string is then converted
to the correct LCD encoding by using the charmap specified at instantiation time.
If you’re dealing with bytestrings (the default string type in Python 2), convert it to a unicode object using
the .decode(encoding) method and the appropriate encoding. Example for UTF-8 encoded strings:

>>> bstring = 'Temperature: 30°C'

>>> bstring
'Temperature: 30°C'
>>> bstring.decode('utf-8')
u'Temperature: 30°C'

22 Chapter 3. Contents
 CHAPTER 4

Indices and tables

• genindex
• modindex
• search

23
 Index

B display_enabled (RPLCD.pigpio.CharLCD attribute), 22

backlight_enabled (RPLCD.gpio.CharLCD attribute), 18
backlight_enabled (RPLCD.i2c.CharLCD attribute), 16 H
backlight_enabled (RPLCD.pigpio.CharLCD attribute), home() (RPLCD.gpio.CharLCD method), 19
21 home() (RPLCD.i2c.CharLCD method), 17
home() (RPLCD.pigpio.CharLCD method), 22
C
CharLCD (class in RPLCD.gpio), 17 L
CharLCD (class in RPLCD.i2c), 15 lf() (RPLCD.gpio.CharLCD method), 19
CharLCD (class in RPLCD.pigpio), 20 lf() (RPLCD.i2c.CharLCD method), 17
clear() (RPLCD.gpio.CharLCD method), 18 lf() (RPLCD.pigpio.CharLCD method), 22
clear() (RPLCD.i2c.CharLCD method), 16
clear() (RPLCD.pigpio.CharLCD method), 21 S
close() (RPLCD.gpio.CharLCD method), 18 shift_display() (RPLCD.gpio.CharLCD method), 19
close() (RPLCD.i2c.CharLCD method), 16 shift_display() (RPLCD.i2c.CharLCD method), 17
close() (RPLCD.pigpio.CharLCD method), 21 shift_display() (RPLCD.pigpio.CharLCD method), 22
command() (RPLCD.gpio.CharLCD method), 18
command() (RPLCD.i2c.CharLCD method), 16 T
command() (RPLCD.pigpio.CharLCD method), 21
text_align_mode (RPLCD.gpio.CharLCD attribute), 19
contrast (RPLCD.pigpio.CharLCD attribute), 21
text_align_mode (RPLCD.i2c.CharLCD attribute), 17
cr() (RPLCD.gpio.CharLCD method), 18
text_align_mode (RPLCD.pigpio.CharLCD attribute), 22
cr() (RPLCD.i2c.CharLCD method), 16
cr() (RPLCD.pigpio.CharLCD method), 21 W
create_char() (RPLCD.gpio.CharLCD method), 18
create_char() (RPLCD.i2c.CharLCD method), 16 write() (RPLCD.gpio.CharLCD method), 19
create_char() (RPLCD.pigpio.CharLCD method), 21 write() (RPLCD.i2c.CharLCD method), 17
crlf() (RPLCD.gpio.CharLCD method), 19 write() (RPLCD.pigpio.CharLCD method), 22
crlf() (RPLCD.i2c.CharLCD method), 16 write_shift_mode (RPLCD.gpio.CharLCD attribute), 19
crlf() (RPLCD.pigpio.CharLCD method), 21 write_shift_mode (RPLCD.i2c.CharLCD attribute), 17
cursor_mode (RPLCD.gpio.CharLCD attribute), 19 write_shift_mode (RPLCD.pigpio.CharLCD attribute),
cursor_mode (RPLCD.i2c.CharLCD attribute), 16 22
cursor_mode (RPLCD.pigpio.CharLCD attribute), 21 write_string() (RPLCD.gpio.CharLCD method), 19
cursor_pos (RPLCD.gpio.CharLCD attribute), 19 write_string() (RPLCD.i2c.CharLCD method), 17
cursor_pos (RPLCD.i2c.CharLCD attribute), 17 write_string() (RPLCD.pigpio.CharLCD method), 22
cursor_pos (RPLCD.pigpio.CharLCD attribute), 22

D
display_enabled (RPLCD.gpio.CharLCD attribute), 19
display_enabled (RPLCD.i2c.CharLCD attribute), 17

24