lcd.i2c

lcd.i2c#

Description#

Plugin to write to an LCD display connected via I2C. 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.

Otherwise, 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 operations. I2C only supported.

Pin mapping:

7  | 6  | 5  | 4  | 3  | 2 | 1  | 0
BL | D7 | D6 | D5 | D4 | E | RS | -

Configuration#

lcd.i2c:
  # [Required]
  # Set your I²C chip type. Supported: "PCF8574",
  # "MCP23008", "MCP23017".
  i2c_expander:   # type=str

  # [Required]
  # The I2C address of your LCD.
  address:   # type=int

  # [Optional]
  # 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'}``
  # expander_params:   # type=Optional[dict]

  # [Optional]
  # The I2C port number. Default: ``1``.
  # port: 1  # type=int

  # [Optional]
  # Number of columns per row (usually 16 or 20). Default: ``16``.
  # cols: 16  # type=int

  # [Optional]
  # Number of display rows (usually 1, 2 or 4). Default: ``2``.
  # rows: 2  # type=int

  # [Optional]
  # Whether the backlight is enabled initially.
  # Default: ``True``. Has no effect if pin_backlight is ``None``
  # backlight_enabled: True  # type=bool

  # [Optional]
  # Some 1 line displays allow a font height of 10px.
  # Allowed: ``8`` or ``10``. Default: ``8``.
  # dotsize: 8  # type=int

  # [Optional]
  # The character map used. Depends on your LCD. This must
  # be either ``A00`` or ``A02`` or ``ST0B``. Default: ``A02``.
  # charmap: A02  # type=str

  # [Optional]
  # Whether or not to automatically insert line
  # breaks. Default: ``True``.
  # auto_linebreaks: True  # type=bool

Dependencies#

pip

pip install RPi.GPIO RPLCD

Actions#

Module reference#

class platypush.plugins.lcd.i2c.LcdI2CPlugin(i2c_expander: str, address: int, expander_params: dict | None = None, port: int = 1, cols: int = 16, rows: int = 2, backlight_enabled: bool = True, dotsize: int = 8, charmap: str = 'A02', auto_linebreaks: bool = True, **kwargs)[source]#

Bases: LcdI2cPlugin

__init__(i2c_expander: str, address: int, expander_params: dict | None = None, port: int = 1, cols: int = 16, rows: int = 2, backlight_enabled: bool = True, dotsize: int = 8, charmap: str = 'A02', auto_linebreaks: bool = True, **kwargs)#
Parameters:

  • i2c_expander – Set your I²C chip type. Supported: “PCF8574”, “MCP23008”, “MCP23017”.

  • address – The I2C address of your LCD.

  • expander_params – 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 – The I2C port number. Default: 1.

  • cols – Number of columns per row (usually 16 or 20). Default: 16.

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

  • backlight_enabled – Whether the backlight is enabled initially. Default: True. Has no effect if pin_backlight is None

  • dotsize – Some 1 line displays allow a font height of 10px. Allowed: 8 or 10. Default: 8.

  • charmap – The character map used. Depends on your LCD. This must be either A00 or A02 or ST0B. Default: A02.

  • auto_linebreaks – Whether or not to automatically insert line breaks. Default: True.

clear()#

Clear the LCD display.

close(clear: bool = False)#

Close the handler to the LCD display and release the GPIO resources.

Parameters:

clear – Clear the display as well on close (default: False).

command(value: int)#

Send a raw command to the LCD.

Parameters:

value – Command to be sent.

cr()#

Write a carriage return (\r) character to the LCD.

create_char(location: int, bitmap: List[int])#

Create a new character. The HD44780 supports up to 8 custom characters (location 0-7).

Parameters:

  • location – The place in memory where the character is stored. Values need to be integers between 0 and 7.

  • bitmap – The bitmap containing the character. This should be a list of 8 numbers, each representing a 5 pixel row.

Example for the smiley character:

[
    0,   # 0b00000
    10,  # 0b01010
    10,  # 0b01010
    0,   # 0b00000
    17,  # 0b10001
    17,  # 0b10001
    14,  # 0b01110
    0    # 0b00000
]
crlf()#

Write a carriage return + line feed (\r\n) sequence to the LCD.

disable_backlight()#

Disable the display backlight.

disable_display()#

Turn off the display.

enable_backlight()#

Enable the display backlight.

enable_display()#

Turn on the display.

home()#

