Remarks

CharacterDisplay
Status Status badge: working
Source code GitHub
NuGet package NuGet Gallery for Meadow.Foundation.Displays.Lcd.CharacterDisplay

The CharacterDisplay class represents a multiline liquid crystal character display.

These displays are commonly found in 16x2 and 20x4 character by row configurations. Each character is represented using a grid of 5x7 pixels.

The current driver implementation uses 4 or 8 GPIO pins. It's common to find controller boards with this displays that provide I2C, SPI, or serial control. These will be supported in a future update.

Code Example

CharacterDisplay display;

public override Task Initialize()
{
    //InitGpio();
    //InitGpioWithPWM();
    //InitI2c();
    InitGrove();

    return base.Initialize();
}

void InitGpio() 
{
    Resolver.Log.Info("InitGpio...");

    display = new CharacterDisplay
    (
        device: Device,
        pinRS: Device.Pins.D10,
        pinE: Device.Pins.D09,
        pinD4: Device.Pins.D08,
        pinD5: Device.Pins.D07,
        pinD6: Device.Pins.D06,
        pinD7: Device.Pins.D05,
        rows: 4, columns: 20
    );
}

void InitGpioWithPWM()
{
    Resolver.Log.Info("InitGpioWithPWM...");

    display = new CharacterDisplay
    (
        device: Device,
        pinV0: Device.Pins.D11,
        pinRS: Device.Pins.D10,
        pinE:  Device.Pins.D09,
        pinD4: Device.Pins.D08,
        pinD5: Device.Pins.D07,
        pinD6: Device.Pins.D06,
        pinD7: Device.Pins.D05,
        rows: 4, columns: 20
    );
}

void InitI2c()
{
    Resolver.Log.Info("InitI2c...");

    display = new CharacterDisplay
    (
        i2cBus: Device.CreateI2cBus(I2cBusSpeed.Standard),
        address: (byte)I2cCharacterDisplay.Addresses.Default,
        rows: 4, columns: 20
    );
}

void InitGrove()
{
    Resolver.Log.Info("InitGrove...");

    display = new CharacterDisplay
    (
        i2cBus: Device.CreateI2cBus(I2cBusSpeed.Standard),
        address: (byte)I2cCharacterDisplay.Addresses.Grove,
        rows: 2, columns: 16,
        isGroveDisplay: true
    );
}

void TestCharacterDisplay() 
{
    Resolver.Log.Info("TestCharacterDisplay...");

    display.WriteLine("Hello", 0);

    display.WriteLine("Display", 1);

    Thread.Sleep(1000);
    display.WriteLine("Will delete in", 0);

    int count = 5;
    while(count > 0)
    {
        display.WriteLine($"{count--}", 1);
        Thread.Sleep(500);
    }

    display.ClearLines();
    Thread.Sleep(2000);

    display.WriteLine("Cursor test", 0);

    for (int i = 0; i < display.DisplayConfig.Width; i++)
    {
        display.SetCursorPosition((byte)i, 1);
        display.Write("*");
        Thread.Sleep(100);
        display.SetCursorPosition((byte)i, 1);
        display.Write(" ");
    }

    display.ClearLines();
    display.WriteLine("Complete!", 0);
}

public override Task Run()
{
    TestCharacterDisplay();

    Resolver.Log.Info("Test complete");

    return base.Run();
}

Sample project(s) available on GitHub

Wiring Example

Characteristic Locus
Inheritance System.Object > CharacterDisplay
Namespace Meadow.Foundation.Displays.Lcd
Assembly CharacterDisplay.dll

Syntax

public class CharacterDisplay : ITextDisplay

Constructors

CharacterDisplay(IDigitalOutputPort, IDigitalOutputPort, IDigitalOutputPort, IDigitalOutputPort, IDigitalOutputPort, IDigitalOutputPort, Byte, Byte)

Create a new CharacterDisplay object

Declaration
public CharacterDisplay(IDigitalOutputPort portRS, IDigitalOutputPort portE, IDigitalOutputPort portD4, IDigitalOutputPort portD5, IDigitalOutputPort portD6, IDigitalOutputPort portD7, byte rows = null, byte columns = null)

Parameters

Type Name Description
IDigitalOutputPort portRS

Port for RS pin

IDigitalOutputPort portE

Port for W pin

IDigitalOutputPort portD4

Port for D4 pin

IDigitalOutputPort portD5

Port for D5 pin

IDigitalOutputPort portD6

Port for D6 pin

IDigitalOutputPort portD7

Port for D7 pin

System.Byte rows

Number of character rows

System.Byte columns

Number of character columns

