Linux Kernel Device Driver

The Linux Kernel Driver for the Aiptek HyperPen tablet basically sits in-between the USB sub-system and the Linux Input Event system, and provides the glue to translate and present movement events into a format that can be read from a kernel device driver.

The Kernel Driver has sole responsibility for understanding the meaning of incoming packets from the tablet; it also undertakes responsibility for programming the tablet into different modes, freeing your client software from having to know vendor- and model-specific information.

Features

The Linux Kernel Driver supports,

  1. Both relative and absolute coordinate modes (in terms of programming the tablet from one mode to another, as well as delivering either absolute or relative movement reports.)
  2. Macrokey support (the function keys running along the upper edge of the tablet.)
  3. Filter events by tool. You can specify that you only want to see input reports from either the Stylus or Mouse device, or allow reports from either device.
  4. Indicates Stylus events as a coming from the (simulated) Pen, Pencil, Eraser (Rubber), Lens, Brush, or Airbrush tools.
  5. Supports button mapping on the Stylus and Mouse. For example, the Mouse's Left Button can be specified to return the Mouse's Right Button event. Useful for left-handed users.
  6. Simulates reports from the Scrolling Wheel. The Scrolling Wheel reports may be received from the Mouse as well as the Stylus.
  7. Simulates reports of the Stylus being held at an angle from the plane of the drawing surface, in terms of X and Y axes.
  8. Pauses sending reports immediately following the pressing of the Stylus/Mouse's button, to avoid spurious movement, or <<jittering>> event reports to be sent.
  9. Reports its status, to the Tablet Manager as well as in human-readable format. The human-readable information appears through special files on the sysfs (procfs for Linux 2.4.x) virtual filesystem.
  10. Accepts programming commands, from the Tablet Manager, as well as through the sysfs (or procfs) file interface.
  11. Reports diagnostic events, in the case that the tablet behaves differently from how it was programmed, or perhaps if events are not being received by the client.

The File Interface

Drivers whose parameters and statistics can be viewed or programmed may create pseudo files. The data in these files are human-readable; to determine values, merely view the appropriate file. Conversely, to program/set an attribute, send a string (via the echo command) to the appropriate file. Under Linux 2.6.x, drivers that support the File Interface create their files in the sysfs file system, which is normally mounted at /sys. Under Linux 2.4.x, the procfs file system, mounted at /proc, was used for this purpose.


The Aiptek Kernel Drivers support the File Interface under both Linux 2.6.x and 2.4.x. Under 2.6.x, the viewable/ programmable parameter files reside at,


/sys/bus/usb/drivers/aiptek

Inside that directory, for each tablet found, you will find a subdirectory with a name like, ./2-1:0 (which contains the USB slot and connector ID.) You might wonder why we care about the USB slot: Well, if we see multiple Aiptek tablets, the Device Driver will support them both. The only way can differentiate them to you is to report their respective interface slots.


Moving into that subdirectory, you'll see the following files,


bAlternateSetting delay input_path pointer_mode vendor
bInterfaceClass detach_state jitter product vendor_id
bInterfaceNumber diagnostic model_code product_id wheel
bInterfaceProtocol event_count mouse_left size xtilt
bInterfaceSubClass execute mouse_middle stylus_lower ytilt
bNumEndpoints firmware_code mouse_right stylus_upper  
coordinate_mode iInterface odm_code tool_mode  

Some of these files are provided automatically by Linux's sysfs, which we show in boldface. The other files are created by the Device Driver. If you are using Linux 2.4, you'll only see the Device Driver-created files, at the path,


/proc/driver/aiptek/USB-slot-connector

(See the explanation above for the USB slot)

What Do The Files Do?


