The 3 Button Serial Mouse mini-HOWTO

Geoff Short, geoff@kipper.york.ac.uk

v1.33, 31 May 1998
How to get a 3 button serial mouse working properly under Linux.

1. 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.

2. Introduction

The most recent version of this document can always be found at http://kipper.york.ac.uk/mouse.html

There is a Japanese translation at http://jf.gee.kyoto-u.ac.jp/JF/JF-ftp/euc/3-Button-Mouse.euc; and a French one at http://www.freenix.fr/linux/HOWTO/mini/3-Button-Mouse.html. Other translations may be available - check your local LDP mirrors.

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. (The record for the cheapest working 3 button mouse currently stands at $1.14!)

Most dual-protocol mice will work in two modes:

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.

As distributions become easier to set up, some of the problems ought to go away. For instance, RedHat have a mouseconfig program to set things up for you. However, some versions of RH5.0 had a bug in mouseconfig, so make sure you check for patches.

3. 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.) There are also an equivalent number of /dev/cua devices, which are almost the same as the ttyS ones, but their use is now discouraged. For convenience make a new link /dev/mouse pointing at this port. For instance, for ttyS0:

ln -s /dev/ttyS0 /dev/mouse

4. 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.

5. 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 a 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.

6. 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.

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, two are more so!

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.

7. Wheeled mice

Mice with wheels have emerged in the last few years, starting with the Microsoft Intellimouse and spreading to other manufacturers. The wheel can be clicked like a button, or rolled up and down. Far and away the best reference for information is http://www.inria.fr/koala/colas/mouse-wheel-scroll/ which describes how to get lots of X applications to recognise the scrolling action.

In general, you'll need a fairly new Xserver to use the scrolling action, but some older servers will recognise the clicking actions. For instance, the Intellimouse is supported by XFree 3.3.1 and later.

8. 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. Note that distributions don't always have the most recent version (1.13 at time of writing) which can be found on mirrors of sunsite.unc.edu.

The main modes for serial mice under gpm are:

gpm -t ms
gpm -t msc
gpm -t help

for Microsoft or MouseSystems modes, or to probe the mouse for you and tell you what it found. To run gpm in MouseSystems mode, you may need a -3 flag, and possibly a DTR option, using the -o dtr flag:

gpm -3 -o dtr -t msc

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.

Changing button mapping for gpm and X ( gustafso@math.utah.edu)

You may find that gpm uses different default button mappings to X, so using both systems on the same machine can be confusing. To make X use the same buttons for select and paste operations as gpm, use the X command

xmodmap -e "pointer = 1 3 2"
which causes the left button to select and the right button to paste, for either 2-button or 3-button mice. To force gpm to use the X standard button mapping, start it with a -B command, eg:
gpm -t msc -B 132

9. Using two mice

In some cases, for instance a laptop with a built-in pointing device, you may wish to use a serial mouse as a second device. In most cases the built-in device uses the PS/2 protocol, and can be ignored if you don't wish to use it. Simply configure gpm or X to use /dev/ttyS0 (or whatever) as usual.

To use both at once, you can use gpm -M to re-export the devices. More details in the gpm man page. Also, XFree 3.3.1 and later support muliple input devices, using the XInput mechanism. Auto-generated XF86Config files should have the necessary comments in them.

10. 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

Microsoft Serial Mouse with Three Button Emulation

MouseSystems Three Button Serial Mouse

Microsoft Serial Mouse with gpm -R

11. Cables, extensions and adaptors

The only wires needed in a mouse cable are as follows: TxD and RxD for data transfer, RTS and/or DTR for power sources, and ground. Translated into pin numbers, they are:

            9-pin port     25-pin port
        TxD     3                2
        RxD     2                3
        RTS     7                4
        DTR     4               20
        Gnd     5                7

The above table may be of use if you wish to make adaptors between 9- and 25-pin plugs, or extension cables.

12. Miscellaneous Problems and Setups

13. 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 had two identical mice in our office on two computers, some things worked on one and not t'other! Any additions to this list would be welcome.