CharacterDisplay(II2cBus, Byte, Byte, Byte, Boolean)

Create a new CharacterDisplay object

Declaration
public CharacterDisplay(II2cBus i2cBus, byte address = null, byte rows = null, byte columns = null, bool isGroveDisplay = false)

Parameters

Type Name Description
II2cBus i2cBus

The I2C bus connected to the display

System.Byte address

The I2C address

System.Byte rows

The number of charcter rows

System.Byte columns

The number of character columns

System.Boolean isGroveDisplay

True if this is a Seeed Studio Grove display (default is false)

CharacterDisplay(IMeadowDevice, IPin, IPin, IPin, IPin, IPin, IPin, IPin, Byte, Byte)

Create a new CharacterDisplay object

Declaration
public CharacterDisplay(IMeadowDevice device, IPin pinV0, IPin pinRS, IPin pinE, IPin pinD4, IPin pinD5, IPin pinD6, IPin pinD7, byte rows = null, byte columns = null)

Parameters

Type Name Description
IMeadowDevice device

The device connected to the display

IPin pinV0

V0 pin

IPin pinRS

RS pin

IPin pinE

W pin

IPin pinD4

D4 pin

IPin pinD5

D5 pin

IPin pinD6

D6 pin

IPin pinD7

D7 pin

System.Byte rows

Number of character rows

System.Byte columns

Number of character columns

CharacterDisplay(IMeadowDevice, IPin, IPin, IPin, IPin, IPin, IPin, Byte, Byte)

Create a new character display object using GPIO

Declaration
public CharacterDisplay(IMeadowDevice device, IPin pinRS, IPin pinE, IPin pinD4, IPin pinD5, IPin pinD6, IPin pinD7, byte rows = null, byte columns = null)

Parameters

Type Name Description
IMeadowDevice device

The device connected to the display

IPin pinRS

The RS pin

IPin pinE

The E pin

IPin pinD4

The D4 pin

IPin pinD5

The D5 pin

IPin pinD6

The D6 pin

IPin pinD7

The D7 pin

System.Byte rows

The number of character rows

System.Byte columns

The number of character columns

CharacterDisplay(IPwmPort, IDigitalOutputPort, IDigitalOutputPort, IDigitalOutputPort, IDigitalOutputPort, IDigitalOutputPort, IDigitalOutputPort, Byte, Byte)

Create a new CharacterDisplay object

Declaration
public CharacterDisplay(IPwmPort portV0, IDigitalOutputPort portRS, IDigitalOutputPort portE, IDigitalOutputPort portD4, IDigitalOutputPort portD5, IDigitalOutputPort portD6, IDigitalOutputPort portD7, byte rows = null, byte columns = null)

Parameters

Type Name Description
IPwmPort portV0

PWM port for backlight

IDigitalOutputPort portRS

Port for RS pin

IDigitalOutputPort portE

Port for W pin

IDigitalOutputPort portD4

Port for D4 pin

IDigitalOutputPort portD5

Port for D5 pin

IDigitalOutputPort portD6

Port for D6 pin

IDigitalOutputPort portD7

Port for D7 pin

System.Byte rows

Number of character rows

System.Byte columns

Number of character columns

Properties

DisplayConfig

The display configuration for text display menu

Declaration
public TextDisplayConfig DisplayConfig { get; }

Property Value

Type Description
TextDisplayConfig

Methods

ClearLine(Byte)

Clear a line of text

Declaration
public void ClearLine(byte lineNumber)

Parameters

Type Name Description
System.Byte lineNumber

The line to clear (0 indexed)

ClearLines()

Clear all lines

Declaration
public void ClearLines()

SaveCustomCharacter(Byte[], Byte)

Save a custom character to the display

Declaration
public void SaveCustomCharacter(byte[] characterMap, byte address)

Parameters

Type Name Description
System.Byte[] characterMap

The character data

System.Byte address

The display character address (0-7)

SetCursorPosition(Byte, Byte)

Set the cursor position

Declaration
public void SetCursorPosition(byte column, byte line)

Parameters

Type Name Description
System.Byte column

The cursor column

System.Byte line

The cursor line

Show()

Update the display

Declaration
public void Show()

Write(String)

Write a string to the display

Declaration
public void Write(string text)

Parameters

Type Name Description
System.String text

The text to show as a string

WriteLine(String, Byte, Boolean)

Write text to a line

Declaration
public void WriteLine(string text, byte lineNumber, bool showCursor = false)

Parameters

Type Name Description
System.String text

The text to dislay

System.Byte lineNumber

The target line

System.Boolean showCursor

If true, show the cursor