mouse_remoted ============= What it is, and how it works ---------------------------- This program is a simple Linux driver for the X-10 univeral remote control including mouse. This device is various known as MK19 or JR20. Probably similar devices would work as well. The remote mouse will work automatically with Linux as a standard mouse, as it emulates a PS/2 mouse and plugs into the PS/2 port. However, there are about 20 other buttons on the device whose functions do not correspond to any standard mouse operation. It would be nice if these buttons could be made to do something useful. mouse_remoted does not interpret these button-presses itself; if simply filters mouse input into two data streams. The first, which appears at /dev/mouse_remote, is simply standard mouse data. The second, which appears at /dev/pc_remote, is a stream of single bytes, each of which corresponds to a press of one of the non-mouse buttons. It is easy to write a simple program that reads from /dev/pc_remote, and does whatever is required. The driver is supplied with a simple program called mouse_remote_exec which executes a shell script corresponding to each button. Using this script, it is straightforward to carry out straightforward operations (e.g., playing audio files, and controlling volume levels) usings the remote control. /dev/mouse_remote and /dev/pc_remote are not standard device entries, they are named pipes (FIFOs) which must be created before use. The Makefile does this automatically. To use mouse_remoted with ordinary mouse-aware software, that software must be configured to take its input from /dev/mouse_remote, not /dev/mouse or /dev/psaux, etc. The mapping of button presses onto bytes does not have any particular significance: it is directly as supplied by the hardware. A list of button-byte mappings is given in the file mouse_remote.h. Alternatively, the test program mouse_remote_test will print the code for each button pressed. This program is an effective test of the driver: if it reports button presses, then it looks as though everything is working. mouse_remote_exec ----------------- This is a simple program to make use of the mouse_remoted driver. It allows remote-control keypresses to execute shell scripts. By default, when button number NN is pressed, it will attempt to execute a program (usually a shell script) called .mouse_remote_NN.sh in the user's home directory. The directory can be changed on the command line. Compiling --------- This program should compile under any Linux system that has the `pthread' and `popt' development packages installed (these are standard parts of all modern Linux distributions). It has been tested with popt version 1.3 and pthreads version 3.1. Simply unpack the distribution tarball into any convenient directory and type `make clean' followed by `make'. Note that the Makefile contains definitions for the devices that mouse_remoted reads and writes, and it is probably best to modify these things here rather that in the source. Installation ------------ Typing `make install' will install the binaries, and also the startup script S90mouse_remote (in rc.d/rc3.d and rc.d/rc5.d). The script has the effect of starting the mouse_remote server at boot time on most Linux systems. You may want to customize this script before installation. The binaries are mouse_remoted, mouse_remote_test and mouse_remote_exec. These can be installed in any convenient place, e.g., /usr/sbin. Notes ----- 1. mouse_remoted should probably be started at boot time. It should certainly be started before any services that depend on it, if they are likely to complain if it isn't started. 2. mouse_remoted is intended _not_ to be run as root. To make this possible, the _real_ mouse device /dev/mouse must be readable by non-root processes. It will not hurt to run mouse_remoted as root, but it should be unnecessary. 3. To use mouse_remoted, the software that uses the mouse must be capable of having its input device reconfigured. For example, for the XFree-86 servers, modify the configuration file (typically /etc/X11/XF86Config) modify the line ``device='' in the section ``pointer'. If your software is hard-coded to use, say, /dev/mouse for input, then it won't be possible to use mouse_remoted. A possible solution, if you have the source code, is to modify mouse_remoted to take input from a different device, then link the real mouse driver (e.g., /dev/psaux) to this new device. Then modify mouse_remoted to write to /dev/mouse. These settings can all be made in the Makefile; it should not be necessary to change the code. 4. There is little to stop mouse_remoted from running alongside another program that takes mouse input from /dev/mouse. Typically GPM does this, and is also started at boot time. This is counterproductive. A given piece of mouse data will only be picked up by one of these programs. Operation will be erratic in all cases. You should reconfigure other mouse-aware software to take input from the output of mouse_remoted (/dev/mouse_remote). 5. The mouse remote generates a constant stream of data if a button is held down. This is appropriate for mouse movements, and for some other things, but in general this is not helpful. mouse_remoted prevents the same button generating output at intervals more frequent than once per second. 6. mouse_remote_exec spawns shell scripts synchronously. Use the '&' directive in the script if the script takes some time and you want mouse control to be regained immediately. The fact that the script is synchronous allows scripts to read from /dev/pc_remote themselves. Bugs ---- Undoubtedly, although no obvious nasty ones. If the mouse_remoted server is killed, either by the system or by a user sending a kill signal, any processes reading /dev/pc_remote will receive a `0' keycode. mouse_remoted uses Linux threads (pthreads) to separate the data collection and data output functions. The use of pthreads leads to astonishingly high values of CPU load to be reported. However, these reports are probably erroneous. The use of this software does not cause any noticeable reduction in speed on my systems. Author & copyright ------------------ This software was written by Kevin Boone, and is copyright (c)2000 Kevin Boone, all rights reserved. Please feel free to use, modify and distribute it as you see fit, subject to the GPL licencsing considerations set out in the file COPYING. It is distributed in the hope that it will prove useful, but there is no warranty of any kind. The author can be contacted on k.boone@kzone.eu.org