Difference between revisions of "Unit AF16x2LCD"

From Ultibo.org
Jump to: navigation, search
(Created page with "Return to Unit Reference === Description === ---- ''To be documented'' === Constants === ---- ''To be documented'' === Type definitions === ---- ''To...")
 
 
(15 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
----
 
----
  
−
''To be documented''
+
'''Adafruit 16x2 Character LCD + Keypad Driver unit'''
 +
 
 +
The Adafruit 16x2 LCD + Keypad is a kit that includes both a 16x2 LCD display using the Hitachi HD44780 LCD controller as well as a custom PCB with an MCP23017 I/O expander to connect it to a Raspberry Pi (any model) using I2C. It is available in Monochrome or RGB Positive and Negative versions.
 +
 +
This unit ties together the various components needed to make one of these boards work with Ultibo by finding the correct I2C device, creating the MCP230XX GPIO device, creating the HD44780 Console device and registering all of it with the correct parameters for the Adafruit kit.
 +
 +
The unit also includes functions to read the 5 buttons on the board and control the LCD backlight.
 +
 +
You will find many LCD display boards based on the Hitachi HD44780 controller and this unit gives an example of how to assembler the available units to create your own driver for a different board.
  
 
=== 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;">'''AF16x2LCD specific constants''' <code> AF16X2LCD_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>AF16X2LCD_CONSOLE_DESCRIPTION = 'Adafruit 16x2 LCD';</code>
 +
| Description of AF16x2LCD device
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>AF16X2LCD_SIGNATURE = $000AF162;</code>
 +
| &nbsp;
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>AF16X2LCD_MODEL_MONO = 0;</code>
 +
| LCD with Monochrome backlight
 +
|-
 +
| <code>AF16X2LCD_MODEL_RGB = 1;</code>
 +
| LCD with RGB backlight;
 +
|-
 +
|}
 +
</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;">'''AF16x2LCD GPIO pin''' <code> GPIO_PIN_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>AF16X2LCD_PLATE_RS = GPIO_PIN_15;</code>
 +
| GPIO pin for the LCD RS line
 +
|-
 +
| <code>AF16X2LCD_PLATE_RW = GPIO_PIN_14;</code>
 +
| GPIO pin for the LCD RW line
 +
|-
 +
| <code>AF16X2LCD_PLATE_EN = GPIO_PIN_13;</code>
 +
| GPIO pin for the LCD EN line
 +
|-
 +
| <code>AF16X2LCD_PLATE_D4 = GPIO_PIN_12;</code>
 +
| GPIO pin for the LCD D4 line
 +
|-
 +
| <code>AF16X2LCD_PLATE_D5 = GPIO_PIN_11;</code>
 +
| GPIO pin for the LCD D5 line
 +
|-
 +
| <code>AF16X2LCD_PLATE_D6 = GPIO_PIN_10;</code>
 +
| GPIO pin for the LCD D6 line
 +
|-
 +
| <code>AF16X2LCD_PLATE_D7 = GPIO_PIN_9;</code>
 +
| GPIO pin for the LCD D7 line
 +
|-
 +
| <code>AF16X2LCD_PLATE_RED = GPIO_PIN_6;</code>
 +
| GPIO pin for the Backlight Red LED
 +
|-
 +
| <code>AF16X2LCD_PLATE_GREEN = GPIO_PIN_7;</code>
 +
| GPIO pin for the Backlight Green LED
 +
|-
 +
| <code>AF16X2LCD_PLATE_BLUE = GPIO_PIN_8;</code>
 +
| GPIO pin for the Backlight Blue LED
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>AF16X2LCD_BUTTON_SELECT = GPIO_PIN_0;</code>
 +
| GPIO pin for the Select button
 +
|-
 +
| <code>AF16X2LCD_BUTTON_RIGHT = GPIO_PIN_1;</code>
 +
| GPIO pin for the Right button
 +
|-
 +
| <code>AF16X2LCD_BUTTON_DOWN = GPIO_PIN_2;</code>
 +
| GPIO pin for the Down button
 +
|-
 +
| <code>AF16X2LCD_BUTTON_UP = GPIO_PIN_3;</code>
 +
| GPIO pin for the Up button
 +
|-
 +
| <code>AF16X2LCD_BUTTON_LEFT = GPIO_PIN_4;</code>
 +
| GPIO pin for the Left button
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Type definitions ===
 
=== Type definitions ===
 
----
 
----
  
−
''To be documented''
+
 
 +
