                                                        Release 05. 18/10/98

                Serial Mouse Info...
                ====================

        Having found information on serial-port mice in several places, some
of which is conflicting, I have decided to gather it all together here.
This document doesn't cover mouse access through operating system / HLL
routines; it works at the hardware and port levels.


Availability of this document.
------------------------------
        At the moment this document is only available by http from
http://www.softnco.demon.co.uk/SerialMouse.txt
or by emailing the author with Serial Mouse Info in the subject line
at chris@softnco.demon.co.uk.

This is Release 05 of the Serial Mouse Info by Chris Softley.
Last Updated 20:52GMT 18th October 1998.



Non-Serial (well, non-RS232) Mice
----------------------------------
        This document only covers RS232 serial mice. It does not cover bus
mice or PS/2 devices. Note that Microsoft no longer include serial mice in
their 'PCxx' (where xx is a year) specifications, in favour of USB or PS/2
devices. Support may therefore disappear in future MS operating systems.
(has anyone ever seen a USB mouse?)
        For info on PS/2 and bus mice, try Ralph Brown's Interrupt List - see
the references at the end. Look under the keyboard controller chip for PS/2
devices.



Mouse Controller ICs
---------------------

        Holtek (www.holtek.com) produce the controller ICs found in many
mice, with part numbers such as HT6515, HT6513, HT8213, etc. The HT8213 is
the latest device, which supports Plug and Pray identification. Much of he
information here is taken from the datasheets for these ICs, which can be
found on the Holtek website (at least, at the time of writing they can ;-)
        Other common mouse controller ICs are the HM8348 (_old_) and the
HM8350. I'm still looking for datasheets for these.
        My logitech mouse contains a chip with the Motorola symbol on it and
the numbers:    LXC437159P
                331016-1101
                F33RCTCTAB9628 (9628 is almost certainly just the date code)
If anyone can shed some light on this chip, please do so. Is this maybe a
PGA?



Connection Details
------------------
        Here I'm attempting to give you an idea of the most generic
connection scheme. Reports of from where the mouse draws its power are
conflicting, as I believe the various different controller ICs use different
strategies.


RS232-C Standard Issues.

        This section briefly describes the features of RS232-C and PC serial
comms that are pertinent to serial mice. For more details see the references
section at the end of this document.
        The serial port to which the mouse connects is (supposed to be) to
the EIA RS232-C standard. This standard, amongst other things, defines the
output voltage for a 'logic-1', 'logic-true', 'logic-high', etc to be MINUS 3
to 15 volts. A 'logic-0', 'logic-false' or 'logic-low', etc is to be in the
range PLUS 3 to 15 volts. Common values are -/+ 5V and -/+12V. Because a
logical true is represented by a -ve voltage, the start bits are at the high
voltage level, the and stop bits are at the low voltage level, and data bits
that are logically true are transmitted at the -ve voltage level as well.
However, all of the handshake lines coming out of or into the PC are
complimented (which from here on I'll indicate with a lower case 'n' as a
prefix) which means that setting, for example, RTS to true in software
results in the compliment of RTS which appears at the output port being at
the +ve voltage level.
        If you watched TxD on a 'scope at 7N1 whilst an ascii ':' was being
transmitted, this is what you'd see:

':' = 0x3A = 0111010b


+ve           -----------       -----                   -----
             |           |     |     |                 |     |
-ve  - - - --             -----       -----------------       ------- - - -
    |marking |Start|D0=0 |D1=1 |D2=0 |D3=1 |D4=1 |D5=1 |D6=0 |Stop |marking

'marking' indicates the line in its quiescent, 'marking time' state, when
no data is being transmitted. In this state the line sits at -3-15V.



RS232-C Pinouts.

        Two connectors are normally used for RS232-C, 25-pin D-type
