LiquidCrystal Module

This Lua module provides access to Hitachi HD44780 based LCDs. It supports 4 bit and 8 bit GPIO interface, 4 bit PCF8574 based I²C interface.

!!! note This module requires bit C module built into firmware. Depending on the interface, gpio or i2c module is also required.

Program example

In this example LED screen is connected using I²C GPIO expander. Program defines five custom characters and prints text.

backend_meta = require "lc-i2c4bit"
lc_meta = require "liquidcrystal"

-- create display object
lc = lc_meta(backend_meta{sda=1, scl=2}, false, true, 20)
backend_meta = nil
lc_meta = nil
-- define custom characters
lc:customChar(0, {0,14,31,31,4,4,5,2})
lc:customChar(1, {4,6,5,5,4,12,28,8})
lc:customChar(2, {14,31,17,17,17,17,17,31})
lc:customChar(3, {14,31,17,17,17,17,31,31})
lc:customChar(4, {14,31,17,17,31,31,31,31})
lc:customChar(5, {14,31,31,31,31,31,31,31})
lc:clear() -- clear display
lc:blink(true) -- enable cursor blinking
lc:home() -- reset cursor position
lc:write("hello", " ", "world") -- write string
lc:cursorMove(1, 2) -- move cursor to second line
lc:write("umbrella", 0, 32, "note", 1) -- mix text strings and characters
lc:cursorMove(1, 3)
lc:write("Battery level ", 2, 3, 4, 5)
lc:home()
lc:blink(false)
for i=1,20 do print(lc:read()) end -- read back first line
lc:home()
for _, d in ipairs(lc:readCustom(0)) do print(d) end -- read back umbrella char
for _, d in ipairs(lc:readCustom(1)) do print(d) end -- read back note char

Require

i2c4bit_meta = require("lc-i2c4bit")
gpio4bit_meta = require("lc-gpio4bit")
gpio8bit_meta = require("lc-gpio8bit")
lc_meta = require("liquidcrystal")

Release

package.loaded["lc-i2c4bit"] = nil
package.loaded["lc-gpio4bit"] = nil
package.loaded["lc-gpio8bit"] = nil
package.loaded["liquidcrystal"] = nil

Initialization

Liquidcrystal module is initialized using closure, which takes backend object as an argument.

I²C backend

Loading I²C backend module returns initialization closure. It configures I²C backend and returns backend object.

Syntax

function({[sda=sda_pin] [, scl=scl_pin] [, busid=id] [, busad=address] [, speed = spd] [, rs = rs_pos] [, rw = rw_pos] [, en = en_pos] [, bl = bl_pos] [, d4 = d4_pos] [, d5 = d5_pos] [, d6 = d6_pos] [, d7 = d7_pos]})

!!! note In most cases only sda and scl parameters are required

Parameters

• sda: I²C data pin. If set to nil, I²C bus initialization step via i2c.setup will be skipped
• scl: I²C clock pin. If set to nil, I²C bus initialization step via i2c.setup will be skipped
• busid: I²C bus ID. Defaults to 0
• busad: chip I²C address. Defaults to 0x27 (default PCF8574 address)
• speed: I²C speed. Defaults to i2c.SLOW
• rs: bit position assigned to RS pin in I²C word. Defaults to 0
• rw: bit position assigned to RW pin in I²C word. Defaults to 1
• en: bit position assigned to EN pin in I²C word. Defaults to 2
• bl: bit position assigned to backlight pin in I²C word. Defaults to 3
• d4: bit position assigned to D4 pin in I²C word. Defaults to 4
• d5: bit position assigned to D5 pin in I²C word. Defaults to 5
• d6: bit position assigned to D6 pin in I²C word. Defaults to 6
• d7: bit position assigned to D7 pin in I²C word. Defaults to 7

Returns

• backend object

Example

backend_meta = require "lc-i2c4bit"
backend = backend_meta{sda=1, scl=2 ,speed=i2c.FAST}

GPIO 4 bit backend

Loading GPIO 4 bit backend module returns initialization closure. It configures GPIO 4 bit backend and returns backend object.

Syntax

function({[, rs = rs_pos] [, rw = rw_pos] [, en = en_pos] [, bl = bl_pos] [, d4 = d4_pos] [, d5 = d5_pos] [, d6 = d6_pos] [, d7 = d7_pos]})

Parameters

• rs: GPIO pin connected to RS pin. Defaults to 0
• rw: GPIO pin connected to RW pin. If set to nil then busy, position and readChar functions will not be available. Note that RW pin must be pulled to the ground if not connected to GPIO
• en: GPIO pin connected to EN pin. Defaults to 1
• bl: GPIO pin controlling backlight. It is assumed, that high level turns backlight on, low level turns backlight off. If set to nil then backlight function will not be available
• d4: GPIO pin connected to D4 pin. Defaults to 2
• d5: GPIO pin connected to D5 pin. Defaults to 3
• d6: GPIO pin connected to D6 pin. Defaults to 4
• d7: GPIO pin connected to D7 pin. Defaults to 5