File Contents Read/Write Description
firmware_code 0x0400 Read-Only Contains the tablet's firmware version number.
model_code 0x0064 Read-Only Contains the tablet's model code. Not meaningful; we've seen several different tablets share the same model code! If you want to know what kind of tablet is attached, look at the size, reported below.
odm_code 0x0004 Read-Only Indicates the manufacturer of this batch of tablets.
size 3000x225 Read-Only Indicates the x-by-y coordinate size of the tablet. As we explained in model_code, the best way to really know what type of tablet is attached.
input_path /dev/input/event1 Read-Only When Linux creates a /dev device driver entry for the tablet, it creates it dynamically at boot time. The problem is, you don't know between reboots where the tablet will be mapped to. So, look here.
coordinate_mode absolute Read-Writable Indicates whether the tablet is programmed to deliver absolute or relative coordinate motion reports. You can also write to this file to program the tablet; legal values are,
absolute|relative
pointer_mode either Read-Writable Indicates whether you want input solely from one input device (e.g., the Mouse or the Stylus,) or whether you accept reports from either. Write to this file to program the Driver. Legal values are,
either|stylus|mouse
tool_mode pen Read-Writable Allows you to specify which &"tool” you want the Stylus to emulate. Valid values are,
pen|pencil|brush| airbrush|eraser|lens
mouse_left left Read-Writable Allows you to specify/remap the event returned by the Mouse's left button. Valid values are,
left|middle|right
mouse_middle middle Read-Writable Allows you to specify/remap the event returned by the Mouse's middle button. Valid values are,
left|middle|right
mouse_right right Read-Writable Allows you to specify/remap the event returned by the Mouse's right button. Valid values are,
left|middle|right
stylus_lower lower Read-Writable Allows you to specify/remap the event returned by the Stylus' lower button. Valid values are,
upper|lower
stylus_upper upper Read-Writable Allows you to specify/remap the event returned by the Stylus' lower button. Valid values are,
upper|lower
wheel 5 Write-Only This parameter allows you to send exactly one Wheel report to the client application. To send a wheel event, write to wheel; the event is sent, and the system won't send another wheel event until you to write to wheel again. Legal values are,
{0-1024}
xtilt disable Read-Writable You can specify for the Driver to simulate reports of your holding the Stylus at an angle from type drawing surface. xtilt measures this from the X axis. xtilt reports are sent along with every input report until disabled. Legal values are,
disable| {-128-127}
ytilt disable Read-Writable You can specify for the Driver to simulate reports of your holding the Stylus at an angle from type drawing surface. ytilt measures this from the Y axis. ytilt reports are sent along with every input report until disabled. Legal values are,
disable| {-128-127}
diagnostic none Read-Only Returns the Device Driver's error diagnostic message, if an error has occurred.
event_count 400 Read-Only Reports a count of the number of events processed since you last programmed the tablet.
jitter 50 Read-Writable When pressing a button on the Mouse or Stylus, the tool often moves until your hand stabilizes. To allow for that, jitter specifies a period in milliseconds during which it will ignore input reports. Legal values are integers.
delay 400 Read-Writable When programming the tablet, the protocol specifies for a delay to occur between messages. We've seen tablets that prefer a delay of 400ms; others prefer 50ms.
execute anything Write-Only Explained in Programming the Tablet.

Commentary on the File Interface Files

When developing this driver, we noticed that we could not rely on the value returned as the product_id to uniquely identify the tablet model you have: we've seen several instances of the Aiptek 6000U and 12000U sharing the same code, and others of the 6000U and 8000U, thus making at least two product_ids the 6000U has been shipped with. But, we do know the size of your tablet. For that reason, we tell you both the product_id and the tablet size.


We've seen circumstances where there are communication errors between the tablet and the USB drivers. Sometimes, having these model_code, product_code, etc., files are very helpful for debugging. But more importantly, a tablet that reports its size as 25x25 is immediately suspect!


input_path relates the device driver entry where the tablet has been mapped to. As we related above, that mapping is done dynamically every reboot. Because more and more device drivers are multi-threaded, even in loading/initialization, you can't just rely on a device entry to point to the tablet, every time. So, how is this a problem? Well, certain environments such as X have configuration files that refer to the tablet by the device driver path. If you are running a system with udev, a "rules" file for the tablet will set up a softlink, /dev/aiptek, that points to the tablet. If you don't have udev, we've made a startup script that'll make the softlink for you at boot-time, but it doesn't respond to hotplug events. We look forward to any patches you may develop...


The Kernel Driver has a limited ability to recognize errors. For example, if you tried to program the tablet to send Relative Coordinate reports, yet the tablet continues to send Absolute Coordinate reports, that's a reportable error. We use the diagnostic file for this purpose:


Contents
Meaning
No Errors The Device Driver notices no errors.
Error: receiving relative reports The tablet was programmed to return Absolute coordinate events, yet is delivering Relative coordinate events.
Error: receiving absolute reports The tablet was programmed to return Relative coordinate events, yet is delivering Absolute coordinate events.
Error: receiving stylus reports You have programmed the Driver to disallow input events from the Stylus (see pointer_mode,) yet we've seen Stylus reports. Usually not a tablet error, but a &"user” error.
Error: receiving mouse reports You have programmed the Driver to disallow input events from the Mouse (see pointer_mode,) yet we've seen Mouse reports. Usually not a tablet error, but a &"user” error.

The most useful of the diagnostic files, however, is event_count. This file reports the count of events processed by the Device Driver. Note that if there are communications problems, you might not see the event_count increment, or as fast as you might expect.


Programming the Table

We designed the Kernel Device Driver so it can be programmed and reprogrammed through the File Interface files, located in the sysfs (or the procfs for Linux 2.4.) But an examples are needed, and furthermore, the mysterious execute needs to be explained. (Note: if you are using X, we designed the Tablet Manager do be a more convenient way to configure the Device Driver.)


The command format is fairly simple, and looks like,


echo absolute > ./coordinate_mode

This becomes a minor issue when programming several Device Driver parameters at once: how does the driver tell that you are done, if you are sending commands to different files? That is the purpose of the execute file: to indicate when you have finished specifying what you want it to do, and when you want the Device Driver to execute your commands. So, let's see how that might be done,


echo absolute >./coordinate_mode
echo pencil > ./tool_mode
echo anything > ./execute

&"Anything,” you ask? Yes, any string you want can be sent to the execute file. It does not interpret what you tell it; only that you told it something.


You can now cat the various File Interface files to see that your new settings have been accepted. Note, until and unless you write something to the execute file, the Device Driver has reprogrammed itself nor the tablet. It has no other way to know when to stop listening.


Esoteric Features

We mentioned in the description of the delay file that there is a delay specified in the Kernel-to-Tablet communication protocol (wherein the Device Driver is obtaining a report or programming the tablet's mode.) There's a discrepancy as to the length of that delay; some units prefer 400ms, while others prefer 50ms. This isn't something that we can narrow down to specific models, although odm_code and firmware_code files should offer meaningful clues. Sadly, we don't have a broad enough survey of the tablets out there to know what differentiates one group from the other. For now, we'll mention that "newer" tablets prefer 50ms.


To get around this, during device driver loading/initialization, we attempt to determine which speed is appropriate for your tablet. We try (in this order,) 50ms, 400ms, 25ms, 100ms, 200ms, and 300ms. But, if you already know your tablet's preferred speed, we support a command-line parameter, which we document shortly.


Another interesting tidbit is that we know from which Input Tool, the Mouse or the Stylus, that an movement report is coming from. The client environments that we work with (generally, X) doesn't really care. They generally use the "tool button" (see the tool_mode file) report to indicate whether a report is coming from a pen, pencil, mouse, etc. This has an interesting connotation: one that a mouse, generally used only to report relative-coordinate reports, happily delivers absolute coordinate reports as well. Two, that X will pretend that a motion report coming from your tablet's mouse is really for an airbrush.


Nonetheless, the information might be useful to another client environment, so we use the REL_MISC event to communicate the actual tool used.


Of note to anyone planning to directly read from the /dev/input/eventX device file is that reports are formatted according to the Linux Input System (see the header file, /usr/include/linux/input.h.) This is interesting as it allows for generic test suites to be developed. One such is evtest, which reads and displays all events to the screen. Tablet Manager has a similar test facility.


Command Line Parameters

If you build the Device Driver to be a dynamically-loadable module, parameters can be processed from the command line. For example,


depmod aiptek programmableDelay=500

These parameters are,


Parameter Equivalent To File
 Meaning
programmableDelay delay Length of delay to use in the Kernel-to-Tablet protocol. See explanation of the delay file in The File Interface and elsewhere.
jitterDelay jitter The delay to use after the user presses or depresses a Mouse or Stylus button, during which tablet reports are ignored. See the explanation of the jitter file in The File Interface.

You can also specify module parameters in the /etc/modules.conf file.