Link here

Keypad Display Wildcard Users Guide

The Keypad/Display WildcardTM provides a convenient interface to a 4 x 20 character display and 4 x 5 keypad. Combined with Mosaic's QCard (running the V4.xx kernel) or the PDQ Board (running the V6.xx kernel), it is an ideal solution for hand-held or space-constrained applications that require a programmable embedded computer and a low-cost yet smart user interface.

  • Measuring only 2" x 2.5", the Keypad/Display Wildcard mounts directly on a QCard Controller or PDQ Board.
  • This Wildcard is shipped with a 4x20 LED-backlit character display and 4x5 keypad, plus a simple ribbon cable interface for custom placement of the keypad and display in your instrument.
  • It has an additional field header that brings out 4 nibble-wise programmable input/output lines and 4 input lines.
  • This Wildcard also contains an onboard 2 KHz buzzer to provide audible feedback for keypad presses, or any other purpose.

The Keypad/Display Wildcard provides a hardware and software interface for a 5x4 keypad and 4x20 liquid crystal display (LCD). These devices connect to the Wildcard via a simple "straight-through" ribbon cable interface. Pre-coded routines (available to both C and Forth programmers) scan the keypad and write to the LCD display.

Technical Specifications
Property Value
Power: 5 VDC from the Wildcard bus at 110 or 160 mA (0.55 W with backlight OFF or 0.80 W with its LED-backlight ON).
Keypad: 5 column by 4 row keypad, tactile feedback, snap-on domes for user-configurable legends, mounting hole size 2.7" x 3.0", standard Grayhill part, interchangeable with other sizes.
Display: 4 line by 20 character LCD display with optional LED backlight
Backlight: LED backlight with software ON/OFF.
Beeper: Software controlled 2 KHz, 0.2 W buzzer at 80 dB
General Purpose I/O: 4 input lines and 4 lines programmable together as all inputs or all outputs with the same pin electrical characteristics as those of the Digital I/O Wildcard
Output current capability: 4mA source, 24mA sink
Connectors: 34-pin dual row 0.1" pitch keypad/display connector
24-pin dual row 0.1" pitch field I/O connector
Weight: 26 gram (board alone, without keypad, display and cable)
Size : 2" x 2.5" x 0.38"1) (50.8mm x 63.5mm x 9.7mm)
Version Compatibility
Note that if you have a Keypad/Display Wildcard with a serial number beginning with only 3 decimal digits rather than 4 decimal digits, it predates the development of the PDQ Board, and will only work reliably with the QCard Controller. In addition, some special versions with a "Q" sticker on one of the square CPLD chips will also not work reliably with the PDQ Board.

Connecting the Wildcard

The Wildcard is shown in Figure 1. On the right the Wildcard Port Header, H1, connects to the QCard or PDQ Board Controller, and on the left the Field Header, H4, provides 8 lines of digital I/O. The 34-pin connector on the side, H2, connects to a ribbon cable to the keypad and display.

Headers and Jumpers on the Keypad/Display Wildcard
Fig. 1  Headers and Jumpers on the Keypad/Display Wildcard.

Mounting on a QCard or PDQ Board controller

With the power off, the Wildcard may be mounted on a QCard, PDQ Board, or PowerDock by directly plugging connector H1 into a Wildcard Port connector on the controller. The corner mounting holes on the module should line up with the standoffs on the controller.

The Wildcard bus does not have keyed connectors. Be sure to insert the module so that all pins are connected. The Wildcard bus and the Wildcard can be permanently damaged if the connection is done incorrectly.

Setting the module address

Each Wildcard Port accommodates up to four Wildcards, at four different module addresses: 0, 1,2, or 3 if installed on Port 0, and 4, 5, 6, or 7 if installed on Port 1. A PDQ Board has two Wildcard ports, and the QCard has only one Wildcard port, Port 0. Even so, if the QCard is mounted on a PowerDock it can hold four Wildcards on the QCard, and four more on Port 1 of the PowerDock. You should set the module addresses on the Wildcards in your system so that they do not conflict, that is, so that no two modules on the same port have the same address (jumper settings). Jumpers J1 and J2 allow you to select the module address.

Important - Set the module address jumpers
On the QCard platform, the Keypad/Display Wildcard must be configured at module address 0 to properly access the software drivers. On the PDQ Board platform, any module address from 0 to 7 can be specified. Use the following table to determine the jumper settings you need for each module address. In the application code, declare the module (Wildcard) address using the function Set_Display_Modulenum; the declared module address must match the hardware jumper settings.
Address Jumper Settings
Wildcard Port Wildcard Address Installed Jumper Shunts
0 0 None
0 1 J1
0 2 J2
0 3 J1 and J2
1 4 None
1 5 J1
1 6 J2
1 7 J1 and J2
Note:On the QCard Controller, you must use address 0. The Keypad/Display Wildcard may not be used with the QScreen or other controllers with integrated graphics.

Setting the jumpers

There are six jumpers on the board allowing you to select various options. Table 1-3 describes their purposes and default settings.

Table 1-3 Default jumper positions.

Jumper Default Setting Meaning
J1 Removed Module address bit. Together with J2 chooses module addresses of 0-3; see Table 1-2.
J2 Removed Module address bit. Should be removed in normal operation to choose page 0 addresses; see Table 1-2.
J3 Connected Enables the onboard beeper. Remove to disable the beeper.
J4 Connected Enables the onboard contrast adjustment potentiometer. Remove if an external pot is used to adjust the display contrast.
J5 Connected Chooses the display type: connected for a Hitachi character or graphics display controller; or removed for a Toshiba graphics display controller. Standard Wildcards ship with a Hitachi-type character display.
J6 Set to "Char" Chooses either a 4x20 character or a graphics display. Standard Wildcards ship with a character display.

Connecting a keypad and display

The keypad/display interface connector, H2 in the photo, is a 34-pin dual-row right-angled header. A 34-line ribbon cable plugs into this header. At the other end of the cable are two female single-row connectors: one at the end for the keypad, and the other in the middle for the display.

The 34-pin female connector should be plugged into H2 with the ribbon exiting the connector toward the board. Line 1 in the ribbon cable (on the edge of the cable that the 10-pin keypad connector is aligned along) mates with pin 1 of H2, closest to the field header, H4.

Important - Maximum Cable Length
The maximum total length of the 34-pin ribbon cable connecting the keypad and display to the Keypad/Display Wildcard is 22 inches (55cm). In some cases in which there is significant load on the Wildcard bus (i.e. a full stack of eight Wildcards), or under extreme temperatures, a shorter cable may be necessary for reliable display operation.

Connecting the keypad

The 10-pin connector on the end of the ribbon cable should connect to the keypad. Take care – the keypad has only 9 pins! The connector should be attached so that pin 1 on the keypad (designated by the "F" on the Grayhill 20-key keypad, Part No. 86JB2), and on the left looking at the back of the keypad with the connector at the top), corresponds to pin 1 on the cable (the edge of the cable that terminates on the Wildcard closest to the field header, H4). In operation, the keypad is oriented so that its connector is on the back at the bottom of the keypad.


Connecting the display

The Wildcard can accommodate liquid crystal display modules up to 4 lines by 20 characters in size. If your display still has a clear plastic cover to protect the display glass from scratches during shipment don’t forget to peel it off.

The processor sends control commands and ASCII data to the display and powers its backlight through a 16-pin bus. The 16-pin single-row female connector on the ribbon cable connects directly to the display pins at the top rear of the display. The edge of the cable to connect to pin 1 of the display (nearest the display’s corner) is the one aligned with pin 1 of the Wildcard’s header H2, and closest to the field header on the Wildcard. It is also the edge closest to the keypad connector. In its standard orientation, the display connector is at the top back of the display, and the display has 4 lines and 20 characters per line.


Powering the Wildcard

