571 lines
16 KiB
Markdown
571 lines
16 KiB
Markdown
# LiquidCrystal Module
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
|
| :----- | :-------------------- | :---------- | :------ |
|
|
| 2019-12-01 | [Matsievskiy Sergey](https://github.com/seregaxvm) | [Matsievskiy Sergey](https://github.com/seregaxvm) | [liquidcrystal.lua](../../lua_modules/liquidcrystal/liquidcrystal.lua) [i2c4bit.lua](../../lua_modules/liquidcrystal/lc-i2c4bit.lua) [gpio4bit.lua](../../lua_modules/liquidcrystal/lc-gpio4bit.lua) [gpio8bit.lua](../../lua_modules/liquidcrystal/lc-gpio8bit.lua) |
|
|
|
|
This Lua module provides access to [Hitachi HD44780](https://www.sparkfun.com/datasheets/LCD/HD44780.pdf) based LCDs. It supports 4 bit and 8 bit GPIO interface, 4 bit [PCF8574](https://www.nxp.com/docs/en/data-sheet/PCF8574_PCF8574A.pdf) 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.
|
|
|
|
```lua
|
|
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
|
|
```lua
|
|
i2c4bit_meta = require("lc-i2c4bit")
|
|
gpio4bit_meta = require("lc-gpio4bit")
|
|
gpio8bit_meta = require("lc-gpio8bit")
|
|
lc_meta = require("liquidcrystal")
|
|
```
|
|
|
|
### Release
|
|
```lua
|
|
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`](https://nodemcu.readthedocs.io/en/release/modules/i2c/#i2csetup) will be skipped
|
|
- `scl`: I²C clock pin. If set to `nil`, I²C bus initialization step via [`i2c.setup`](https://nodemcu.readthedocs.io/en/release/modules/i2c/#i2csetup) 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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
while liquidcrystal:busy() do end
|
|
```
|
|
|
|
## liquidcrystal.clear
|
|
Clear LCD screen.
|
|
|
|
#### Syntax
|
|
`liquidcrystal.clear(self)`
|
|
|
|
#### Parameters
|
|
- `self`: `liquidcrystal` instance
|
|
|
|
#### Returns
|
|
- sent data
|
|
|
|
#### Example
|
|
```lua
|
|
liquidcrystal:clear()
|
|
```
|
|
|
|
## liquidcrystal.cursorLeft
|
|
Move cursor one character to the left.
|
|
|
|
#### Syntax
|
|
`liquidcrystal.cursorLeft(self)`
|
|
|
|
#### Parameters
|
|
- `self`: `liquidcrystal` instance
|
|
|
|
#### Returns
|
|
- sent data
|
|
|
|
#### Example
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
liquidcrystal:cursor(true)
|
|
```
|
|
|
|
## liquidcrystal.cursorRight
|
|
Move cursor one character to the right.
|
|
|
|
#### Syntax
|
|
`liquidcrystal.cursorRight(self)`
|
|
|
|
#### Parameters
|
|
- `self`: `liquidcrystal` instance
|
|
|
|
#### Returns
|
|
- sent data
|
|
|
|
#### Example
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
liquidcrystal:display(true)
|
|
```
|
|
|
|
## liquidcrystal.home
|
|
Reset cursor and screen position.
|
|
|
|
#### Syntax
|
|
`liquidcrystal.home(self)`
|
|
|
|
#### Parameters
|
|
- `self`: `liquidcrystal` instance
|
|
|
|
#### Returns
|
|
- sent data
|
|
|
|
#### Example
|
|
```lua
|
|
liquidcrystal:home()
|
|
```
|
|
|
|
## liquidcrystal.leftToRight
|
|
Print text left to right (default).
|
|
|
|
#### Syntax
|
|
`liquidcrystal.leftToRight(self)`
|
|
|
|
#### Parameters
|
|
- `self`: `liquidcrystal` instance
|
|
|
|
#### Returns
|
|
- sent data
|
|
|
|
#### Example
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
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
|
|
```lua
|
|
liquidcrystal:rightToLeft()
|
|
```
|
|
|
|
## liquidcrystal.scrollLeft
|
|
Move text to the left.
|
|
|
|
#### Syntax
|
|
`liquidcrystal.scrollLeft(self)`
|
|
|
|
#### Parameters
|
|
- `self`: `liquidcrystal` instance
|
|
|
|
#### Returns
|
|
- sent data
|
|
|
|
#### Example
|
|
```lua
|
|
liquidcrystal:scrollLeft()
|
|
```
|
|
|
|
## liquidcrystal.scrollRight
|
|
Move text to the right.
|
|
|
|
#### Syntax
|
|
`liquidcrystal.scrollRight(self)`
|
|
|
|
#### Parameters
|
|
- `self`: `liquidcrystal` instance
|
|
|
|
#### Returns
|
|
- sent data
|
|
|
|
#### Example
|
|
```lua
|
|
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](https://www.sparkfun.com/datasheets/LCD/HD44780.pdf#page=17)
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
liquidcrystal:write("hello world")
|
|
liquidcrystal:write("hello yourself", "!!!", 243, 244)
|
|
```
|
|
|
|
|