and 9-pin D-type, the 9-pin variety being most common on mice. Whilst the
RS232-C standard does not specify any particular type of connector, it
does specify that the DTE end (computer end) should be a male (I.e. has
the pins) and the DCE end (mouse end) should be a female (I.e. has the
sockets into which the pins fit), and it specifies pin-outs for 9-pin and
25-pin connectors.

        9-Pin Male                      25-Pin Male

                                                  1 1 1 1
        1 2 3 4 5               1 2 3 4 5 6 7 8 9 0 1 2 3
        | | | | |               | | | | | | | | | | | | |
        O O O O O               O O O O O O O O O O O O O
         O O O O                 O O O O O O O O O O O O
         | | | |                 | | | | | | | | | | | |
         6 7 8 9                 1 1 1 1 1 1 2 2 2 2 2 2
                                 4 5 6 7 8 9 0 1 2 3 4 5

        9-Pin Female                    25-Pin Female

                                1 1 1 1
        5 4 3 2 1               3 2 1 0 9 8 7 6 5 4 3 2 1
        | | | | |               | | | | | | | | | | | | |
        * * * * *               * * * * * * * * * * * * *
         * * * *                 * * * * * * * * * * * *
         | | | |                 | | | | | | | | | | | |
         9 8 7 6                 2 2 2 2 2 2 1 1 1 1 1 1
                                 5 4 3 2 1 0 9 8 7 6 5 4

0 = socket, * = pin.


9 - Pin | 25 - Pin | Name | Direction  | Description
--------|----------|------|------------|-------------------------------------
  np    |    1     | na   |    na      | Protective Ground (e.g. screen)
  3     |    2     | TXD  |PC -> Periph| Transmitted Data
  2     |    3     | RXD  |PC <- Periph| Received Data
  7     |    4     |nRTS  |PC -> Periph| Request to Send
  8     |    5     |nCTS  |PC <- Periph| Clear to Send
  6     |    6     |nDSR  |PC <- Periph| Data Set Ready
  5     |    7     | SGND |    na      | Signal Ground
  1     |    8     |nCD   |PC <- Periph| Carrier Detect (sometimes 'DCD')
  np    |    9     | na   |    na      | (reserved - do not use)
  np    |    10    | na   |    na      | (reserved - do not use)
  np    |    11    | na   |    na      | (unassigned)
  np    |    12    | na   |PC <- Periph| Secondary Carrier Detect
  np    |    13    | na   |PC <- Periph| Secondary Clear to Send
  np    |    14    | na   |PC -> Periph| Secondary Transmitted Data
  np    |    15    | na   |PC <- Periph| Transmission Signal Element Timing
  np    |    16    | na   |PC <- Periph| Secondary Received Data
  np    |    17    | na   |PC <- Periph| Receiver Signal Element Timing
  np    |    18    | na   |    na      | (unassigned)
  np    |    19    | na   |PC -> Periph| Secondary Request to Send
  4     |    20    |nDTR  |PC -> Periph| Data Terminal Ready
  np    |    21    | na   |PC <- Periph| Signal Quality Indicator
  9     |    22    |nRI   |PC <- Periph| Ring Indicator
  np    |    23    | na   |PC<-->Periph| Data Signal Rate Selector
  np    |    24    | na   |PC -> Periph| Transmit Signal Element Timing II
  np    |    25    | na   |    na      | (unassigned)

na = not applicable
np = not present.
prefix of n means signal is inverse-logic (in this case high output voltage
for logical true. Awkward, but hey, I didn't write RS232-C ;-)

Mouse Power Supply & Connections

As RS232 requires both positive and negative voltages, a split rail supply
to the mouse is required. The negative supply is generally achieved by
leaving the TxD line in the 'marking' state with no data being sent on it,
which causes it to sit at the -ve voltage level. Often the mouse circuitry
will be powered only by TxD and the Signal Ground, and will use the other
(most positive) rail only for the purposes of transmission to the PC. In
this way mouse chips can remain powered even if the most positive rail is
lost -this technique may be used by the mouse to remember its configuration.

Usually one of 3 combinations is used for the mouse to get its positive
supply:

        i)   RTS is set to true. This causes the nRTS output to assume a
             positive voltage.

        iii) DTR is used in place of RTS.

        iv)  DTR and RTS are both combined in some way to provide the mouse
             positive supply.

