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
orB
If you have a HAT, A is usually marked 1 and B is 2Example: 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
orA02
orST0B
. - 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
orFalse
.
-
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
orblink
).
-
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
orright
).
-
write
(value)¶ Write a raw byte to the LCD.
-
write_shift_mode
¶ The shift mode when writing (
cursor
ordisplay
).
-
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
toNone
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
oractive_low
to configure the operating control for the backlight. Has no effect if pin_backlight isNone
- backlight_enabled (bool) – Whether the backlight is enabled initially.
Default:
True
. Has no effect if pin_backlight isNone
- numbering_mode (int) – Which scheme to use for numbering of the GPIO pins,
either
GPIO.BOARD
orGPIO.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
or10
. Default:8
. - charmap (str) – The character map used. Depends on your LCD. This must
be either
A00
orA02
orST0B
. 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
orblink
).
-
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
orright
).
-
write
(value)¶ Write a raw byte to the LCD.
-
write_shift_mode
¶ The shift mode when writing (
cursor
ordisplay
).
-
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'
- pin_rs (int) – Pin for register select (RS). Default:
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
toNone
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
oractive_low
to configure the operating control for the backlight. Has no effect if pin_backlight isNone
. - 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 toFalse
to disable PWM for the backlight. Default:False
. Has no effect if pin_backlight isNone
. - 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 isNone
. - 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
oractive_low
to configure the operating control for the LCD contrast. Has no effect if pin_contrast isNone
. - 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
or10
. Default:8
. - charmap (str) – The character map used. Depends on your LCD. This must
be either
A00
orA02
orST0B
. 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
orblink
).
-
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
orright
).
-
write
(value)¶ Write a raw byte to the LCD.
-
write_shift_mode
¶ The shift mode when writing (
cursor
ordisplay
).
-
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'