www.nico.schottelius.org/software/gpm2.mdwn

You know, [[gpm]] is a hack.

The idea of gpm2 is to be a nicer hack:

 * Support multiple mice
 * Do not draw stuff, but write gpm2 client to do so (os/terminal specific stuff)
 * Usable under different OS
 * Modular design, easy way to add new mice protocols
 * Allow hotplugging of mice (i.e. gpm2d can run without any mice at startup)

## Trying out gpm2

gpm2 is in its early design stage, but can so far display movement of a
ps/2 compatible mouse.

    git clone git://git.schottelius.org/gpm2
    cd gpm2
    ./gpm2hack.sh /dev/input/mice
    # move the mouse
    # press enter key to end demonstration

If you do not see mouse movement deltas, either your mouse in connected
to a different device or you probably do not have permissions to communicate
with it.

## Development

### Names

 * gpm2_*: Stuff that may appear in a library
 * *: Stuff that will only be used in the gpm2 main process

## Mouse protocols

Protocols in gpm2 are *not* part of the main system. Instead,
each protocol is implemented in its own binary, which is called
from gpm2d.

This prevents to create just another ugly "static" struct array
or the need to dlopen() and friends.

### Implementing a protocol

If you want to implement a mouse protocol, there are some things
to take care of:

 * You have a free choice of the programming language
 * gpm2d will exec() gpm2-<protocol> from its path,
 * gpm2d will connect stdin stdout of gpm2-<protocol> to the device file
 * gpm2d will connect stderr to gpm2d, so gpm2-<protocol> can send messages
 * gpm2d can drop priviliges to a specific, non-root user
 * gpm2d will send SIGTERM to gpm2-<protocol> to signal normal termination
  * gpm2-<protocol> should close the file and exit
 * gpm2-<protocol> reports about events via stderr

### Reading options from gpm2d

If at some point gpm2d needs to pass protocol options to the protocol
handler, they can be found in GPM2_PROTO_OPTS.

## Support

### IRC

You can join #gpm on irc.freenode.org.


## WARNING

Everything below this line are just random thoughts.

## Events

Events are produced by the mice handlers and forwarded to gpm2d.

### Format

As gpm2 can be used independently of the programming language, no
binary data is exchanged. An event always consists of one line
(terminated with \n), which contains up to GPM2_LINE_MAX characters
(including \n).


## Client channel

Clients for gpm2 do not need to be c programs, but can be of any kind.
The communication is a simple ASCII stream.

### Client connection to gpm2d

Clients need to open /var/run/gpm2/gpm2d.sock to connect to gpm2d.

### Event: mouse_event

    mouseid ev-type ... (more to follow)

### Event: mouse_added <file> <proto>
### Event: mouse_removed <file> <proto>

## Control channel

The control channel can be used to change things in gpm2, whereas
the client channel is read-only.

### Control connection to gpm2d

If you want to control gpm2d, you need to open /var/run/gpm2/gpm2d-control.sock.

### Command: mouse_add <file> <proto>
### Command: mouse_remove <file> <proto>


[[!tag unix]]