Keypad/Display C Glossary

This glossary defines important constants and functions from the Keypad Display Wildcard driver code. This Wildcard is useful your instrumentation requires human interaction or control.

Backlight_Off

void Backlight_Off( void )

Turns off the LED backlight on the Keypad/Display Wildcard.

Backlight_On

void Backlight_On( void )

Turns on the LED backlight on the Keypad/Display Wildcard.

BufferPosition

uint BufferPosition( int line, int column )

Given the specified LCD display line number n1 [0 ≤ n1 < LinesPerDisplay] and the specified character position in the display line [0 ≤ n2 < CharsPerDisplayLine], returns the offset of the specified position relative to the base address returned by DisplayBuffer. Clamps the returned offset to ensure that it is not greater than the size of the buffer. Note that for a graphics-style display the input parameter "line" is interpreted differently depending on whether the display is being used in "text mode" or "graphics mode". In text mode, "line" corresponds to the character line#; in graphics mode, "line" corresponds to the pixel line#.

Character_4x20

void IsDisplay( void )

This function configures the software for the standard 4-line by 20 character text-mode (alphanumeric/Hitachi-style) display. Saves the display configuration in EEPROM so that the LCD display is properly initialized upon subsequent restarts and resets by the InitDisplay routine. The encoded information is accessible via the routines CharsPerDisplayLine and LinesPerDisplay. Note that because this routine saves the configuration information in EEPROM, you need not execute it each time the board starts up (but doing so has no adverse effects).

Type: _forth function
Forth name: Character_4x20
Header file: wkpd.h

CharsPerDisplayLine

int CharsPerDisplayLine( void )

Returns the number of characters per line in the LCD display as specified by the last execution of IsDisplay or Character_4x20; valid return values are 8, 12, 16, 20, 24, 30, and 40 characters per line. The result returned by this routine is used by BufferPosition, PutCursor, UpdateDisplay, and UpdateDisplayLine.

Type: _forth function
Forth name: CHARS/DISPLAY.LINE
Header file: intrface.h

CharToDisplay

void CharToDisplay( char c )

Writes the specified data byte c to the LCD display. Does not write to the Display Buffer. If an alphanumeric (character) display is being used, this command writes the specified ASCII character at the current cursor position and increments the cursor position. (Caution: the cursor does not always follow a contiguous path as it is incremented; there may be discontinuities at the ends of lines.) If a graphics display is in use, this function must be used in conjunction with a function that specifies the meaning of the data byte. Disables interrupts for up to 7 microseconds while the byte is written.

See also CommandToDisplay and UpdateDisplay.

Type: _forth function
Forth name: CHAR>DISPLAY
Header file: intrface.h

Chirp

void Chirp ( uint duration_microseconds )

Activates the beeper on the Keypad/Display Wildcard for a time period specified by duration_microseconds, which can be in the range from 1 to 65535 microseconds. Very short durations may not be audible. Specifying decimal 1000 microseconds (1 millisecond) produces a click that provides good audible feedback after a keypress. Longer durations produce a more tonal beep.

Type: _forth function
Forth name: Chirp
Header file: wkpd.h

ClearDisplay

void ClearDisplay( void )

Clears (blanks) the LCD display and moves the cursor to home position at the start of line 0. If a character display is in use [see Character_4x20], fills the 80 character DisplayBuffer with ASCII blank characters. If a graphics display is being used in text mode, fills a heap-based buffer with ASCII blanks if a Hitachi graphics controller is in use, or with zeros if a Toshiba graphics controller is in use. If a graphics display is being used in graphics mode, erases (zeros) the heap-based buffer. Disables interrupts for up to 7 microseconds per byte written to the display.

CommandToDisplay

void CommandToDisplay( char cmd )

Writes the specified cmd byte to the LCD display as a command (as opposed to a data byte to be displayed). Does not modify the contents of the Display Buffer. Disables interrupts for up to 7 microseconds per byte written to the display.

DisplayBuffer

xaddr DisplayBuffer( void )

Returns the 32-bit base address (including page) of the buffer that holds the display data. To write all or part of this buffer to the LCD display, call UpdateDisplay or UpdateDisplayLine, respectively. If a character display is in use, the returned xaddr is the base address of an 80 character buffer in the system RAM. If a graphics display is in use, the returned xaddr is the starting address of a heap-based array. Each byte in the DisplayBuffer represents a character position or graphical byte on the LCD display. To display characters on the LCD display, simply write the desired ASCII characters or graphical data into this buffer and execute UpdateDisplayLine or UpdateDisplay. UpdateDisplayLine causes the contents of a specified line in the DisplayBuffer to be written to the corresponding line of the display. UpdateDisplay causes the contents of all lines in DisplayBuffer to be written to the corresponding lines of the display.

