*======================================*
| USB Mouse Driver Version 0.90 ALPHA  |
| [C] Jan Thomas 2007                  |
| md5 d1ceb0ec68586b8d969c7540cc926fff |
*======================================*


|What it is
*----------

Umouse.prg is a USB mouse driver for your ATARI ST/TT/Falcon. 

You need either the EtherNAT (http://nature.atari.org/) or the NetUSBee
(http://hardware.atari.org/). The NetUSBee is cross platform, and works
on any Atari hardware with a cartridge port. The EtherNAT is a CT60 bus
device, and therefore is only compatible with CT60 Falcons.


|How it works
*------------

When you run Umouse.prg it first looks for an EtherNAT card or a 
NetUSBee card, and looks for a mouse on both ports of each card (if 
you are lucky enough to have both!). Once a mouse is found, an 
interrupt routine is installed which periodically polls the USB 
endpoint for status packets. These packets contain mouse X/Y and button
information, which is then fed to the AES.


|Installation
*------------

TOS :-

Copy umouse.prg to the AUTO folder, and reboot. If you do this try to 
have the mouse driver as late as possible before GEM/AES starts. 
It seems better to run it after NVDI (if you use it).

MiNT :-

Copy umouse.prg to your C:\MiNT\ system directory (for example) and add
the following to your xaaes.cnf file:

    run u:\c\mint\umouse.prg

Obviously, if you put it somewhere else, change the path in the config 
file to reflect this.

Generally :-

...of course you can run it from the desktop AFTER you boot. With Atari
machines this isn't a showstopper if you don't have a normal wired 
mouse because Atari thoughtfully allowed us to use ALT+Arrow keys to 
move the mouse cursor, and Insert/Clr Home for the left and right 
buttons. It could get a little annoying though doing it every time...


|Notes and Known Issues
*----------------------

Before running umouse.prg you need to plug the mouse into one of the 
two USB sockets!

If you are currently using an original Atari mouse or some other 
treacle gunged up device, and you are using a mouse accelerator to give
it some life - you may want to disable this accelerator before running 
the mouse driver. Modern USB mice can be many times more responsive 
than the original BUS design type mouse from the early 80's.

Some mice will not detect reliably. Some won't detect at all. That is
to say, they do not respond to the hosts queries in the correct manner,
or they don't support boot-protocol. Boot protocol is a simple protocol
which is intended for use where a full USB Host stack is not used, or
able for whatever reason to be deployed. It means that the driver does
not have to go through a full HID enumeration process and go to the
trouble of asking for HID type reports. The benefits are that this is
quicker (as in less CPU cycles) but I suspect that not all USB mice
support the boot protocol for some reason.

If you get the message "Mouse not found!" after running, try AGAIN. In 
fact try 3 times at least. Currently I'm not 100% sure that my USB bus
reset code is 100% watertight, and some mouses may be taking too long to
respond after power-up. This seems to happen more often if you plug in 
the mouse and immediately run the driver. 

This is an alpha version. Debug logging defaults to being ON and is set 
to level 4 which is maximum info. This is now switchable in the config 
file (UMOUSE.CNF). If you want to change the debug level you must put
the UMOUSE.CNF file in C:\ (root directory) and change the DEBUG_LEVEL
value. 0 is off. You must copy UMOUSE.CNF to C:\ if you want to use it!


A file called umouse.log will be created or appended to in the 
directory where the driver is run from (Auto loaded drivers will write
the log to C:\) and information about the USB hardware, the device's 
descriptors, and any mouse found, will be saved to it. If you run this
driver from a floppy device the logging will be forced to level 1 (due
to disk accesses) but this will not be very useful to me... ;-)

Please - when you send me the umouse.log file, make sure that it's full 
of level 4 info for maximum troubleshooting. This will really help
future development.


|Contact information
*-------------------

If you decide to try this driver, please send me an email to:

    usb@janthomas.org.uk 

Please include useful information such as your hardware (ST/TT etc) USB
adapter make, and the make/model numbers of the mice that you tried. 
Don't forget to include a copy of the umouse.log. It could be helpful
to know what programs you are running from the AUTO folder and in what
order, and any accessories/extensions special hardware etc etc. The more
information the better!

Of course, and bug reports or feature requests will be gratefully 
accepted!


|To-do
*-----

    - Support for middle button and mouse wheel
    - Finish configuration file support
    - Optimisation of main interrupt routine
    - Move from boot-protocol to HID


|Changelog      (Anyone ever read these?)
*---------

0.90 Added ability to parse config file (only DEBUG_LEVEL for now)
     Debug level can be changed (in config file)
     Fixed issue with reading mouse product name
     A few other bugs removed
     
0.80 First release to public
     Added multi level debugging (Forced ON in this version!)
     Added dialog boxes when run in GEM.
    
0.70 Fixed bug related to detection of hardware with CPU caches on 

0.60 Fixed problem when started from AUTO folder
     Minor optimisation to interrupt routine

0.50 Improved USB reset mechanism to make mouse detection more reliable
     Added function to remove driver if already running
     Added ability to load from AUTO folder

0.40 Fixed bugs related to hardware timing
    
0.30 Better hardware access and error detection
    
0.20 Autodetects EtherNat and NetUSBee
   
0.10 First version
     Numerous bugs and lacking any real features, but hey, it works...


|Distribution
*------------

This binary and it's sources are copyright 2007 Jan Thomas. This 
package may be freely given away without charge and no cost and only in
its entirety and must be accompanied by this unaltered text file.


|Disclaimer
*----------

No warranty or fitness for any purpose expressed or implied. If this 
driver deletes your hard disk, I am not responsible. That said, it 
shouldn't and if it does, it will get a smacked bottom.
