Table of Contents

Class Hd44780

Namespace
Iot.Device.CharacterLcd
Assembly
Iot.Device.CharacterLcd.dll

Supports LCD character displays compatible with the HD44780 LCD controller/driver. Also supports serial interface adapters such as the MCP23008.

public class Hd44780 : ICharacterLcd
Inheritance
Hd44780
Implements
Derived
Extension Methods

Remarks

The Hitatchi HD44780 was released in 1987 and set the standard for LCD controllers. Hitatchi does not make this chipset anymore, but most character LCD drivers are intended to be fully compatible with this chipset. Some examples: Sunplus SPLC780D, Sitronix ST7066U, Samsung KS0066U, Aiptek AIP31066, and many more.

Some compatible chips extend the HD44780 with addtional pins and features. They are still fully compatible. The ST7036 is one example.

This implementation was drawn from numerous datasheets and libraries such as Adafruit_Python_CharLCD.

Constructors

Hd44780(Size, LcdInterface)

Initializes a new HD44780 LCD controller.

public Hd44780(Size size, LcdInterface lcdInterface)

Parameters

size Size

The logical size of the LCD.

lcdInterface LcdInterface

The interface to use with the LCD.

Fields

ClearDisplayCommand

Command which can be used to clear the display

protected const byte ClearDisplayCommand = 1

Field Value

byte

ReturnHomeCommand

Command which can be used to return (cursor) home

protected const byte ReturnHomeCommand = 2

Field Value

byte

SetCGRamAddressCommand

Command which can be used to set CG RAM address

protected const byte SetCGRamAddressCommand = 64

Field Value

byte

SetDDRamAddressCommand

Command which can be used to set DD RAM address

protected const byte SetDDRamAddressCommand = 128

Field Value

byte

_lcdInterface

LCD interface used by the device

protected readonly LcdInterface _lcdInterface

Field Value

LcdInterface

_rowOffsets

Offsets of the rows

protected readonly byte[] _rowOffsets

Field Value

byte[]

Properties

AutoShift

When enabled the display will shift rather than the cursor.

public bool AutoShift { get; set; }

Property Value

bool

BacklightOn

Enable/disable the backlight. (Will always return false if no backlight pin was provided.)

public virtual bool BacklightOn { get; set; }

Property Value

bool

BlinkingCursorVisible

Enable/disable the blinking cursor.

public bool BlinkingCursorVisible { get; set; }

Property Value

bool

DisplayOn

Enable/disable the display.

public bool DisplayOn { get; set; }

Property Value

bool

Increment

Gets/sets whether the cursor location increments (true) or decrements (false).

public bool Increment { get; set; }

Property Value

bool

NumberOfCustomCharactersSupported

Returns the number of custom characters for this display. A custom character is one that can be user-defined and assigned to a slot using CreateCustomCharacter(int, SpanByte)

public virtual int NumberOfCustomCharactersSupported { get; }

Property Value

int

Size

Logical size, in characters, of the LCD.

public Size Size { get; }

Property Value

Size

UnderlineCursorVisible

Enable/disable the underline cursor.

public bool UnderlineCursorVisible { get; set; }

Property Value

bool

Methods

Clear()

Clears the LCD, returning the cursor to home and unshifting if shifted. Will also set to Increment.

public void Clear()

CreateCustomCharacter(int, byte[])

Fill one of the 8 CGRAM locations (character codes 0 - 7) with custom characters. See CreateCustomCharacter(int, SpanByte) for details.

public void CreateCustomCharacter(int location, byte[] characterMap)

Parameters

location int

Should be between 0 and 7

characterMap byte[]

Provide an array of 8 bytes containing the pattern

CreateCustomCharacter(int, SpanByte)

Fill one of the 8 CGRAM locations (character codes 0 - 7) with custom characters.

public void CreateCustomCharacter(int location, SpanByte characterMap)

Parameters

location int

Should be between 0 and 7

characterMap SpanByte

Provide an array of 8 bytes containing the pattern

Remarks

The custom characters also occupy character codes 8 - 15.

You can find help designing characters at https://www.quinapalus.com/hd44780udg.html.

The datasheet description for custom characters is very difficult to follow. Here is a rehash of the technical details that is hopefully easier:

Only 6 bits of addresses are available for character ram. That makes for 64 bytes of available character data. 8 bytes of data are used for each character, which is where the 8 total custom characters comes from (64/8).