See also StringToDisplay and BufferPosition.

Type: _forth function
Forth name: DISPLAY.BUFFER
Header file: intrface.h

DisplayOptions

void DisplayOptions( int display_on, int cursor_on, int cursor_blink, int text_mode )

Sets the display and cursor options on the LCD display. Each of the input parameters is a flag that takes a false (0) or true (non-zero) value. If display_on is true, the contents of the display are visible; if false, the display appears blank. If cursor_on is true, the cursor is on (typically an underscore character); if false, the cursor is off. If cursor_blink is true, the cursor blinks (typically a flashing box the size of a single character); if false, the cursor blink is turned off. If text_mode is true, the display is operating in "text mode"; if false, it is operating in "graphics mode". Note that graphics mode should only be specified if a graphics display is in use; see IsDisplay. Note also that the cursor is never visible in graphics mode. The InitDisplay function leaves the display enabled with the cursor off and cursor blink off.

Implementation detail: In addition to writing the appropriate command byte to the display, DisplayOptions stores the command byte in an hidden system variable called PRIOR_CURSOR_STATE. This variable is referenced by UpdateDisplayLine and UpdateDisplay to blank the cursor during updates to character displays (to prevent annoying flickering) and restore it to its prior state after the update is complete. It is also used by LinesPerDisplay to infer whether the display is being operated in text mode or graphics mode, which in turn determines whether LinesPerDisplay reports the number of character lines or the number of pixel lines in the display. This routine intermittently disables interrupts up to 7 µsec per command byte written to the display.

Type: _forth function
Forth name: DISPLAY.OPTIONS
Header file: intrface.h

InitDisplay

void InitDisplay( void )

Initializes the liquid crystal display (LCD) interface. If a graphics-style display has been specified by IsDisplay, initializes and dimensions an appropriately sized array in that heap; the base address of this array is returned by DisplayBuffer. If a character-style (alphanumeric) display has been specified by Character_4x20 or IsDisplay, then the display buffer is located in the system RAM. InitDisplay calls ClearDisplay to clear the DisplayBuffer and write the blank data to the LCD display. Homes the cursor to the start of line 0, and leaves the display enabled with the cursor off and not blinking. Intermittently disables interrupts for up to 7 µsec per byte transmitted to the display.

IsDisplay

void IsDisplay( int numRows, int numCols, int textMode, int charDisplay, int hitachi )

This primitive is typically not used; the high level routine Character_4x20 is recommended when using the standard 4-line by 20 character text-mode display. IsDisplay is used only for non-standard displays. Based on the specified number of rows, number of columns, and flags that indicate text or graphics mode, character versus graphics display, and Hitachi versus Toshiba graphics controller chip, this routine saves the display configuration in EEPROM so that the LCD display is properly initialized upon subsequent restarts and resets by the InitDisplay routine. The encoded information is accessible via the routines CharsPerDisplayLine and LinesPerDisplay. When IsDisplay is executed, numRows and numCols should be expressed as the number of 8x6- or 8x8-pixel characters that the screen can accommodate. The standard width font for Toshiba graphics displays is set by hardware inputs on the display module to either 6 or 8 pixels wide. The standard width font for Hitachi graphics displays is 8 pixels in graphics mode, and can be set to either 6 pixels or 8 pixels wide in text mode. The allowed values of numRows are 2, 4, 8 or 16 lines per display. The allowed values of numCols are 8, 12, 16, 20, 24, 30, and 40 characters or bytes per line. The textMode input parameter selects between text mode (if textMode is true/non-zero) and graphics mode (if textMode is false/zero) for graphics displays; character displays always operate in text mode. The charDisplay input parameter selects between a strictly alphanumeric character display if charDisplay is true, and a graphics display if the charDisplay is false. The hitachi input parameter specifies the type of controller that drives the graphics display module. If hitachi is true, a Hitachi 61830 controller chip is assumed; if hitachi is false, we assume a Toshiba 6963 graphics controller chip. NOTE that if a graphics display is specified (charDisplay is false) but the text mode is specified (textMode is true), the data buffer created by InitDisplay in the DisplayHeap will be too small to accommodate graphical data. Thus if you want to use both the text and graphics modes of a graphics display, declare a graphics mode display (i.e., with a false textMode flag), and use the DisplayOptions routine to convert to and from text mode. Then the dimensioned buffer will be large enough for either character or graphical data. To declare a 4x20 character display, use:

  IsDisplay( 4,20,-1,-1,-1 );

The 4x20 character display is the default type. Remember to execute InitDisplay after executing IsDisplay. Note that because IsDisplay saves the configuration information in EEPROM, you need not execute it each time the board starts up. See Character_4x20.

Type: _forth function
Forth name: IS.DISPLAY
Header file: intrface.h

IsDisplayAddress

void IsDisplayAddress( uint RamAddress )

Configures a graphics display so that the next data write will occur at the specified RamAddress in the display RAM. This routine can be used in conjunction with UpdateDisplayRam to write data to the "off-screen" RAM that is typically present on a graphics display module. Then modifying the "home address" (upper left location) of the display allows scrolling of data across the display; see the source code of the graphics extension source code file for more details. IsDisplayAddress has no effect if a character display is installed.

Type: _forth function
Forth name: IS.DISPLAY.ADDRESS
Header file: intrface.h

LinesPerDisplay

int LinesPerDisplay( void )

Returns the number of lines in the LCD display. For character displays and for graphics displays being operated in "text mode", the result n equals the number of character lines (rows) in the display (the allowed values are 2, 4, 8 or 16 lines per display). For graphics displays being operated in "graphics mode", the result n equals the number of horizontal pixels on the display (which in turn is 8 times the number of character lines on the display). The type of display and the display mode (text mode vs. graphics mode) are determined by the most recent execution of DisplayOptions or InitDisplay (which implements the configuration specified by Character_4x20 or IsDisplay). The result returned by this routine is used by BufferPosition, PutCursor, UpdateDisplay, and UpdateDisplayLine.

Type: _forth function
Forth name: LINES/DISPLAY
Header file: intrface.h

PutCursor

void PutCursor( int line, int column)

