Girder plug-in for LCD/VFD displays

Version 2.8. MMcM 06/03

Files

These are the files contained in this archive and what purpose they serve.

readme.htm
This file.
LCD.dll
The Girder plug-in proper.
This file must be placed in the Plugins folder beneath where Girder is installed.
Device specific files.

simlcd.dll Simulated LCD

lcdrvr1.dll LCDriver 1.x

cfontzlcd.dll Crystalfontz

molcd.dll Matrix Orbital

paralcd.dll Parallel port

These files must be in the Windows path; it is simplest to put them in the same folder where Girder is installed. Only the file(s) for the device(s) being used is needed. However, there is no harm in installing them all. These are separate files because each depends on other device driver DLLs that may not be installed at all.
AllChars.gml
A Girder script for displaying all possible characters sixteen at a time. Useful for working out a custom character map.

Getting started

You can interface to the display directly or through LCDriver. LCDriver is a control panel applet that provides a standard driver that supports many kinds of displays and that can be used by multiple applications. (Unfortunately, multiple applications cannot use the display at the same time in the present version.) Any hardware that works with this driver ought to work with this plug-in. LCDriver can be downloaded from this site. If you want to use LCDriver, it should be installed, configured and tested before selecting LCDriver as the device.
An HD44780 LCD controller can be connected directly to a parallel (printer) port. The necessary simple circuit is outlined here and here.
A Windows device driver that gives low-level access to the parallel port is needed. This plug-in uses PortIO, which is available from this site. It should be installed before selecting Parallel as the device.
Once the hardware is installed and any driver has been installed, launch Girder and select the Settings menu item under File. Enable the LCD plug-in (check its checkbox and Apply).
With the LCD plug-in still selected in the dialog, click the Settings button.
Choose the device type that corresponds to the display being used. If there is an error right away loading a DLL, check that the necessary device specific file was installed along with any necessary driver.
Click the Test... button. Some simple text should be displayed. If not, double check the hardware connections and settings.
The plug-in is now ready for use with Girder.
The most interesting use is together with the DVDSpy plug-in, which generates events when the state of a software media player changes. These events are accompanied by payload text, which can be displayed using variable pldn. See the readme file for that plug-in for more details. A sample Girder file is included that displays some information in a format suitable for 4x20 displays.

Use

This plug-in displays bits of text on chosen area of the display. The area is specified by the starting row and column and the number of characters. The text can come from several places:

A fixed string, possibly expanding variables.
The contents of a string variable, as set by some other plug-in, or the event payload.
The current date and time, formatted using a strftime control string.

A number of lines of the display can be filled at once. This does not give as fine control over placement or width. It is most suitable when a number of variables are being expanded in the text.

Several special actions that are also possible:

Clearing the display.
Closing the display so that it can be used by other applications.
The contents of a string variable, interpreted as a filename. Any directory and file type portion of the name are stripped before display.
Displaying a single character (such as a control character), given its integer code.

Hardware specific capabilities

Contrast and Brightness
Most LCD displays have software contrast controls. Most VFD displays have software brightness controls. Some backlit LCD displays have software brightness control for the backlight. One or the other of contrast and brightness can be set in the plug-in Settings dialog.
Marquee mode
Crystalfontz devices support a continuous horizontal scrolling display one line of the display. This works both with LCDriver and the direct serial connection. Text that is too large to display all at once (up to twice the width of the display) can be displayed in this way by choosing Marquee. The text occupies the entire row; neither the starting column nor the width is given. If the actual text fits in the row, it is just displayed normally. For other kinds of devices, marquee is simulated, with a lot more flickering, by redrawing the entire row periodically. Crystalfontz displays can scroll by less than a single character width; the simulated display always draws whole characters.
Custom characters
Most displays allow up to eight application defined characters. This plug-in takes care of managing the allocation of custom character indices based on what is being displayed. The command specifies the position on the display and the bits that make up the character.
The character definition consists of eight numbers, one for each row. The five least significant bits of each number are the five dots of the row, with the most significant bit on the left. For conventience, 0b is allowed as a number prefix for binary numbers. So, for example,
```
    0b11110
    0b10001
    0b10001
    0b11110
    0b10100
    0b10010
    0b10001
```
is shaped like a capital R.
Keypad input
Some Matrix Orbital displays have a keypad row/column matrix, which can be wired to a keypad membrane overlay (or a bunch of push buttons). If enabled in the plug-in Settings dialog, pressing a keypad button will generate a Girder event.
General purpose output
Most Matrix Orbital displays have one or more general purpose outputs (GPOs). These are low-current 5VDC outputs suitable for connecting to LEDs, fans, and relays. If the chosen display has GPOs, there is a special action to turn one on or off.

LUA functions

The following functions are defined in LUA so that the display can be controlled directly from a script.

LCD_Size()
Return the size of the display as two numbers (width, height).
LCD_Close()
Close the display.
LCD_String(row, column, width, string)
Display the given string at the given position. If width is negative, the rest of the line is used. If column is negative, a marquee is started on the given row.
LCD_CustomCharacter(row, column, bits)
Display the given custom character at the given position.

Registry

Settings for the plug-in are stored in the registry key HKEY_LOCAL_MACHINE\Software\Girder3\SoftPlugins\LCD. Most, but not all, are controlled through the Settings dialog. Here is a complete reference to the values used.

