Table of Contents

Interface ICharacterLcd

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

Interface for character LCD Low-Level handler

public interface ICharacterLcd
Extension Methods

Properties

BacklightOn

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

bool BacklightOn { get; set; }

Property Value

bool

BlinkingCursorVisible

Enable/disable the blinking cursor.

bool BlinkingCursorVisible { get; set; }

Property Value

bool

DisplayOn

Enable/disable the display.

bool DisplayOn { 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)

int NumberOfCustomCharactersSupported { get; }

Property Value

int

Size

Returns the size of the display.

Size Size { get; }

Property Value

Size

UnderlineCursorVisible

Enable/disable the underline cursor.

bool UnderlineCursorVisible { get; set; }

Property Value

bool

Methods

Clear()

Clears the display and moves the cursor to the top left.

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.

void CreateCustomCharacter(int location, byte[] characterMap)

Parameters

location int

Should be between 0 and NumberOfCustomCharactersSupported.

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.

void CreateCustomCharacter(int location, SpanByte characterMap)

Parameters

location int

Should be between 0 and NumberOfCustomCharactersSupported.

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.

SetCursorPosition(int, int)

Moves the cursor to an explicit column and row position.

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.

Exceptions

ArgumentOutOfRangeException

The given position is not inside the display.

Write(char[])

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

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.

void Write(SpanChar text)

Parameters

text SpanChar

Text to print

Write(string)

Write text to the display, without any character translation.

void Write(string text)

Parameters

text string

Text to be displayed.

Remarks

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