Positions the LCD display cursor at the line number specified by line and the character number specified by column. The next character or graphical byte sent to the display by the CharToDisplay routine will appear at the specified cursor position, and then the cursor position will automatically increment. The input parameters line and column are 0 based (that is, the top line on the display is line#0, and the left-most character on each line is column#0). PutCursor clamps line to one less than LinesPerDisplay, and clamps column to one less than CharsPerDisplayLine. The line number follows the same rules explained in the description of BufferPosition: for a graphics-style display the line number is interpreted differently depending on whether the display is being used in "text mode" or "graphics mode". In text mode, line corresponds to the character line number; in graphics mode, line corresponds to the pixel line number which is 8 times the character line number. Note that the cursor may not be visible, and is never visible in graphics mode; see DisplayOptions. Also note that after the cursor reaches the end of a line it may skip to the start of a line elsewhere on the display. This routine intermittently disables interrupts for up to 7 µsec per command byte.

Type: _forth function
Forth name: PUT.CURSOR
Header file: intrface.h

Read_Extra_IO

uchar Read_Extra_IO( void )

Returns a value representing the current logic levels on the Extra IO port on the Keypad/Display Wildcard (1 = high, 0 = low). These eight digital I/O lines 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. See Set_Extra_IO_Direction and Write_Extra_IO. Implementation detail: Reads the byte at offset 0x0D from the Wildcard base.

Type: _forth function
Forth name: Read_Extra_IO
Header file: wkpd.h

ScanKeypad

int ScanKeypad( void )

Scans the keypad. If a key is being depressed, PAUSEs and waits until the key is released, then returns the key number under a true flag. If no key is depressed, returns a false flag. Consult the Keypad glossary entry for a detailed description of keypad orientation. Disables interrupts for up to 12 microseconds each time a row is scanned.

ScanKeypress

int ScanKeypress( void )

Scans the keypad. If a key is being depressed, returns the key number under a true flag; unlike ScanKeypad, ScanKeypress does not wait for the key to be released. If no key is depressed, returns a false flag. When using ScanKeypress, make sure that multiple calls to your program do not misinterpret a single keystroke as multiple entries from the keypad. Consult the Keypad glossary entry for a detailed description of keypad orientation. Disables interrupts for up to 12 microseconds each time a row is scanned.

Set_Display_Modulenum

void Set_Display_Modulenum( uint modulenum )

Declares the module number of the Keypad/Display Wildcard and stores it in a reserved EEPROM location. 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.

Type: _forth function
Forth name: Set_Display_Modulenum
Header file: wkpd.h

Set_Extra_IO_Direction

void Set_Extra_IO_Direction( int output )

If the parameter named output passed to this function is true, configures the lower nibble DIO_0 through DIO_3 of "extra IO" on the Keypad/Display Wildcard as outputs. If the parameter named output passed to this function is false, configures the lower nibble DIO_0 through DIO_3 as inputs (the default at power-up). See Read_Extra_IO_Direction and Write_Extra_IO. Implementation detail: Writes to bit 0 at offset 0x0E from the Wildcard base (1=output, 0 = input).

Type: _forth function
Forth name: Set_Extra_IO_Direction
Header file: wkpd.h

StringToDisplay

void StringToDisplay( char* string, uint stringPage, int linenum, int column )

For most programs, the macro form named STRING_TO_DISPLAY is recommended; see its glossary entry. The function StringToDisplay should be used when the specified string resides on a different memory page than the routine that invokes StringToDisplay, for example in an application that is compiled on multiple pages on the QCard. Pass the function the correct stringPage, and set the upper byte of the stringPage = 0xFF to signal that the string is a null-terminated "C-style" string as opposed to a counted "Forth-style" string.

Type: _forth function
Forth name: $>DISPLAY
Header file: intrface.h

STRING_TO_DISPLAY

void STRING_TO_DISPLAY( char* string, int linenum, int column )

A macro that calls the _forth function:

void StringToDisplay(char* string, uint stringPage, int linenum, int column)

The macro supplies the parameter stringPage = the current page, and sets the upper byte of the page = 0xFF to signal the routine that the string is a null-terminated "C-style" string. The routine moves the contents of the counted string specified by string to the location in DisplayBuffer starting at the specified character number 'column' on the specified line number 'linenum'. Confines the string to the specified line in DisplayBuffer by clamping the number of characters moved to a maximum equal to the number of character positions remaining after the specified position on the specified line. The line number 'linenum' should be less than the value returned by LinesPerDisplay, and the column parameter should be less than the value returned by CharsPerDisplayLine. Does not modify the contents of the LCD display; this will occur upon the next execution of UpdateDisplayLine or UpdateDisplay. If a Toshiba graphics display has been declared by IsDisplay, subtracts 0x20 from each ASCII character in the string to accommodate the encoding of the Toshiba graphics controller's character ROM.

NOTE: While this macro always works properly if your application resides on a single page of memory on the QCard, this macro cannot be used if the specified string resides on a memory page that is different from the page of the calling routine. If the string resides on a different page from the calling function, use the function StringToDisplay and pass it the proper string page, remembering to set the upper byte of the page = 0xFF to signal that the string is null-terminated.

Type: macro; Calls function: StringToDisplay
Forth name: $>DISPLAY
Header file: intrface.h

UpdateDisplay

void UpdateDisplay( void )

Writes the contents of the DisplayBuffer to the LCD display. When finished, leaves the display cursor pointing at the first position in the first line. For character displays, the cursor is turned off during the write to the display and is restored to its prior state after the update is complete, thus avoiding "flickering" of the cursor. Intermittently disables interrupts for up to 7 µsec per byte.

Type: _forth function
Forth name: UPDATE.DISPLAY
Header file: intrface.h

UpdateDisplayLine

void UpdateDisplayLine( int lineNum )

Writes the contents of the specified lineNum in the DisplayBuffer to the LCD display. lineNum is zero-based, and is clamped to a maximum of 1 less than the value returned by LinesPerDisplay. UpdateDisplayLine writes CharsPerDisplayLine characters to the display. When finished, leaves the display cursor pointing at the first position in the line following lineNum. For character displays, the cursor is blanked during the write to the display and is restored to its prior state after the update is complete, thus avoiding "flickering" of the cursor. The lineNum follows the same rules explained in the description of BufferPosition: for a graphics-style display the lineNum is interpreted differently depending on whether the display is being used in "text mode" or "graphics mode". In text mode, lineNum corresponds to the character line number; in graphics mode, lineNum corresponds to the pixel line number which is 8 times the character line number. Intermittently disables interrupts for up to 7 µsec per byte.

Type: _forth function
Forth name: UPDATE.DISPLAY.LINE
Header file: intrface.h

UpdateDisplayRam

void UpdateDisplayRam( void )

A low-level primitive. Writes the contents of the Display Buffer to the LCD display. Unlike the related UpdateDisplay function, UpdateDisplayRam does NOT put the cursor and the display ram pointer to the "home position" at the upper left corner before writing to the display. When used with graphics displays, this function can be called after IsDisplayAddress to write display data into "off-screen" display RAM, and then data can be scrolled onto the screen by changing the display's "home address". When finished, UpdateDisplayRam leaves the display cursor and the display ram pointer at the first position in the first line. Intermittently disables interrupts for up to 7 µsec per byte.

See also IsDisplayAddress and UpdateDisplay.

Type: _forth function
Forth name: (UPDATE.DISPLAY)
Header file: intrface.h

Write_Extra_IO

void Write_Extra_IO( uchar value )

Writes value to the extra IO port on the Keypad/Display Wildcard (1 = high, 0 = low). These eight digital I/O lines 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. This routine will affect only those lines that are configured as outputs. See Set_Extra_IO_Direction and Read_Extra_IO. Implementation detail: Writes to the byte at offset 0x0D from the Wildcard base.

Type: _forth function
Forth name: Write_Extra_IO
Header file: wkpd.h