The Keypad/Display Wildcard derives its power from the Wildcard bus so it is automatically powered when plugged in. It should not be hot-inserted into an active controller however. Instead, you should turn off power, install all Wildcards, then power up your system.


Adjusting the contrast and attaching an external contrast control

A contrast potentiometer is located on the board. The Wildcard is shipped with a high-contrast "supertwist" LCD display that has a wide viewing angle. In most applications the contrast/viewing angle potentiometer can be left in its default setting, as shipped from the factory, with no adjustments required. If you wish to change the contrast setting, simply twist the potentiometer using a small screwdriver. While the 4x20 character displays provide good contrast over a wide viewing angle at a fixed contrast value, the contrast may need to be readjusted if the temperature changes significantly.

An additional three wires on the Keypad/Display cable bring out +5V, V_Contrast, and VEE/GND, respectively. These signals also are provided on the field header, H4. You can connect a panel-mounted potentiometer to these three signals on either connector if your application requires external control of the display’s contrast and/or viewing angle. To do so, connect the endpoints of a 10K potentiometer to +5V and VEE/GND and run its centertap to V_Constrast. Jumper J4 should be removed, and J6 set to either "Char" or "Graphics" for the display type used.



A package of pre-coded device driver functions is provided to make it easy to control the Keypad/Display Wildcard. This code is available as a pre-compiled "kernel extension" library to C and Forth programmers. Both C and Forth source code versions of a demonstration program are provided. This demo program illustrates how to initialize and control the keypad, display, backlight, and beeper on the Keypad/Display Wildcard.


Installing the Keypad/Display Wildcard driver software

The Keypad/Display Wildcard device driver software is provided as a pre-coded modular runtime library, known as a kernel extension library because it enhances the on-board kernel's capabilities. The library functions are accessible from C and Forth.

Instructions for PDQ Board platform

Instructions for QCard platform


Using the driver code with the C language

The C demo is located in your installation directory. It is also provided here for reference.

Instructions for PDQ

Instructions for QED/Q-line


Using the driver code with Forth

The Forth demo is located in your installation directory. It is also provided here for reference.

Instructions for PDQ

Instructions for QED/Q-line


Using the keypad

The keypad offers a simple yet effective means for an operator to control a computer-based instrument. By pushing a keypad button, the user shorts a "row" circuit to a "column" circuit. Your controller’s driver hardware and software detect the connection by reading the 4 rows as digital inputs, and holding them in a default "high" state with pull-up resistors. Each of the 5 columns is connected to a digital output. The processor scans each column low in turn and reads each of the row inputs to see if it has been pulled low. If it has, the processor deduces that a user is holding down the key at the intersection of that row and column.

By scanning the rows and columns, the processor can identify which key was pressed. The routines of Table 1-4 are pre-coded software driver functions; they scan the keypad and report which (if any) key is being depressed. Using these routines we can take any desired action based on input obtained from the keypad. Consult the Keypad/Display Wildcard C Glossary or Forth Glossary for detailed descriptions of these routines.

Table 1-4 Keypad driver functions.

C Name Forth Name Function
ScanKeypad ?KEYPAD Scans the keypad and if a key is being pressed it waits for a key release, returning with the key number. Calls Pause while waiting to enable multitasking. If no key is being pressed, it returns immediately with a -1.
ScanKeypress ?KEYPRESS Scans the keypad returning with its current state: either –1 for no key pressed or the key number. Does not wait for a key release. ScanKeypress provides a way of monitoring the state of the keypad without "tying up" the processor while waiting for a key to be released. When using ScanKeypress, make sure that multiple calls to your program do not misinterpret a single keystroke as multiple entries from the keypad.
Keypad KEYPAD Waits for a key release and returns with the key number on key release. While waiting, it calls Pause to give other tasks a chance to run.

These software drivers refer to keys by numbers from 0 through 19. Key 0 is the lower right key, Key 1 is directly above it, and Key 19 is the upper left key. The keys are oriented as:

19 15 11 7 3
18 14 10 6 2
17 13 9 5 1
16 12 8 4 0

