RPLCD 0.3.0

Implemented

• Simple to use API

• Support for both 4 bit and 8 bit modes

• Support for custom characters

• Python 2/3 compatible

• Caching: Only write characters if they changed

• No external dependencies

Wishlist

These things may get implemented in the future, depending on my free time and motivation:

• I²C support

Writing To Display

Basic text output with multiline control.

>>> from RPLCD import CharLCD
>>> lcd = CharLCD()
>>> lcd.write_string(u'Raspberry Pi HD44780')
>>> lcd.cursor_pos = (2, 0)
>>> lcd.write_string(u'http://github.com/\n\rdbrgn/RPLCD')

Context Managers

Unlike other uses of context managers, these implementations prepare the configuration before writing to the display, but don’t reset it after the block ends.

>>> from RPLCD import CharLCD, cleared, cursor
>>> lcd = CharLCD()
>>>
>>> with cleared(lcd):
>>>     lcd.write_string(u'LCD is cleared.')
>>>
>>> with cursor(lcd, 2, 0):
>>>     lcd.write_string(u'This is he 3rd line.')

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). To actually show a stored character on the display, use unichr() function in combination with the location number you specified previously (e.g. write_string(unichr(2)).

>>> from RPLCD import CharLCD, cleared, cursor
>>> lcd = CharLCD()
>>>
>>> smiley = (
...     0b00000,
...     0b01010,
...     0b01010,
...     0b00000,
...     0b10001,
...     0b10001,
...     0b01110,
...     0b00000,
... )
>>> lcd.create_char(0, smiley)
>>> lcd.write_string(unichr(0))

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

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.

From PyPI

You can install RPLCD directly from PyPI using pip:

$ sudo pip install RPLCD

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.

Init, Setup, Teardown

import RPi.GPIO as GPIO
from RPLCD import CharLCD, BacklightMode

# Initialize display. All values have default values and are therefore
# optional.
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,
              auto_linebreaks=True,
              pin_backlight=None, backlight_enabled=True,
              backlight_mode=BacklightMode.active_low)

...

# If desired, reset the GPIO configuration and optionally clear the screen.
# Note that this can lead to undesired effects on the LCD, because the GPIO
# pins are not configured as input or output anymore.
lcd.close(clear=True)

Properties

• display_enabled -> True / False

• cursor_pos -> (row, col)

• text_align_mode -> Alignment.left / Alignment.right

• write_shift_mode -> ShiftMode.cursor / ShiftMode.display

• cursor_mode -> CursorMode.hide / CursorMode.line / CursorMode.blink

• backlight_enabled -> True / False

High Level Functions

• write_string(value): Write the specified unicode string to the display. You can use newline (\n) and carriage return (\r) characters to control line breaks.

• clear(): Overwrite display with blank characters and reset cursor position.

• home(): Set cursor to initial position and reset any shifting.

• shift_display(amount): Shift the display. Use negative amounts to shift left and positive amounts to shift right.

• create_char(location, bitmap): Write a new character into the CGRAM at the specified location (0-7). See the examples section for more information.

Mid Level Functions

• command(value): Send a raw command to the LCD.

• write(value): Write a raw byte to the LCD.

Context Managers

• cursor(lcd, row, col): Control the cursor position before entering the block.

• cleared(lcd): Clear the display before entering the block.