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.
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
i2c4bit_meta = require("lc-i2c4bit")
gpio4bit_meta = require("lc-gpio4bit")
gpio8bit_meta = require("lc-gpio8bit")
lc_meta = require("liquidcrystal")
package.loaded["lc-i2c4bit"] = nil
package.loaded["lc-gpio4bit"] = nil
package.loaded["lc-gpio8bit"] = nil
package.loaded["liquidcrystal"] = nil
Liquidcrystal module is initialized using closure, which takes backend object as an argument.
Loading I²C backend module returns initialization closure. It configures I²C backend and returns backend object.
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
sda
: I²C data pin. If set to nil
, I²C bus initialization step via i2c.setup
will be skippedscl
: I²C clock pin. If set to nil
, I²C bus initialization step via i2c.setup
will be skippedbusid
: 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 0rw
: bit position assigned to RW
pin in I²C word. Defaults to 1en
: bit position assigned to EN
pin in I²C word. Defaults to 2bl
: bit position assigned to backlight pin in I²C word. Defaults to 3d4
: bit position assigned to D4
pin in I²C word. Defaults to 4d5
: bit position assigned to D5
pin in I²C word. Defaults to 5d6
: bit position assigned to D6
pin in I²C word. Defaults to 6d7
: bit position assigned to D7
pin in I²C word. Defaults to 7backend_meta = require "lc-i2c4bit"
backend = backend_meta{sda=1, scl=2 ,speed=i2c.FAST}
Loading GPIO 4 bit backend module returns initialization closure. It configures GPIO 4 bit backend and returns backend object.
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]})
rs
: GPIO pin connected to RS
pin. Defaults to 0rw
: 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 GPIOen
: GPIO pin connected to EN
pin. Defaults to 1bl
: 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 availabled4
: GPIO pin connected to D4
pin. Defaults to 2d5
: GPIO pin connected to D5
pin. Defaults to 3d6
: GPIO pin connected to D6
pin. Defaults to 4d7
: GPIO pin connected to D7
pin. Defaults to 5backend_meta = require "lc-gpio4bit"
backend = backend_meta{rs=0, rw=1, en=4, d4=5, d5=6, d6=7, d7=8}
Loading GPIO 8 bit backend module returns initialization closure. It configures GPIO 8 bit backend and returns backend object.
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]})
rs
: GPIO pin connected to RS
pin. Defaults to 0rw
: 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 GPIOen
: GPIO pin connected to EN
pin. Defaults to 1bl
: 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 availabled0
: GPIO pin connected to D0
pin. Defaults to 2d1
: GPIO pin connected to D1
pin. Defaults to 3d2
: GPIO pin connected to D2
pin. Defaults to 4d3
: GPIO pin connected to D3
pin. Defaults to 5d4
: GPIO pin connected to D4
pin. Defaults to 6d5
: GPIO pin connected to D5
pin. Defaults to 7d6
: GPIO pin connected to D6
pin. Defaults to 8d7
: GPIO pin connected to D7
pin. Defaults to 9backend_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}
Loading Liquidcrystal module returns initialization closure. It requires backend object and returns LCD object.
function(backend, onelinemode, eightdotsmode, column_width)
backend
: backend objectonelinemode
: true
to use one line mode, false
to use two line modeeightdotsmode
: true
to use 5x8 dot font, false
to use 5x10 dot fontcolumn_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
charactersscreen object
lc_meta = require "liquidcrystal"
lc = lc_meta(backend, true, true, 20)
Autoscroll text when printing. When turned off, cursor moves and text stays still, when turned on, vice versa.
liquidcrystal.autoscroll(self, on)
self
: liquidcrystal
instanceon
: true
to turn on, false
to turn offliquidcrystal:autoscroll(true)
Control LCDs backlight. When using GPIO backend without bl
argument specification function does nothing.
liquidcrystal.backlight(self, on)
self
: liquidcrystal
instanceon
: true
to turn on, false
to turn offliquidcrystal:backlight(true)
Control cursors blink mode.
liquidcrystal.blink(self, on)
self
: liquidcrystal
instanceon
: true
to turn on, false
to turn offliquidcrystal:blink(true)
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.
liquidcrystal.busy(self)
self
: liquidcrystal
instancetrue
if device is busy, false
if device is ready to receive commandswhile liquidcrystal:busy() do end
Clear LCD screen.
liquidcrystal.clear(self)
self
: liquidcrystal
instanceliquidcrystal:clear()
Move cursor one character to the left.
liquidcrystal.cursorLeft(self)
self
: liquidcrystal
instanceliquidcrystal:cursorLeft()
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.
liquidcrystal.cursorMove(self, col, row)
self
: liquidcrystal
instancecol
: new cursor position column. If row
not specified, new cursor position addressrow
: new cursor position row or nil
liquidcrystal:cursorMove(5, 1)
liquidcrystal:cursorMove(10, 4)
liquidcrystal:cursorMove(21)
Control cursors highlight mode.
liquidcrystal.cursor(self, on)
self
: liquidcrystal
instanceon
: true
to turn on, false
to turn offliquidcrystal:cursor(true)
Move cursor one character to the right.
liquidcrystal.cursorRight(self)
self
: liquidcrystal
instanceliquidcrystal:cursorRight()
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.
liquidcrystal.customChar(self, index, bytes)
self
: liquidcrystal
instanceindex
: custom char index in range from 0 to 7bytes
: 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 linenil
liquidcrystal:customChar(5, {14,31,31,31,31,31,31,31})
liquidcrystal:write(5)
Turn display on and off. Does not affect display backlight. Does not clear the display.
liquidcrystal.display(self, on)
self
: liquidcrystal
instanceon
: true
to turn on, false
to turn offliquidcrystal:display(true)
Reset cursor and screen position.
liquidcrystal.home(self)
self
: liquidcrystal
instanceliquidcrystal:home()
Print text left to right (default).
liquidcrystal.leftToRight(self)
self
: liquidcrystal
instanceliquidcrystal:leftToRight()
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.
liquidcrystal.position(self)
self
: liquidcrystal
instancelocal pos = liquidcrystal:position() -- save position
-- some code
liquidcrystal:cursorMove(pos) -- restore position
Return current character numerical representation.
When using GPIO backend without rw
argument specification function does nothing.
liquidcrystal.read(self)
self
: liquidcrystal
instanceliquidcrystal: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
Return custom char byte array.
When using GPIO backend without rw
argument specification function returns zeros.
liquidcrystal.readCustom(self, index)
self
: liquidcrystal
instanceindex
: custom char index in range from 0 to 7lc: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
Print text right to left.
liquidcrystal.rightToLeft(self)
self
: liquidcrystal
instanceliquidcrystal:rightToLeft()
Move text to the left.
liquidcrystal.scrollLeft(self)
self
: liquidcrystal
instanceliquidcrystal:scrollLeft()
Move text to the right.
liquidcrystal.scrollRight(self)
self
: liquidcrystal
instanceliquidcrystal:scrollRight()
Print text.
liquidcrystal.write(self, ...)
self
: liquidcrystal
instance...
: strings or char codes. For the list of available characters refer to HD44780 datasheetnil
liquidcrystal:write("hello world")
liquidcrystal:write("hello yourself", "!!!", 243, 244)