Mouse Systems optical mouse, serial version
Works well (as you might expect from the name!) without ClearDTR or ClearRTS in the config.
WiN mouse, as sold by Office World for eight quid.
Standard dual-mode Microsoft/MouseSystems.
Agiler Mouse 2900
Standard dual-mode Microsoft/MouseSystems. SYSGRATION SYS2005 chip is solderable.
Sicos mouse,
Works ok, needs ClearDTR & Clear RTS in config.
Index sell a mouse for 10 quid,
Doesn't work in 3 button mode, but does have nice instructions :-)
Artec mouse
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 Easymouse 3 button mouse
Works fine with Mouseman protocol without the ChordMiddle parameter set. From Roderick Johnstone ( rmj@ast.cam.ac.uk)
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
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).
qMouse (3-button), FCC ID E6qmouse X31.
Sells in the USA for about $10. Works with `gpm -t msc -r 20'. No jumpers or switches for MouseSystems 3-button mode. Unreliable in X. Does not respond to echo "*n" > /dev/mouse.
Mitsumi Mouse (2-button), FCC ID EW4ECM-S3101.
Sells in the USA for about $12. Reliable in X and under gpm, smooth double-button. (These two from gustafso@math.utah.edu)
PC Accessories mouse that i got from CompUSA for under $10.
Has PC/MS switch on bottom. Works OK. (From steveb@communique.net)
First Mouse - seriously cheap at 7.79 pounds at Tempo.
Dual Microsoft/MouseSystems, mode set by button depress at power-up. No switches, no links. Four wire connection, echo '*n' doesn't work. `gpm -R' works a treat. (From peterk@henhouse.demon.co.uk)
Trust 3-button mouse.
Dual-mode with switch, works OK as MouseSystems in `PC' mode. gpm doesn't like the Microsoft mode.
Chic 410
Works perfectly when kept in ms mode and used with the gpm -R command. From Stephen M. Weiss ( steve@esc.ie.lehigh.edu)
KeyMouse 3-button mouse.
Works OK with ClearDTR and ClearRTS in Xconfig; `-o dtr' needed with gpm. (From EZ4PHIL@aol.com)
Qtronix keyboard `Scorpio 60'
All three buttons work in MouseSystems protocol. (From hwe@uebemc.siemens.de)
Tecra 720 laptop
The glidepoint is on /dev/cua0; the stick is on /dev/psaux. (From apollo@anl.gov)
Anubis mouse
Works fine, need to hold down left button whenever switching to the X virtual console. (From Joel Crisp)
Yakumo No.1900 mouse
Works with gpm -R -t ms exporting to X. (From Oliver Schwank)
Genius `Easy Trak' Trackball
Is not Microsoft compatible, use Mouseman in the Xconfig and it will work fine. (From VTanger@aol.com.)
Highscreen Mouse Pro
`Works fine' says alfonso@univaq.it.
Logitech CA series
Works in X using MMseries protocol, at 2400 Baud, 150 SampleRate. (Should also apply to Logitech CC, CE, C7 & C9 mice). (From vkochend@nyx.net.)
A4-Tech mouse
Works OK, needs DTR line under both X and gpm. (From deane@gooroos.com)
Vertech mouse
Normal Microsoft/Mousesystems behaviour, can be soldered for a permenant fix. (From duncan@fs3.ph.man.ac.uk.)
Boeder M-7 ``Bit Star'' (and other M series apart from M13)
Switches to Mousesystems protocol by holding any button down at power-on. (From mailto:sjt@tappin.force9.co.uk.)
Mouse Systems ``Scroll'' Mouse (four buttons and a roller/button)
Has a 2/3 switch - in mode 3 functions as a three button MouseSystems mouse, ignoring extra button & wheel. Doesn't need ClearRTS/DTR. (From parker1@airmail.net.)
Radio Shack 3-button Serial Mouse
Model 26-8432, available in Tandy for about 20 quid. Works as Mousesystems with ClearDTR. (From Sherilyn@sidaway.demon.co.uk.)
Dexxa serial mouse
Works fine using Microsoft protocol in Xconfig, no ChordMiddle or anything needed. (From mailto:slevy@ncsa.uiuc.edu.)
Belkin 3 button mouse
As purchased from Sears (\$10), needs -o rts under gpm (and probably ClearRTS under X) when in PC mode. (From mailto:mmicek@csz.com.)

14. Further Information

15. Mouse Tail

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: