NAME

       matrix_kb  - Convert integers to HAL pins.  Optionally scan a matrix of IO ports to create
       those integers.

SYNOPSIS

       loadrt matrix_kb config=RxCs,RxCs... names=name1,name2...

       Creates a component configured for R rows and N columns of matrix keyboard.

       If the s option is specified then a set of output rows will be cyclically toggled,  and  a
       set of input columns will be scanned.

       The  names parameter is optional, but if used then the HAL pins and functions will use the
       specified names rather than the default ones.  This  can  be  useful  for  readbility  and
       2-pass HAL parsing.

       There must be no spaces in the parameter lists.

DESCRIPTION

       This  component  was written to convert matrix keyboard scancodes into HAL pins.  However,
       it might also find uses in converting integers from 0 to N into N HAL pins.

       The component can work in two ways, and the HAL pins created vary according to mode.

       In the default mode the component expects to be given a scan code from a  separate  driver
       but could be any integer from any source.  Most typically this will be the keypad scancode
       from a Mesa 7I73.  The default codes for keyup and keydown are  based  on  the  Mesa  7I73
       specification with 0x40 indicating a keydown and 0x80 a keyup event.  If using the 7I73 it
       is important to match the keypad size jumpers with the HAL component.  Valid  configs  for
       the  7I73  are  4x8  and  8x8.   Note  that the component will only work properly with the
       version 12 (0xC) 7I73  firmware.   The  firmware  version  is  visible  on  the  component
       parameters in HAL.

       In  the optional scan-generation mode the matrix_kb.N.keycode pin changes to an output pin
       and a set of output row pins and  input  column  pins  are  created.   These  need  to  be
       connected  to  physical  inputs  and  outputs to scan the matrix and return values to HAL.
       Note the negative-logic parameter described below, this will need to be set  on  the  most
       common forms of inputs which float high when unconnected.

       In  both  modes  a  set  of  HAL output pins are created corresponding to each node of the
       matrix.

FUNCTIONS

       matrix_kb.N
              Perform all requested functions.  Should be run in  a  slow  thread  for  effective
              debouncing.

PINS

       matrix_kb.N.col-CC-in bit in
              The input pin corresponding to column C.

       matrix_kb.N.key.rRcC bit out
              The pin corresponding to the key at row R column C of the matrix.

       matrix_kb.N.keycode unsigned in or out depending on mode.
              This  pin  should be connected to the scancode generator if hardware such as a 7I73
              is being used.  In this mode it  is  an  input  pin.  In  the  internally-generated
              scanning mode this pin is an output, but will not normally be connected.

       matrix_kb.N.row-RR-out bit out
              The  row  scan drive pins.  Should be connected to external hardware pins connected
              to the keypad.  The row scan drive pins.Should be connected  to  external  hardware
              pins connected to the keypad.

PARAMETERS

       matrix_kb.N.key_rollover unsigned r/w (default 2)
              With  most  matrix  keyboards  the  scancodes are only unambiguous with 1 or 2 keys
              pressed.  With more keys pressed phantom keystrokes can appear.  Some keyboards are
              optimised  to reduce this problem, and some have internal diodes so that any number
              of keys may be pressed simultaneously.  Increase the value  of  this  parameter  if
              such  a  keyboard  is  connected, or if phantom keystrokes are more acceptable than
              only two keys being active at one time.

       matrix_kb.N.negative-logic bit r/w (default 1) only in scan mode
              When no keys are pressed a typical digital input will float high.  The  input  will
              then be pulled low by the keypad when the corresponding poll line is low.  Set this
              parameter to 0 if the IO in use requires one row at a time to be high, and  a  high
              input corresponds to a button press.