wdaemon README

	wdaemon is an application to provide Wacom tablets hotplugging on
X.org which doesn't supports input device hotplugging yet. wdaemon works by
creating virtual input devices using uinput kernel module and making them
available while at run time keeps looking for specified devices to be
plugged in. When X.org is started, it finds the virtual device and initializes
it and starts waiting for events, that won't happen until the real device is
connected. Once a device is plugged, udev will create its file and wdaemon
will find that, opening the newly created device file and starts forwarding
the events from the real device to the virtual device. Check
	http://jake.ruivo.org/~aris/wdaemon/wdaemon.png
picture.

wdaemon Auto-Configuration
--------------------------
	A new option was added in 0.14 (-a) to generate a wdaemon.conf based
on the plugged tablets. To use it, first plug all the tablets you have and
intend to use, make a backup of the current /etc/wdaemon.conf (if it exists)
and then run
	wdaemon -a >/etc/wdaemon.conf
and then restart wdaemon. You can then skip to xorg.conf configuration.

Configuration
-------------
	The first step to configure wdaemon to work properly is to define
udev rules to make sure every Wacom tablet you have will have a unique file,
like /dev/input/intuos3-6x8 or /dev/input/graphire2_5x7. If you have only one
tablet, it's safe to skip this step and just use /dev/input/wacom as your
device name. In modern systems, /dev/input/by-id/ directory creates symbolic
links like:
	/dev/input/by-id/usb-Tablet_PTZ-630-event-mouse
which will point to the event device of a Intuos3 6x8 or you can use already
defined rules in xserver-xorg-input-wacom.rules file present in some
distributions. Just plugging your tablet and checking /dev/input/ and
/dev/input/by-id/ is a good start: maybe your distribution already have the
rules already in place. If it doesn't, you can use 10-wacom.rules included
in this package, that will create
	/dev/input/wacomX,
	/dev/input/wacom-tablets/wacom-<model>-tabletX and
	/dev/input/wacom-tablets/wacom-<model>-tablet-<phys path>
You generaly can use the second file if you don't plan to have more than one
tablet with the same model (or just don't care about the order they'll be
used). In case you have a complex setup, the last link provides unique type
per USB port. Once you get a persistent name for each tablet model you have,
you can go to the next step.
	The second step consists in creating a persistent name for uinput
created devices, so you can configure your xorg.conf right. A rule example to
do this:
	KERNEL="event*", PROGRAM="/etc/udev/scripts/is_uinput.sh", \
		RESULT="056a-0000", \
		SYMLINK="input/uinput-devices/uinput-wacom-penpartner-tablet%e"
This will create a symbolic link for penpartner tablets. Notice it needs
is_uinput.sh script (included in this package). Also included in this package,
11-uinput-wacom.rules has these rules done for most tablets.
	Why do you need these links? To avoid having to hand configure your
X.org. Once the uinput links and tablet links are done, you need to configure
wdaemon to monitor the tablets. Let's say we have two tablets, an Intuos3 6x8
and a Graphire4 4x5. Using provided 10-wacom.rules, we'll get these symbolic
links with them attached:
	/dev/input/wacom
	/dev/input/wacom1
	/dev/input/wacom-tablets/graphire4-4x5-tablet
	/dev/input/wacom-tablets/graphire4-4x5-tablet-pci-0000:00:1d.3-usb-0:2:1.0
	/dev/input/wacom-tablets/intuos3-6x8-tablet
	/dev/input/wacom-tablets/intuos3-6x8-tablet-pci-0000:00:1d.3-usb-0:1:1.0
We can use graphire4-4x5-tablet and intuos3-6x8-tablet as they're different
types. So we go ahead and write the /etc/wdaemon.conf:
	device = 36,/dev/input/wacom-tablets/intuos3-6x8-tablet
	device = 6,/dev/input/wacom-tablets/graphire4-4x5-tablet
Notice the spaces. The wdaemon parser is very rudimentary at this point and
can get easily confused. In order to determine "36" and "6", you must know what
type of tablet you have. This needs to be done in order to wdaemon create the
uinput device properly so it can fake your tablet. It could be done just
copying the settings from your tablet, but that would require the tablet being
physically connected. To get the list of supported tablets and their numbers,
run:
	# wdaemon -w
	wdaemon version 0.07
	Available Wacom tablet types:
	0       Wacom Penpartner
	1       Wacom Graphire
	2       Wacom Graphire2 4x5
	3       Wacom Graphire2 5x7
	4       Wacom Graphire3
	5       Wacom Graphire3 6x8
	6       Wacom Graphire4 4x5
	7       Wacom Graphire4 6x8
	8       Wacom Volito
	(...)
	34      Wacom Intuos2 12x18
	35      Wacom Intuos3 4x5
	36      Wacom Intuos3 6x8
	37      Wacom Intuos3 9x12
	38      Wacom Intuos3 12x12
	(...)