Set cursor to initial position and reset any shifting.

lf()#

Write a line feed (\n) character to the LCD.

set_cursor_pos(position: List[int])#

Change the position of the cursor on the display.

Parameters:

position – New cursor position, as a list of two elements.

set_text_align(mode: str)#

Change the text align mode.

Parameters:

mode – Supported values: left, right.

shift_display(amount: int)#

Set cursor to initial position and reset any shifting.

toggle_backlight()#

Toggle the display backlight on/off.

toggle_display()#

Toggle the display state.

write(value: int)#

Write a raw byte to the LCD.

Parameters:

value – Byte to be sent.

write_string(value: str, position: List[int] | None = None)#

Write a string to the display.

Parameters:

  • value – String to be displayed.

  • position – String position on the display as a 2-int list.

class platypush.plugins.lcd.i2c.LcdI2cPlugin(i2c_expander: str, address: int, expander_params: dict | None = None, port: int = 1, cols: int = 16, rows: int = 2, backlight_enabled: bool = True, dotsize: int = 8, charmap: str = 'A02', auto_linebreaks: bool = True, **kwargs)[source]#

Bases: LcdPlugin

Plugin to write to an LCD display connected via I2C. 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.

Otherwise, 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 operations. I2C only supported.

Pin mapping:

7  | 6  | 5  | 4  | 3  | 2 | 1  | 0
BL | D7 | D6 | D5 | D4 | E | RS | -
__init__(i2c_expander: str, address: int, expander_params: dict | None = None, port: int = 1, cols: int = 16, rows: int = 2, backlight_enabled: bool = True, dotsize: int = 8, charmap: str = 'A02', auto_linebreaks: bool = True, **kwargs)[source]#
Parameters:

  • i2c_expander – Set your I²C chip type. Supported: “PCF8574”, “MCP23008”, “MCP23017”.

  • address – The I2C address of your LCD.

  • expander_params – 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 – The I2C port number. Default: 1.

  • cols – Number of columns per row (usually 16 or 20). Default: 16.

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

  • backlight_enabled – Whether the backlight is enabled initially. Default: True. Has no effect if pin_backlight is None

  • dotsize – Some 1 line displays allow a font height of 10px. Allowed: 8 or 10. Default: 8.

  • charmap – The character map used. Depends on your LCD. This must be either A00 or A02 or ST0B. Default: A02.

  • auto_linebreaks – Whether or not to automatically insert line breaks. Default: True.

clear()#

Clear the LCD display.

close(clear: bool = False)#

Close the handler to the LCD display and release the GPIO resources.

Parameters:

clear – Clear the display as well on close (default: False).

command(value: int)#

Send a raw command to the LCD.

Parameters:

value – Command to be sent.

cr()#

Write a carriage return (\r) character to the LCD.

create_char(location: int, bitmap: List[int])#

Create a new character. The HD44780 supports up to 8 custom characters (location 0-7).

Parameters:

  • location – The place in memory where the character is stored. Values need to be integers between 0 and 7.

  • bitmap – The bitmap containing the character. This should be a list of 8 numbers, each representing a 5 pixel row.

Example for the smiley character:

[
    0,   # 0b00000
    10,  # 0b01010
    10,  # 0b01010
    0,   # 0b00000
    17,  # 0b10001
    17,  # 0b10001
    14,  # 0b01110
    0    # 0b00000
]
crlf()#

Write a carriage return + line feed (\r\n) sequence to the LCD.

disable_backlight()#

Disable the display backlight.

disable_display()#

Turn off the display.

enable_backlight()#

Enable the display backlight.

enable_display()#

Turn on the display.

home()#

Set cursor to initial position and reset any shifting.

lf()#

Write a line feed (\n) character to the LCD.

set_cursor_pos(position: List[int])#

Change the position of the cursor on the display.

Parameters:

position – New cursor position, as a list of two elements.

set_text_align(mode: str)#

Change the text align mode.

Parameters:

mode – Supported values: left, right.

shift_display(amount: int)#

Set cursor to initial position and reset any shifting.

toggle_backlight()#

Toggle the display backlight on/off.

toggle_display()#

Toggle the display state.

write(value: int)#

Write a raw byte to the LCD.

Parameters:

value – Byte to be sent.

write_string(value: str, position: List[int] | None = None)#

Write a string to the display.

Parameters:

  • value – String to be displayed.

  • position – String position on the display as a 2-int list.