
                 Advanced Docking Station
              Keyboard Driver 2.0 for onHand
                    from Piehl Systems  
                       3/27/2002


1.  Overview

The included keyboard driver (kbdriver.c) is a module designed
to provide external keyboard input into an onHand C program.  A test
program (kbtest.c) is also provided to test your keyboard
initialization file (keyboard.ini) for your particular keyboard.

Please note:  this driver does not enable the built-in onHand programs
(Schedule, Memo, etc.) to use the keyboard.  Only the programs which are
recompiled with this driver can operate using the keyboard.

The driver will automatically open or close the serial port when
needed and translate cursor and ENTER/MENU button input from the
onHand to equivalent keyboard codes.  The MENU button returns the
same code as the keyboard ESC key.  The technique allows programs
using the driver to use onHand buttons and/or keyboard input (using
cursor keys) without including specialized code for each method
of input.  Further, compiled onHand executables ideally should be
usable with various keyboard brands without the need to recompile
for each application/keyboard combination.

Note that schedule alarms will generally NOT work in most cases
while the keyboard is actually connected.

2.  Using the keyboard driver within your programs

The driver includes the following procedures:

KBInit      - reads the keyboard.ini file and resets the driver
KBGetKey    - returns an ASCII key value (returns 0, if no key pressed)
KBTerminate - closes the serial connection

A keyboard.ini file has been provided for the HalfKeyboard by 
Matias Corporation.  Adapting the driver to other brands will
require substituting a different keyboard.ini file.  To use an
external keyboard, the keyboard.ini file must be resident in the
SYSTEM folder on your onHand.

The keyboard.ini file provides a mapping between codes sent from your
keyboard and the ASCII code returned by KBGetKey.  Settings consist
of a hex code, followed by either a character definition (ex. 80=aA),
or a key name (ex. B1=SPACE).  The character definition includes the
character when the key is pressed alone ("a") and another character
returned when the key is pressed while holding the SHIFT key ("A").

The list of settings in the keyboard.ini file can be delimited by
spaces and/or CR-LF.  Note that a special key called "RELEASE" 
is defined, since the driver must track the release of the SHIFT key.
The ALT and CTRL keys are handled with the same release code.


The function KBGetKey accepts a KeyMode parameter, which affects how
the driver handles various keyboard codes.  For most applications,
you can call KBGetKey(0), which should handle most types of document
editing or similar keyboard applications.  If your application
requires continuous processing, or other special key repeating
characteristics (games, etc.), other bits can be set in the
KeyMode parameter to detect whether a key is continously held down.
For details, the KeyMode values are documented in the kbdriver.c code.


3. Event handling for KBGetKey(0)

If no key is pressed, the CPU will pause for approximately 1 second,
or until a key is pressed, allowing the onHand to save power.
If keys are set up to repeat on a delayed basis, the need to hold down
the key for a 1 second delay will prevent unwanted repeating.

In general, the Esc and Enter keys on the keyboard will work in a
manner equivalent to the MENU and ENTER buttons on the onHand.
However, note that if the buttons are actually used on the onHand
while the keyboard is connected, it may be necessary to hold down
the button longer than usual to get a response.

This results from the driver paying much more attention to the serial
port in this mode whenever the keyboard is connected.  If you need to use
the onHand buttons and the keyboard concurrently, KBGetKey(1) does
not have this problem.


4. Event handling for KBGetKey (1)

When calling KBGetKey(1), a key value will be fetched and the function
returns immediately.  There is the benefit of no sluggishness in response
using either the keyboard or the internal onHand controls.  However,
depending on your application, the CPU could operate continuously
and consume much more of your battery power.


5. Using the KBTest and KBDemo utilities

The utility (kbtest.c) will report bytes received by the serial port.
The program does not use kbdriver.c, but rather it is intended to
be used prior to building a new keyboard.ini file.

The included utility (kbdemo.c) displays numerical counters and a
hexadecimal key code return by the driver.  The utility provides
an easy way to test whether your keyboard.ini settings are properly
indicating to the driver how to translate the keyboard's scan codes
to ASCII codes needed by your software.


6. About this software

Piehl Systems provides this software free and "as is".  This product
(kbdrv20.zip) is available for free, unlimited use and/or modification
for use in any onHand application.   If you need support, please
inquire about technical services from Piehl Systems.

Distributing this product is prohibited, except when the original
ZIP file is copied and given away without a fee or obligation.


Piehl Systems - Copyright 2002
