Difference between revisions of "Unit I2CLCD"

From Ultibo.org
Jump to: navigation, search
 
(5 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
----
 
----
  
−
'''Generic I2C LCD Driver'''
+
'''Generic I2C LCD Driver unit'''
 +
 
 +
Generic 16x2 or 20x4 LCD displays with an I2C interface are available from many suppliers and commonly include a Hitachi HD44780 LCD and NXP PCF8574 I/O expander to convert the I2C data into GPIO inputs for the display.
 +
 +
This unit combines the drivers for the HD44780 and PCF8574 to create a console device which can be used with the standard console and console window API.
 +
 +
Only text mode is supported as the HD44780 does not support setting individual pixels.
 +
 +
Some examples of generic displays that will work with the unit include the following:
 +
 +
https://www.amazon.com/SunFounder-Serial-Module-Display-Arduino/dp/B019K5X53O
 +
 
 +
https://www.auselectronicsdirect.com.au/2-x-16-lcd-display-module-with-i2c-interface-for-a
 +
 
 +
But you can find these units from many suppliers worldwide.
  
 
=== Constants ===
 
=== Constants ===
 
----
 
----
  
−
''To be documented''
+
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''I2CLCD specific constants''' <code> I2CLCD_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>I2CLCD_CONSOLE_DESCRIPTION = 'Generic I2C LCD';</code>
 +
| style="width: 50%;"|Description of I2CLCD device
 +
|-
 +
| <code>I2CLCD_SIGNATURE = $00CF8574;</code>
 +
| &nbsp;
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''I2CLCD GPIO''' <code> I2CLCD_PIN_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>I2CLCD_PIN_RS = GPIO_PIN_0;</code>
 +
| style="width: 50%;"|GPIO pin for the LCD RS line
 +
|-
 +
| <code>I2CLCD_PIN_RW = GPIO_PIN_1;</code>
 +
| GPIO pin for the LCD RW line
 +
|-
 +
| <code>I2CLCD_PIN_EN = GPIO_PIN_2;</code>
 +
| GPIO pin for the LCD EN line
 +
|-
 +
| <code>I2CLCD_PIN_BACKLIGHT = GPIO_PIN_3;</code>
 +
| GPIO pin for the LCD Backlight
 +
|-
 +
| <code>I2CLCD_PIN_D4 = GPIO_PIN_4;</code>
 +
| GPIO pin for the LCD D4 line
 +
|-
 +
| <code>I2CLCD_PIN_D5 = GPIO_PIN_5;</code>
 +
| GPIO pin for the LCD D5 line
 +
|-
 +
| <code>I2CLCD_PIN_D6 = GPIO_PIN_6;</code>
 +
| GPIO pin for the LCD D6 line
 +
|-
 +
| <code>I2CLCD_PIN_D7 = GPIO_PIN_7;</code>
 +
| GPIO pin for the LCD D7 line
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Type definitions ===
 
=== Type definitions ===
 
----
 
----
  
−
''To be documented''
+
 
 +
'''I2CLCD display'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PI2CLCDDisplay = ^TI2CLCDDisplay;</code>
 +
 
 +
<code>TI2CLCDDisplay = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>Signature:LongWord;</code>
 +
| style="width: 50%;"|Signature for entry validation
 +
|-
 +
| <code>Width:LongWord;</code>
 +
| Width in columns of this display
 +
|-
 +
| <code>Height:LongWord;</code>
 +
| Height in rows of this display
 +
|-
 +
| <code>I2C:PI2CDevice;</code>
 +
| I2C device for this display
 +
|-
 +
| <code>GPIO:PGPIODevice;</code>
 +
| GPIO (PCF8574) device for this display
 +
|-
 +
| <code>Console:PConsoleDevice;</code>
 +
| Console (HD44780) device for this display
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Public variables ===
 
=== Public variables ===
 
----
 
----
  
−
''To be documented''
+
 
 +
'''I2CLCD specific variables'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>I2CLCD_AUTOSTART:LongBool = True;</code>
 +
| style="width: 40%;"|If True then auto start the I2CLCD device on boot
 +
|-
 +
|}
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>I2CLCD_I2C_ADDRESS:Word = $27;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>I2CLCD_I2C_DEVICE:String = 'I2C0';</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>I2CLCD_LCD_WIDTH:LongWord = 16;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>I2CLCD_LCD_HEIGHT:LongWord = 2;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
<br />
  
 
=== Function declarations ===
 
=== Function declarations ===
 
----
 
----
  
−
''To be documented''
 
  
 +
