SUPERHERMES LITE
On-Disk Manual
(c) 1997 TF Services

INTRODUCTION

SuperHermes LITE has two main features:

   Hermes - a replacement for the original QL 8049 keyboard, sound, and
serial port chip, also  called  an  Intelligent  Peripheral  Controller
(IPC).  The 8049  chip had  a number  of problems  from the  start (See
Appendix II).

    Keyboard Interface  - allows  the use  of standard  AT or  XT (IBM)
keyboards on the QL.

superHermes LITE in  a interface board  that plugs into  the QL exactly
where the 8049 chip is.   From  the  interface  a  cable  connects  the
interface to the external keyboard.

A software driver  (extensions  file)  is  loaded  at  boot  time  that
supports both the keyboard and the Hermes functions.

The  keyboard  is  very  configurable.   The  user  may  redefine  what
characters are sent to the  QL  when  specific  keys  are  hit  on  the
keyboard.  A  number of differently configured  drivers are included on
the disk,  most defined by  country.  These drivers  are configured for
the general  QL user.  Some  additional configuration may  be needed by
the user to get all they functionality they need.

Current Hermes Owners

If  you already have a Hermes chip  installed on the QL, this interface
replaces  that chip both  physically and in  function.  The superHermes
LITE  software driver replaces your existing Hermes driver and includes
the software to handle the keyboard interface.


PACKAGE CONTENTS

The superHermes LITE package contains the following items:

     superHermes LITE Interface
     Keyboard Cable (to 5 Pin DIN)
     This Manual
     superHermes LITE Software Disk

The Disk contains the following files:
     
     superHermesLITE_doc   -  This manual.
     BOOT                  -  Boot file.
     KBDGEN_BAS            -  Keyboard Config. Program.
     config                -  Standard QJump config program.

  For each country it includes:

     IPCEXTxx_BIN          - LRESPR'able driver/extensions file.
     IPCEXTxx_ROM          - ROM'able driver.
     KBD_xx_BAS            - Keyboard Config. program.
     BOOTxx                - BOOT file.

Be sure to  make a copy of  the distribution disk and  use this as your
working copy and only make changes to your working copy disk.
 

INSTALLATION

There  are two items to install for superHermes LITE; the interface and
software driver.   It is recommended that you  change your boot file to
reflect  the new driver before you install the interface.  The keyboard
will not work without the software driver.

If  you do not wish to  change your boot file, there  is a boot file on
the installation  disk that you can modify  to supply the right driver.
There are drivers for different countries.

If  you do change your boot file, be sure to copy the proper drivers to
your boot disk from the installation disk.

SOFTWARE DRIVER

The software driver is loaded at boot time with either of the following
commands:

     LRESPR FLP1_IPCEXTxx_BIN

or

     a = RESPR size
     LBYTES FLP1_IPCEXTxx_BIN,a
     CALL a

xx  stands for the country  code of the driver  you choose (see below).
If you  are booting off of  a different drive, such  as WIN1_, you need
use  it instead of FLP1_.   Be sure to place  the LRESPR command before
any HOT_GO or ERT_ commands.

If  you have an existing Hermes chip, you will replace the older Hermes
driver with this new driver.  Do not load both drivers.

Current drivers are:

IPCEXTUK_BIN    5558 bytes     UK driver

IPCEXTUS_BIN    5542 bytes     US driver

