diagram.json


# example from Thomas.
# i2c_lcd_Thomascountz_email_example

from machine import Pin, I2C
import utime
from pcf8574 import PCF8574
from hd44780 import HD44780
from lcd import LCD

lcd = None      # pylint: disable=C0103
hd44780 = None  # pylint: disable=C0103


def init_lcd(sda_pin, scl_pin):

    print("Create an I2C object")
    i2c = I2C(1, sda=Pin(sda_pin), scl=Pin(scl_pin), freq=400000)

    print("Create a PCF8574 object")
    pcf8574 = PCF8574(i2c)

    print("Create an HD44780 object")
    hd44780_obj = HD44780(pcf8574, num_lines=2, num_columns=16)

    print("Create an LCD object")
    lcd_obj = LCD(hd44780_obj, pcf8574)

    # run only once:
    print("Clear the display")
    lcd_obj.clear()

    print("Turn on backlight")
    lcd_obj.backlight_on()

    return lcd_obj, hd44780_obj


def write_text_at_pos_clear(text, line, col, delay=0.5):
    # erases the rest of the line
    if isinstance(text, list):
        for word in text:
            hd44780.set_cursor(line, col)
            hd44780.write_string(word)
            utime.sleep(delay)
    else:
        hd44780.write_string(text)


def write_text_at_pos_keep_rest(text, line, col, delay=0):
    # keeps the rest of the line as it was.
    hd44780.set_cursor(line, col)
    for char in text:
        hd44780.write_char(char)  # Cursor "auto-advances"
        if delay > 0:
            utime.sleep(delay)


def main_test():
    global lcd, hd44780
    lcd, hd44780 = init_lcd(6, 7)

    print("Test writing a string to the first line of the LCD")
    lcd.write_line("Hello, world!", 0)
    utime.sleep(3)

    # Ref: https://github.com/Thomascountz/micropython_i2c_lcd/issues/4
    print("Test writing an 8-character string at a specific cursor position")
    greetings = ["friends!", "amigos!", "venner!", "Freunde!", "vrienden!", "YOU!"]
    write_text_at_pos_clear(greetings, line=0, col=7, delay=0.5)

    utime.sleep(2)

    print("Clear the display")
    lcd.clear()

    print("Test writing 8 characters to a specific cursor position one at a time")

    love_upy = "I <3 uPy!"
    write_text_at_pos_keep_rest(love_upy, 0, 7, delay=0.5)
    utime.sleep(2)

    print("Write a string to the first line of the LCD.")
    print("Test if newline is honored")

    lcd.write_line("Hilsner fra\nHolland", 0)
    utime.sleep(1)
    lcd.write_line("Hilsner fra", 0)
    lcd.write_line("Holland", 1)
    utime.sleep(1)

    print("Wait for a while")
    utime.sleep(2)

    print("Test blinking the cursor")
    lcd.reset_cursor(0)
    print("done cursor.reset")
    utime.sleep(2)

    lcd.cursor_on()
    print("done cursor_on")
    utime.sleep(2)

    lcd.blink_on()
    print("done blink.on")
    utime.sleep(2)

    print("Test hiding the cursor")
    lcd.cursor_off()
    print("done cursor_off")
    utime.sleep(2)

    lcd.blink_off()
    print("done blink.off")
    utime.sleep(2)

    print("Test turning off and on the display")
    lcd.display_off()
    print("done display_off")
    utime.sleep(2)

    lcd.display_on()
    print("done display_on")
    utime.sleep(2)

    print("Clear the LCD and put backlight OFF")
    lcd.clear()
    utime.sleep(1)
    lcd.backlight_off()


if __name__ == "__main__":
    try:
        main_test()
    except KeyboardInterrupt:
        lcd.backlight_off()


main.py

from machine import I2C
from hd44780_4bit_payload import HD447804BitPayload
from hd44780_4bit_driver import HD447804BitDriver
from backlight_driver import BacklightDriver


