LiquidCrystal Module¶

Since	Origin / Contributor	Maintainer	Source
2019-12-01	Matsievskiy Sergey	Matsievskiy Sergey	liquidcrystal.lua i2c4bit.lua gpio4bit.lua gpio8bit.lua

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, 2) and desktop applications 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)