HD44780 ======= Introduction ------------ The HD44780 is sufficiently different from the other supported LCD displays to warrant a dedicated page to describe its features (and limitations). .. image:: images/hd44780_clock.jpg It is a very popular LCD display that is widely available, cheap and available in several form factors with 16 character x 2 line and 20 character by 4 line displays the most common. As with most LCD displays, it comes with a backlight which ``luma.lcd`` can control using a GPIO pin. PWM modulation is supported if varying the intensity of the backlight is desired. They are normally connected to SBCs using a parallel 6800-series interface implemented bitbang-style using the SBCs GPIO pins. Alternatively, they are also sold pre-connected to a few different I2C backpacks including the PCF8574, MCP23008 and MCP23017 I2C expanders. .. Note: Currently ``luma.core`` only supports the ``bitbang_6800`` and ``pcf8574`` interfaces Capabilities ------------ The HD44780 is mainly a character-based device and can be purchased with different font tables installed in its ROM. The two most popular are the A00 ROM (English/Japanese) and the A02 ROM (English/European). See :download:`HD44780 ` for details on which characters are included in each. In addition to the built-in characters, HD44780s can have up to eight custom written into their RAM. This feature is used by ``luma.lcd`` to provide a limited graphics capability. Character-mode Usage ~~~~~~~~~~~~~~~~~~~~ When using :py:class:`luma.lcd.device.hd44780` the most common way of controlling the display is to use the `text` property which operates similarly to the :py:class:`luma.core.virtual.sevensegment` wrapper class. To use it, assign the `text` property a string containing the values that you want displayed: .. code:: python from luma.core.interface.parallel import bitbang_6800 from luma.lcd.device import hd44780 interface = bitbang_6800(RS=7, E=8, PINS=[25, 24, 23, 27]) device = hd44780(interface, width=16, height=2) device.text = 'Hello World' The newline character can be used to display characters on the next line of the display: .. code:: python device.text = 'Hello\nWorld' It is the only control character that works however. Other control characters such as carriage return (ascii 13) and line feed (ascii 10) will be silently ignored. .. note: Unlike sevensegment's text property which throws an exception if you exceed the bounds of the display, there is no bounds checking on the displayed text. If you exceed a line boundary it will not wrap to the next line and content below the lowest line on the device will not be displayed. Graphics-mode Usage ~~~~~~~~~~~~~~~~~~~ It is also possible to display graphical content using the `display` method which works similarly to other ``luma.lcd`` and ``luma.oled`` displays. However there is a significant limitation. There can only be 8 characters worth of 'custom' content displayed at any point in time. If you exceed this limit, the ``undefined`` character (a value set during initialization of the hd44780) will be displayed instead. While 8 custom characters may seem limited, with some creativity it can be very useful. To understand how to leverage this capability requires some explanation of how the screen of the display is organized and how ``luma.lcd`` manages the custom character space. Each character position on an HD44780 display is made up of a 5 pixel by 8 pixel grid. When a character is requested to be displayed, the HD44780 looks up the character from its font table and copies the pixels from the font table ROM to the address in RAM that corresponds to the current character position. If there is not a character within the font table that matches what needs to be displayed, a custom character can be created within a small space in the display's RAM that is reserved for this purpose. There are several restrictions that have to be kept in mind though: - The custom character must be a 5x8 image - It can only be displayed in alignment with the other characters on the display - There can be a maximum of 8 special characters on the screen at any given time - If the driver has run out of custom characters for a screen, the remaining cells with non-standard content will display the `undefined` character instead. However there are a few features that can be leveraged to extend beyond these restrictions: - The HD44780 class will automatically create the appropriate custom characters - The content of a special character can be used multiple times on the screen - The content of all of the special characters can be changed every time the screen is redrawn Here is a small example of how this can be leveraged: .. code:: python from luma.core.interface.parallel import bitbang_6800 from luma.lcd.device import hd44780 from luma.core.render import canvas from PIL import Image, ImageDraw interface = bitbang_6800(RS=7, E=8, PINS=[25, 24, 23, 27]) device = hd44780(interface, width=16, height=2) def progress_bar(width, height, percentage): img = Image.new('1', (width, height)) drw = ImageDraw.Draw(img) drw.rectangle((0, 0, width - 1, height - 1), fill='black', outline='white') drw.rectangle((0, 0, width * percentage, height - 1), fill='white', outline='white') return img progress = 0.25 fnt = device.get_font('A00') with canvas(device) as draw: draw.text((5, 0), f'Installing {progress*100:.0f}%', font=fnt, fill='white') draw.bitmap((5, 8), progress_bar(70, 8, progress), fill='white') .. image:: images/hd44780_progress.jpg There are a few of things that deserve highlighting in this code. - The ``get_font`` method of the ``hd44780`` class is used to retrieve the internal font used by the device. This enables us to place exact replicas of the characters within the font tables on the canvas. When these characters are displayed, because they are already normal characters, they do not consume any of the customer character RAM. The ``hd44780`` class contains both the A00 and A02 font tables. You should request the table that matches what is installed in your display. - The progress bar is drawn using normal :mod:`PIL.ImageDraw` primitives in this case a couple of calls to the ``rectangle`` method and a call to the ``text`` method. - The size of the progress bar was carefully chosen. It is 70 pixels wide by 8 pixels high. This will fill 14 characters worth of space. This is because each cell is 5 pixels wide (70/5=14) and it is 8 pixels high (8/8=1). Normally 14 cells worth of graphical content would be a problem. However, the progress bar only requires four custom characters regardless of what position the progress value is set to. To see why that is you need to look at what each cell looks like within the progress bar at each state the progress bar. The different conditions of the progress bar can be expressed in 5 states: .. csv-table:: **CUSTOM CHARACTERS** :header: "First", "Middle", "End" :widths: 20, 20, 20 "Left Empty", "Middle Empty", "Right Empty" "Filling", "Middle Empty", "Right Empty" "Filled", "Filling, Middle Empty", "Right Empty" "Filled", "Filled, Filling, Middle Empty", "Right Empty" "Filled", "Filled", "Right Filling" "Filled", "Filled", "Filled" So the maximum number of custom characters is as little as one, but never exceeds four. - The progress bar was carefully placed to align with the character cell boundaries. If we had placed the progress bar image one pixel to the left if would have consumed two additional custom characters as the beginning and end of the progress bar would be spread across character cell boundaries. In this particular case, it would still have displayed correctly because we would be under the 8 character limit. .. tip:: When displaying text, to avoid using custom character space you should: * Use the internal font installed in your device which can be retrieved using ``get_font`` * Make sure to align the placement of the text to the 5x8 cell structure of the display Good:: draw.text( (5,0), 'Good', fill='white' font=device.get_font('A00')) Bad:: draw.text( (6,1), 'Bad', fill='white' font=device.get_font('A00')) Embedded Font Tables ~~~~~~~~~~~~~~~~~~~~ The :py:class:`luma.lcd.device.hd44780` class leverages :py:mod:`luma.core.bitmap_font` to include two fonts that replicate the two font tables that are commonly available for the hd44780 device. These are: =========== ================== Font Table Font Name =========== ================== A00 English Japanese A02 English European =========== ================== You can retrieve either of these fonts using the ``get_font`` method: .. code:: python fnt = device.get_font('A02') You can also combine fonts together in order to display characters not included within your device's character table. As an example, the 'Black Right-Pointing Triable' symbol ``Unicode U+25b6`` is not contained in the A00 character table but is frequently used as a 'Play' symbol for multi-media systems. It is however included in the A02 font table. We can pull the symbol from A02 and add it to the current embedded font to enable us to use it. .. code:: python fnt = device.get_font('A02') device.font.combine(fnt, '\u25b6') device.text = '\u25b6 Play' This feature leverages the custom character capability so it has the same 8 character limitation. If you exceed 8 characters within a screen, the ``undefined`` character will be used for all additional characters that are not contained within the devices font table. The table for all display characters can be found in the :py:attr:`luma.lcd.const.hd44780.FONTDATA` attribute. See the documentation for :py:mod:`luma.core.bitmap_font` for more information on how to use the ``bitmap_font`` module.