                           X10 MouseRemote for Linux
                                  by Dan Wilga

X10's MouseRemote is a remote control that not only acts as a universal remote
for a variety of home theater components, but it can also work as a wireless RF
mouse for any PC. Combine this with some way to get the video from the PC to
your home theater setup and an Internet connection, and you've got a great Web
browser, MP3, CD, and DVD player right in your living room.

One of the things that seems to be missing is good software to take advantage
of the special buttons on the MouseRemote under Unix. Here is my attempt to
solve that problem. It was tested in Linux, but the client at least should work
on nearly any flavor of Unix. The server may need some tweaking.


The Server
----------

The server is a modified version of a daemon called MultiMouse. Originally,
this program was designed to allow more than one mouse to be used at the same
time. Then, tomtek@tomtek.com modified it to decode MouseRemote packets and
write them to a FIFO (pipe) that could be read by a client. Tom also wrote a
client in C, but I didn't think it was quite flexible enough, so I rewrote it
in Perl and also fixed a little bug in Tom's modified code.

To compile the server, start by looking at the Makefile. The default install
locations are /usr/local/bin for the multimoused (daemon), and /usr/local/sbin
for multimouse, which is a script to simplify running multimoused.

If everything is to your liking, type:

  make
  make install

Please note that the two FIFOs this script creates for you will have the
permissions 666, meaning any user can read or modify them. You may want to
restrict this after running make install. The first FIFO, /dev/mumse is the new
MultiMouse device. The FIFO /dev/x10.fifo is the MouseRemote data.

Next, you will have to start MultiMouse. You should do this by running the
/usr/local/bin/multimouse command as root. Here are some suggested
commandlines. Modify these depending on your particular device names:

  For a PS/2 mouse:
    /usr/local/bin/multimouse -X10 /dev/psaux &

    This assumes you are using the psaux device for the PS/2 port, and your
    desktop mouse is also plugged into the MouseRemote interface.

  For a serial mouse:
    /usr/local/bin/multimouse -SX10 /dev/ttyS0 &

    Note the different device name: SX10 (Serial X10?).
    This assumes you are using the ttyS0 (COM1 in PC-speak) device for the
    MouseRemote, and your desktop mouse is also plugged into the MouseRemote
    interface.

Once you get things working, you can add this command to one of your system
startup files, like /etc/rc.d/rc.local.

Next, you have to change the configurations for all of your programs that
normally use the mouse port to instead use the new MultiMouse device,
/dev/mumse.

IMPORTANT: You also need to change the mouse protocol type to MouseSystems,
regardless of the actual type your mouse is! It took me a while to figure this
one out :-).

For example, let's say your X Window configuration, XF86Config, looks like
this:

Section "Pointer"
   Protocol        "Microsoft"
   Device          "/dev/psaux"
   ...whatever...
EndSection

You should change this to:

Section "Pointer"
   Protocol        "MouseSystems"
   Device          "/dev/mumse"
   ...whatever...
EndSection

Once you've done this, and made sure the daemon is running, you should be able
to use X just like you always did, with either your regular mouse or the
MouseRemote.


The Client
----------

Now we come to the good part: doing something with all that MouseRemote data
that is in the FIFO. To run my program you will need:

  Perl 5 or newer               http://www.perl.org
  Time::HiRes module    http://cpan.perl.org/modules/by-module/Time/

You will probably want to run the client as a particular user, and you don't
want other users to be able to run it. So it might just be easiest to leave it
somewhere in the home directory of that user. Of course, you can always put it
somewhere like /usr/local if you want to.

The first thing you'll want to do is have a look at the configuration file,
MouseRemote.conf. It has comments about how to configure the commands that will
be run when you hit each key on the remote, depending on which mode the remote
is in.

Note that the MouseRemote only sends keystrokes for PC, WEB, CD, DVD, and PHONE
modes to the interface. There's no way for this program to act on keystrokes
while one of the other devices is selected.

Within the .conf file, the keys can be listed in any order, or left out
completely. Each device has its own section of the file, starting with
[DEVICENAME].

If a key's name starts with a period (like ".VolDown"), then when you press and
hold that key on the remote, the script will try to execute the command as
quickly as possible, repeatedly, until you let go of the key. You'll want to
use this for functions like Page Up/Down and Volume Up/Down.

If the name does not start with a period, then the script will wait a while
before trying to execute the command again. This prevents things like a command
to close the top browser window from quickly closing all of your windows before
you let go of the key.

The key repeat rate is controlled by the constant $DEBOUNCE_EXPIRE in the
MouseRemote.pl file. The default is 0.75, or 3/4 of a second. However, you may
find that even with autorepeat turned on, programs like Netscape react a little
slowly. This is due to the fact that we're using a Perl script to run a program
to do something that is more readily controlled in the user interface (X). On
my Cyrix P200, scrolling a Web page in Netscape is only a tiny bit slower than
I'd like it to be, though.

I haven't included any CD or DVD commands in the sample file because I don't
have a sound card in my Linux box, so I wouldn't be able to test these things.
For more information on Netscape's "remote" parameter, run:  netscape --help.
And if you manage to figure out how to make Netscape immediately scroll to the
top/bottom of the current Web page, let me know :-).

Before you run MouseRemote.pl, you may have to change the very first line of
the program to point to the exact location of your Perl executable. Do a
"whereis perl" to find this.

Runtime syntax:

  MouseRemote.pl [-c configfile] [-d] [-h] [-p pidfile] [PC|CD|WEB|DVD|PHONE]

  -d: Turn on debugging messages
  -c: Load an alternate conf file. By default, when the program runs it looks
      for the config file MouseRemote.conf in the current directory.
  -h: This help message
  -p: File where the script's pid is written. The default is MouseRemote.pid.
  Device name: The default device to use. This script has no way of knowing
      what device is currently selected by the MouseRemote when it starts, so
      you may have to press a device button before using a MouseRemote button
      for the first time after the script starts. The WEB device is the default
      if this parameter is not used.

If you want to use MouseRemote.pl to control Netscape or other X Window
programs, you must run it as the same user who is going to be using those
programs. For testing, a good way to do this is from a command window opened
within the X session.

Once you get MouseRemote.pl working the way you want it to, you'll probably
want to add it to the .Xclients file of whatever user runs X. It's important
that you NOT do this for more than one user, though. A sample command you could
add to .Xclients would be:

  cd ~/MouseRemote
  exec MouseRemote.pl &

To force MouseRemote.pl to reload its config file, send it a SIGHUP signal. One
way to do this is:

  kill -SIGHUP `cat MouseRemote.pid`

So, it only follows that you can also terminate the process with:

  kill `cat MouseRemote.pid`


About My Setup
--------------

I currently run a RedHat Linux machine with X10's Big Picture for video
transmission and the MouseRemote feature. My MouseRemote.conf is setup almst
identically to the sample included in this package.

I find that clicktv.com (the address is listed for the Guide button) is one of
the better sources for TV listings. No annoying frames, and only one ad banner
to deal with.


References
----------

MultiMouse      Original Author                 manabe@papilio.tutics.tut.ac.jp
                Modified by                     tomtek@tomtek.com
                                                http://www.44.cyberhost.net/
                                                        tomtek/HA/home.html

X10 USA         MouseRemote/Big Picture/etc.    www.x10.com

MouseRemote.pl  Dan Wilga                       gribnif@pair.com
                                                www.pair.com/gribnif/ha