It is (to my knowledge) impossible to completely 'turn off' the mouse through
software, as the lines used to power it will always be at the +ve or -ve
state. The closest you can get is to clear DTR and RTS, and set bit 6 of the
LCR. Setting this bit puts the line in 'broken' state, where it sits at the
+ve level.

Inside most (vanilla) mice, only four connections to the serial port are
made. These are typically as follows:

   Pin 2  -- RxD  -- Used to send position & status information to PC
   Pin 3  -- TxD  -- -ve power supply to mouse
   Pin 5  -- SGND -- gnd power supply to mouse
   Pin 7  -- nRTS -- Used for +ve supply, reset (maybe to send data to it??)
or
   Pin 4  -- nDTR -- Used for +ve supply, reset (maybe to send data to it??)

In my Logitech mouse we have still only the four most common connections
inside the mouse as above (using nRTS not nDTR), however pins 6 and 4 are
looped together in the plug giving a loopback between Data Terminal Ready and
Data Set Ready.
(This actually turns out to be an MS requirement for Plug & Pray).

So, looking on the bright side, there are only 2 lines to the mouse over
which we have any control, and then there's RxD on which we need to receive
data. How hard can it be?




Communicating with the Mouse
----------------------------

        Microsoft compatible mice communicate in 7 N 1 (7 databits, no
parity, one stop bit) at 1200 baud. There are mice which use higher
baud rates (9600) but according to Microsoft, you should always be
able to hold a meaningful conversation with an MS-compatible mouse
after you initialise it at 1200 baud, 7N1. By a quirk of RS232, you can
ID a mouse systems mouse this way, too, despite the fact that they like to
be spoken to in 8 N 1, 1200 baud.
        Guessing that a mouse may be present under the MS P&P spec is
simple - a P&P mouse will assert DSR when RTS and DTR are asserted by the PC.
This gives you the starting point - _something_ is present. On the strength
of this you can attempt to initialise the mouse. Note that non-P&P mice don't
necessarily assert DSR, so you probably have to try to reset the mouse
anyway if you want to look for non P&P devices.
        The mouse is initialised on a rising edge of either DTR or RTS. IMO
the safest bet is to take both of these low (i.e. not set in software and
therefore  a -ve output to the mouse) and set bit 6 of the LCR, wait at least
0.2 of a second, and then raise RTS & DTR, and clear bit 6 of the LCR.
This should reset the mouse. There is a timing diagram below
which shows the official Microsoft way to initialise the mouse, intended for
use with P&P mice, but it should work for regular mice too.
        The mouse should then respond with some data. The first word of this
data (as the serial comms are 7-bits, a word in this context is 7-bits)
according to the MS spec, should be an ASCII upper case 'M' - I.e. 4D hex.
This indicates the presence of a mouse. Some mouse-systems compatible mice
are reported to return a lowercase ASCII 'm' (6D hex). Many 3-button mice
return an ASCII '3' (33 hex) after the initial M. According to the MS P&P
info, after resetting a mouse it should return the 'M', followed by a string
which contains various plug & pray things. This is an ASCII string, but as
non-P&P mouse drivers look at bit 6 of a received byte (see below) to signal
the start of a mouse data packet, having bit 6 set is to be avoided. This is
achieved by not using proper ASCII, but subtracting 20 hex from the character
values. From the P&P spec, you should watch for either the start of a packet
(bit 6 set) or 0x08 which indicates the start of P&P data, having grabbed the
old-style mouse identifier ('M' | 'm' ['3']). I don't know the full details
of the P&P data, however the P&P data block ends when either the first packet
is received (in which case the validity of the P&P data is questionable) or
an 0x09 is received indicating the end of the P&P block.

A 'full' P&P block looks like this (I think...)

