Girder plug-in for LCD/VFD displays

Supported displays

Files

These are the files contained in the distribution 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.
  

  cfontzlcd.dll	Crystalfontz
  futabavfd.dll	Futaba
  imonvfd.dll	SoundGraph iMON
  lcdhype.dll	LcdHype
  lcdrvr1.dll	LCDriver 1.x
  molcd.dll	Matrix Orbital
  noritakevfd.dll	Noritake
  noritakepvfd.dll	Noritake (parallel)
  paralcd.dll	Parallel port
  simlcd.dll	Simulated LCD
  vlsyslis.dll	VLSystem L.I.S.

  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.

• LCDTests.gml
  A Girder script for basic testing of drawing and command capabilities. It includes commands for displaying all possible characters sixteen at a time. This is 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, or if there is an error opening the device, 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

• 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). Some Crystalfontz displays have lighted push buttons. If enabled in the plug-in Settings dialog, pressing a keypad button will generate a Girder event. No attempt is made to make the events compatible from one display to another. Furthermore, some displays generate separate press and release events.

• 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 and relays. If the chosen display has GPOs, there is a special action to turn one on or off.

• Fans
  Some displays have high-current 12VCD outputs suitable for connecting to a fan. The power to a fan can be regulated by setting the pulse width modulation (PWM) duty cycle. If the chosen display has such fan controls, there is a special action to set the power level.

  These displays generally also have a means of monitoring how fast the fan is turning. This can generate an event.

• Temperature sensors
  Some displays support the Dallas 1-wire (DOW) sensor bus. Up to 32 temperature sensors can be daisy chained to this bus and used to monitor temperature at various points. This can generate an event.

LUA functions

• 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.
• lcd.GPO(gpo, on/off)
  Set the given GPO state.
• lcd.FanPower(gpo, power)
  Set the given fan's power (PWM duty cycle). power is a fraction: 0 for no power and 1 for full power.
• lcd.Raw(string)
  Output the raw bytes of the given string without any regard to the state of the display. The bytes are by definition not portable from one display device to another.
• lcd.GetSetting(key)
  Return a registry setting for the display device. key is one of the registry values described below.
• lcd.SetSetting(key, value)
  Change a registry setting for the display device. The change takes effect the next time the device is opened.

Multiple displays

Registry

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.
InputMap	This is actually a subkey. Each of its values maps a raw keypad input to an event. If the default value is *, unknown inputs are sent through as is.
EnableFans	Translate fan RPM changes into Girder events.
FanInterval	The interval in milliseconds between checks of the fans.
Fans	This is actually a subkey. Each of its values gives the name for a fan. If the fan number starts with *, the fan is disabled. The default value specifies the number of pulses per revolution needed to calculate RPM.
EnableSensors	Translate temperatute sensor changes into Girder events.
SensorInterval	The interval in milliseconds between reads of the sensors.
Sensors	This is actually a subkey. Each of its values gives the name for a sensor. If the sensor unique id starts with *, the sensor is disabled.
Port	For serial devices, the name of the port, such as COM1. For parallel devices, the name of the port, such as LPT1, or its hex address.
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 delay interval to wait for the HD44780 to notice a signal transition. If you have a slow HD44780, try increasing this number. If you have a fast HD44780, you may be able to decrease this number to a fraction of a millisecond.
ParallelCommandDelay	The delay interval to wait for the HD44780 to process a command or shift the data register. If you have a slow HD44780, try increasing this number. If you have a fast HD44780, try decreasing it.
ParallelExtraDelay	The delay interval to wait for the HD44780 to initialize or clear the screen. If you have set the command delay very small, you may need to increase this number.
SimLCDFontSize	The font size (height) for LcdHype and the Simulated LCD window. The default is 10.
SimLCDFontSizeW	The font width for LcdHype or 0 to keep it proportional to the height. The default is 0.
SimLCDFont	The font face name for LcdHype and the Simulated LCD window. The defaults are Lucida Console and Courier New respectively
SimLCDFontStyle	The font style for LcdHype and the Simulated LCD window. The defaults are Regular and Bold respectively.
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.
Enabled	Whether the display is enabled. Only available when there is more than one display defined.

Delay intervals can be specified as an integer number of milliseconds or a floating point fraction of a second. The fractional format supports intervals less than one millisecond.

Terms

Contact