LcdDisplay API docs CI

LcdDisplay allows you to control a Hitachi HD44780-compatible Liquid-crystal display (LCD) in Elixir.

For the specification of the HD44780 LCD, please refer to the HD44780 data sheet.



You can install LcdDisplay by adding lcd_display to your list of dependencies in mix.exs:

def deps do
    {:lcd_display, "~> 0.2.0"}


As an example, if you want to control a Hitachi HD44780 type display through the 8-bit I/O expander PCF8574, you can use LcdDisplay.HD44780.PCF8574 module as a display driver.

Start an LCD driver and get a PID

driver_config = %{
  driver_module: LcdDisplay.HD44780.PCF8574,
  i2c_bus: "i2c-1",          # I2C bus name
  i2c_address: 0x27,         # 7-bit address
  rows: 2,                   # the number of display rows
  cols: 16,                  # the number of display columns
  font_size: "5x8"           # "5x10" or "5x8"

{:ok, pid} = LcdDisplay.start_link(driver_config)

The resulting process will be supervised and locally registered under the composite key of the display module and the specified display name.

Many configuration values are optional, falling back to default values. Please refer to each display module documentation.

Run commands

Please refer to the LcdDisplay.HD44780.Driver documentation for supported display commands.

# Print text
LcdDisplay.execute(pid, {:print, "Hello world"})

# Print a character at a time
LcdDisplay.execute(pid, {:print, 0b00110001})
LcdDisplay.execute(pid, {:print, 0b00110000})
LcdDisplay.execute(pid, {:print, 0b00100101})

LcdDisplay.execute(pid, :clear)

Driver modules

Different products out there use different I/O expanders, so please be aware of which I/O expander you are using if you use something like an I2C backpack. Also the pin assignment between the LCD and the I/O expander is important since this library assumes certain pin assignment based on popular products out there.

for parallel I/O

When you connect an LCD standalone directly to the GPIO pins on your target device, the LcdDisplay.HD44780.GPIO driver module is useful.

Here are some relevant products:

for PCF8574-based I2C modules

Many inexpensive I2C modules on uses PCF8574. A pre-assembled 16x2 LCD with I2C module is typically less than US$10. Handson Technology I2C Serial Interface 1602 LCD Module User Guide summarizes the typical specifications of the PCF8574-based I2C module.

for Adafruit I2C / SPI character LCD backpack

The Adafruit i2c / SPI character LCD backpack supports both I2C and SPI interfaces. It uses MCP23008 for I2C and SN74HC595 for SPI as of writing.

for other I/O expanders

It is easy to make your own driver modules in case you want a custom pin assignment, a different I/O expander or some custom features.