API

CharLCD (I²C)

The main class for controlling I²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)[source]

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 I²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.
  • 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.

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'

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)[source]

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:
  • 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 configure 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.
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:

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

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)[source]

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 configure 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 backlight 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 configure 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 contrast 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. Default: 0.5. Has no effect if pin_contrast is None
  • 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.

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'