--------------------------------------------
Logitech FirstMouse+ Diagnostics
By A. Norman (norman@physics.wm.edu)
--------------------------------------------

--------------------------------------------
Background
--------------------------------------------
This is a small utility that reads mouse
events directly from the PS/2 port and interprets
them as the type of event they would represent.

It is designed as a diagnostic tools for use in
attempting to get OEM versions of the FirstMouse+
(based on a Zilog controler chip) to work under 
linux (by probing to see why the scroll wheel
doesn't register) As such it interprets events
as would normally be reported by a retail FirstMouse+
(e.g. scroll up is considered to be 0x0fdec8)

When you first run this diagnostic with with an M-S48
or M-S48-OEM mouse the wheel events will NOT register.
Only AFTER proper initialization will they be issued
properly, and show up under the diagnostic.

For reference the following events are supported:

0x00000008 : Mouse Button Release    
0x00000009 : Mouse Button 1 DOWN     
0x0000000a : Mouse Button 2 DOWN     
0x0000000c : Mouse Button 3 DOWN     
0x000fdec8 : Mouse Button Wheel Up   
0x0001d6c8 : Mouse Button Wheel Down 
0x00000108 : Mouse Right             
0x0000ff18 : Mouse Left              
0x00010008 : Mouse Up                
0x00ff0028 : Mouse Down              
Other      : Unknown Event        

(note:	events are three bytes long with low byte 
 representing the first data passed on the
 port.  Event codes are padded with a zero
 byte to form a long word)

-------------------------------------------
Compilation
-------------------------------------------
To compile the routine use the provided makefile.

Type:

> make

This will create the standard util.

Other supported targets are:

> make clean
> make proper

Which clean up after partial builds

--------------------------------------------
Running
--------------------------------------------
The utility should be run from the console
as root (it can be run as a normal user 
depending on the device specified) and with 
gpm turned off. (to turn off gpm on a RedHat
system issue: "/etc/rc.d/init.d/gpm stop" as 
root).  The utility should NOT be run from an
xterm, or in any other environment which 
probes mouse activity.

General syntax for operation is:

Mouse_Diag /dev/mouse

where /dev/mouse should be the device that
your mouse is attached to.  Ommiting the 
device will cause the program to default to
/dev/psaux.

To prevent certain loop conditions the program
will automatically terminate after a set number
of events (default 255).  This value may be
changed using the MAX_EVENTS macro in the
mouse_diag.c source.

--------------------------------------------
Output
--------------------------------------------

The utility will output the event number, then
the binary data pattern (three bytes padded with
a zero byte to form a single long word per event)
followed by the interpretation of the event.

Currently this has been tested with the Logitech
FirstMouse+ Retail and OEM versions.

--------------------------------------------
Bugs
--------------------------------------------

Due to the manner in which the byte stream is 
read, it is possible lose sync under some 
situations (primarily rapid movement upon 
start up)  To prevent this start the program
during a period of mouse inactivity, and then
either click button one or move the mouse
until events register.

The feature will be fixed once an internal
FIFO is implemented (which will allow event
scanning for proper sync)

--------------------------------------------
Questions?
--------------------------------------------
I will not answer the following questions because
they are covered in the documentation.  Please
do not email me with them....it wastes my time.

Ques: Why does Mouse_Diag not show wheel events 
for my M-S48/M-S48-OEM mouse?

Ans: Because you need to initialize the mouse
for the wheel to become active (see paragraph
three of this document)

Ques: Where do I find the initialization code for
my mouse?

Ans: "Enable_Logitech_Wheel" is the initialization
program.  It can be found in the same directory
that you obtained Mouse_Diag from.

Ques: What kernel version is this based off of?

Ans: 2.0.36 with SMP patches compiled with
gcc 2.7.2.3 

Ques: Why does this not work with my USB mouse

Ans: Because it is designed for PS/2 devices.  PS/2
devices are not even remotely similar to USB devices.

Ques: Are you a Logitech tech, developer, employee,
salesman, groupie, yadda, yadda, yadda......

Ans: NO!!!!  I am a poor PhD student who is trying 
to finish his dissertation and who just happened to 
get stuck with an OEM mouse....hence I fixed the problem.
There is nothing more to it.

Ques: When is the next release scheduled and will 
it allow me to use my cordless/USB/serial mouse, allow
me to scroll in <blank> applications, teach my dog to 
program in Fortran, fix the kitchen sink, yadda...
yadda....yadda...

Ans: If I find a bug that is greavious enough to merit
a new revision, then it will be posted.  There will not
be "enhancements" unless I really get bored.  As for your
dog and the kitchen sink....real dogs program in LISP, call
a plumber about the sink.

If you have further questions...read the documentation
(and the man page) first to make sure that it isn't 
already addressed there, then consider contacting me
via email to:

Andrew Norman (norman@physics.wm.edu)

and include the program name "Mouse_Diag"
in your subject line.