For example, if the user presses and releases the key in the upper right corner while the KEYPAD routine is running, the number 3 will be returned. For example, from the Forth prompt you can type in,


and the controller will wait for a key press, typing the key number when it is released.

Table 1-5 summarizes the pinout of the 34-pin Keypad/Display Header.

Table 1-5 H2: Keypad/Display Header

Signal Pins Signal
KPC4 1 2 GND
KPC3 3 4 +5V
KPR3 5 6 V_Contrast
KPR0 7 8 Display_A1
KPC2 9 10 Display_R//W
KPR1 11 12 Display_E
KPR2 13 14 Display_D0
KPC1 15 16 Display_D1
KPC0 17 18 Display_D2
+5 19 20 Display_D3
V_Contrast 21 22 Display_D4
VEE/GND 23 24 Display_D5
+5 25 26 Display_D6
/BEEPER_ON 27 28 Display_D7
DIO_0 29 30 LED Backlight+
DIO_1 31 32 LED Backlight-
DIO_2 33 34 VEE
Note: Keypad connections are aligned along one side and the display connections
are aligned along the other side. Keypad signals on odd-numbered pins 1-17 are
tapped from the cable by a 10-pin single-row female connector (of which only
pins 1-9 are used), and the display signals on even-numbered pins 2-32 are
tapped by a 16-pin single-row female connector.

Customizing the keypad legends

The keypad has removable transparent key caps so that you can insert customized legends into the keys. You can easily print your customized legend, logo or text onto paper, cut it to size, and insert it into the keys.


Mounting the keypad

When you are ready to use the keypad for instrumentation, please consult the following diagram for mounting guidance:


Using the general purpose I/O

Eight lines of general purpose digital I/O are provided for your use. These lines are provided on the Wildcard’s Field Header, H4, at the pin locations shown here:

H4: Field Header
Signal Pins Signal
GND 1 2 +5V
+5V 3 4 V+Raw
V_Contrast 5 6 VEE/GND
+5V 7 8 /BEEPER_ON
DI_7 9 10 DI_6
DI_5 11 12 DI_4
DIO_3 13 14 DIO_2
DIO_1 15 16 DIO_0
NC 17 18 NC
NC 19 20 NC
NC 21 22 NC
NC 23 24 NC
Note: Four general purpose digital input/outputs DIO_0-DIO_3 are brought
out to pins 13-16, and four inputs DI_4-DI_7 are brought out to pins 9-12.

I/O lines DIO_0 through DIO_3 are group-configurable as either inputs or outputs, and DI_4 through DI_7 are always inputs input lines. These lines exhibit the same pin electrical characteristics as those of the Digital I/O Wildcard – consult its manual for electrical drive capability and logic levels.

Several bytes of memory, starting at offset 0 from the memory-mapped Wildcard base address, are used to communicate with the Wildcard. Table 1-7 summarizes the Wildcard memory map; this information is labeled "for experts" because it is not needed to control the Wildcard. Rather, a set of pre-defined drivers makes it easy to control the beeper, backlight, and digital I/O on the Wildcard.

Eight digital I/O lines called "extra IO" are arranged as a single byte comprising two nibbles of four lines each. The lower nibble named DIO_0 through DIO_3 is group-configurable as either inputs or outputs, and the upper nibble lines, DI_4 through DI_7, are always inputs. The driver function Set_Extra_IO_Direction sets the direction of the lower nibble at bits 0-3; pass it a true flag to set the nibble as outputs, or a false flag to leave the nibble as inputs (the default). The Read_Extra_IO function returns the current logic levels on the Extra IO port (1 = high, 0 = low). The Write_Extra_IO function sets the logic levels of any bits configured as outputs.

For experts: Keypad/Display Wildcard memory map.
Module Offset Bit Positions Meaning
0x02 0 A write of 1 to the least significant bit turns on the beeper, 0 turns it off.
0x02 1 A write of 1 turns on the backlight, 0 turns it off.
0x0D 0-3 Either inputs or outputs
0x0D 4-7 Digital inputs
0x0E 0 A write of 1 configures the lower nibble of offset 0x0D to all outputs; resetting to 0 configures the nibble to all inputs.

