Programming an LCD character display on the Raspberry Pi

This is a guide to programming an LCD module for the Raspberry. The LCD display used here is a HD44780 based 16x2 character display. The module can be connected directly to the Raspberry Pi GPIO ports with just a variable resistor needed to adjust the contrast. I used a mypifi LCD board. The LCD board requires soldering, but provides an easy way to connect and remove the display from the Raspberry Pi.

The board can be mounted directly on the Raspbery Pi or with a bit of alteration can be mounted to a Pimoroni PiBow case.

It's possible to control the LCD display using LCDProc which acts as a service that you can send messages to. LCDProc is useful for say monitoring system status, but I wanted more direct control so I chose to program it directly using Pythong with the RPLCD module which uses Raspberry Pi GPIO module. I've already used the GPIO module in Guide to programming the Raspberry Pi GPIO ports using python. .

The RPiGPIO module is installed by default, but to install the RPLCD module use:
sudo pip install RPLCD
This is now ready to run a program to write to the LCD display.

The easiest way to understand is with a short code example. The following creates a lcd object and shows an example of moving the cursor and sending text to the display.

#!/usr/bin/env python3

import time

import RPi.GPIO as GPIO

from RPLCD import CharLCD





lcd = CharLCD(cols=16, rows=2,

                pin_rw=None,

                pin_rs=7,

                pin_e=8,

                pins_data=[25,24,23,18],

                numbering_mode=GPIO.BCM)



lcd.write_string('PenguinTutor.com')

lcd.cursor_pos = (1, 0)

lcd.write_string('This is line 2')

time.sleep (5)

lcd.cursor_pos = (1, 8)

lcd.write_string('row:')

time.sleep (20);

Create this using a text editor and save it as display.py. This script needs to be run as root (to provide sufficient permissions to access the GPIO port), this is done by running the script through sudo. The first line (known as a shebang) defines this as a python script. This is required if you want to run it from the command line without specifying python each time it is run (as long as appropriate permissions are set on the file to allow execute permission).

With the shebang entry (and execute permission set) then you can run:
sudo ./display.py
Otherwise run using:
sudo python3 display.py

The next three lines are three different ways to import an external module into python so that it's available for use later in the program. The first entry imports the time module, which is included as standard with Python. Without an other options on the import line then we need to refer to anything within the class by prefixing it with 'time.'. For example when we use the sleep function we enter this as time.sleep().

The second import line imports the RPi.GPIO module which is pre-installed in the standard Raspbian image. The full title of the module is RPi.GPIO, but to save typing we import it as though it's just GPIO. So for instance to refer to the BCM constant used to select the numbering mode then instead of entering RPi.GPIO.BCM then we can refer to it as GPIO.BCM.

The third imports the CharLCD elements of the RPLCD module. These can then be referred to as CharLCD (for example the class constructor can be called as CharLCD.

We then create an instance of a CharLCD object called lcd. The parameters included in the arguments define the ports to use which are created based on the BCM GPIO references on the processor (as opposed to the pin number of the GPIO connector).

The entries included in this example code refers to the port numbers used by the mypifi LCD pcb. The defaults used by default int he RPLCD module are: pin_rs=15, pin_rw=18, pin_e=16, pins_data=[21, 22, 23, 24],numbering_mode=GPIO.BOARD .

Now that the object has been created we can use it to send messages to the LCD character display. In this example I have used the two main functions which are cursor_pos (to move the position of the cursor) and write_string (to display some text). The cursor position is entered as (row, column; for example 0,0 would refer to row 0 (top line) position (0,) - although we haven't included this in the code as that is the default position. The first two write_string entries will be run straight away, putting 'PenguinTutor.com' on the first line (0) and 'This is line 2' on the second.
The position (1, 8) is the second row (numbered 1) and the 8th character. You will see that moving the cursor to that position and then writing 'row:' will jsut replace the 4 characters at that position replacing line with row:.

It is not normally neccessary to close the LCD display (as normally the code will continue to run updating the display as appropriate), but if required this can be done using lcd.close(clear=True) which will also clear the screen.

This example has only covered the most basic functions. For more details of the other functions available then see the RPLCD readme.rst available in the module or using this link.

Conclusion

The RPLCD module makes it easier to send messages from the Raspberry Pi to an LCD character display. This guide only shows the most basic functions, but there is more that can be achieved.