So we have number 6 for Graphire4 4x5 and 36 for Intuos3 6x8:
	device = 36,/dev/input/wacom-tablets/intuos3-6x8-tablet
	device = 6,/dev/input/wacom-tablets/graphire4-4x5-tablet
This sample wdaemon.conf will look for an Intuos3 6x8 tablet in the specified
device file and for a Graphire4 4x5 in the another specified file. That's why
we need persistent names for tablets. With the provided System V type of
initscript (wdaemon.initrd), wdaemon will start and create two new input
devices that will look like wacom tablets, even if the real tablets aren't
plugged. Checking /proc/bus/input/devices you'll get:
	I: Bus=0006 Vendor=056a Product=00b1 Version=270f
	N: Name="uinput: Wacom Intuos3 6x8"
	P: Phys=
	H: Handlers=mouse3 event4 js0
	B: EV=f
	B: KEY=18ff 1f00ff 0 0 0 0
	B: REL=100
	B: ABS=1000f00017b

	I: Bus=0006 Vendor=056a Product=0015 Version=270f
	N: Name="uinput: Wacom Graphire4 4x5"
	P: Phys=
	H: Handlers=mouse4 event5 js1
	B: EV=f
	B: KEY=18ff 1f00ff 0 0 0 0
	B: REL=100
	B: ABS=1000f00017b
The uinput udev rules are needed in turn to make the device file names for
these new uinput created devices fixed, because X.org will need it. Using the
provided 11-uinput-wacom.rules, we got these symbolic links:
	/dev/input/uinput-devices/uinput-wacom-graphire4-4x5-tablet
	/dev/input/uinput-devices/uinput-wacom-intuos3-6x8-tablet
Notice that the order used in wdaemon.conf is used to create the devices, so
if you got two tablets of same kind with a wdaemon.conf like this:
	device = 36,/dev/input/wacom-tablets/intuos3-6x8-tablet-pci-0000:00:1d.3-usb-0:2:1.0
	device = 6,/dev/input/wacom-tablets/graphire4-4x5-tablet
	device = 36,/dev/input/wacom-tablets/intuos3-6x8-tablet-pci-0000:00:1d.3-usb-0:1:1.0
Notice that the symbolic link used was the one with physical path to make sure
the order won't change. We could just use:
	device = 36,/dev/input/wacom-tablets/intuos3-6x8-tablet
	device = 6,/dev/input/wacom-tablets/graphire4-4x5-tablet
	device = 36,/dev/input/wacom-tablets/intuos3-6x8-tablet1
If we don't care about the order. Anyway, with the given order, the symbolic
link
	/dev/input/uinput-devices/uinput-wacom-intuos3-6x8-tablet
will always point to the first Intuos3 tablet specified in the configuration
file and
	/dev/input/uinput-devices/uinput-wacom-intuos3-6x8-tablet1
will point to the second one.
	With the wdaemon.conf configured, it's possible to configure X.org to
use the uinput created devices:
	Section "InputDevice"
		Identifier "cursor"
		Driver "wacom"
		Option "Type" "cursor"
		Option "Device" "/dev/input/uinput-devices/uinput-wacom-intuos3-6x8-tablet"
		Option "Mode" "relative"
		Option "Tilt" "on"
		Option "Threshold" "20"
		Option "Suppress" "6"
		Option "USB"    "On"
	EndSection
Just go ahead and configure X.org for Wacom as you already does it, but using
the uinput created devices instead of real ones. Just restart X.org and you
can plug and unplug the tablets as much as you want. Even if X.org starts
without any tablet plugged, you can plug them later and they'll just work.

If you have problems
--------------------
	Enabling debug with -d <level> option along with -o <file> option is
a good idea to try to discover what's going on. If you're unable to find a
solution, send:
	- xorg.conf
	- Xorg.*.log
	- wdaemon.conf
	- the command line options used
and before and after the event that trigger the problem (e.g. before you plug
the tablet, after you plug the tablet), capture these:
	- ls -l of all /dev/input files
	- /proc/bus/input/devices
You can send the output to aristeu.sergio@gmail.com with subject:
	[wdaemon] <problem description>