Returns

• backend object

Example

backend_meta = require "lc-gpio4bit"
backend = backend_meta{rs=0, rw=1, en=4, d4=5, d5=6, d6=7, d7=8}

GPIO 8 bit backend

Loading GPIO 8 bit backend module returns initialization closure. It configures GPIO 8 bit backend and returns backend object.

Syntax

function({[, rs = rs_pos] [, rw = rw_pos] [, en = en_pos] [, bl = bl_pos] [, d0 = d0_pos] [, d1 = d1_pos] [, d2 = d2_pos] [, d3 = d3_pos] [, d4 = d4_pos] [, d5 = d5_pos] [, d6 = d6_pos] [, d7 = d7_pos]})

Parameters

• rs: GPIO pin connected to RS pin. Defaults to 0
• rw: GPIO pin connected to RW pin. If set to nil then busy, position and readChar functions will not be available. Note that RW pin must be pulled to the ground if not connected to GPIO
• en: GPIO pin connected to EN pin. Defaults to 1
• bl: GPIO pin controlling backlight. It is assumed, that high level turns backlight on, low level turns backlight off. If set to nil then backlight function will not be available
• d0: GPIO pin connected to D0 pin. Defaults to 2
• d1: GPIO pin connected to D1 pin. Defaults to 3
• d2: GPIO pin connected to D2 pin. Defaults to 4
• d3: GPIO pin connected to D3 pin. Defaults to 5
• d4: GPIO pin connected to D4 pin. Defaults to 6
• d5: GPIO pin connected to D5 pin. Defaults to 7
• d6: GPIO pin connected to D6 pin. Defaults to 8
• d7: GPIO pin connected to D7 pin. Defaults to 9

Returns

• backend object

Example

backend_meta = require "lc-gpio8bit"
backend = backend_meta{rs=15, rw=2, en=5, d0=23, d1=13, d2=33, d3=32, d4=18, d5=19, d6=21, d7=22}

Liquidcrystal initialization

Loading Liquidcrystal module returns initialization closure. It requires backend object and returns LCD object.

Syntax

function(backend, onelinemode, eightdotsmode, column_width)

Parameters

• backend: backend object
• onelinemode: true to use one line mode, false to use two line mode
• eightdotsmode: true to use 5x8 dot font, false to use 5x10 dot font
• column_width: number of characters in column. Used for offset calculations in function cursorMove. If set to nil, functionality of cursorMove will be limited. For most displays column width is 20 characters

Returns

screen object

Example

lc_meta = require "liquidcrystal"
lc = lc_meta(backend, true, true, 20)

liquidcrystal.autoscroll

Autoscroll text when printing. When turned off, cursor moves and text stays still, when turned on, vice versa.

Syntax

liquidcrystal.autoscroll(self, on)

Parameters

• self: liquidcrystal instance
• on: true to turn on, false to turn off

Returns

• sent data

Example

liquidcrystal:autoscroll(true)

liquidcrystal.backlight

Control LCDs backlight. When using GPIO backend without bl argument specification function does nothing.

Syntax

liquidcrystal.backlight(self, on)

Parameters

• self: liquidcrystal instance
• on: true to turn on, false to turn off

Returns

• backlight status

Example

liquidcrystal:backlight(true)

liquidcrystal.blink

Control cursors blink mode.

Syntax

liquidcrystal.blink(self, on)

Parameters

• self: liquidcrystal instance
• on: true to turn on, false to turn off

Returns

• sent data

Example

liquidcrystal:blink(true)

liquidcrystal.busy

Get busy status of the LCD. When using GPIO backend without rw argument specification function does nothing.

!!! note At least some HD44780s and/or interfaces have been observed to count polling the busy flag as grounds for incrementing their position in memory. This is mysterious, but software should restore the position after observing that the busy flag is clear.

Syntax

liquidcrystal.busy(self)

Parameters

• self: liquidcrystal instance

Returns

• true if device is busy, false if device is ready to receive commands

Example

while liquidcrystal:busy() do end

liquidcrystal.clear

Clear LCD screen.

Syntax

liquidcrystal.clear(self)

Parameters

• self: liquidcrystal instance

Returns

• sent data

Example

liquidcrystal:clear()

liquidcrystal.cursorLeft

Move cursor one character to the left.

Syntax

liquidcrystal.cursorLeft(self)

Parameters

• self: liquidcrystal instance

Returns

• sent data

Example

liquidcrystal:cursorLeft()

liquidcrystal.cursorMove

Move cursor to position. If row not specified, move cursor to address col.

!!! note Note that column and row indexes start with 1. However, when omitting row parameter, cursor addresses start with 0.

Syntax

liquidcrystal.cursorMove(self, col, row)

Parameters

• self: liquidcrystal instance
• col: new cursor position column. If row not specified, new cursor position address
• row: new cursor position row or nil

Returns

• sent data

Example

liquidcrystal:cursorMove(5, 1)
liquidcrystal:cursorMove(10, 4)
liquidcrystal:cursorMove(21)

