X Window System Input Driver
The Aiptek HyperPen X Window System Input Driver is designed to take movement reports from your Aiptek tablet and convert them into Proximity and Button Events required by the X Server and X's client applications. This driver can, in conjunction with the Tablet Manager, report on and dynamically reconfigure its parameters without rebooting X.
Which X?
The Input Driver works with X.Org and XFree86 releases of the X Window System for Linux.
Features
- Supports three pseudo-devices per tablet: the Stylus, Cursor and Eraser (synonymous with “rubber.”)
- Both Relative and Absolute coordinate reports are supported.
- Keyboard events from the up-to 24 macrokeys found along the top edge of the tablet (number of keys your tablet has depends on the model.)
- Direct events from the tablet to go to different X displays.
- Specify an active area, wherein input events from the tablet are accepted.
- Specify minimum and maximum pressure values which will be accepted from the tablet's Stylus.
- Specify minimum threshold values, on X, Y and pressure axes, to smooth out spurious movement reports, or "jittering." (This is different than the Kernel Device Driver's idea of “jitter.”)
- Stylus pressure readings may by filtered through a curve function, or reported linearly.
- X and Y coordinates may be inverted. By default, the upper left corner is coordinate (0,0). By inverting X, Y or both, any of the four corners of the tablet may be (0,0).
- X-Tilt and Y-Tilt, which report the angle at which the stylus point is held against the drawing surface (respective to both the X and Y axes.) That angle can be specified through the Linux Kernel Driver (the xtilt and ytilt files,) or through the Tablet Manager.
- Wheel reports, from the fictional Mouse Wheel, are supported. The Wheel value can be set through the Tablet Mnager or directly, through the Linux Kernel Driver (through the wheel file.)
The Three Devices
Commercial digital tablets have separate tools for freestyle drawing, erasing, and tracing. These correspond to the Stylus, Rubber (or Eraser) and the Cursor. The stylus can choose to behave as a pen, pencil, brush or airbrush. The puck, a device useful for tracing, has a lens on it for pinpoint accuracy. Inputs from all three tools come in from different devices. And of course there is the eraser...
On consumer-oriented tablets such as the Aiptek models, there is no puck, but there is a mouse. There's no eraser at all, so one has to be simulated. Both tools' input comes in through the same physical device driver, and then there's this matter of switching from pen to pencil to lens...
Active Area Parameters
The X Window Input Driver allows the user to specify that a certain portion of the tablet's physical drawing area will be used for drawing; events from outside that area are not accepted. This is called the active area. The driver allows you to specify the active area using one of three sets of parameters,
- xMax/yMax. The drawing area is assumed to begin at (0,0); what you are therefore doing is describing the maximum X and Y coordinate values of the opposite corner of the rectangle.
- xOffset/yOffset, xSize/ySize. The coordinate pair, xOffset, yOffset describes the physical location of what will be considered to be coordinate (0,0); xSize/ySize describes the coordinate of the opposite corner of the rectangle, using relative coordinates (e.g., with width and height.)
- xTop/yTop, xBottom, yBottom. xTop/yTop describes the physical location of what will be considered coordinate (0,0); xBottom/yBottom describes the coordinate of the opposite corner of the rectangle, using physical coordinates.
The following shows how the active area parameters may be used with your tablet.
 |
Looking at the above, the upper right corner of the tablet is the Origin Coordinate, e.g., (0,0). X coordinates are measured from left to right, and Y coordinates are measured from the upper corner downwards, towards the user.
With that in mind, xMax is the rightmost coordinate you can draw to; the leftmost coordinate is the Tablet Origin. Along the same lines, yMax is the bottommost coordinate you can draw to.
xTop and yTop give you the ability to specify where the simulated Origin Coordinate will be, e.g., the leftmost and uppermost coordinate of your drawing area. It's measured in actual coordinates from the Tablet's real Origin Coordinate. xBottom and yBottom are also expressed in real coordinates from the Tablet's real Origin Coordinate.
xOffset and yOffset are also measured in coordinates from the Tablet's real Origin Coordinate. However, the xSize and ySize measures are relative to the simulated (xOffset,yOffset) origin coordinate.
Why so much flexibility, to the point of distraction? Well, xOffset/xSize parameters are the most flexible insofar as you can share active area parameters with another tablet user without necessarily caring what model they own, but it's also the hardest to measure and specify. xMax/yMax is the easiest, but it favors the person who has his tablet to the right of the keyboard. Frankly, they are all useful, and excludng one for the other would have been a mistake. And, sorry for the distraction.
Handling Inverted Coordinates
By default, the X axis begins at the left corner of the tablet and increments linearly to the right corner. The left corner is considered to be coordinate (0) and the right corner considered to have the maximal X coordinate (whose value is governed by your tablet's size.) By inverting the X axis, that right corner is now considered coordinate (0), and the left corner has the maximum X value. Either or both axes may be inverted.
The question arises through: how do you specify xTop/yTop, et al parameters, when the axes will be inverted? The answer is, all parameters are considered to be specified from the relative (0,0) coordinate.
Sample Config File
If you are using the XFree86 X Server, the configuration file is known as /etc/X11/XF86Config or /etc/X11/XF86Config-4. If you using the X.Org X Server, the file is called /etc/X11/xorg.conf. (The X.Org server will look for XF86Config if the xorg.conf file cannot be found; XFree86 will look for XF86Config-4 if XF86Config is missing.)
### We're only showing the Aiptek-specific parameters |
Notes on the "Config" File
(Sorry, it's technical.) There's no real foolproof way to identify a digital tablet, in both the X Server or the USB, or the Linux HID interface. Under X, there is a notion of a tablet having the Atom of "Tablet", yet also the requirement that there be three devices, one for the Stylus, another for Eraser, and the third for Puck. There's no Atom for any of those. Yes, you can create an Atom for you driver, but there's no law that says the client application is going to understand what your Atom means. So, base hackery takes place. What kind of hackery? How about string compares for the driver's name? Yes, you can call your instance of the Aiptek driver anything you want, but unless you give it the name "pen", "eraser" or "cursor", Gtk won't recognize what's going on.
But in the meantime, name your drivers pen, eraser, and cursor in order to find contentment with Gtk. And no, I don't know what to do if you have more than one tablet. "pen0" and "pen1"? Require all styluses to have names that begin with "pen"? It's all hackery, and it's something I'd like to throw out and rewrite from top to bottom...
What else? Well, you'll notice that X wants to know the actual path of the where the tablet's movement data can be read from. And if you read my notes from the Linux Kernel Driver, you'll note that we have no guarantee where it is going to be, between reboots of the computer, or hotplug events. udev takes care of this by creating the softlink for you at boot- or hotplug-time. But if your system doesn't have udev, you get to engage in hackery: figure out where the tablet currently is located (/dev/input/event0? /dev/input/event5?), then run either a sed script or your favorite text editor to change the path in the config file (sigh)...
Or, you create the notion of a fixed location like shown above, /dev/input/aiptek, and make sure that it is a softlink to where the tablet's actually located. We've done the latter, and wrote a sysvinitrc script; it establishes the softlink at bootup. But it sadly requires that the tablet be attached at bootup. It doesn't understand hotplug events could/may have move the tablet to /dev/input/event22, instead of /dev/input/event0, where it was a boot-time... Your patches desired.
As of this writing, X is just beginning to understand hotplug events. The code isn't merged in, yet, so we're looking to see how this enhancement takes form.