Keypad Display Wildcard Users Guide

The Keypad/Display Wildcard^TM 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

COLD

COLD

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

Instructions for PDQ

#include <mosaic/allqed.h>
//__GNUC__ is true for Mosaic PDQ IDE
 
#ifdef __GNUC__
#include <wkpd.h>
#else
#include "library.h"
#include "library.c"
#endif

Instructions for QED/Q-line

#include "library.c"

#include "library.h"

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

Instructions for PDQ

MosaicPDQ\forth\demos\UART_Wildcard\kp_display_demo_includer_PDQ.4th

''Keypad_Test''

Instructions for QED/Q-line

WHICH.MAP 0=
IFTRUE 4 PAGE.TO.RAM  \ if in standard.map...
       5 PAGE.TO.RAM
       6 PAGE.TO.RAM
      DOWNLOAD.MAP
ENDIFTRUE

4 PAGE.TO.FLASH
5 PAGE.TO.FLASH
6 PAGE.TO.FLASH
STANDARD.MAP
SAVE

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.

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:

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,

KEYPAD .

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

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.

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

• Keypad dimensions

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:

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.

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.

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.

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.

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.

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.

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:

main

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

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);
     UpdateDisplay();
  }

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;
   while(!done)
   {  current_key = (int) Keypad();
       Chirp(1000);
        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.

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

UPDATE.DISPLAY.LINE ( line# -- )

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:

Character_4x20
0 Set_Display_Modulenum
Backlight_On
Init.DISPLAY

Now we can type in the following definition:

: SHOW.MESSAGE ( -- )
   CLEAR.DISPLAY
   " My favorite color is"  0 0 $>DISPLAY
   " purple."               1 0 $>DISPLAY
   UPDATE.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

SHOW.MESSAGE

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,

DISPLAY.BUFFER 1 0 BUFFER.POSITION XN+ 20 BLANK
" blue." 1 0 $>DISPLAY
1 UPDATE.DISPLAY.LINE

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
1 UPDATE.DISPLAY.LINE

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

CLEAR.DISPLAY

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

COMMAND>DISPLAY ( byte -- )

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:

: EXERCISE.KEYPAD  ( -- )
  INIT.DISPLAY    \ Initialize the display
  BEGIN
    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
  AGAIN
  ;

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.

• Download Keypad/Display Wildcard Schematics as printable PDF

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

Display Dimensions provided by Mosaic:

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

• Keypad dimensions

See also →

• Keypad Display C Demo
• Keypad Display Forth Demo
• Keypad/Display C Glossary
• Keypad/Display Forth Glossary
• Keypad dimensions