liquidcrystal.cursor

Control cursors highlight mode.

Syntax

liquidcrystal.cursor(self, on)

Parameters

• self: liquidcrystal instance
• on: true to turn on, false to turn off

Returns

• sent data

Example

liquidcrystal:cursor(true)

liquidcrystal.cursorRight

Move cursor one character to the right.

Syntax

liquidcrystal.cursorRight(self)

Parameters

• self: liquidcrystal instance

Returns

• sent data

Example

liquidcrystal:cursorRight()

liquidcrystal.customChar

Define new custom char. Up to 8 custom characters with indexes 0 to 7 may be defined in eight dot mode. They are accessed via write function by index. In ten dot mode only 4 custom characters may be used. They are numbered from 0 to 7 with half of them being aliases to each other (0 to 1, 2 to 3 etc).

!!! note Upon redefinition of a custom character all its instances will be updated automatically.

This function resets cursor position to home if `liquidcrystal.position` function is not available.

There are web services ([1](https://omerk.github.io/lcdchargen/), [2](https://www.quinapalus.com/hd44780udg.html)) and [desktop applications](https://pypi.org/project/lcdchargen/) that help create custom characters.

Syntax

liquidcrystal.customChar(self, index, bytes)

Parameters

• self: liquidcrystal instance
• index: custom char index in range from 0 to 7
• bytes: array of 8 bytes in eight bit mode or 11 bytes in ten bit mode (eleventh line is a cursor line that can also be used) that defines new char bitmap line by line

Returns

nil

Example

liquidcrystal:customChar(5, {14,31,31,31,31,31,31,31})
liquidcrystal:write(5)

liquidcrystal.display

Turn display on and off. Does not affect display backlight. Does not clear the display.

Syntax

liquidcrystal.display(self, on)

Parameters

• self: liquidcrystal instance
• on: true to turn on, false to turn off

Returns

• sent data

Example

liquidcrystal:display(true)

liquidcrystal.home

Reset cursor and screen position.

Syntax

liquidcrystal.home(self)

Parameters

• self: liquidcrystal instance

Returns

• sent data

Example

liquidcrystal:home()

liquidcrystal.leftToRight

Print text left to right (default).

Syntax

liquidcrystal.leftToRight(self)

Parameters

• self: liquidcrystal instance

Returns

• sent data

Example

liquidcrystal:leftToRight()

liquidcrystal.position

Get current position of the cursor. Position is 0 indexed. When using GPIO backend without rw argument specification function does nothing.

!!! note At least some HD44780s and/or interfaces have been observed to count reading the position as grounds for incrementing their position in memory. This is mysterious, but software likely intends to restore the position anyway.

Syntax

liquidcrystal.position(self)

Parameters

• self: liquidcrystal instance

Returns

• 0 indexed position of the cursor

Example

local pos = liquidcrystal:position() -- save position
-- some code
liquidcrystal:cursorMove(pos) -- restore position

liquidcrystal.read

Return current character numerical representation. When using GPIO backend without rw argument specification function does nothing.

Syntax

liquidcrystal.read(self)

Parameters

• self: liquidcrystal instance

Returns

• numerical representation of the current character

Example

liquidcrystal:home() -- goto home
local ch = liquidcrystal:read() -- read char
liquidcrystal:cursorMove(1, 2) -- move to the second line
for i=ch,ch+5 do lc:write(i) end -- print 6 chars starting with ch

liquidcrystal.readCustom

Return custom char byte array. When using GPIO backend without rw argument specification function returns zeros.

Syntax

liquidcrystal.readCustom(self, index)

Parameters

• self: liquidcrystal instance
• index: custom char index in range from 0 to 7

Returns

• table of size 8 in eight dot mode or 11 in ten dot mode. Each 8 bit number represents a character dot line

Example

lc:customChar(0, {0,14,31,31,4,4,5,2}) -- define custom character
for _, d in ipairs(lc:readCustom(0)) do print(d) end -- read it back

liquidcrystal.rightToLeft

Print text right to left.

Syntax

liquidcrystal.rightToLeft(self)

Parameters

• self: liquidcrystal instance

Returns

• sent data

Example

liquidcrystal:rightToLeft()

liquidcrystal.scrollLeft

Move text to the left.

Syntax

liquidcrystal.scrollLeft(self)

Parameters

• self: liquidcrystal instance

Returns

• sent data

Example

liquidcrystal:scrollLeft()

liquidcrystal.scrollRight

Move text to the right.

Syntax

liquidcrystal.scrollRight(self)

Parameters

• self: liquidcrystal instance

Returns

• sent data

Example

liquidcrystal:scrollRight()

liquidcrystal.write

Print text.

Syntax

liquidcrystal.write(self, ...)

Parameters

• self: liquidcrystal instance
• ...: strings or char codes. For the list of available characters refer to HD44780 datasheet

Returns

nil

Example

liquidcrystal:write("hello world")
liquidcrystal:write("hello yourself", "!!!", 243, 244)