'''AF16x2LCD specific types'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PAF16x2LCDPlate = ^TAF16x2LCDPlate;</code>
 +
 
 +
<code>TAF16x2LCDPlate = 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>
 +
| Signature for entry validation
 +
|-
 +
| <code>Model:LongWord;</code>
 +
| Plate model (eg AF16X2LCD_MODEL_MONO)
 +
|-
 +
| <code>Invert:LongBool;</code>
 +
| Invert polarity of Backlight (Active low if True)
 +
|-
 +
| <code>I2C:PI2CDevice;</code>
 +
| I2C device for this plate
 +
|-
 +
| <code>GPIO:PGPIODevice;</code>
 +
| GPIO (MCP23017) device for this plate
 +
|-
 +
| <code>Console:PConsoleDevice;</code>
 +
| Console (HD44780) device for this plate
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Public variables ===
 
=== Public variables ===
 
----
 
----
  
−
''To be documented''
+
 
 +
'''AF16x2LCD specific variables'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>AF16X2LCD_MODEL:LongWord = AF16X2LCD_MODEL_RGB;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>AF16X2LCD_I2C_ADDRESS:Word = $20;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>AF16X2LCD_I2C_DEVICE:String = 'I2C0';</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 AF16x2LCDInit;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Initialize the AF16x2LCD 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 AF16x2LCDStart(Model:LongWord; Invert:Boolean; const Device:String; Address:Word):THandle;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Start the AF16x2LCD 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;"
 +
|-
 +
! Model
 +
| The Adafruit 16x2 LCD Plate model (eg AF16X2LCD_MODEL_RGB)
 +
|-
 +
! Invert
 +
| Invert the signal level for the LCD backlight (If True then GPIO_LEVEL_LOW equals On)
 +
|-
 +
! Device
 +
| The I2C device that the MCP23017 I/O Expander on the LCD Plate is connected to
 +
|-
 +
! Address
 +
| The I2C address of the MCP23017 I/O Expander on the LCD Plate
 +
|-
 +
! Return
 +
| The handle of the AF16x2LCD on success or INVALID_HANDLE_VALUE on failure
 +
|-
 +
! Note
 +
| This function will be called during startup if the parameter AF16X2LCD_AUTOSTART is True
 +
Can be called multiple times to support more than one 16x2 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 AF16x2LCDStop(Handle:THandle):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Stop the AF16x2LCD 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 AF16x2LCD or INVALID_HANDLE_VALUE for the default display
 +
|-
 +
! Return
 +