class PCF8574(HD447804BitDriver, BacklightDriver):
    """
    A class for controlling the HD44780 LCD controller through a PCF8574 I/O expander.

    This class implements the HD447804BitController interface, providing methods for
    writing 4-bit payloads to the HD44780 LCD controller via the PCF8574.

    Usage:

    >>> i2c = I2C(0, sda=Pin(0), scl=Pin(1), freq=400000)
    >>> pcf = PCF8574(i2c)
    >>> pcf.write(HD447804BitPayload(e=1, rs=0, rw=0, data=0x0F))

    :param i2c: An instance of the `machine.I2C` class representing the I2C bus.
    :param address: The I2C address of the PCF8574. Defaults to 0x27.
    """

    # PCF8574 device address
    DEFAULT_ADDRESS = 0x27

    # PCF8574 <-> HD44780 byte shifts
    RS_SHIFT = 0  # P0 - Register Select
    RW_SHIFT = 1  # P1 - Read/Write
    ENABLE_SHIFT = 2  # P2 - Enable bit
    DATA_SHIFT = 4  # P4-P7 - Data lines

    # PCF8574 <-> Backlight byte shift
    BACKLIGHT_SHIFT = 3  # P3 - Backlight control

    def __init__(self, i2c: I2C, address: int = DEFAULT_ADDRESS):
        self.i2c = i2c
        self.address = address
        self.backlight = 0  # backlight is initially off

    def write(self, payload: HD447804BitPayload):
        """
        Write a 4-bit payload to the HD44780 LCD controller through the PCF8574.

        This method prepares a byte to be sent to the hardware, consisting of the
        4-bit payload and control signals for the HD44780 LCD controller, and the
        backlight control pin connected to the PCF8574. The byte is then sent to
        the I2C interface.

        :param payload: An instance of the HD447804BitPayload class.
        """

        byte = (
            self.backlight << self.BACKLIGHT_SHIFT
            | payload.e << self.ENABLE_SHIFT
            | payload.rs << self.RS_SHIFT
            | payload.rw << self.RW_SHIFT
            | payload.data << self.DATA_SHIFT
        )
        self._write_byte(byte)

    def backlight_on(self):
        """
        Turn the backlight on.

        This method sets the backlight control pin connected to the PCF8574 to 1.
        This does not effect the state of the HD44780 LCD controller because the
        E pin is not set.
        """
        self.backlight = 1
        self._write_byte(self.backlight << self.BACKLIGHT_SHIFT)

    def backlight_off(self):
        """
        Turn the backlight off.

        This method sets the backlight control pin connected to the PCF8574 to 0.
        This does not effect the state of the HD44780 LCD controller because the
        E pin is not set.
        """
        self.backlight = 0
        self._write_byte(self.backlight << self.BACKLIGHT_SHIFT)

    def _write_byte(self, byte: int):
        """
        Write a byte to the I2C bus.

        This method writes a byte to the I2C bus, using the address of the PCF8574.

        :param byte: The byte to write to the I2C bus.
        """
        # print("Writing byte:  b'{:08b}'".format(byte & 0xFF))
        self.i2c.writeto(self.address, bytes([byte & 0xFF]))


pcf8574.py

from hd44780 import HD44780
from backlight_driver import BacklightDriver
import utime


class LCD:
    """
    A high-level API for controlling HD44780-based LCD displays.

    This class provides methods to write text to the LCD, control the
    cursor and display properties, and clear the display.

    Usage:

    >>> lcd = LCD_Display(hd44780)
    >>> lcd.clear()
    >>> lcd.write_line(0, "Hello, world!")

    :param hd44780: An instance of the `HD44780` class.
    """

    def __init__(self, hd44780: HD44780, backlight_driver: BacklightDriver):
        self.hd44780 = hd44780
        self.backlight_driver = backlight_driver

    def get_hd44780(self):
        """
        Return the underlying HD44780 instance.

        This can be used by advanced users to access the lower-level functions of the HD44780 class.
        """
        return self.hd44780

    def clear(self):
        """
        Clear the LCD display.
        """
        self.hd44780.clear()

    def reset_cursor(self, line: int = 0):
        """
        Move the cursor to the home position.

        :param line: The line number (0-based).
        """
        self.hd44780.set_cursor(line, 0)

    def write_line(self, text: str, line: int = 0):
        """
        Write a string of text to a specific line on the LCD.

        If the string is longer than the number of columns, it will be clipped
        to fit on the line. If the string is shorter than the number of columns,
        the rest of the line will be filled with spaces.

        :param text: The text to write.
        :param line: The line number (0-based).
        """
        self.reset_cursor(line)
        self.hd44780.write_string(text)

    def write_lines(self, text: str):
        """
        Write a string of text to the LCD, split into two lines.

        The string is split at the first '\n' character into two lines. If there
        is no '\n' character, the entire string is written to the first line and
        the second line is cleared.

        If the string contains more than one '\n' character, only the first one
        is used to split the string.

        :param text: The text to write.
        """
        # Split the text into two lines at the first '\n' character
        lines = text.split("\n", 1)

        # Write the first line to the LCD
        self.write_line(lines[0], 0)

        # If there is a second line, write it to the LCD
        if len(lines) > 1:
            self.write_line(lines[1], 1)
        else:
            # If there is no second line, clear the second line on the LCD
            self.write_line("", 1)

    def marquee_text(self, text: str, line: int = 0, delay: float = 0.2):
        """
        Display a line of text as a scrolling marquee on the LCD.

        The text will appear from the right edge of the display and disappear at the left edge. The text will be
        scrolled from right to left by manually updating the visible portion of the text. After the text has
        completely disappeared, it will start again from the right.

        :param text: The text to display.
        :param line: The line number (0-based) on which to display the marquee.
        :param delay: The delay, in seconds, between each step of the marquee. Default is 0.2 seconds.
        """
        # Pad the text with spaces on both sides equal to the width of the display
        text = " " * self.hd44780.num_columns + text + " " * self.hd44780.num_columns

        # Write the visible portion of the text string to the display and update it
        for i in range(len(text) - self.hd44780.num_columns + 1):
            self.reset_cursor(line)
            self.hd44780.write_string(text[i : i + self.hd44780.num_columns])
            utime.sleep(delay)

    def scroll_content_off_screen(self, direction: str = "right", delay: float = 0.2):
        """
        Scroll the current display content off the LCD to the specified edge.

        :param direction: The direction to which to exit the text. Can be 'left' or 'right'.
        :param delay: The delay, in seconds, between each step of the scroll. Default is 0.2 seconds.
        """
        for _ in range(self.hd44780.num_columns):
            if direction == "left":
                self.hd44780.move_left()
            else:
                self.hd44780.move_right()
            utime.sleep(delay)

    def display_on(self):
        """
        Turn on (unblank) the LCD.
        """
        self.hd44780.display_on()

    def display_off(self):
        """
        Turn off (blank) the LCD.
        """
        self.hd44780.display_off()

    def cursor_on(self):
        """
        Make the cursor visible.
        """
        self.hd44780.cursor_on()

    def cursor_off(self):
        """
        Make the cursor invisible.
        """
        self.hd44780.cursor_off()

    def blink_on(self):
        """
        Turn on the cursor blink.
        """
        self.hd44780.blink_on()

    def blink_off(self):
        """
        Turn off the cursor blink.
        """
        self.hd44780.blink_off()

    def backlight_on(self):
        """
        Turn on the LCD backlight.
        """
        self.backlight_driver.backlight_on()

    def backlight_off(self):
        """
        Turn off the LCD backlight.
        """
        self.backlight_driver.backlight_off()


lcd.py

class HD447804BitPayload:
    def __init__(self, e: int, rs: int, rw: int, data: int):
        self.e = e
        self.rs = rs
        self.rw = rw
        self.data = data


hd44780_4bit_payload.py

