CircuitPython Usage

It's easy to use the Nokia 5110/3310 LCD with CircuitPython and the Adafruit CircuitPython PCD8544 module. This module allows you to easily write Python code to control the display.

You can use this display with any CircuitPython microcontroller board.

To demonstrate the usage, we'll initialize the library and use Python code to control the LCD from the board's Python REPL.

Initialization

First need to initialize the SPI bus. To do that, run the following commands:

Download: file
import adafruit_pcd8544
import board
import busio
import digitalio

spi = busio.SPI(board.SCK, MOSI=board.MOSI)
dc = digitalio.DigitalInOut(board.D6) # data/command
cs = digitalio.DigitalInOut(board.D5) # Chip select
reset = digitalio.DigitalInOut(board.D9) # reset

display = adafruit_pcd8544.PCD8544(spi, dc, cs, reset)

The last three parameters to the initializer are the pins connected to the display's DCCS, and reset lines in that order.  Again make sure to use the right pin names as you have wired up to your board!

Controlling the Backlight LED

You can control the display backlight LED as well. Just be sure the LED line is wired up to your microcontroller. Just start by initializing it as a DigitalInOut output line. If you wired it to a different output, be sure to change the port accordingly.

Download: file
backlight = digitalio.DigitalInOut(board.D10) # backlight
backlight.switch_to_output()

To turn it on, just set it to True and to turn it off, just set it to False.

Download: file
# Turn Backlight on
backlight.value = True

#Turn Backlight off
backlight.value = False

Contrast and Bias

Two important settings so that you can see what is on the display are the contrast and Bias Settings. Let's start by taking a look at the Bias Setting.

Bias

The Bias setting controls the amount of voltage that goes to the display. The higher the value, the darker the display will be. It's kind of like the brightness setting on a monitor, but will make the pixels more intense. A value of 4-5 is usually pretty good. For example, to set it to 5, you would type:

Download: file
display.bias = 5

Contrast

The contrast setting controls the difference between the dark and light pixels and can be set to anywhere between 0-127. This is like the contrast setting on a monitor. Too high of a value will make everything appear dark and to low of a value will make everything appear too light. A value of around 50-60 seems to look good. For example, to set it to 50, you would type:

Download: file
display.contrast = 50

You may want to play around with different combinations of these values to see what makes your particular display the most readable.

Drawing

The PCD8544 module currently supports a basic set of commands to draw on the display.  You can set individual pixels, fill the screen, and write lines of text. 

To fill or clear the entire screen use the fill function.  This function takes a parameter which specifies the color to fill with, either 0 for white or 1 for black.  For example to fill the screen black:

Download: file
display.fill(1)
display.show()

Notice the fill function doesn't actually change the display.  You must call show after making drawing commands to send the updated pixel data to the display!

To clear the screen to white just call fill again but with the color 0:

Download: file
display.fill(0)
display.show()

To set a pixel use the pixel function.  This function takes the following parameters:

  • Pixel X position
  • Pixel Y position
  • Pixel color (0 = white, 1 = black)

For example to set the first pixel black:

Download: file
display.pixel(0, 0, 1)
display.show()

Try setting other pixels white by changing the X and Y position.  Remember you have to call show after setting pixels to see them appear!

Text

To write text to your display, you must download a font file and copy it to your CIRCUITPY drive. Click the button below to download the file, and then copy font5x8.bin to your CIRCUITPY drive.

You can write a line of text with the text function.  This function takes the following parameters:

  • String of text
  • Text X position
  • Text Y position
  • Text color (0 = white, 1 = black)

For example to clear the screen and then write two lines of text:

Download: file
display.fill(0)
display.text('Hello', 0, 0, 1)
display.text('World', 0, 10, 1)
display.show()

Notice the second line of text starts at Y position 10, this moves it down the display 10 pixels so it's below the first line of text.  The font used by the text function is 8 pixels tall so a size of 10 gives a bit of room between the lines.

Invert

Finally you can invert the display colors with the invert property:

Download: file
display.invert = True

Note that the invert function doesn't need to have show called after it to see the change.

To go back to a non-inverted display run:

Download: file
display.invert = False

That's all there is to drawing on the Nokia 5110/3310 LCD display with CircuitPython!  The drawing functions are basic but provide building blocks for more advanced usage.  For example you can display text with sensor readings or other state, or even program a simple game like pong!

Full Example Code

import time
import board
import busio
import digitalio

import adafruit_pcd8544

# Initialize SPI bus and control pins
spi = busio.SPI(board.SCK, MOSI=board.MOSI)
dc = digitalio.DigitalInOut(board.D6) # data/command
cs = digitalio.DigitalInOut(board.D5) # Chip select
reset = digitalio.DigitalInOut(board.D9) # reset

display = adafruit_pcd8544.PCD8544(spi, dc, cs, reset)

display.bias = 4
display.contrast = 60

# Turn on the Backlight LED
backlight = digitalio.DigitalInOut(board.D10) # backlight
backlight.switch_to_output()
backlight.value = True

print("Pixel test")
# Clear the display.  Always call show after changing pixels to make the display
# update visible!
display.fill(0)
display.show()

# Set a pixel in the origin 0,0 position.
display.pixel(0, 0, 1)
# Set a pixel in the middle position.
display.pixel(display.width//2, display.height//2, 1)
# Set a pixel in the opposite corner position.
display.pixel(display.width-1, display.height-1, 1)
display.show()
time.sleep(2)

print("Lines test")
# we'll draw from corner to corner, lets define all the pair coordinates here
corners = ((0, 0), (0, display.height-1), (display.width-1, 0),
           (display.width-1, display.height-1))

display.fill(0)
for corner_from in corners:
    for corner_to in corners:
        display.line(corner_from[0], corner_from[1],
                     corner_to[0], corner_to[1], 1)
display.show()
time.sleep(2)

print("Rectangle test")
display.fill(0)
w_delta = display.width / 10
h_delta = display.height / 10
for i in range(11):
    display.rect(0, 0, int(w_delta*i), int(h_delta*i), 1)
display.show()
time.sleep(2)

print("Text test")
display.fill(0)
display.text('hello world', 0, 0, 1)
display.text('this is the', 0, 8, 1)
display.text('CircuitPython', 0, 16, 1)
display.text('adafruit lib-', 0, 24, 1)
display.text('rary for the', 0, 32, 1)
display.text('PCD8544! :) ', 0, 40, 1)

display.show()

while True:
    display.invert = True
    time.sleep(0.5)
    display.invert = False
    time.sleep(0.5)
This guide was first published on Dec 17, 2012. It was last updated on Dec 17, 2012. This page (CircuitPython Usage) was last updated on Feb 20, 2020.