'''Initialization functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure I2CLCDInit;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Initialize the I2CLCD unit and parameters</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| Called only during system startup
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function I2CLCDStart(const Device:String; Address:Word; Width,Height:LongWord):THandle;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Start the I2CLCD driver and register the GPIO and Console devices associated with the display</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Device
 +
| The I2C device that the PCF8574 I/O Expander on the display is connected to
 +
|-
 +
! Address
 +
| The I2C address of the PCF8574 I/O Expander on the display
 +
|-
 +
! Width
 +
| The width in columns of the HD44780 LCD on the display
 +
|-
 +
! Height
 +
| The height in rows of the HD44780 LCD on the display
 +
|-
 +
! Return
 +
| The handle of the I2CLCD on success or INVALID_HANDLE_VALUE on failure
 +
|-
 +
! Note
 +
| This function will be called during startup if the parameter I2CLCD_AUTOSTART is True.
 +
Can be called multiple times to support more than one LCD display.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function I2CLCDStop(Handle:THandle):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Stop the I2CLCD driver and deregister the GPIO and Console devices associated with the display</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Handle
 +
| The handle of the I2CLCD or INVALID_HANDLE_VALUE for the default display
 +
|-
 +
! Return
 +
| True if completed or False on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''I2CLCD functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function I2CLCDBacklightOn(Handle:THandle):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Turn on the backlight on the I2CLCD display</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Handle
 +
| The handle of the I2CLCD or INVALID_HANDLE_VALUE for the default display
 +
|-
 +
! Return
 +
| True if completed or False on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function I2CLCDBacklightOff(Handle:THandle):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Turn off the backlight on the I2CLCD display</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Handle
 +
| The handle of the I2CLCD or INVALID_HANDLE_VALUE for the default display
 +
|-
 +
! Return
 +
| True if completed or False on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
Return to [[Unit_Reference|Unit Reference]]
 
Return to [[Unit_Reference|Unit Reference]]

Latest revision as of 05:44, 31 August 2021

Return to Unit Reference


Description

Generic I2C LCD Driver unit

Generic 16x2 or 20x4 LCD displays with an I2C interface are available from many suppliers and commonly include a Hitachi HD44780 LCD and NXP PCF8574 I/O expander to convert the I2C data into GPIO inputs for the display.

This unit combines the drivers for the HD44780 and PCF8574 to create a console device which can be used with the standard console and console window API.

Only text mode is supported as the HD44780 does not support setting individual pixels.

Some examples of generic displays that will work with the unit include the following:

https://www.amazon.com/SunFounder-Serial-Module-Display-Arduino/dp/B019K5X53O

https://www.auselectronicsdirect.com.au/2-x-16-lcd-display-module-with-i2c-interface-for-a

But you can find these units from many suppliers worldwide.

Constants


I2CLCD specific constants I2CLCD_*
I2CLCD_CONSOLE_DESCRIPTION = 'Generic I2C LCD'; Description of I2CLCD device
I2CLCD_SIGNATURE = $00CF8574;  


I2CLCD GPIO I2CLCD_PIN_*
I2CLCD_PIN_RS = GPIO_PIN_0; GPIO pin for the LCD RS line
I2CLCD_PIN_RW = GPIO_PIN_1; GPIO pin for the LCD RW line
I2CLCD_PIN_EN = GPIO_PIN_2; GPIO pin for the LCD EN line
I2CLCD_PIN_BACKLIGHT = GPIO_PIN_3; GPIO pin for the LCD Backlight
I2CLCD_PIN_D4 = GPIO_PIN_4; GPIO pin for the LCD D4 line
I2CLCD_PIN_D5 = GPIO_PIN_5; GPIO pin for the LCD D5 line
I2CLCD_PIN_D6 = GPIO_PIN_6; GPIO pin for the LCD D6 line
I2CLCD_PIN_D7 = GPIO_PIN_7; GPIO pin for the LCD D7 line


Type definitions


I2CLCD display

PI2CLCDDisplay = ^TI2CLCDDisplay;

TI2CLCDDisplay = record

Signature:LongWord; Signature for entry validation
Width:LongWord; Width in columns of this display
Height:LongWord; Height in rows of this display
I2C:PI2CDevice; I2C device for this display
GPIO:PGPIODevice; GPIO (PCF8574) device for this display
Console:PConsoleDevice; Console (HD44780) device for this display


Public variables


I2CLCD specific variables

I2CLCD_AUTOSTART:LongBool = True; If True then auto start the I2CLCD device on boot
I2CLCD_I2C_ADDRESS:Word = $27;
I2CLCD_I2C_DEVICE:String = 'I2C0';
I2CLCD_LCD_WIDTH:LongWord = 16;
I2CLCD_LCD_HEIGHT:LongWord = 2;


Function declarations


Initialization functions 

procedure I2CLCDInit;
Description: Initialize the I2CLCD unit and parameters
Note Called only during system startup 


function I2CLCDStart(const Device:String; Address:Word; Width,Height:LongWord):THandle;
Description: Start the I2CLCD driver and register the GPIO and Console devices associated with the display
Device The I2C device that the PCF8574 I/O Expander on the display is connected to
Address The I2C address of the PCF8574 I/O Expander on the display
Width The width in columns of the HD44780 LCD on the display
Height The height in rows of the HD44780 LCD on the display
Return The handle of the I2CLCD on success or INVALID_HANDLE_VALUE on failure
Note This function will be called during startup if the parameter I2CLCD_AUTOSTART is True.

Can be called multiple times to support more than one LCD display. 


function I2CLCDStop(Handle:THandle):Boolean;
Description: Stop the I2CLCD driver and deregister the GPIO and Console devices associated with the display
Handle The handle of the I2CLCD or INVALID_HANDLE_VALUE for the default display
Return True if completed or False on failure


I2CLCD functions 

function I2CLCDBacklightOn(Handle:THandle):Boolean;
Description: Turn on the backlight on the I2CLCD display
Handle The handle of the I2CLCD or INVALID_HANDLE_VALUE for the default display
Return True if completed or False on failure 


function I2CLCDBacklightOff(Handle:THandle):Boolean;
Description: Turn off the backlight on the I2CLCD display
Handle The handle of the I2CLCD or INVALID_HANDLE_VALUE for the default display
Return True if completed or False on failure


Return to Unit Reference

Retrieved from "https://ultibo.org/mediawiki_ultibo_org/index.php?title=Unit_I2CLCD&oldid=5146"