Controlling the beeper

The beeper on the Wildcard is controlled by the pre-coded Chirp routine in the Keypad-Display Wildcard driver. Simply pass this routine the number of microseconds (from 1 to 65,535) that you wish the beeper to sound. Very short durations may be inaudible. Passing decimal 1000 activates the beeper for 1 millisecond, providing a clicking sound that provides effective feedback for keypresses. Significantly longer durations will have a more tonal sound. If the shorting bar is removed from jumper J3 the beeper is disabled. An external device capable of sinking 40 ma. can also turn on the beeper by pulling pin 27 on header H2, or pin 8 on the field header H4, to ground. A bipolar transistor, FET or switch can be used.


Controlling the backlight

The LED display backlight on the Wildcard is turned on by the pre-coded Backlight_On routine in the Keypad-Display Wildcard driver. The Backlight_Off function turns the backlight off.


Driver Functions for the beeper, extra I/O, and backlight

Table 1-8 summarizes the driver functions for the Beeper, Extra I/O, and Backlight as described in the previous sections.

Table 1-8 Beeper, Extra I/O, and Backlight Driver Functions.

C Name Forth Name
Backlight_Off Backlight_Off
Backlight_On Backlight_On
Chirp Chirp
Read_Extra_IO Read_Extra_IO
Set_Extra_IO_Direction Set_Extra_IO_Direction
Write_Extra_IO Write_Extra_IO

Using the display

Your controller includes built-in software drivers for an LCD up to 4 lines by 20 characters in size. A ribbon cable connects the board to the display.

Since displays are controlled differently depending on their size and type, your controller must be configured for the kind of display that is present. A built-in library function named Character_4x20 properly declares the display as a 4-line by 20-character display. If you use a non-standard display, it can be declared using the lower-level routines IsDisplay in C (or IS.DISPLAY in Forth); see the C Glossary or Forth Glossary for details. Fortunately, your controller stores the display configuration information in non-volatile EEPROM that retains its data even when power is removed, so you don’t have to reconfigure the board after each power-up. Both character and graphics displays are pre-configured at the factory to operate in "text mode", so all of the sample code described here will work without further configuration on your part.

As described above, the Set_Display_Modulenum function declares the module number of the Keypad/Display Wildcard. On the QCard platform, module number 0 must be used, and Set_Display_Modulenum prints a warning if a non-zero module number is specified. On the PDQ Board platform, any module number in the range 0 to 7 can be specified using Set_Display_Modulenum. In all cases, the hardware jumpers J1 and J2 must be set to correspond to the declared module number as described in setting-the-jumpers.

The display interface is based on a simple idea: you write the desired characters to a display buffer in the controller’s RAM, and then use the pre-coded UpdateDisplay function (or UPDATE.DISPLAY in Forth) to transfer the contents of the buffer to the display. You control a character display by writing ASCII characters or strings to a 4 line by 20 character buffer in RAM using STRING_TO_DISPLAY ($>DISPLAY in Forth) and then executing UpdateDisplay (UPDATE.DISPLAY in Forth) to make the contents visible.

Additional pre-coded routines allow you to control the cursor and write individual data and control symbols to the display. To get a feel for the capabilities of these functions, you can browse through the Keypad/Display Wildcard C Glossary or Forth Glossary.

Table 1-9 lists the display driver functions.

Table 1-9 Display driver functions.

C Name Forth Name
Character_4x20 Character_4x20
Set_Display_Modulenum Set_Display_Modulenum
UpdateDisplayRam (UPDATE.DISPLAY)

These functions allow lots of flexibility in using the display, but as discussed below, you really need only a few to make it work well in most applications.


Programming the display in C

Table 1-4, Table 1-8 and Table 1-9 provide the function names for the keypad, display and other I/O on this Wildcard. An informative C demonstration program is available here, and instructions for loading the C demo are presented here. After compiling and downloading the demo program, simply type main from the terminal window. Several things should happen:

When you run the program you should see the following message on your LCD display:

Welcome! Press any
keypad button to see
how the display and
keypad work together

If you press any button on the keypad, you should see the message

I’d rather be...

on the first line, followed by a message on the second line that varies depending on the column of the keypad button that you choose. Try it out. To terminate the test, push a button in the left-most column of the keypad; you’ll see the message

I’d rather be...
Done with this test.

Now if you type carriage returns from your terminal, the QED-Forth monitor will respond with the "ok" prompt, meaning that it is ready for the next command.

You can type:


from your terminal any time you like, and the main function as defined in the latest download file will be executed.


Writing to the LCD display

Let’s take a look at the definition of the ShowMessage function whose source code can be found near the bottom of the wkpddemo file. This function writes a message to the LCD Display. The definition of the function is:

_Q void ShowMessage(void)
  {  STRING_TO_DISPLAY("Welcome! Press any  ", 0, 0);
     STRING_TO_DISPLAY("keypad button to see", 1, 0);
     STRING_TO_DISPLAY("how the display and ", 2, 0);
     STRING_TO_DISPLAY("keypad work together", 3, 0);

The _Q keyword declares this function as one that can be interactively called, and the void keywords tell the compiler that this function does not expect any input parameters and does not return a value. Each of the first four lines in the definition specifies the contents of a line on the display. The STRING_TO_DISPLAY macro expects three input parameters: a string pointer, the line number, and the character position. It writes the specified string into the display buffer (located in the controller’s RAM) starting at the specified line and character position. Note that each of the first four statements in the definition represents one line of the message, and the string is displayed starting at character position 0 (the left-most position) on each line. Lines are numbered 0 through 3 on a character display. Character positions are numbered 0 through 19 on a character display.

The fifth statement in ShowMessage calls the UpdateDisplay function which writes the contents of the display buffer to the display.

To show the welcoming message on the display without printing a message to the terminal or running the keypad demonstration, type from your terminal:

ShowMessage( )

followed by a carriage return. Be sure to type at least one space after the ( character. You should see the welcoming message appear on your LCD display. You will also see at your terminal a line of text that summarizes the return value of the function in several formats (decimal, hexadecimal, and floating point), followed by the "ok" prompt. Because the ShowMessage function does not return anything, the return value summary is not useful here. The "ok" prompt indicates that controller has successfully called the function and is now ready to execute another command.

For more information, consult the detailed descriptions of the STRING_TO_DISPLAY macro and the UpdateDisplay function in the C Glossary.



Now let’s take a look at the ManageKeypad routine whose source code appears just before ShowMessage in the wkpddemo.c file:

_Q void ManageKeypad(void)
{  int current_key, done = 0;
   {  current_key = (int) Keypad();
        switch(current_key / 4)
      {  case 0: idRatherBe("Sky Diving");   break; // col 0
         case 1: idRatherBe("Traveling"); break; // col 1
         case 2: idRatherBe("Watching TV");  break; // col 2
         case 3: idRatherBe("Eating");    break; // col 3
         case 4: idRatherBe("Done with this test.");
         done = 1;            break; // col 4

As described earlier, the _Q declaration tags the function as one that will be interactively callable from QED-Forth to speed debugging. The void keywords tell the compiler that this function does not return a value, and does not expect any input parameters. The first line declares an automatic (stack-based) variable named "done" and initializes it to zero. The next line is a while statement that runs until the "done" flag is true (nonzero). The body of the while loop is a switch statement that calls the Keypad function which waits for a keypress. The Chirp function gives a 1000 microsecond (1 millisecond) audible feedback indication after each key is released. Keypad returns the index of the selected key. This index is divided by 4 using truncating integer arithmetic as indicated by the (int) cast to calculate the selected keypad column number. The column number is used by the switch statement to select which message is displayed on the screen. If column 4 at the left of the keypad is selected, the "done" flag is set to true and the while statement terminates.

To interactively execute the function, simply type at your terminal:

ManageKeypad( )

followed by a carriage return; remember to type at least one space after the ( character. The function is now waiting for you to press a button on the keypad; once you do, you’ll see the message:

I’d rather be...

<selected string goes here>

on the display. The routine will continue to run until you choose a key in the leftmost column of the keypad. Then you will see the printed summary of the routine’s return value at your terminal, followed by QED-Forth’s "ok" prompt. The return value summary is not meaningful in this case because the ManageKeypad function does not return a value.


Programming the display in Forth

The operating system maintains an 80 character buffer whose base extended address (or xaddress) is returned by the routine,

DISPLAY.BUFFER ( -- xaddr )

The offset from the start of this buffer to a specified line and character position is returned by the routine,

BUFFER.POSITION ( line#\char# -- buffer.offset )

The user can write ASCII characters into this buffer using standard operators such as C! or CMOVE, or with the assistance of the handy utility routine

$>DISPLAY ( x$addr\line#\char# -- )

which is pronounced "string-to-display" (in Forth, $ is often used to represent a string).

$>DISPLAY moves the string starting at x$addr to the buffer starting at the specified line number (0, 1, 2, or 3) and character position (0 through 19) in the display buffer. This routine moves only as many characters as will fit on the specified line. Executing $>DISPLAY modifies the contents of the buffer but does not alter the display.

Placing the appropriate line number (0, 1, 2, or 3) on the stack and executing


transfers the specified line’s contents from the buffer to the display. Executing UPDATE.DISPLAY transfers all of the lines in the display buffer to the display.

Let’s try an example. First we initialize the display by typing at the QED Terminal window prompt:

0 Set_Display_Modulenum

Now we can type in the following definition:

   " My favorite color is"  0 0 $>DISPLAY
   " purple."               1 0 $>DISPLAY

SHOW.MESSAGE first executes CLEAR.DISPLAY which clears the display and fills the DISPLAY.BUFFER with ASCII blanks. The next two lines in the definition specify the contents of the top two lines of the display. The characters between the quotation marks specify a string to be moved to the display buffer, and the two numbers immediately preceding $>DISPLAY are the line number (numbered 0 through 3) and the character position (numbered 0 through 19) to which the string is moved. If you execute


the message will appear on the display.

To modify only the line reporting the color "purple" without changing the rest of the display, you could execute from the terminal,

" blue." 1 0 $>DISPLAY

The first command blanks line#1 in the display, eliminating the prior contents. BUFFER.POSITION calculates the offset to the start of line 1, and XN+ adds this offset to the DISPLAY.BUFFER base address to yield the start address of line# 1 in the buffer. BLANK then blanks the 20 characters on the line in the buffer. The following command line moves the string "blue." to the display buffer, and UPDATE.DISPLAY.LINE writes the new contents of line 1 to the display. Note that the top line of the display is unchanged.

We could have avoided the need for the BLANK command by making the new "color" string as long or longer than the original string on line 1. For example, the following two commands have the same effect as three commands above:

" blue.               "  1 0 $>DISPLAY

The extra trailing spaces in the string ensure that none of the prior string remains in the buffer.

To clear the display, fill the display buffer with blanks, and home the cursor to the upper left corner of the display, simply type


and of course executing SHOW.MESSAGE again replaces the original message on the display.

The routine INIT.DISPLAY initializes the display so that it is ready to accept characters, homes the cursor to the upper left position, and blanks the screen, cursor, and display buffer. This routine is executed upon every processor reset or restart on the QCard, but must be explicitly called from your high level routine on the PDQ Platform. It is good style to invoke INIT.DISPLAY from your application code on either platform. INIT.DISPLAY also initializes the system variable LINES/DISPLAY to 4 and the system variable CHARS/DISPLAY.LINE to 20.

Throughout the above examples you probably noticed that no cursor was visible on the display. This is because INIT.DISPLAY also turns the cursor off. You have full control over the cursor, however. The routine

DISPLAY.OPTIONS ( display.on?\cursor.on?\cursor.blinking? -- )

sets the cursor and display state based on the three flags passed to it on the stack. The first flag, called display.on?, specifies whether the display is enabled or disabled. This feature can be used to flash the display by rapidly enabling and disabling the display via successive calls to DISPLAY.OPTIONS. The second flag, called cursor.on?, specifies whether the cursor is visible as an underbar at the current cursor position. The top flag on the stack, called cursor.blinking?, specifies whether the cursor is visible as a blinking box obscuring the current character position. The default condition is: display enabled, cursor off, cursor not blinking. This condition applies after a reset, restart, or execution of INIT.DISPLAY. Try passing different flag combinations to DISPLAY.OPTIONS to see what the results are.

Several lower level utilities are available to the programmer. For example, the routine

PUT.CURSOR ( line#\character# -- )

places the cursor at the specified location on the display. Note that whether or not the cursor is visible depends on the configuration set by DISPLAY.OPTIONS. Once the cursor has been placed, each succeeding character written to the display appears at the cursor location and causes the cursor position to be incremented by 1. Please note, however, that in many displays the cursor does not advance smoothly as one might expect from the end of one line to the start of the following line! Please test your routines carefully when using these low level utilities to control the display.

To send a single character directly to the display at the current cursor position, bypassing the display buffer, execute

CHAR>DISPLAY ( char -- )

This automatically increments the cursor position (but note that the cursor may skip to the start of an unexpected line after the end of a line is reached). CHAR>DISPLAY does not update the contents of the DISPLAY.BUFFER.

To send a command character directly to the display, execute


If for some reason you need to send custom commands to the display, consult the display data sheet (available from Mosaic Industries) to determine the numerical value associated with each valid command. For example, the command byte that clears the display is 0x01.

The following routine uses both the keypad and display, showing on the display the key number of a pressed key:

  INIT.DISPLAY    \ Initialize the display
    PAUSE.ON.KEY  \ allows you to type a CR from the terminal to bail out of the loop
    " You pressed key#:" 0 0 $>DISPLAY  \ write to buffer
    KEYPAD        \ get the key number ( -- key# )
    1000 Chirp    \ give audible feedback
    S>D <# # # #> DROP 1XN- ( -- x$addr ) \ convert key# to a string
    1 0 $>DISPLAY  ( -- ) \ write key# to buffer
    UPDATE.DISPLAY \ write to display

After executing EXERCISE.KEYPAD, the identifier of each key that you press is displayed as a 2-digit number (in the current BASE) on the LCD display. Type a carriage return at the terminal and press one final key on the keypad to exit the routine.

The Keypad_Test function in the Forth demo code provides a more complete example. It allows the user to test the display by putting a grid of "X"s on the display, one "X" for each keypad button. Then as the user presses each key the corresponding "X" is removed. It also produces a key click on each key release, showing how to make beeps of a particular duration, and shows how to turn on the backlight. You can download the following code after any coldstart. The demo program is available at Keypad Display Forth Demo, and instructions for loading it are described here.


Keypad/Display Wildcard schematics

keypad display schematic
Fig. 2  Circuit schematic of Keypad/Display control logic.
lcd display schematic
Fig. 3  Circuit schematic of Keypad/Display connectors.

Keypad/Display Dimensions

This diagram details the dimensions of the display, including total height when connected to the supplied cable.

Display Dimensions provided by Mosaic: instrumentation:4-x-20-lcd-display-backlight-keypad:keypad-display-cable.png

The manufacturer of the keypad provides a dimensional diagram of the keypad.
Keypad Dimensions:

See also →

Height is from the bottom of the PCB to the top of the tallest component on the top side of the PCB.
This page is about: Keypad and LCD Display Module for Data Entry, Instrument Control – Control your instrument with a 4x20 LCD display and 4x5 keypad designed for front panel feedback and control. Keypad, 4x20 LCD Display, Embedded Display, Embedded Keypad, Beeper, Buzzer, operator control