Word | Length | Value | Value + 0x20 | ASCII | Description
-----|--------|-------|--------------|-------|-------------------------------
+0   |   1    | 0x08  |    0x28      |  (    | P&P data will follow
+1   |   2    |varies |   varies     |varies | P&P Version No. Typically
     |        |       |              |       | 0x01, 0x24 for version 1.
+3   |   3    |varies |   varies     |varies | 3-character manufacturer ID,
     |        |       |              |       | same as that used to ID
     |        |       |              |       | EISA bus devices.
     |        |       |              |       | e.g. 'HTK' for Holtek.
+6   |   4    |varies |   varies     |varies | Unique Product identifier
+10  |see desc| 0x3C  |    0x5C      |  \    | A backslash here indicates the
     |        |       |              |       | start of a block of extended
     |        |       |              |       | P&P data.
+11* | varies |varies?|   varies?    |varies?| P&P class name.
     |        |       |              |       | Most likely to be \MOUSE but
     |        |       |              |       | info is scarce.
+??* |   8    |varies |   varies     | \.... | A backslash indicates the
     |        |       |              |       | start of this field, which
     |        |       |              |       | contains the pnp driver id.
     |        |       |              |       | eg. PNP0F0C
+11/?|   2    |varies |   varies     |varies | Checksum. Either at +11 or
/*   |        |       |              |       | varies if extended info
     |        |       |              |       | present. May not be present.
     |        |       |              |       | Method of calculation unknown.
+13/?|   1    | 0x09  |    0x29      |   )   | End of P&P block


* -- item only present as part of extended P&P data, after the '\'

        The Holtek datasheets have a diagram showing the P&P initialisation
sequence, not very clear but here goes anyway:

 Time:| T1 | T2 | T3 | T4      | T2b| T4b    | idle.....

   lh  ----      --------- - -       ---- - - - - - -
  DTR:     |    |              |    |
   ll       ----                ----

   lh                 ---- - -       ---- - -
  RTS:               |         |    |        |
   ll  --------------           ----          ---- - - - -

All periods are of 200ms duration (well, 200ms +/- 35ms)

T1:  DTR Held high whilst waiting for DSR in response. DSR must be active
     at end of T1 if a P&P mouse is connected.
T2:  Interval for external device to power down or detect port state.
     (allows for DTR-powered devices to power down)
T3:  DTR raised before RTS as 'signature delay' indicating presence
     of P&P enumerator rather than regular mouse driver.
T4:  Raise DTR & wait for the ID information. Receive ID information.
T2b: Power off mouse again.
T4b: DTR & RTS raised simultaneously to start mouse in work mode.

In addition, each word received during T4 must arrive no more
than 200ms after the previous one. Also, the entire P&P ID
string must have been completely received within 2.2s.

Now that the mouse is initialised, it will communicate in one of
three basic ways (unless its a posh one which will use an extension
of one of these standards)

Normal Microsoft Mode:
        Comms at 7N1, 1200 baud. Data is received in 3-word packets,
as follows

   bit:| 6 | 5 | 4 | 3 | 2 | 1 | 0 |
-------|---|---|---|---|---|---|---|
Word 1 | 1 | LB| RB| V7| V6| H7| H6|
Word 2 | 0 | H5| H4| H3| H2| H1| H0|
Word 3 | 0 | V5| V4| V3| V2| V1| V0|


Where LB is 1 if the left button is pressed and 0 otherwise
      RB is 1 if the right button is pressed and 0 otherwise
V7:V0 are the 8-bit 2's complement amount of vertical motion.
      Positive values are when the mouse is moved towards the user.
H7:H0 are the 8-bit 2's complement amount of horizontal motion.
      Positive is to the user's right.

The first word is the only one which ever has bit 6 set, and so this
bit is to be used to determine the start of a packet. Whenever you
receive a word with bit 6 set, treat this as the first byte of a new
packet. It is advisable to discard any incomplete packets (I.e.
fewer than 3 bytes).

Microsoft Plus (M+) Mode:
        This is an extension to regular microsoft mode, allowing for
3-button mice (and perhaps other features I don't know about). Normally,
data is sent with the same 3-word packet structure as for normal mode,
at 1200 baud 7N1 as for normal mode. However, if the middle button is
pressed, a fourth word will be sent in addition. The MSB of this 4th
word will always be clear, and bit 5 will contain the middle button
status. This extra word is the sole source of information about the
middle button- receiving a 3-byte packet, which is possible under this
protocol, tells you _nothing_ about the middle button and its status
hould be assumed not to have changed. My logitech uses this scheme.


Mouse Systems Mode:
        This is somewhat different and uses 1200 baud, 8N1, serial
communications, and a 5 byte packet structure:

  bit:| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
------|---|---|---|---|---|---|---|---|
Word 1| 1 | 0 | 0 | 0 | 0 |nLB|nMB|nRB|
Word 2| <<<<<<<<< H7: H0 >>>>>>>>>>>>>|
Word 3| <<<<<<<<< V7: V0 >>>>>>>>>>>>>|
Word 4| <<<<<<<<<EH7: EH0>>>>>>>>>>>>>|
Word 5| <<<<<<<<<EV7: EV0>>>>>>>>>>>>>|

Under Mouse Systems mode it is not so easy to synchronize with the
start of a packet and the likelihood of errors occurring is greater if
data are lost. This is because you look for the start of a packet
by checking for a byte of 10000xxx, however as there is no guarantee
that the other words in the packet will not match this signature, you
become reliant on receiving 5 words before waiting again for the
signature.

nLB is the inverted left button status, nMB is the same for the
middle button, nRB is the same for the right button.
AFAIK H7:H0 and V7:V0 are the same as in microsoft mode, except that
vertical movement is counted the other way around. I.e. away
from the user is up.

I have conflicting information about the values in words 4 and 5, so
it's probably safest to ignore these. One source says that W4 = W2 and
W5 = W3, the Holtek data sheets say that EV7:0 and EH7:0 contain vertical
and horizontal overflow counts respectively (I.e. they bring the number of
bits used for each count up to 16 - for if you're moving the mouse
seriously fast, or its a really high-resolution mouse.)



Example Mouse Circuit
---------------------

        The following is a typical mouse circuit based on the Holtek HT82M13.

  9-Pin Female
    D-Conn
       |        --------------------------------------------*-----*---*----
       |1      |                      HT82M13               |     |   |    |
 nCD---O---n/c |                 1  -----   ------  16      |     |   |    |
       |       |            n/c ---|HBLB \_/   Vdd|---------* LEDY|_  |    |
       |2      |                   |              | e     c |    \ /  |    |
 RxD-<-O-------+-----       n/c ---|TEST       Y2 |--<SY2>--*  ~ ---  |    |
       |       |     |             |              |         |   ~ |   |10u |
       |3      |     |      n/c ---|MS         Y1 |--<SY1>--*     |  ---   |
 TxD->-O-------+--   |             |              |         |     |  ---   |
       |       |  |  |          ---|OSCI          |         |     |   |    |
       |4      |  |  |          |  |              |         | LEDX|_  |    |
nDTR->-O----   |  |  |         --- |              | e     c |    \ /  |    |
       |    |  |  |  | 32768Hz [ ] |           X2 |--<SX2>--*  ~ ---  |   __|
       |5   |  |  |  |         --- |              |         |   ~ |   |  |/ \
SGND---O----+--   |  |          |  |           X1 |--<SX1>--*     |   |   ---
       |    |     |  |          ---|OSCO          |         |     |   | 5v1|
       |6   |     |  |             |              |         | 1k5  >  |    |
nDSR-<-O----      |  |      3M     |              |         |     <   |    |
       |       ---+--+--*-/\/\/\---|RTS           |  ___    |      >  |    |
       |7     |   |  |  >          |           L  |--o o----*     |   |    |
nRTS->-O------    |  |  < 4k7      |              |  ___    |     |   |    |
       |          |   --*----------|RxD        M  |--o o----*     |   |    |
       |8         |                |              |  ___    |     |   |    |
nCTS---O---n/c    |            ----|Vss        R  |--o o----      |   |    |
       |          |           |  8  --------------  9             |   |    |
       |9         |           |                                   |   |    |
nRI----O---n/c     -----------*-----------------------------------*---*----


<S...> are phototransistors with emitter and collector connections denoted by
e and c. The crystal is a standard 32KHz tuning fork type watch crystal.


Note that this doesn't blow anything up in the event of:
        i) >5V output from the PC
        ii) TxD going to +ve
because there is significant output impedance in the port
(one source gives 2k-ohms as a working figure.)



Appendix 1: P&P Codes for Various Mouse Types:

Device ID              Description
 PNP0F00              Microsoft bus mouse
 PNP0F01              Microsoft serial mouse
 PNP0F02              Microsoft InPort mouse
 PNP0F03              Microsoft PS/2-style mouse
 PNP0F04              Mouse Systems mouse
 PNP0F05              Mouse Systems 3-button mouse (COM2)
 PNP0F06              Genius mouse (COM1)
 PNP0F07              Genius mouse (COM2)
 PNP0F08              Logitech serial mouse
 PNP0F09              Microsoft BallPoint serial mouse
 PNP0F0A              Microsoft Plug and Play mouse
 PNP0F0B              Microsoft Plug and Play BallPoint mouse
 PNP0F0C              Microsoft-compatible serial mouse
 PNP0F0D              Microsoft InPort-compatible mouse
 PNP0F0E              Microsoft-compatible PS/2-style mouse
 PNP0F0F              Microsoft Serial BallPoint-compatible mouse
 PNP0F10              Texas Instruments QuickPort mouse
 PNP0F11              Microsoft-compatible bus mouse
 PNP0F12              Logitech PS/2-style mouse
 PNP0F13              PS/2 port for PS/2-style mouse
 PNP0F14              Microsoft Kids mouse
 PNP0F15              Logitech bus mouse
 PNP0F16              Logitech SWIFT device
 PNP0F17              Logitech-compatible serial mouse
 PNP0F18              Logitech-compatible bus mouse
 PNP0F19              Logitech-compatible PS/2-style mouse
 PNP0F1A              Logitech-compatible SWIFT device
 PNP0F1B              HP Omnibook mouse
 PNP0F1C              Compaq LTE Trackball PS/2-style mouse
 PNP0F1D              Compaq LTE Trackball serial mouse
 PNP0F1E              Microsoft Kids Trackball mouse
 PNP0F1F              Reserved by Microsoft Input Device Group
 PNP0F20              Reserved by Microsoft Input Device Group
 PNP0F21              Reserved by Microsoft Input Device Group
 PNP0F22              Reserved by Microsoft Input Device Group
 PNP0F23              Reserved by Microsoft Input Device Group
 PNP0FFF              Reserved by Microsoft Systems

References.
-----------
        Holtek datasheets from www.holtek.com

        Ralph Brown's Interrupt List, an absolute must have for anyone
who programs a PC, contains serial port details (in the file ports.lst
as of this writing). The following availability info is taken from v.54
of the list:
Internet: on the SimTel.Net mirrors as files interRRa.zip to
        interRRf.ZIP in directory /pub/msdos/info, where RR stands for the
        release number. Note that you must use a binary transfer mode.
        The SimTel.Net mirrors include oak.oakland.edu [141.210.10.117],
        wuarchive.wustl.edu [128.252.135.4], ftp.uu.net [137.39.1.9],
        nic.funet.fi [128.214.6.100], src.doc.ic.ac.uk [146.169.3.7], and
        archie.au [139.130.4.6].

        Christian Blum's Serial FAQ has some very good details of the PC
serial ports. Obtain the files via anonymous ftp from ftp.phil.uni-sb.de
(134.96.80.220), pub/staff/chris.

        Try the usenet hierarchy comp.sys.ibm.pc.hardware.* for serial port
information and perhaps a newer version of the serial FAQ.






