THE 3 BUTTON SERIAL MOUSE MINI-HOWTO Geoff Short (grs100@york.ac.uk) v1.06 2nd July 1996 _________________________________________________________________ 0. Disclaimer 1. Introduction 2. Serial ports 3. Switched Mice 4. Normal Mice 5. Switching a Mouse to 3-Button Mode 6. Using gpm to Change Mouse Modes 7. XF86Config and Xconfig file examples 8. Miscellaneous Problems and Setup 9. Models Tested 10. Mouse Tail _________________________________________________________________ 0. Disclaimer The following document is offered in good faith as comprising only safe programming and procedures. No responsibility is accepted by the author for any loss or damage caused in any way to any person or equipment, as a direct or indirect consequence of following these instructions. 1. Introduction The most recent version of this document can always be found at http://kipper.york.ac.uk/mouse.html Most X applications are written with the assumption that the user will be working with a 3 button mouse. Serial mice are commonly used on computers and are cheap to buy. Many of these mice have 3 buttons and claim to use the Microsoft protocol, which in theory means they are ideal for the X windows setup. Most dual-protocol mice will work in two modes: * 2-button Microsoft mode. * 3-button MouseSystems mode. This document leads you through the different steps needed to configure your mouse in these two different modes, especially the steps needed to use the more useful 3-button mode. 2. Serial ports The first thing to do is to make sure the software can find the mouse. Work out which serial port your mouse is connected to - usually this will be /dev/ttyS0 (COM1 under DOS) or /dev/ttyS1 (COM2). (ttyS0 is usually the 9 pin socket, ttyS1 the 25 pin socket, but of course there is no hard and fast rule about these things.) You can also use the cua devices instead of ttyS, but it makes no difference as far as mice are concerned. For convience make a new link /dev/mouse pointing at this port. For instance, for ttyS0: * ln -s /dev/ttyS0 /dev/mouse 3. Switched Mice Some mice, not usually the cheapest ones, have a switch on the bottom marked `2/3'. Sometimes this may be `PC/MS'. In this case the `2' setting is for 2 button Microsoft mode, and the `3' for 3 button MouseSystems mode. The `PC/MS' switch is a bit more complicated. You will probably find the `MS' setting is for Microsoft, and the `PC' is for MouseSystems. You may find the `PC' setting described as ps/2 mode, but it should do MouseSystems as well. If you have such a mouse, you can switch the switch to `3' or `PC', put the MouseSystems settings in your XConfigs (see below) and the mouse should work perfectly in 3-button mode. 4. Normal Mice If you don't have any switches, and no instructions, then a little bit of experimentation is needed. The first thing to try is to assume the mouse maker is telling the truth, and the mouse is full Microsoft. Set up your Xconfigs to expect a Microsoft mouse (see the Xconfig section) and give it try. If the mouse didn't work at all, then you don't have a Microsoft mouse, or there is some other problem. Try the other protocols in the configs, the man page for the config file is the best place to start looking. Also look in the Miscellaneous Problems section below. What you will probably find is that when you run X, the mouse works fine but only the outer two buttons do anything. You can of course accept this, and emulate the third button (press both buttons at once to click the middle one) like you do with a two button mouse. To do this, change your Xconfig file as shown in the Xconfig example section below. This may mean you have bought a 3 button mouse for no good reason, and you are certainly no further forward. So, now you need to look at your hardware. 5. Switching a Mouse to 3-Button Mode Even cheap mice can also work under the Mouse Systems protocol, with all three buttons working. The trick is to get the mouse to think it's a Mouse Systems one, something you rarely see in your instructions. * Before you power up your computer, hold down the left mouse button (and keep it held down until it has booted to be on the safe side.) When the mouse first gets power, if the left button is held down it switches into Mouse Systems mode. A simple fact, but not always publicised. Note that a soft reboot of your computer may not cut the mouse power and therefore may not work. There are a number of other ways of switching the mode, which may or may not work with your particular mouse. Some of these are less drastic than rebooting your computer, one is more so! * If your computer is get-at-able you can unplug the mouse and plug it back in with the button held down, although I of course cannot recommend this as you are not supposed to plug things in when the power is on. * You may be able to reset the mouse by typing echo "*n" > /dev/mouse, which should have the same effect as unplugging it. Hold the left button down for Mouse Systems mode, not for Microsoft. You could put this in whatever script you use to start X up. * Bob Nichols (rnichols@interaccess.com) has written a small c program to do the same thing, which may work if echo "*n" does not (and vice versa). You can find a copy of his source code at http://kipper.york.ac.uk/src/fix-mouse.c * Someone has reported that the `ClearDTR' line in the Xconfig is enough to switch their mouse into Mouse Systems mode. * If you are brave enough, open the mouse up (remember that this will invalidate your warranty) and have a look inside. In some cases, the mouse may have a switch inside, for some strange reason known only to the manufacturer. More likely on the cheap mice is a jumper which you can move. The switch or jumper may have the same effect as a `MS/PC' switch described in the Switched Mice section above. You may find that the circuit board is designed for a switch between 2 & buttons, but it hasn't been fitted. It will look something like: ----------- | o | o | o | SW1 ----------- 1 2 3 Try linking pins 1-2 or 2-3, and see if it changes the behaviour of the mouse. If it does, you can either fit a small switch, or solder across the contacts for a quick and permenant solution. It is also possible that you need to hold down the left button when booting X windows. Some systems may send some sort of signal or spike to the mouse when X starts, so bear this in mind as well. So there you have it, the choice is yours. Stick with the default Microsoft two buttons, or work out how to switch the mode and set X up to take advantage of this. 6. Using gpm to Switch Mouse Modes gpm is the program that lets you use the mouse in console mode. It is usually included in linux distributions, and can be started from the command line or in the startup script /etc/rc.d/rc.local. gpm is the cause of much problem to people using bus mice, since it locks the mouse and stops X from using it - those of us using serial mice don't have this problem. The two main modes for serial mice under gpm are: * gpm -t ms for Microsoft mode; * gpm -t msc for MouseSystems mode. You may also be able to use gpm to probe the mouse for you and tell you what protocol the mouse is currently using: * gpm -t help However, gpm is often able to recognise all three buttons of the mouse even in Microsoft mode. And newer versions (Version 1.0 and later (?)) can then make this information available to other programs. For this to work, you need to run gpm with the -R tag, like this: * gpm -R -t ms This will make gpm re-export the mouse data to a new device, called /dev/gpmdata, which looks like a mouse to any other program. Note that this device ALWAYS uses the MouseSystems protocol. You can then set your Xconfig to use this instead of /dev/mouse as shown below, but of course you must ensure gpm is always running when you use X. Some people have reported that some middle-button events are not correctly interpreted by X using this technique, this may be down to an individual mouse setup. 7. XF86Config and Xconfig file examples The location of your configuration file for X depends on the particular release and distribution you have. It will probably be either /etc/Xconfig /etc/XF86Config or /usr/X11/lib/X11/XF86Config. You should see which one it is when you start X - it will be echoed to the screen before all the options are displayed. The syntax is slightly different between the XF86Config and Xconfig files, so both are given. Microsoft Serial Mouse * XF86config: Section "Pointer" Protocol "microsoft" Device "/dev/mouse" EndSection * Xconfig: # # Mouse definition and related parameters # Microsoft "/dev/mouse" Microsoft Serial Mouse with Three Button Emulation * XF86config: Section "Pointer" Protocol "microsoft" Device "/dev/mouse" Emulate3Buttons EndSection * Xconfig: # # Mouse definition and related parameters # Microsoft "/dev/mouse" Emulate3Buttons MouseSystems Three Button Serial Mouse * XF86config: Section "Pointer" Protocol "mousesystems" Device "/dev/mouse" ClearDTR # These two lines probably won't be needed, ClearRTS # try without first and then just the DTR EndSection * Xconfig: # # Mouse definition and related parameters # MouseSystems "/dev/mouse" ClearDTR # These two lines probably won't be needed, ClearRTS # try without first and then just the DTR Microsoft Serial Mouse with gpm -R * XF86config: Section "Pointer" Protocol "MouseSystems" Device "/dev/gpmdata" EndSection * Xconfig: # # Mouse definition and related parameters # MouseSystems "/dev/gpmdata" 8. Miscellaneous Problems and Setups * If you have trouble with your mouse in X or console mode, check you are not running a getty on the serial line, or anything else such as a modem for that matter. Also check for IRQ conflicts. * Problems with serial devices may be due to the serial port not being initialised correctly at boot. This is done by the setseral command, run from the start-up script /etc/rc.d/rc.serial. Check the man page for setserial and the Serial-HOWTO for more details. It may be worth a little experimentation with types, for instance try setserial /dev/mouse uart 16550 or 16550a regardless of what port you actually have. * Logitech mice may require the line ChordMiddle to enable the middle of the three buttons to work. This line replaces Emulate3Buttons or goes after the /dev/mouse line in the config file. You may well need the ClearDTR and ClearRTS lines in your Xconfig. * Swapping buttons: use the xmodmap command to change which physical button registers as each mouse click. eg: xmodmap -e "pointer = 3 2 1" will turn round the buttons for use in the left hand. If you only have a two-button mouse then it's just numbers 1 & . * Acceleration: use the xset m command to change the mouse settings. eg xset m 2 will set the acceleration to 2. Look at the manpage for full details. * Pointer offset: If the click action appears to be coming from the left or right of where the cursor is, it may be that your screen is not aligned. This is a problem with the S3 driver, which you may be able to fix using xvidtune. Try Invert_VCLK/InvertVCLK, or EarlySC. This info from Bill Lavender (lavender@MCS.COM) and Simon Hargrave. In the XF86Config, it might look like this: + XF86Config: Subsection "Display" Modes "1024x768" "800x600" "640x480" "1280x1024" Invert_VCLK "*" 1 9. Models tested There are a lot of different mice out there, and I cannot honestly say that you should go out and buy one rather than the other. What I can do is give a list of what I think these mice do, based on experience and heresay. Even with this information you should be a little cautious - we have two identical mice in our office on two computers, some things work on one and not t'other! Any additions to this list would be welcome. WiN mouse, as sold by Office World for eight quid. Standard dual-mode Microsoft/MouseSystems. Agiler, Standard dual-mode Microsoft/MouseSystems. Not solderable. Sicos, Works ok, needs ClearDTR & lear RTS in config. Index sell a mouse for 10 quid, Doesn't work in 3 button mode, but does have nice instructions :-) Artec, Usual dual-protocol mouse, needs `ClearDTR' set in config, NOT `ClearRTS' DynaPoint 3 button serial mouse. Usual dual-protocol mouse, needs `ClearDTR' AND `ClearRTS' in Xconfig. Genius 3 button mouse Steven Aizic is working on this one for me. Truemouse, made in Taiwan Works OK, needs `ClearDTR' in config. (From Tim MacEachern) Champ brand mouse Needs to have switch in PC mode, which enables MouseSystems protocol also. (From tnugent@gucis.cit.gu.edu.au) MicroSpeed mouse Usual dual-protocol mouse. Venus brand ($7) Has a jumper inside to switch between 2 and 3 button mode. (From mhoward@mth.com ) Saturn mouse Switched mouse, works OK as MouseSystems in 3-button position. (From grant@oj.rsmas.miami.edu .) Manhattan mouse. Switch for `MS AM' / `PC AT' modes, MS mode works fine with the gpm -R method. (From komanec@umel.fee.vutbr.cz). Inland mouse. Switch for `PC/MS' modes, works fine. (From http://ptsg.eecs.berkeley.edu/~venkates). 10. Mouse Tail Fuller details of the Xconfig and XF86Config files are found on the relevant man pages, and in the documentation about installing X windows such as the Xfree86 HOWTO. Much of the information for this document has been trawled from the various linux newsgroups. I am sorry I did not keep a record of everyone who has indirectly contributed by this route, thank you all very much. So, to sum up: * Even cheap 3 button Microsoft mice can be made to work. * Configure your copy of X to expect a Mouse Systems mouse. * Hold down the left button at power-on to switch the mouse to MouseSystems mode. * You might need to hold the left button down when starting X. * Mice are more intelligent than you think.