| True if completed or False on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''AF16x2LCD 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 AF16x2LCDGetButton(Handle:THandle; Button:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the GPIO level of a button on the AF16x2LCD 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 AF16x2LCD or INVALID_HANDLE_VALUE for the default display
 +
|-
 +
! Button
 +
| The button to get the level for (eg AF16X2LCD_BUTTON_LEFT)
 +
|-
 +
! Return
 +
| The GPIO level of the button (eg GPIO_LEVEL_HIGH) or GPIO_LEVEL_UNKNOWN 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 AF16x2LCDBacklightOn(Handle:THandle):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Turn on the backlight on the AF16x2LCD 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 AF16x2LCD 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 AF16x2LCDBacklightOff(Handle:THandle):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Turn off the backlight on the AF16x2LCD 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 AF16x2LCD 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 AF16x2LCDBacklightColor(Handle:THandle; Red,Green,Blue:Byte):Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the backlight color on the AF16x2LCD 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 AF16x2LCD or INVALID_HANDLE_VALUE for the default display
 +
|-
 +
! Red
 +
| The Red value (0 for Off/1 for On)
 +
|-
 +
! Green
 +
| The Green value (0 for Off/1 for On)
 +
|-
 +
! Blue
 +
| The Blue value (0 for Off/1 for On)
 +
|-
 +
! 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 04:09, 24 April 2018

Return to Unit Reference


Description

Adafruit 16x2 Character LCD + Keypad Driver unit

The Adafruit 16x2 LCD + Keypad is a kit that includes both a 16x2 LCD display using the Hitachi HD44780 LCD controller as well as a custom PCB with an MCP23017 I/O expander to connect it to a Raspberry Pi (any model) using I2C. It is available in Monochrome or RGB Positive and Negative versions.

This unit ties together the various components needed to make one of these boards work with Ultibo by finding the correct I2C device, creating the MCP230XX GPIO device, creating the HD44780 Console device and registering all of it with the correct parameters for the Adafruit kit.

The unit also includes functions to read the 5 buttons on the board and control the LCD backlight.

You will find many LCD display boards based on the Hitachi HD44780 controller and this unit gives an example of how to assembler the available units to create your own driver for a different board.

Constants


AF16x2LCD specific constants AF16X2LCD_*
AF16X2LCD_CONSOLE_DESCRIPTION = 'Adafruit 16x2 LCD'; Description of AF16x2LCD device
 
AF16X2LCD_SIGNATURE = $000AF162;  
 
AF16X2LCD_MODEL_MONO = 0; LCD with Monochrome backlight
AF16X2LCD_MODEL_RGB = 1; LCD with RGB backlight;


AF16x2LCD GPIO pin GPIO_PIN_*
AF16X2LCD_PLATE_RS = GPIO_PIN_15; GPIO pin for the LCD RS line
AF16X2LCD_PLATE_RW = GPIO_PIN_14; GPIO pin for the LCD RW line
AF16X2LCD_PLATE_EN = GPIO_PIN_13; GPIO pin for the LCD EN line
AF16X2LCD_PLATE_D4 = GPIO_PIN_12; GPIO pin for the LCD D4 line
AF16X2LCD_PLATE_D5 = GPIO_PIN_11; GPIO pin for the LCD D5 line
AF16X2LCD_PLATE_D6 = GPIO_PIN_10; GPIO pin for the LCD D6 line
AF16X2LCD_PLATE_D7 = GPIO_PIN_9; GPIO pin for the LCD D7 line
AF16X2LCD_PLATE_RED = GPIO_PIN_6; GPIO pin for the Backlight Red LED
AF16X2LCD_PLATE_GREEN = GPIO_PIN_7; GPIO pin for the Backlight Green LED
AF16X2LCD_PLATE_BLUE = GPIO_PIN_8; GPIO pin for the Backlight Blue LED
 
AF16X2LCD_BUTTON_SELECT = GPIO_PIN_0; GPIO pin for the Select button
AF16X2LCD_BUTTON_RIGHT = GPIO_PIN_1; GPIO pin for the Right button
AF16X2LCD_BUTTON_DOWN = GPIO_PIN_2; GPIO pin for the Down button
AF16X2LCD_BUTTON_UP = GPIO_PIN_3; GPIO pin for the Up button
AF16X2LCD_BUTTON_LEFT = GPIO_PIN_4; GPIO pin for the Left button


Type definitions


AF16x2LCD specific types

PAF16x2LCDPlate = ^TAF16x2LCDPlate;

TAF16x2LCDPlate = record

Signature:LongWord; Signature for entry validation
Model:LongWord; Plate model (eg AF16X2LCD_MODEL_MONO)
Invert:LongBool; Invert polarity of Backlight (Active low if True)
I2C:PI2CDevice; I2C device for this plate
GPIO:PGPIODevice; GPIO (MCP23017) device for this plate
Console:PConsoleDevice; Console (HD44780) device for this plate


Public variables


AF16x2LCD specific variables

AF16X2LCD_MODEL:LongWord = AF16X2LCD_MODEL_RGB;
AF16X2LCD_I2C_ADDRESS:Word = $20;
AF16X2LCD_I2C_DEVICE:String = 'I2C0';


Function declarations


Initialization functions 

procedure AF16x2LCDInit;
Description: Initialize the AF16x2LCD unit and parameters
Note Called only during system startup 


function AF16x2LCDStart(Model:LongWord; Invert:Boolean; const Device:String; Address:Word):THandle;
Description: Start the AF16x2LCD driver and register the GPIO and Console devices associated with the display
Model The Adafruit 16x2 LCD Plate model (eg AF16X2LCD_MODEL_RGB)
Invert Invert the signal level for the LCD backlight (If True then GPIO_LEVEL_LOW equals On)
Device The I2C device that the MCP23017 I/O Expander on the LCD Plate is connected to
Address The I2C address of the MCP23017 I/O Expander on the LCD Plate
Return The handle of the AF16x2LCD on success or INVALID_HANDLE_VALUE on failure
Note This function will be called during startup if the parameter AF16X2LCD_AUTOSTART is True

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


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


AF16x2LCD functions 

function AF16x2LCDGetButton(Handle:THandle; Button:LongWord):LongWord;
Description: Get the GPIO level of a button on the AF16x2LCD display
Handle The handle of the AF16x2LCD or INVALID_HANDLE_VALUE for the default display
Button The button to get the level for (eg AF16X2LCD_BUTTON_LEFT)
Return The GPIO level of the button (eg GPIO_LEVEL_HIGH) or GPIO_LEVEL_UNKNOWN on failure 


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


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


function AF16x2LCDBacklightColor(Handle:THandle; Red,Green,Blue:Byte):Boolean;
Description: Set the backlight color on the AF16x2LCD display
Handle The handle of the AF16x2LCD or INVALID_HANDLE_VALUE for the default display
Red The Red value (0 for Off/1 for On)
Green The Green value (0 for Off/1 for On)
Blue The Blue value (0 for Off/1 for On)
Return True if completed or False on failure


Return to Unit Reference

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