--------------------------------------------
Logitech FirstMouse+ Scroll Wheel
Initialization
By A. Norman (norman@physics.wm.edu)
--------------------------------------------

--------------------------------------------
Background
--------------------------------------------
This 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)

Specificly this utility sends the proper series of 
of initialization strings to the mouse device
(or /dev/mouse or user specified device) 

After running this utility the mouse will issue
the proper event strings for movement, buttons 1-3,
and wheel scrolling.

To verify this you should run the companion 
diagnositic routines which will read the mouse
events directly from the psaux port.

For reference the following are considered
to be the "standard" MouseManPlus protocol
event strings:

0x000008 : Mouse Button Release    
0x000009 : Mouse Button 1 DOWN     
0x00000a : Mouse Button 2 DOWN     
0x00000c : Mouse Button 3 DOWN     
0x0fdec8 : Mouse Button Wheel Up   
0x01d6c8 : Mouse Button Wheel Down 
0x000108 : Mouse Right             
0x00ff18 : Mouse Left              
0x010008 : Mouse Up                
0xff0028 : Mouse Down              

(note:	events are three bytes long with low byte 
 representing the first data passed on the
 port.)

-------------------------------------------
Compliation
-------------------------------------------
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

--------------------------------------------
Testing
--------------------------------------------
Initially the utility should be run from the
console as root and with gpm turned off
(to turn off gpm on a RedHat
system issue: "/etc/rc.d/init.d/gpm stop" as 
root). 

Following this run the companion diagnostic 
tool and verify that the wheel does issue events.

After this you may restart gpm.

General syntax for operation is:

Enable_Logitech_Wheel /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/mouse.

This utility does not obtain an exclusive read
write lock on the port, so be aware that response
strings will not be quelled.

--------------------------------------------
Running
--------------------------------------------
Both gpm and X (XFree86) will partially initialize
the mouse when they start and end.  Due to this
the Enable_Logitech_Wheel utility must be run AFTER
basic X or gpm start up.

To do this place a line similar to:

/usr/local/bin/...../Enable_Logitech_Wheel /dev/mouse

in your .xinitrc or startx scripts and make sure that
the utility is suid root.

After this you can check that the mouse is issueing 
the proper command sequences using "xev" (the Xwindows
event tester)  If everything is functioning correctly 
wheel events will register as buttons 4 and 5.

If you do not get events check to make sure that the following
lines are present in your /etc/X11/XF86Config:

Section "Pointer"
    Protocol    "MouseManPlusPS/2"
    Device      "/dev/mouse"
    Buttons 5
    ZAxisMapping 4 5

To actually map buttons 4 and 5 to scroll events
(in particular clients) see the Scroll-Mouse 
Mini Howto and make the appropriate modifications 
to your Xresources.

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

The program will only issue output in the event
that it is unable to open the specified device
(e.g. you forgot to run the util as root) or
if command line help is requested with the 
-h or --help flags.

--------------------------------------------
Compatibility
--------------------------------------------

Currently this has been tested with the Logitech
FirstMouse+ M-S48 and is compatible (although
not necessary) with M-C48 (the retail mouse)

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

The mouse will issue reply strings in 
response to the initialization commands. 
These strings are not trapped and will be 
interpreted by any running window managers 
etc...as valid events.  To avoid this make
sure that the utility is started before 
your window manager.

--------------------------------------------
Questions?
--------------------------------------------
Contact me via email to:

Andrew Norman (norman@physics.wm.edu)

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