We have  defined the unshifted key next to  '1' as '`' thus making this
key combination  the same as the  QL key.  The original  IBM key can of
course  be produced by pressing < CTRL SHIFT \ > as on the QL keyboard.
It  is interesting that the  standard QL UK layout  is identical to the
IBM US layout  (other than the `  sign) - a sign  that Sinclair had his
sights on the US market?

IPCEXTAM_BIN    5542 bytes     Alternative US keyboard driver

This  is the similar to the 'normal' US keyboard above, but the |\ key
has  moved to the right of the right hand shift.  If you are unsure of
what keyboard you have,  just run  the programs  and compare  your IBM
keyboard layout.
  
IPCEXTDE_BIN    5562 bytes     German driver

The  key '\' is a 'third' key and  not available as a direct key press.
As  this is a direct key  press on the German QL  we have had to define
'\' as  grave (unshifted key immediately to right  of ) - you may like
to put a sticker on this key to remind you. 

IPCEXTAG_BIN  5564 bytes  Alternative German driver

This  is an alternative German layout and has a narrow delete key, with
'#' and '\'/'/' to the left of it.

IPCEXTDA_BIN    5596 bytes     Danish driver

The  <1/2> key is not in the QL character set, so this is defined as @.
The  QL doesn't have accent keys, so the IBM accent keys are defined as
`$.  The QL doesn't have an acute accent, so that is defined as '|' 

IPCEXTFR_BIN    5636 bytes   French driver (normal shifted IBM numbers)
IPCEXTFN_BIN    5654 bytes     French driver (unshifted IBM numbers)

Due to limits in  the translation  method, \  is defined  using ALTKEY.
'#' is translated with '3' key, and '"' is top left ('2')

IPCEXTNO_BIN    5642 bytes      Norwegian driver

There is no accent key on the QL so the IBM accent key is translated to
^  $.  @  is available  in the  'third' key  position using  the ALTKEY
supplied. 

IPCEXTSW_BIN    5612 bytes     Swedish driver

The  <1/2> key is not in the QL character set, so this is defined as `.
The QL does not  have  accent  keys,  so  this  key  is  defined  as  $
(unshifted) and  shifted as ^.  Tilde cannot be  accessed directly from
the  QL keyboard, but this can obtained  using ALTKEY (defined as ALT $
in our alt_swedish program)

IPCEXTIT_BIN    5606 bytes     Italian driver

Due  to limitations in the keyboard translating algorithm, we have been
unable to produce normal key presses for:
     - this is produced by ALT SHIFT 
     - this is produced by ALT SHIFT 
    | - this is produced by ALT \ or ALT SHIFT \

This  assumes you use  ALTKEY (toolkit II)  definitions in ALT_ITALIAN,
which  also defines the  'third' keys.  We  are completely re-designing
the translation algorithms for all  countries  so  that  we  can  fully
define the very complex Italian keyboard.


INTERFACE INSTALLATION ( QL CASE )

Installing the interface is the most difficult part of the installation
process.  It  requires you to open your QL,  pull out the 8049 chip (or
Hermes chip)  and put in the  interface.  Be sure to  read ALL of these
installation  directions before opening your QL.  Remember to take your
time and be gentle with your QL, it's getting old.

1.  Unplug the QL.
Remove  all incoming power  from the QL.   Depending on how  your QL is
laid out,  you may want to disconnect  the monitor, serial cables, disk
drivers, etc.  You will need to turn your QL upside down.

2. Unscrew the Case.
Turn  the QL upside down.  Remove the four short screws along the front
edge and  the four long  screws along the  back edge. Do  not touch the
other two screws as they go to the microdrives.

3.  Opening the Case.
Turn  the QL  right side  up.  Carefully  remove the  top of  the case.
Careful with the keyboard membrane connect to the motherboard.  You may
have to  unplug the keyboard membrane from  the motherboard to get room
to  work.  Watch out for the wires connecting the microdrives lights to
the  motherboard.  If you do not plan to use the QL keyboard again, you
can remove  the membrane at this time.  You  should be able to move the
top of the  case to the back  and expose the front  of the QL including
the microdrives.

4.  Locate the 8049 Chip.
Just  to the left of  MDV1_ is the 8049  chip.  It is a  long chip in a
socket (not soldered  to the  board).  If  you are  a Hermes   or other
keyboard  interface owner, you know where this is.  Using a small screw
driver  or chip puller,  gently ease it  out of its  socket (either the
8049,  Hermes, or other interface).   Take care not to  bend any of its
legs,  they might snap off.  If there is an additional "spacer" socket,
you can  remove it  also.  Be  sure to  put your  old 8049,  Hermes, or
interface  away in a safe place, preferably with the legs in a piece of
stryofoam and in a plasic bag.

If  you unplugged the keyboard membrane in the last step, and you still
want  to keep the old keyboard, you can plug the membrane back into the
motherboard now.  Be careful bending the membrane as it might crack.

5.  Installing the SuperHermes Lite Interface.
Now place the SuperHermes Lite interface over the empty socket and line
up the  legs with the socket.   The main part of  the interface will be
sticking out  to the left of the socket.   There is really only one way
to put the  interface into  the socket.   Once the  legs are  lined up,
gently push the socket into place

Run  the keyboard connecting cable through the expansion port to get it
out of the QL case.   Plug  the  small  end  of  this  cable  into  the
interface.

Connect the hooded  microclip (the small  wire with a  plastic hood) to
pin 30B of the  expansion  port.   The  expansion  port  is  where  the
(Super)Gold  Card and disk drives are connected.  Look at the expansion
port from the front of the QL (the expansion port will be on the left).
From  the back of the QL, count forward  three pins on the outer row of
the expansion port.  This is pin 30B.  You really can't reach the inner
row, only the  outer row is  exposed.  Connect the  hooded microclip to
this pin.   Carefully attach  it where  it will  not contact  any other
pins.

6. Closing up the QL
Reverse  the steps above to close up the QL.  This includes putting the
screws back in and connecting the power, monitor, and other cables.

You are now ready to put the BOOT disk into the disk drive and test out
your new keyboard interface.


INTERFACE INSTALLATION ( IBM-STYLE CASE )

The  installation of the interface on a QL mounted in an IBM-Style case
is is very similar to installing it in the QL case.

1.  Disconnect the power cord and open the case.

2. Same as step 4 above.

3. Same as step 5 above.

4. The  panel mounting keyboard socket should  fit in the circular holein the case.  

5.  Replace the case cover and plug the power cord back in.


CONFIGURATION

BOOT-UP CONFIGURATION

The software driver  file has a  couple of options  that are configured
with  the standard QJUMP config program.  This driver has been modified
from the full superHermes, so only two of the configurable options have
any  significance with the  superHermes LITE.  These  are the IPCENABLE
and  Numlock On/Off options.  The NumLock On/Off option allows the user
to  choose of they want the NumLock key to be turned on or off when the
keyboard is initialized at boot time.

The run the config program, enter the following line:

     exec flp1_config;"flp1_IPCEXTxx_BIN"

This  will execute config with it reading the proper file.  Just follow
through  the config prompts  to set the  options.  Be sure  to save the
file before exiting config.


KEYBOARD CONFIGURATION

superHermes LITE  comes with a  program that lets  you easily configure
the  keyboard.  Simply stated, the you define what QL keys you want the
interface to send  to the QL when  you press an IBM  key.  To start the
keyboard configuration program, type:

     lrun flp1_KBD_xx_BAS

This program  will  load  and  set  variables  defining  what  national
keyboard you are using.  It then MERGEs the main keyboard configuration
program.   If this MERGE does  not work, just type  RUN and continue on
from  there.  It will take a few moments for the program to load.  Give
it some time.

Once  the program loads, you will see a drawing for two keyboards.  The
upper  keyboard is the QL  keyboard, the lower one  is the AT keyboard.
There  are also some extra "keys" just  above the numeric keypad on the
IBM keyboard.   These are the  program command keys.   The other "keys"
just  to the right of the QL keyboard can essentially be ignored.  This
program  was written by the superHermes  LITE developer and were needed
only by him.

A Help  menu is displayed at the bottom  of the screen.  Hitting the F1
key will page through all of the help screens, in an endless loop.

The keyboard configuration program has a number of commands.  They are:

   F1   -  More help
           Same as '???' key.
   F2   -  Load the full translation table from the current
           IPCEXTxx_BIN file.
           Same as 'GET' key.
   F3   -  Save the translation file to IPCEXTxx_NEW.
           Same as 'PUT' key.
   F4   -  Toggle IBM SHIFT key.
   F5   -  Toggle IBM NumLock key.
   SPACE - Select current key.
   ENTER - Select current key.
   TAB  -  Toggle between 2 cursors.
   F12  -  Save translation file in DATA statements.
           (CTRL-F2)
   ESC  -  Exit the program.

You operate the  program by  using the  arrow keys  to move  the cursor
around.   You select keys or  command by using the  SPACE or ENTER keys
(along with the function keys).

The general process for configuring a key is this:

   - Select key or key combination on IBM keyboard.
     This will display the current setting on the QL keyboard.
   - Select the key or key combination you want on the QL keyboard.
     (Remember SPACE or ENTER toggles key on or off)

You will do this for each  and  every  key  you  want  configured.   An
example is this:

Have the PgUp and PgDwn keys on the IBM keyboard send the proper QL key
combination for  Page Up  and Page  Down.  On  the QL  the Page  Up key
combination  is ALT Up Arrow and Page Down is ALT Down Arrow.  Here are
the following steps:

   - Move the cursor to the PgUp key on the IBM keyboard.
   - Hit the SPACE bar to select this key.
   - Move the cursor to the QL ALT key.
   - Hit the SPACE bar to select this key.
   - Move the cursor to the QL Up Arrow key.
   - Hit the SPACE bar to select this key.

You  are now done with the  PgUp key.  You can now  move on to the PgDn
key:

   - Move the cursor to the PgDn key on the AT keyboard.
   - Hit the SPACE bar to select this key.
   - Move the cursor to the QL ALT key.
   - Hit the SPACe bar to select this key.
   - Move the cursor to the QL Down Arrow key.
   - Hit the SPACE bar to select this key.

When  you changed to a  different key on the  IBM keyboard, you current
setting  is saved to memory.  Only when  you are completely done do you
want  to save the whole configuration to  disk.  You do this by hitting
the F3 key or selecting the PUT 'key'.  The configuration will be saved
with  the name flp1_IPCEXTxx_NEW.  Be sure that there is enough room on
FLP1_ to save  the file.   The program  will load  in the  old keyboard
configuration and  then save the new  keyboard configuration.  This can
take a few moments.  If there are  any  QL  keys  that  have  not  been
defined with an IBM key,  the  program  will  report  this  before  the
configuration is  saved.  You will  need to correct  the problem before
the configuration can be saved.

The keyboard configuration program defaults  to  FLP1_.   This  can  be
changed by editing the KBD_xx_BAS program and changing any occurance of
FLP1_ to what ever device you want (MDV, WIN, etc.).

Keyboard Configration Hints

Before  you start the keyboard configuration  program, sit down and map
out all keys that you want to configure and what the appropriate QL key
or key combination is.

Optional Methods of Keyboard Configuration

The  KBD_xx_BAS program includes a number  of DATA statements that hold
the  keyboard configuration.  You can manually edit the DATA statements
to configure  the keyboard.  The knowledge to  do this is very detailed
on   involved  it  is  not  recommended   for  most  users.   The  file
KEYBOARD_DOC  provides further details on configuring the keyboard this
way.   The keyboard configuration program uses the F12 key (CTRL-F2) to
save the current configuration to a file as DATA statements. 


HERMES EXTENSIONS

To make it easy to utilise the new features offered by Hmermes, a small
set of SuperBASIC  extensions are  supplied (they  are included  in the
software  driver).  Other than IPCVER$, the extensions will report "not
found" if a non-Hermes IPC is present.

Since the SuperHermes  Lite is  a cut-down  version of  SuperHermes, it
does not have the full  Hermes  functionality  in  the  extensions.   A
number  of  Hermes  commands  are  not  supported  or  have  diminished
functionality.

IPCVER$

This  function tells you what version of  IPC you have.  It will return
the  version number, a  dot and the  revision number as  a text string.
For non-Hermes IPCs, it will always return "0.0".

     Syntax:  PRINT IPCVER$

RXBAUD%

This function reads and  sets  the  serial  port  input  rates.   Albin
Hessler's  v2.04 or greater serial mouse driver will now allow use with
Hermes split baud rates.

     Syntax: RXBAUD% (parameter%)

parameter% give the  port and  value to  send.  The  result is  the old
value, including  whether the port is open  or not.  The value consists
of the following:

  bit 7: Send 0=ser1, 1=ser2.  Return 0=open or 1=closed. (code 128)
  bit 6:  Set if BAUD command  is not to affect  this input port. (code
64)
  bits 3  - 0: Standard baud  rates (bit 4 is  ignored at present) code
0-7 = 19200,  9600,  4800,  2400,  1200,  600,  300,  75.   codes  8-15
duplicate the  above, at present, but will  be used for additional baud
rates, e.g., RTTY speeds.

All other  bits are reserved and  must be zero.  E.g.  To pick off ser1
receive to  be used for a mouse operating  at 1200 baud only, one would
do

   rx0% = RXBAUD%(64+4)

(provided a modified  serial mouse  driver is  installed).  If  this is
done  before anything else, rxo% will be set to 129, showing that ser1_
was  not open (128), and it was being affected by the normal "BAUD" (no
64)  and its current baud  rate was 9600 (1).   If other compiled jobs,
etc., change the baud  rate, or  you do  a new  "BAUD 19200"  say, ser1
input will stay  running at  1200 baud.   To revert  to what  was there
originally, you could do a

   PRINT RXBAUD%(rx0% && 127)

which would print 68 if the port was open, or 196 if it was closed.

IPCEXT

This  may be used  to set the  audible keyclick.  Its  full function is
limited on the SuperHermes Lite.

     Syntax: IPCEXT command%

command% may be one of the following:

   6:  keyclick off
   7:  keyclick on

All other value apply only to Hermes or SuperHermes and are ignored.

IPCENABLE and IPCDISABLE

     Syntax: IPCDISABLE feature%
     Syntax: IPCENABLE  feature%

The only applicable value  for  feature%  is  6,  which  sets  the  IPC
interrupt  status.  Defaults  in extensions  CONFIG block.   Enable IPC
interrupt for full 19200 bps for ser1/2 receive.


PROBLEMS WITH THE OLD 8049 IPC

Serial Input

Serial input requires  signal from  the QL  when its  character recieve
buffer  is full (ser1 CTS - Clear To  Send and ser2 DTR - Data Terminal
Ready).  This could easily not be activated in time by the 8049, due to
badly designed  code in the chip.  It results in, at  best, the loss of
incoming  characters, or at worse, a  "serial overrun" where the serial
ports  "hordes" a number of  characters and only doles  them out when a
new character comes in.  This was seen mostly when using a modem.  This
"serial overrun" can only be stopped by reseting the QL.

Keyboard Handling

Key rollover  (especially when shift  keys are involved)  does not work
well.  When keys  are pressed there  is a tendency  for unwanted repeat
characters ( key bounce  ) to  appear.  They  occurred mostly  in early
versions  of the 8049, when a key was typed and the neighboring key was
also touched.   Add-on  keyboards,  such  as  the  Schoen  or  Keyboard
Products, where especially  prone  to  this  problem,  resulting  in  a
slightly "crackly" key.

Baud Rates

Independent  baud rates are not possible  with the current 8049.  Input
at 9600 baud requires two stop bits, where the industry standard is one
stop bit.  Input at 19200 baud is impossible.

Sound

"Fuzzy" and "random" on sound  commands  shift  the  underlying  pitch.
Sound duration is dependent on the pitch.

MINERVA CONSIDERATIONS

The Minerva soft  resets (CALL 390,  and CTRL ALT  SHIFT TAB) and
Miracle's RES_128 cause  problems  with  (Super)Gold  Card  as  Miracle
Systems patch  out the reset command in their  copy of the ROM code, so
the PIC  on the superHermes LITE is not  reset, and it thinnks keys are
still  being held  down on  the AT  keyboard.  We  are working  on ways
around  this, which may involve patching the (Super)Gold Card protected
RAM  area.  For the present, CTRL ALT SHIFT TAB will not work.  To use,
for instance, CALL 390,17 from the keyboard, use PAUSE 40: CALL 390,17.
This ensures  that there  are no  pending key  presses.  CALL  390 from
programs should be OK, unless  key  presses  are  pending  when  it  is
invoked.  RES_128 will not work with PAUSE 40 : RES_128.


KEYBOARD PINOUTS

superHermes      Color     Function     Keyboard
------------------------------------------------
     1           green      clock          1
     2           white      data           2
     3           yellow     reset          3
     4           black      GND            4
     5           red        +5V            5


HARDWARE CONSIDERATIONS

If you find you  are getting  data input  corruption using  ser1/2 then
check the following

     - Have you opened the QL port with handshaking enabled?

     -   Does  your  serial  cable   support  handshaking.   QL/CTS  to
SENDER/CTS and QL/DTR to  SENDER/RTS.   Many  leads  have  "loopbacked"
handshaking.

     -  Is the QL  IC25 working?   There should  be output  on relevant
handshake line  of -12V to stop  ser1 CTS/Pin 8 or  ser2 DTR/pin 11.  A
24D RS232 tester, with red/green leds, can help diagnose faults.

     - Is  the sending device set to  accept handshaking?  Check the QL
serial socket wires are all there and contacting the plug.


FALKENBURG HARD DISK DRIVE

The  Falkenburg hard disk interface makes  WIN1_ a higher priority boot
than  FLP1_ (or even MDV1_).   This means that if  you make a WIN1_BOOT
error, or the WIN1_BOOT file loads  but  fails  later  due  to  a  "bad
medium", and it  has not  yet loaded  the superHermes  LITE extensions,
then you will not be able to use the AT keyboard.  It is suggested that
you put  the  following  as  your  first  lines,  and  do  this  BEFORE
installing superHermes  LITE and  AT keyboard  (and make  the necessary
change to the BOOT).

   10 TK2_EXT
   20 FLP_USE 'FLP'
   30 IF FTEST('FLP1_BOOT')=0 : LRUN 'FLP1_BOOT'

This  will allow you to boot off  floppy disk, and load the superHermes
LITE extensions, if you get  problems,  unless  of  course  'WIN1_BOOT'
fails with bad medium.   Clearly  it  is  very  desirable  to  use  the
IPCEXTxx_ROM.

    Source: geocities.com/siliconvalley/pines/5865

               ( geocities.com/siliconvalley/pines)                   ( geocities.com/siliconvalley)