Library The name of the DLL containing the device specific interface.
Device The name of the specific device being used; often the display model number.
Cols The number of columns.
Rows The number of rows.
CharacterMap The device code to use for each character. Many displays put characters like ¥ where \ and ~ should be. Most displays have accented European characters at non-standard indices. Some displays have variants of g, j, p, q, and y with proper descenders at different codes; since the underline cursor is not used, these can yield a superior display.
MarqueePixelWidth The number of pixels to shift a scrolling display each time. By convention, 6 pixels represents a single character when computing the frequency of the simulated marquee, which cannot scroll by a partial character. The default is 6.
MarqueeSpeed The interval, in milliseconds, between shifts of a scrolling display. When simulating a marquee, both the speed and pixel width are taken into account when computing the frequency of redrawing. The default is 1000, that is, one second.
Contrast The contrast setting for an LCD. A number between 0 and 100. The default is 50.
Brightness The brightness setting for a VFD, or the backlight brightness for a backlit LCD. A number between 0 and 100. The default is 50.
EnableInput Translate keypad button presses into Girder events.
Port The name of the serial port device, such as COM1.
PortSpeed The speed of the serial port, such as 9600.
PortRTS Whether RTS is turned on for the serial line. The default is on.
PortDTR Whether DTR is turned on for the serial line. The default is on.
MarqueeSimulated For LCDriver, whether a marquee is simulated in software. Necessary when using LCDriver with a display other than Crystalfontz.
ParallelStrobeDelay The interval, in milliseconds, to wait for the HD44780 to notice a signal transition. If you have a slow HD44780, try increasing this number.
ParallelCommandDelay The interval, in milliseconds, to wait for the HD44780 to process a command or shift the data register. If you have a slow HD44780, try increasing this number.
SimLCDFontSize The font size in the Simulated LCD window. The default is 10.
SimLCDFont The font face name in the Simulated LCD window. The default is Courier New.
SimLCDFontStyle The font style in the Simulated LCD window. The default is Bold.
SimLCDTextColor The text (foreground) color in the Simulated LCD window. A single RGB value. The default is black.
SimLCDBackColor The background color in the Simulated LCD window. A single RGB value. The default is a greenish yellow.
SimLCDXPos The X position of the Simulated LCD window. The default is the last position.
SimLCDYPos The Y position of the Simulated LCD window. The default is the last position.
SimLCDAlwaysOnTop Whether the Simulated LCD window stays on top of other windows. The default is on.
DebounceTime The debounce time for a keypad in milliseconds. The default for Matrix Orbital is 52ms.

Terms

This plug-in is released as open source under The MIT License. You use it at your own risk. See license.txt for details.

Contact

To report problems or make suggestions, post a message to the Girder forum, rather than sending email directly.

`simlcd.dll`	Simulated LCD
`lcdrvr1.dll`	LCDriver 1.x
`cfontzlcd.dll`	Crystalfontz
`molcd.dll`	Matrix Orbital
`paralcd.dll`	Parallel port

`Library`	The name of the DLL containing the device specific interface.
`Device`	The name of the specific device being used; often the display model number.
`Cols`	The number of columns.
`Rows`	The number of rows.
`CharacterMap`	The device code to use for each character. Many displays put characters like `¥` where `\` and `~` should be. Most displays have accented European characters at non-standard indices. Some displays have variants of `g`, `j`, `p`, `q`, and `y` with proper descenders at different codes; since the underline cursor is not used, these can yield a superior display.
`MarqueePixelWidth`	The number of pixels to shift a scrolling display each time. By convention, 6 pixels represents a single character when computing the frequency of the simulated marquee, which cannot scroll by a partial character. The default is `6`.
`MarqueeSpeed`	The interval, in milliseconds, between shifts of a scrolling display. When simulating a marquee, both the speed and pixel width are taken into account when computing the frequency of redrawing. The default is `1000`, that is, one second.
`Contrast`	The contrast setting for an LCD. A number between 0 and 100. The default is `50`.
`Brightness`	The brightness setting for a VFD, or the backlight brightness for a backlit LCD. A number between 0 and 100. The default is `50`.
`EnableInput`	Translate keypad button presses into Girder events.
`Port`	The name of the serial port device, such as `COM1`.
`PortSpeed`	The speed of the serial port, such as `9600`.
`PortRTS`	Whether RTS is turned on for the serial line. The default is on.
`PortDTR`	Whether DTR is turned on for the serial line. The default is on.
`MarqueeSimulated`	For LCDriver, whether a marquee is simulated in software. Necessary when using LCDriver with a display other than Crystalfontz.
`ParallelStrobeDelay`	The interval, in milliseconds, to wait for the HD44780 to notice a signal transition. If you have a slow HD44780, try increasing this number.
`ParallelCommandDelay`	The interval, in milliseconds, to wait for the HD44780 to process a command or shift the data register. If you have a slow HD44780, try increasing this number.
`SimLCDFontSize`	The font size in the Simulated LCD window. The default is `10`.
`SimLCDFont`	The font face name in the Simulated LCD window. The default is `Courier New`.
`SimLCDFontStyle`	The font style in the Simulated LCD window. The default is `Bold`.
`SimLCDTextColor`	The text (foreground) color in the Simulated LCD window. A single RGB value. The default is black.
`SimLCDBackColor`	The background color in the Simulated LCD window. A single RGB value. The default is a greenish yellow.
`SimLCDXPos`	The X position of the Simulated LCD window. The default is the last position.
`SimLCDYPos`	The Y position of the Simulated LCD window. The default is the last position.
`SimLCDAlwaysOnTop`	Whether the Simulated LCD window stays on top of other windows. The default is on.
`DebounceTime`	The debounce time for a keypad in milliseconds. The default for Matrix Orbital is 52ms.