from hd44780_4bit_payload import HD447804BitPayload


class HD447804BitDriver:
    """
    An interface for controlling the HD44780 LCD controller through a 4-bit data bus.
    """

    def write(self, payload: HD447804BitPayload):
        raise NotImplementedError


hd44780_4bit_driver.py

import utime
from hd44780_4bit_driver import HD447804BitDriver
from hd44780_4bit_payload import HD447804BitPayload


class HD44780:
    """
    A class for interacting with HD44780 LCD drivers through a PCF8574 I/O expander.

    This class provides methods for writing characters and strings to the LCD,
    clearing the display, and controlling the display properties.

    Usage:

    >>> pcf = PCF8574(i2c)
    >>> lcd = HD44780(pcf, num_lines=2, num_columns=16)
    >>> lcd.clear()
    >>> lcd.write_string("Hello, world!")

    :param pcf: An instance of the `PCF8574` class.
    :param num_lines: The number of lines on the LCD.
    :param num_columns: The number of columns on the LCD.
    """

    # HD44780 LCD control command set
    LCD_CLR = 0x01  # DB0: clear display
    LCD_HOME = 0x02  # DB1: return to home position
    LCD_ENTRY_MODE = 0x04  # DB2: set entry mode
    LCD_DISPLAY_CTRL = 0x08  # DB3: display control
    LCD_CURSOR_SHIFT = 0x10  # DB4: cursor shift
    LCD_FUNCTION_SET = 0x20  # DB5: function set
    LCD_SET_CGRAM_ADDR = 0x40  # DB6: set CG RAM address
    LCD_SET_DDRAM_ADDR = 0x80  # DB7: set DD RAM address

    # Flags for display on/off control
    LCD_ON_DISPLAY = 0x04  # DB2: turn display on
    LCD_ON_CURSOR = 0x02  # DB1: turn cursor on
    LCD_ON_BLINK = 0x01  # DB0: turn on cursor blink

    # Flags for display/cursor shift
    LCD_MOVE_DISP = 0x08  # DB3: move display (0-> move cursor)
    LCD_MOVE_RIGHT = 0x04  # DB2: move right (0-> left)

    # Flags for entry mode set
    LCD_ENTRY_INC = 0x02  # DB1: increment (cursor moves to the right)
    LCD_ENTRY_SHIFT = 0x01  # DB0: shift (enable automatic display shift)

    # Flags for function set
    LCD_8_BIT_MODE = 0x10  # DB4: 8-bit data length
    LCD_2_LINE = 0x08  # DB3: two line display
    LCD_5x10_DOTS = 0x04  # DB2: 5x10 dot character font

    def __init__(self, driver: HD447804BitDriver, num_lines: int, num_columns: int):
        self.driver = driver
        self.num_lines = min(num_lines, 4)
        self.num_columns = min(num_columns, 40)
        self.display_control = self.LCD_DISPLAY_CTRL | self.LCD_ON_DISPLAY
        self.entry_mode_set = self.LCD_ENTRY_MODE | self.LCD_ENTRY_INC

        self._initialize()

    def _initialize(self):
        """
        Initialize the LCD in 4-bit mode and clear the display.

        This method performs the initialization sequence for the HD44780 driver
        in 4-bit mode according to the datasheet. The sequence involves switching
        to 8-bit mode first, repeating the 8-bit function set command three times
        (the first two with a delay), then switching to 4-bit mode. After the
        interface length is set, we send the function set command with the number
        of lines and character font size, clear the display, and set the entry mode.

        Time delays are incorporated at several steps in this sequence. These
        delays are necessary because the execution times for these commands are
        longer during the initialization process and we cannot check the busy flag
        during this time (as the interface is in the process of being set up).

        The specific timing values come from the HD44780 datasheet and are based on
        the worst-case times for each command.
        """
        # Wait for more than 40ms after power rises above 2.7V
        utime.sleep_ms(50)

        # Switch to 8-bit mode.
        # This is the first step of the initialization sequence.
        self._write_nibble(0x03)
        # The execution time for this command is longer during initialization,
        # so we wait for more than 4.1ms.
        utime.sleep_ms(5)

        # Repeat the function set command in 8-bit mode.
        self._write_nibble(0x03)
        # Again, the execution time for this command is longer during initialization,
        # so we wait for more than 100us.
        utime.sleep_us(150)

        # Repeat the function set command in 8-bit mode one more time.
        self._write_nibble(0x03)
        # We can use a shorter delay here.
        utime.sleep_ms(1)

        # Switch to 4-bit mode.
        # This is the second step of the initialization sequence.
        self._write_nibble(0x02)
        # We can use a shorter delay here.
        utime.sleep_ms(1)

        # Now that we're in 4-bit mode, we can set the number of display lines and
        # character font size with the function set command.
        # We use the LCD_2_LINE flag if the number of lines is more than one,
        # otherwise we don't set this flag (which defaults to one line).
        self._write_command(
            self.LCD_FUNCTION_SET | (self.LCD_2_LINE if self.num_lines > 1 else 0x00)
        )
        # We can use a shorter delay here.
        utime.sleep_ms(1)

        # Set the display control flags.
        # This command sets the display on/off, cursor on/off, and cursor blink on/off flags.
        # In this case, we're turning the display on and leaving the cursor and blink off.
        self._write_command(self.display_control)

        # Clear the display.
        self.clear()

        # Set the entry mode.
        # This command sets the direction that the cursor moves when we write data to the display.
        # In this case, we're incrementing the address counter (moving the cursor to the right)
        # and we're not shifting the display.
        self._write_command(self.LCD_ENTRY_MODE | self.LCD_ENTRY_INC)

    def _write_nibble(self, nibble: int):
        """
        Write a 4-bit nibble to the LCD.

        param nibble: The 4-bit nibble to write.
        """
        payload = HD447804BitPayload(e=1, rs=0, rw=0, data=nibble)
        self.driver.write(payload)
        payload = HD447804BitPayload(e=0, rs=0, rw=0, data=nibble)
        self.driver.write(payload)

    def _write_byte(self, byte: int, mode: str = "data"):
        """
        Write a byte to the LCD.

        For 4-bit interface data, only four bus lines (DB4 to DB7) are used for transfer.
        Bus lines DB0 to DB3 are disabled. The data transfer between the HD44780 and the
        MPU is completed after the 4-bit data has been transferred twice. As for the order
        of data transfer, the four high order bits (for 8-bit operation, DB4 to DB7) are
        transferred before the four low order bits (for 8-bit operation, DB0 to DB3). The
        busy flag must be checked (one instruction) after the 4-bit data has been
        transferred twice. Two more 4-bit operations then transfer the busy flag and
        address counter data.

        The Register Select (RS) pin selects between data and instruction registers. If
        RS = 0, the instruction register is selected, allowing the user to send a command
        such as Clear Display, Return Cursor to Home, etc. If RS = 1, the data register
        is selected, allowing the user to send data to be displayed on the LCD.

        :param byte: The byte to write.
        :param mode: The mode to write the byte in. Must be "data" or "command".
        """
        if mode == "data":
            rs = 1
        elif mode == "command":
            rs = 0
        else:
            raise ValueError("mode must be 'data' or 'command'")

        # Prepare high order bits and write them
        high_nibble = byte >> 4
        payload_high = HD447804BitPayload(e=1, rs=rs, rw=0, data=high_nibble)
        self.driver.write(payload_high)
        payload_high = HD447804BitPayload(e=0, rs=rs, rw=0, data=high_nibble)
        self.driver.write(payload_high)

        # Prepare low order bits and write them
        low_nibble = byte & 0x0F
        payload_low = HD447804BitPayload(e=1, rs=rs, rw=0, data=low_nibble)
        self.driver.write(payload_low)
        payload_low = HD447804BitPayload(e=0, rs=rs, rw=0, data=low_nibble)
        self.driver.write(payload_low)

        utime.sleep_us(50)  # data needs > 37us to settle

    def _write_command(self, cmd: int):
        """
        Write a command to the LCD.

        :param cmd: The command to write.
        """
        self._write_byte(cmd, mode="command")

    def _write_data(self, data: int):
        """
        Write data to the LCD.

        :param data: The data to write.
        """
        self._write_byte(data, mode="data")

    def clear(self):
        """
        Clear the LCD display and move the cursor to the top left corner.
        """
        self._write_command(self.LCD_CLR)
        self._write_command(self.LCD_HOME)

    def write_char(self, char: str):
        """
        Write a character to the LCD at the current cursor position.

        :param char: The character to write.
        """
        self._write_data(ord(char))

    def write_string(self, text: str):
        """
        Write a string of text to the LCD at the current cursor position.

        If the string is longer than the number of columns, it will be clipped
        to fit on the current line. If the string is shorter than the number of
        columns, the rest of the line will be filled with spaces.

        :param text: The text to write.
        """
        for i in range(self.num_columns):
            if i < len(text):
                self.write_char(text[i])
            else:
                self.write_char(" ")

    def set_cursor(self, line: int, column: int):
        """
        Set the cursor position.

        :param line: The line number (0-based).
        :param column: The column number (0-based).
        """
        self._update_cursor(column, line)

    def _update_cursor(self, cursor_x: int, cursor_y: int):
        """
        Update the cursor position on the LCD.

        :param cursor_x: The column number (0-based).
        :param cursor_y: The line number (0-based).
        """
        addr = cursor_x & 0x3F
        if cursor_y & 1:
            addr += 0x40  # Lines 1 & 3 add 0x40
        if cursor_y & 2:  # Lines 2 & 3 add number of columns
            addr += self.num_columns
        self._write_command(self.LCD_SET_DDRAM_ADDR | addr)

    def display_on(self):
        """
        Turn on (unblank) the LCD.
        """
        self.display_control |= self.LCD_ON_DISPLAY
        self._write_command(self.display_control)

    def display_off(self):
        """
        Turn off (blank) the LCD.
        """
        self.display_control &= ~self.LCD_ON_DISPLAY
        self._write_command(self.display_control)

    def cursor_on(self):
        """
        Make the cursor visible.
        """
        self.display_control |= self.LCD_ON_CURSOR
        self._write_command(self.display_control)

    def cursor_off(self):
        """
        Make the cursor invisible.
        """
        self.display_control &= ~self.LCD_ON_CURSOR
        self._write_command(self.display_control)

    def blink_on(self):
        """
        Turn on the cursor blink.
        """
        self.display_control |= self.LCD_ON_BLINK
        self._write_command(self.display_control)

    def blink_off(self):
        """
        Turn off the cursor blink.
        """
        self.display_control &= ~self.LCD_ON_BLINK
        self._write_command(self.display_control)

    def move_left(self):
        """
        Shift the display to the left without changing the DDRAM content.
        """
        self._write_command(self.LCD_CURSOR_SHIFT | self.LCD_MOVE_DISP)

    def move_right(self):
        """
        Shift the display to the right without changing the DDRAM content.
        """
        self._write_command(
            self.LCD_CURSOR_SHIFT | self.LCD_MOVE_DISP | self.LCD_MOVE_RIGHT
        )

    def auto_scroll_on(self):
        """
        Enable automatic display shift after each character is written.
        """
        self.entry_mode_set |= self.LCD_ENTRY_SHIFT
        self._write_command(self.entry_mode_set)

    def auto_scroll_off(self):
        """
        Disable automatic display shift.
        """
        self.entry_mode_set &= ~self.LCD_ENTRY_SHIFT
        self._write_command(self.entry_mode_set)


hd44780.py

class BacklightDriver:
    """
    An interface for controlling the backlight of an LCD display.
    """

    def backlight_on(self):
        raise NotImplementedError

    def backlight_off(self):
        raise NotImplementedError