Each byte corresponds to a character line. Characters are only 5 bits wide so only bits 0-4 are used for display. Whatever is in bits 5-7 is just ignored. Store bits there if it makes you happy, but it won't impact the display. '1' is on, '0' is off.

In the built-in characters the 8th byte is usually empty as this is where the underline cursor will be if enabled. You can put data there if you like, which gives you the full 5x8 character. The underline cursor just turns on the entire bottom row.

5x10 mode is effectively useless as displays aren't available that utilize it. In 5x10 mode 16 bytes of data are used for each character. That leaves room for only 4 custom characters. The first character is addressable from code 0, 1, 8, and 9. The second is 2, 3, 10, 11 and so on...

In this mode 11 bytes of data are actually used for the character data, which effectively gives you a 5x11 character, although typically the last line is blank to leave room for the underline cursor. Why the modes are referred to as 5x8 and 5x10 as opposed to 5x7 and 5x10 or 5x8 and 5x11 is a mystery. In an early pre-release data book 5x7 and 5x10 is used (Advance Copy #AP4 from July 1985). Perhaps it was a marketing change?

As only 11 bytes are used in 5x10 mode, but 16 bytes are reserved, the last 5 bytes are useless. The datasheet helpfully suggests that you can store your own data there. The same would be true for bits 5-7 of lines that matter for both 5x8 and 5x10.

Dispose()

Releases unmanaged resources used by Hd44780 and optionally release managed resources

public virtual void Dispose()

GetTwoLineMode(int)

Determines if the device should use two line mode

protected virtual bool GetTwoLineMode(int rows)

Parameters

rows int

Number of rows on the device

Returns

bool

True if device should use two line mode

Home()

Moves the cursor to the first line and first column, unshifting if shifted.

public void Home()

InitializeRowOffsets(int)

Initializes row offsets

protected virtual byte[] InitializeRowOffsets(int rows)

Parameters

rows int

Rows to be initialized

Returns

byte[]

Array of offsets

SendCommand(byte)

Sends command to the device

protected void SendCommand(byte command)

Parameters

command byte

Byte representing the command to be sent

SendCommandAndWait(byte)

The initialization sequence and some other complex commands should be sent with delays, or the display may behave unexpectedly. It may show random, blinking characters or display text very faintly only.

protected void SendCommandAndWait(byte command)

Parameters

command byte

The command to send

SendCommands(SpanByte)

Send commands to the device

protected void SendCommands(SpanByte commands)

Parameters

commands SpanByte

Each byte represents command being sent to the device

SendData(byte)

Sends byte to the device

protected void SendData(byte value)

Parameters

value byte

Byte to be sent to the device

SendData(SpanByte)

Sends data to the device

protected void SendData(SpanByte values)

Parameters

values SpanByte

Data to be send to the device

SendData(SpanChar)

Sends data to the device

protected void SendData(SpanChar values)

Parameters

values SpanChar

Data to be send to the device

SetCursorPosition(int, int)

Moves the cursor to an explicit column and row position.

public void SetCursorPosition(int left, int top)

Parameters

left int

The column position from left to right starting with 0.

top int

The row position from the top starting with 0.

ShiftCursorLeft()

Move the cursor left one position.

public void ShiftCursorLeft()

ShiftCursorRight()

Move the cursor right one position.

public void ShiftCursorRight()

ShiftDisplayLeft()

Move the display left one position.

public void ShiftDisplayLeft()

ShiftDisplayRight()

Move the display right one position.

public void ShiftDisplayRight()

WaitForNotBusy(int)

Wait for the device to not be busy.

protected void WaitForNotBusy(int microseconds)

Parameters

microseconds int

Time to wait if checking busy state isn't possible/practical.

Write(char[])

Write a raw byte stream to the display. Used if character translation already took place

public void Write(char[] text)

Parameters

text char[]

Text to print

Write(SpanChar)

Write a raw byte stream to the display. Used if character translation already took place

public void Write(SpanChar text)

Parameters

text SpanChar

Text to print

Write(string)

Write text to display.

public void Write(string text)

Parameters

text string

Text to be displayed.

Remarks

There are only 256 characters available. There are chip variants with different character sets. Characters from space ' ' (32) to '}' are usually the same with the exception of '', which is a yen symbol on some chips '¥'.