1
0
mirror of https://github.com/kidoman/embd synced 2024-12-22 21:00:05 +01:00
embd/controller/hd44780/hd44780.go

649 lines
19 KiB
Go
Raw Normal View History

/*
Package hd44780 allows controlling an HD44780-compatible character LCD
controller. Currently the library is write-only and does not support
reading from the display controller.
Resources
This library is based three other HD44780 libraries:
Adafruit https://github.com/adafruit/Adafruit-Raspberry-Pi-Python-Code/blob/master/Adafruit_CharLCD/Adafruit_CharLCD.py
hwio https://github.com/mrmorphic/hwio/blob/master/devices/hd44780/hd44780_i2c.go
LiquidCrystal https://github.com/arduino/Arduino/blob/master/libraries/LiquidCrystal/LiquidCrystal.cpp
*/
package hd44780
import (
"time"
"github.com/golang/glog"
"github.com/kidoman/embd"
)
type entryMode byte
type displayMode byte
type functionMode byte
// RowAddress defines the cursor (DDRAM) address of the first column of each row, up to 4 rows.
// You must use the RowAddress value that matches the number of columns on your character display
// for the SetCursor function to work correctly.
type RowAddress [4]byte
var (
// RowAddress16Col are row addresses for a 16-column display
RowAddress16Col RowAddress = [4]byte{0x00, 0x40, 0x10, 0x50}
// RowAddress20Col are row addresses for a 20-column display
RowAddress20Col RowAddress = [4]byte{0x00, 0x40, 0x14, 0x54}
)
// BacklightPolarity is used to set the polarity of the backlight switch, either positive or negative.
type BacklightPolarity bool
const (
// Negative indicates that the backlight is active-low and must have a logical low value to enable.
Negative BacklightPolarity = false
// Positive indicates that the backlight is active-high and must have a logical high value to enable.
Positive BacklightPolarity = true
writeDelay = 37 * time.Microsecond
pulseDelay = 1 * time.Microsecond
clearDelay = 1520 * time.Microsecond
// Initialize display
lcdInit byte = 0x33 // 00110011
lcdInit4bit byte = 0x32 // 00110010
// Commands
lcdClearDisplay byte = 0x01 // 00000001
lcdReturnHome byte = 0x02 // 00000010
lcdCursorShift byte = 0x10 // 00010000
lcdSetCGRamAddr byte = 0x40 // 01000000
lcdSetDDRamAddr byte = 0x80 // 10000000
// Cursor and display move flags
lcdCursorMove byte = 0x00 // 00000000
lcdDisplayMove byte = 0x08 // 00001000
lcdMoveLeft byte = 0x00 // 00000000
lcdMoveRight byte = 0x04 // 00000100
// Entry mode flags
lcdSetEntryMode entryMode = 0x04 // 00000100
lcdEntryDecrement entryMode = 0x00 // 00000000
lcdEntryIncrement entryMode = 0x02 // 00000010
lcdEntryShiftOff entryMode = 0x00 // 00000000
lcdEntryShiftOn entryMode = 0x01 // 00000001
// Display mode flags
lcdSetDisplayMode displayMode = 0x08 // 00001000
lcdDisplayOff displayMode = 0x00 // 00000000
lcdDisplayOn displayMode = 0x04 // 00000100
lcdCursorOff displayMode = 0x00 // 00000000
lcdCursorOn displayMode = 0x02 // 00000010
lcdBlinkOff displayMode = 0x00 // 00000000
lcdBlinkOn displayMode = 0x01 // 00000001
// Function mode flags
lcdSetFunctionMode functionMode = 0x20 // 00100000
lcd4BitMode functionMode = 0x00 // 00000000
lcd8BitMode functionMode = 0x10 // 00010000
lcd1Line functionMode = 0x00 // 00000000
lcd2Line functionMode = 0x08 // 00001000
lcd5x8Dots functionMode = 0x00 // 00000000
lcd5x10Dots functionMode = 0x04 // 00000100
)
// HD44780 represents an HD44780-compatible character LCD controller.
type HD44780 struct {
Connection
eMode entryMode
dMode displayMode
fMode functionMode
rowAddr RowAddress
}
// NewGPIO creates a new HD44780 connected by a 4-bit GPIO bus.
func NewGPIO(
rs, en, d4, d5, d6, d7, backlight interface{},
blPolarity BacklightPolarity,
rowAddr RowAddress,
modes ...ModeSetter,
) (*HD44780, error) {
pinKeys := []interface{}{rs, en, d4, d5, d6, d7, backlight}
pins := [7]embd.DigitalPin{}
for idx, key := range pinKeys {
if key == nil {
continue
}
var digitalPin embd.DigitalPin
if pin, ok := key.(embd.DigitalPin); ok {
digitalPin = pin
} else {
var err error
digitalPin, err = embd.NewDigitalPin(key)
if err != nil {
glog.V(1).Infof("hd44780: error creating digital pin %+v: %s", key, err)
return nil, err
}
}
pins[idx] = digitalPin
}
for _, pin := range pins {
if pin == nil {
continue
}
err := pin.SetDirection(embd.Out)
if err != nil {
glog.Errorf("hd44780: error setting pin %+v to out direction: %s", pin, err)
return nil, err
}
}
return New(
NewGPIOConnection(
pins[0],
pins[1],
pins[2],
pins[3],
pins[4],
pins[5],
pins[6],
blPolarity),
rowAddr,
modes...,
)
}
// NewI2C creates a new HD44780 connected by an I²C bus.
func NewI2C(
i2c embd.I2CBus,
addr byte,
pinMap I2CPinMap,
rowAddr RowAddress,
modes ...ModeSetter,
) (*HD44780, error) {
return New(NewI2CConnection(i2c, addr, pinMap), rowAddr, modes...)
}
// New creates a new HD44780 connected by a Connection bus.
func New(bus Connection, rowAddr RowAddress, modes ...ModeSetter) (*HD44780, error) {
controller := &HD44780{
Connection: bus,
eMode: 0x00,
dMode: 0x00,
fMode: 0x00,
rowAddr: rowAddr,
}
err := controller.lcdInit()
if err != nil {
return nil, err
}
err = controller.SetMode(append(DefaultModes, modes...)...)
if err != nil {
return nil, err
}
return controller, nil
}
func (controller *HD44780) lcdInit() error {
glog.V(2).Info("hd44780: initializing display")
err := controller.WriteInstruction(lcdInit)
if err != nil {
return err
}
glog.V(2).Info("hd44780: initializing display in 4-bit mode")
return controller.WriteInstruction(lcdInit4bit)
}
// DefaultModes are the default initialization modes for an HD44780.
// ModeSetters passed in to a constructor will override these default values.
var DefaultModes []ModeSetter = []ModeSetter{
FourBitMode,
OneLine,
Dots5x8,
EntryIncrement,
EntryShiftOff,
DisplayOn,
CursorOff,
BlinkOff,
}
// ModeSetter defines a function used for setting modes on an HD44780.
// ModeSetters must be used with the SetMode function or in a constructor.
type ModeSetter func(*HD44780)
// EntryDecrement is a ModeSetter that sets the HD44780 to entry decrement mode.
func EntryDecrement(hd *HD44780) { hd.eMode &= ^lcdEntryIncrement }
// EntryIncrement is a ModeSetter that sets the HD44780 to entry increment mode.
func EntryIncrement(hd *HD44780) { hd.eMode |= lcdEntryIncrement }
// EntryShiftOff is a ModeSetter that sets the HD44780 to entry shift off mode.
func EntryShiftOff(hd *HD44780) { hd.eMode &= ^lcdEntryShiftOn }
// EntryShiftOn is a ModeSetter that sets the HD44780 to entry shift on mode.
func EntryShiftOn(hd *HD44780) { hd.eMode |= lcdEntryShiftOn }
// DisplayOff is a ModeSetter that sets the HD44780 to display off mode.
func DisplayOff(hd *HD44780) { hd.dMode &= ^lcdDisplayOn }
// DisplayOn is a ModeSetter that sets the HD44780 to display on mode.
func DisplayOn(hd *HD44780) { hd.dMode |= lcdDisplayOn }
// CursorOff is a ModeSetter that sets the HD44780 to cursor off mode.
func CursorOff(hd *HD44780) { hd.dMode &= ^lcdCursorOn }
// CursorOn is a ModeSetter that sets the HD44780 to cursor on mode.
func CursorOn(hd *HD44780) { hd.dMode |= lcdCursorOn }
// BlinkOff is a ModeSetter that sets the HD44780 to cursor blink off mode.
func BlinkOff(hd *HD44780) { hd.dMode &= ^lcdBlinkOn }
// BlinkOn is a ModeSetter that sets the HD44780 to cursor blink on mode.
func BlinkOn(hd *HD44780) { hd.dMode |= lcdBlinkOn }
// FourBitMode is a ModeSetter that sets the HD44780 to 4-bit bus mode.
func FourBitMode(hd *HD44780) { hd.fMode &= ^lcd8BitMode }
// EightBitMode is a ModeSetter that sets the HD44780 to 8-bit bus mode.
func EightBitMode(hd *HD44780) { hd.fMode |= lcd8BitMode }
// OneLine is a ModeSetter that sets the HD44780 to 1-line display mode.
func OneLine(hd *HD44780) { hd.fMode &= ^lcd2Line }
// TwoLine is a ModeSetter that sets the HD44780 to 2-line display mode.
func TwoLine(hd *HD44780) { hd.fMode |= lcd2Line }
// Dots5x8 is a ModeSetter that sets the HD44780 to 5x8-pixel character mode.
func Dots5x8(hd *HD44780) { hd.fMode &= ^lcd5x10Dots }
// Dots5x10 is a ModeSetter that sets the HD44780 to 5x10-pixel character mode.
func Dots5x10(hd *HD44780) { hd.fMode |= lcd5x10Dots }
// EntryIncrementEnabled returns true if entry increment mode is enabled.
func (hd *HD44780) EntryIncrementEnabled() bool { return hd.eMode&lcdEntryIncrement > 0 }
// EntryShiftEnabled returns true if entry shift mode is enabled.
func (hd *HD44780) EntryShiftEnabled() bool { return hd.eMode&lcdEntryShiftOn > 0 }
// DisplayEnabled returns true if the display is on.
func (hd *HD44780) DisplayEnabled() bool { return hd.dMode&lcdDisplayOn > 0 }
// CursorEnabled returns true if the cursor is on.
func (hd *HD44780) CursorEnabled() bool { return hd.dMode&lcdCursorOn > 0 }
// BlinkEnabled returns true if the cursor blink mode is enabled.
func (hd *HD44780) BlinkEnabled() bool { return hd.dMode&lcdBlinkOn > 0 }
// EightBitModeEnabled returns true if 8-bit bus mode is enabled and false if 4-bit
// bus mode is enabled.
func (hd *HD44780) EightBitModeEnabled() bool { return hd.fMode&lcd8BitMode > 0 }
// TwoLineEnabled returns true if 2-line display mode is enabled and false if 1-line
// display mode is enabled.
func (hd *HD44780) TwoLineEnabled() bool { return hd.fMode&lcd2Line > 0 }
// Dots5x10Enabled returns true if 5x10-pixel characters are enabled.
func (hd *HD44780) Dots5x10Enabled() bool { return hd.fMode&lcd5x8Dots > 0 }
// SetModes modifies the entry mode, display mode, and function mode with the
// given mode setter functions.
func (hd *HD44780) SetMode(modes ...ModeSetter) error {
for _, m := range modes {
m(hd)
}
functions := []func() error{
func() error { return hd.setEntryMode() },
func() error { return hd.setDisplayMode() },
func() error { return hd.setFunctionMode() },
}
for _, f := range functions {
err := f()
if err != nil {
return err
}
}
return nil
}
func (hd *HD44780) setEntryMode() error {
return hd.WriteInstruction(byte(lcdSetEntryMode | hd.eMode))
}
func (hd *HD44780) setDisplayMode() error {
return hd.WriteInstruction(byte(lcdSetDisplayMode | hd.dMode))
}
func (hd *HD44780) setFunctionMode() error {
return hd.WriteInstruction(byte(lcdSetFunctionMode | hd.fMode))
}
// DisplayOff sets the display mode to off.
func (hd *HD44780) DisplayOff() error {
DisplayOff(hd)
return hd.setDisplayMode()
}
// DisplayOn sets the display mode to on.
func (hd *HD44780) DisplayOn() error {
DisplayOn(hd)
return hd.setDisplayMode()
}
// CursorOff turns the cursor off.
func (hd *HD44780) CursorOff() error {
CursorOff(hd)
return hd.setDisplayMode()
}
// CursorOn turns the cursor on.
func (hd *HD44780) CursorOn() error {
CursorOn(hd)
return hd.setDisplayMode()
}
// BlinkOff sets cursor blink mode off.
func (hd *HD44780) BlinkOff() error {
BlinkOff(hd)
return hd.setDisplayMode()
}
// BlinkOn sets cursor blink mode on.
func (hd *HD44780) BlinkOn() error {
BlinkOn(hd)
return hd.setDisplayMode()
}
// ShiftLeft shifts the cursor and all characters to the left.
func (hd *HD44780) ShiftLeft() error {
return hd.WriteInstruction(lcdCursorShift | lcdDisplayMove | lcdMoveLeft)
}
// ShiftRight shifts the cursor and all characters to the right.
func (hd *HD44780) ShiftRight() error {
return hd.WriteInstruction(lcdCursorShift | lcdDisplayMove | lcdMoveRight)
}
// Home moves the cursor and all characters to the home position.
func (hd *HD44780) Home() error {
err := hd.WriteInstruction(lcdReturnHome)
time.Sleep(clearDelay)
return err
}
// Clear clears the display and mode settings sets the cursor to the home position.
func (hd *HD44780) Clear() error {
err := hd.WriteInstruction(lcdClearDisplay)
if err != nil {
return err
}
time.Sleep(clearDelay)
// have to set mode here because clear also clears some mode settings
return hd.SetMode()
}
// SetCursor sets the input cursor to the given position.
func (hd *HD44780) SetCursor(col, row int) error {
return hd.SetDDRamAddr(byte(col) + hd.lcdRowOffset(row))
}
func (hd *HD44780) lcdRowOffset(row int) byte {
// Offset for up to 4 rows
if row > 3 {
row = 3
}
return hd.rowAddr[row]
}
// SetDDRamAddr sets the input cursor to the given address.
func (hd *HD44780) SetDDRamAddr(value byte) error {
return hd.WriteInstruction(lcdSetDDRamAddr | value)
}
// WriteInstruction writes a byte to the bus with register select in data mode.
func (hd *HD44780) WriteChar(value byte) error {
return hd.Write(true, value)
}
// WriteInstruction writes a byte to the bus with register select in command mode.
func (hd *HD44780) WriteInstruction(value byte) error {
return hd.Write(false, value)
}
// Close closes the underlying Connection.
func (hd *HD44780) Close() error {
return hd.Connection.Close()
}
// Connection abstracts the different methods of communicating with an HD44780.
type Connection interface {
// Write writes a byte to the HD44780 controller with the register select
// flag either on or off.
Write(rs bool, data byte) error
// BacklightOff turns the optional backlight off.
BacklightOff() error
// BacklightOn turns the optional backlight on.
BacklightOn() error
// Close closes all open resources.
Close() error
}
// GPIOConnection implements Connection using a 4-bit GPIO bus.
type GPIOConnection struct {
RS, EN embd.DigitalPin
D4, D5, D6, D7 embd.DigitalPin
Backlight embd.DigitalPin
BLPolarity BacklightPolarity
}
// NewGPIOConnection returns a new Connection based on a 4-bit GPIO bus.
func NewGPIOConnection(
rs, en, d4, d5, d6, d7, backlight embd.DigitalPin,
blPolarity BacklightPolarity,
) *GPIOConnection {
return &GPIOConnection{
RS: rs,
EN: en,
D4: d4,
D5: d5,
D6: d6,
D7: d7,
Backlight: backlight,
BLPolarity: blPolarity,
}
}
// BacklightOff turns the optional backlight off.
func (conn *GPIOConnection) BacklightOff() error {
if conn.Backlight != nil {
return conn.Backlight.Write(conn.backlightSignal(false))
}
return nil
}
// BacklightOn turns the optional backlight on.
func (conn *GPIOConnection) BacklightOn() error {
if conn.Backlight != nil {
return conn.Backlight.Write(conn.backlightSignal(true))
}
return nil
}
func (conn *GPIOConnection) backlightSignal(state bool) int {
if state == bool(conn.BLPolarity) {
return embd.High
} else {
return embd.Low
}
}
// Write writes a register select flag and byte to the 4-bit GPIO connection.
func (conn *GPIOConnection) Write(rs bool, data byte) error {
glog.V(3).Infof("hd44780: writing to GPIO RS: %t, data: %#x", rs, data)
rsInt := embd.Low
if rs {
rsInt = embd.High
}
functions := []func() error{
func() error { return conn.RS.Write(rsInt) },
func() error { return conn.D4.Write(int((data >> 4) & 0x01)) },
func() error { return conn.D5.Write(int((data >> 5) & 0x01)) },
func() error { return conn.D6.Write(int((data >> 6) & 0x01)) },
func() error { return conn.D7.Write(int((data >> 7) & 0x01)) },
func() error { return conn.pulseEnable() },
func() error { return conn.D4.Write(int(data & 0x01)) },
func() error { return conn.D5.Write(int((data >> 1) & 0x01)) },
func() error { return conn.D6.Write(int((data >> 2) & 0x01)) },
func() error { return conn.D7.Write(int((data >> 3) & 0x01)) },
func() error { return conn.pulseEnable() },
}
for _, f := range functions {
err := f()
if err != nil {
return err
}
}
time.Sleep(writeDelay)
return nil
}
func (conn *GPIOConnection) pulseEnable() error {
values := []int{embd.Low, embd.High, embd.Low}
for _, v := range values {
time.Sleep(pulseDelay)
err := conn.EN.Write(v)
if err != nil {
return err
}
}
return nil
}
// Close closes all open DigitalPins.
func (conn *GPIOConnection) Close() error {
glog.V(2).Info("hd44780: closing all GPIO pins")
pins := []embd.DigitalPin{
conn.RS,
conn.EN,
conn.D4,
conn.D5,
conn.D6,
conn.D7,
conn.Backlight,
}
for _, pin := range pins {
err := pin.Close()
if err != nil {
glog.Errorf("hd44780: error closing pin %+v: %s", pin, err)
return err
}
}
return nil
}
// I2CConnection implements Connection using an I²C bus.
type I2CConnection struct {
I2C embd.I2CBus
Addr byte
PinMap I2CPinMap
Backlight bool
}
// I2CPinMap represents a mapping between the pins on an I²C port expander and
// the pins on the HD44780 controller.
type I2CPinMap struct {
RS, RW, EN byte
D4, D5, D6, D7 byte
Backlight byte
BLPolarity BacklightPolarity
}
var (
// MJKDZPinMap is the standard pin mapping for an MJKDZ-based I²C backpack.
MJKDZPinMap I2CPinMap = I2CPinMap{
RS: 6, RW: 5, EN: 4,
D4: 0, D5: 1, D6: 2, D7: 3,
Backlight: 7,
BLPolarity: Negative,
}
// PCF8574PinMap is the standard pin mapping for a PCF8574-based I²C backpack.
PCF8574PinMap I2CPinMap = I2CPinMap{
RS: 0, RW: 1, EN: 2,
D4: 4, D5: 5, D6: 6, D7: 7,
Backlight: 3,
BLPolarity: Positive,
}
)
// NewI2CConnection returns a new Connection based on an I²C bus.
func NewI2CConnection(i2c embd.I2CBus, addr byte, pinMap I2CPinMap) *I2CConnection {
return &I2CConnection{
I2C: i2c,
Addr: addr,
PinMap: pinMap,
}
}
// BacklightOff turns the optional backlight off.
func (conn *I2CConnection) BacklightOff() error {
conn.Backlight = false
return conn.Write(false, 0x00)
}
// BacklightOn turns the optional backlight on.
func (conn *I2CConnection) BacklightOn() error {
conn.Backlight = true
return conn.Write(false, 0x00)
}
// Write writes a register select flag and byte to the I²C connection.
func (conn *I2CConnection) Write(rs bool, data byte) error {
var instructionHigh byte = 0x00
instructionHigh |= ((data >> 4) & 0x01) << conn.PinMap.D4
instructionHigh |= ((data >> 5) & 0x01) << conn.PinMap.D5
instructionHigh |= ((data >> 6) & 0x01) << conn.PinMap.D6
instructionHigh |= ((data >> 7) & 0x01) << conn.PinMap.D7
var instructionLow byte = 0x00
instructionLow |= (data & 0x01) << conn.PinMap.D4
instructionLow |= ((data >> 1) & 0x01) << conn.PinMap.D5
instructionLow |= ((data >> 2) & 0x01) << conn.PinMap.D6
instructionLow |= ((data >> 3) & 0x01) << conn.PinMap.D7
instructions := []byte{instructionHigh, instructionLow}
for _, ins := range instructions {
if rs {
ins |= 0x01 << conn.PinMap.RS
}
if conn.Backlight == bool(conn.PinMap.BLPolarity) {
ins |= 0x01 << conn.PinMap.Backlight
}
glog.V(3).Infof("hd44780: writing to I2C: %#x", ins)
err := conn.pulseEnable(ins)
if err != nil {
return err
}
}
time.Sleep(writeDelay)
return nil
}
func (conn *I2CConnection) pulseEnable(data byte) error {
bytes := []byte{data, data | (0x01 << conn.PinMap.EN), data}
for _, b := range bytes {
time.Sleep(pulseDelay)
err := conn.I2C.WriteByte(conn.Addr, b)
if err != nil {
return err
}
}
return nil
}
// Close closes the I²C connection.
func (conn *I2CConnection) Close() error {
glog.V(2).Info("hd44780: closing I2C bus")
return conn.I2C.Close()
}