KeyboardHost 1.1                                     John Elliott, 9 July 2011
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  KeyboardHost is a program to assist in the creation of custom firmware for
the IBM 6110344 keyboard (the 'Terminal Model F'). The firmwares it creates
should also be usable on other, similar keyboards, such as the 6110668, and
possibly also on the 84-key AT Model F or 104-key Terminal Model F. They will
not work on the 83-key PC/XT Model F keyboard.

  KeyboardHost is written in Java; it should be possible to launch it either 
by double-clicking KeyboardHost.jar, or from the command line with 

  java -jar KeyboardHost.jar

In use
~~~~~~

  To generate custom ROM images, KeyboardHost needs images of the original 
firmware from two IBM keyboards: 1503099.bin from the 84-key AT keyboard, and
1385001.bin from the 122-key Terminal Model F keyboard. You will need to 
extract these from genuine IBM hardware, or get someone else to do it for
you.

  When KeyboardHost is run, it will display a screen similar to this:

IBM 5170 ROM image:
  1503099.bin___________________________________  [Load...]           [Launch]

IBM 3270PC ROM image:
  1385001.bin___________________________________  [Load...]           [Launch]

Hybrid 1k ROM image:
  [Create] __________ [Layout...]  [Customize...] [Load...] [Save...] [Launch]

Hybrid 2k ROM image:
  [Create] __________ [Layout...]  [Customize...] [Load...] [Save...] [Launch]


  Use the top two 'Load...' buttons to load the original IBM ROM images. Once
you have done this, the 'Create' buttons on the bottom two lines are enabled.
Click the appropriate 'Create' button to create a 1k or 2k ROM image.

The Custom ROM Images
~~~~~~~~~~~~~~~~~~~~~
  The two ROM images this program can generate have the following features:

    1k image                          |  2k image
   -----------------------------------+-------------------------------------
   - Has been tested on real hardware.| - Has been tested only under 
                                      |   emulation.
                                      |
   - Supports only one scancode set.  | - Supports all three scancode sets.
                                      |
   - Keys return 1-byte scancodes.    | - Keys can return 1-byte scancodes 
                                      |  or 2-byte E0 xx scancodes.
                                      |
   - No keyboard ID.                  | - Supports keyboard ID.
                                      |
   -----------------------------------+-------------------------------------

  Note the first point in particular. While my EPROM programmer can (just 
about) program an 8748, it doesn't work with an 8749. Consequently, I 
haven't been able to test the 2k ROM image, and have no way of knowing what
it will do when run on real hardware.

Customizing
~~~~~~~~~~~

  Once you have created a custom ROM image (or loaded one you have previously
saved) you can use the 'Customize' option to alter what scancodes it returns.

  The customize screen looks like this:

Keyboard ID: [ab] [86]                             
Remap key:   [01 L9            [v]] [01 L9            [8]]
       to:   [E01F Left Windows[v]] [E01F Left Windows[8]]  
 
with a keyboard layout below, labelled with Set 3 scancodes.

  The "Keyboard ID" field is only available when customising the 2k ROM. It
should be fairly straightforward to change it.

  The rest of the screen deals with the mapping of Scancode Set 3 (as produced
natively by the keyboard) to Set 2. To select a key to remap, either click on
it, or choose it using the first row of controls at the top of the screen. 
Then select the code it should send using the second row.

  When you have finished, select "OK" to save your changes, or "Cancel" to 
abandon them.

Physical Layout
~~~~~~~~~~~~~~~

  By default, the new firmware expects to be loaded in a 122-key keyboard. If
you want to use it in an 84-key AT keyboard, or a 104-key "space unsaver"
terminal keyboard, it's advisable to edit the key sensitivity table. To do
this, click "Layouts". The resulting screen looks like this:

[122-key] [104-key] [84-key AT (all positions)] [84-key AT (stock positions)]

Key [01 L9          [v]] [01 L9               [8]] Sensitivity [ 1 [8]]

with a keyboard layout below. Each key is marked with its sensitivity. IBM
appear to use sensitivity 1-4 for keys that exist, and 7 for keys that don't.

To select one of the standard layouts, click the corresponding button on the
first row of controls. The four layouts are:

* 122-key full 3270
* 104-key Space Unsaver
*  84-key AT (all positions)
*  84-key AT (stock positions)

The difference between the last two is that IBM's firmware for the AT keyboard
assigns sensitivity 7 to key positions that exist but (in the default
configuration) don't have keys above them. If you want to put keys in any of
these positions (eg, for the 'Big Backspace' mod), I'd suggest using the 
"84-key AT (all positions)" layout.

If you want to amend the sensitivity of one or more keys by hand, use the
second row of controls (or the keyboard layout) to select the key, and then
enter the sensitivity for that key. I'd recommend sticking to the values used
by IBM (1-4 for keys that exist, 7 for keys that don't). 

Testing
~~~~~~~

  To test a keyboard layout, click the "Launch" button for its entry. The 
following controls will appear:

* A keyboard, labelled with internal key numbers. These are similar to Set 3
 scancodes except that they start at 0, not 1.

* Twelve checkboxes, marked "KBDID A" and "KBDID B".

* Three greyed-out checkboxes, marked "Num", "Caps" and "Scrl".

* A large text field, which displays data the keyboard has sent to the 
 computer. Hopefully this will hold "AA", for a self-test pass.

* A smaller text field with a "Send" button beside it.

  Clicking buttons on the keyboard is the equivalent of pressing keys. When 
you press each one, its scancode should appear in the lower area (and, if 
the keyboard is set to repeat, you will get a stream of scancodes until you
click the button again to release the key). Note that key number 50 is always
down. On a real keyboard, this is used in the self-test; if key 50 is ever 
up, the self-test fails.

  The checkboxes marked "KBDID A" and "KBDID B" correspond to the keyboard 
identity jumpers / DIP switches. These are only checked by the original 
1385001 firmware; other firmwares ignore them.

  The three checkboxes marked "Num", "Caps" and "Scrl" are what you would see
on a PC/AT LED panel. If you are using a firmware which supports LEDs (ie,
any firmware other than the 1385001) you should be able to set them using 
an ED nn command. For example, type "ed 02" in the bottom text field and click
"Send". The "Caps" checkbox should become ticked.

  Testing is done by running the firmware under 8048 emulation. The emulation
is reasonably complete, but 8048 features not used by the original IBM 
firmware (such as timer interrupts) are not emulated.

Changelog
~~~~~~~~~

1.1: "Physical layout" editor allows key sensitivity to be changed.

1.0: Initial release.
