Linux multitouch howtos

We get a lot of questions on how to use the Linux multitouch drivers or how to help us with the development of the drivers for new multitouch panels. We try to provide some guidance here. See our multitouch devices page for more information about known devices and their support.

How to...

  • find the right driver for your device
  • report a new device
  • hasten support for a new device
  • get the drivers and prepare for compilation
  • use our drivers.git repository
  • compile and install
  • test your device and report problems
  • force hid-multitouch to manage your device

  • How to find the right driver for your device

    After providing specific drivers for a few models of panels, we are deploying a new unified driver named hid-multitouch that is able to deal with most HID panels, handles suspend-to-ram, and uses the latest multitouch protocol. Depending on your panel, your kernel version and your goals, there are several options open to you.

    1. Gather information

  • use lsusb or any other means to determine the USB ID of your panel (something like 12e4:d321).
  • Check the list of devices to know what support is available. Look at the last two columns.
  • use uname -a to determine your kernel version number.
  • determine if you are using Android or a more classical Linux distro, and if you care for multitouch or just getting your panel to work at all. If you have an Android version older than 4.0, the principles below apply except that you need customized drivers for what we call protocol A'.

    2. Assess your situation
  • if your device is not in the list, please report it. See How to report... below.
  • if the cell in the Generic Multitouch Driver column is green and your kernel is more recent than the version number in this cell, your panel should be supported automatically. It will both have single touch emulation and work with the most recent multitouch applications (protocol B). If you are using a Linux distro, you can proceed to How to test... below. If you are using Android, refer to our Android howto.
  • if your kernel is more recent than the version number in the rightmost cell, your panel should be supported automatically. However, it will only have the single touch emulation and work with older multitouch demos (protocol A). If you are using a Linux distro, you can proceed to How to test... below. If you are using an Android, refer to our Android howto.
  • if your kernel is older, you're in for some hacking. Skip to step 3 below if you have the required programming skills. Otherwise, you'll need to wait for future kernel releases.
  • if the cell in the Generic Multitouch Driver column is not green and the cell to its right is empty, your device is not supported yet. Yellow means we are working on it. Red means we are not. Refer to How to hasten... below.

    3. If necessary, download and compile the code
  • if you want an Android-specific driver (with protocol A', that is for Android older than 4.0) refer to our Android howto.
  • if you want the generic hid-multitouch driver (with protocol B), you can go to the HID Linux source tree for production versions. Sometimes more recent developments are available in our development repository. See How to use... below.
  • if for some reason you need a device-specific driver, a few are available in branches of our development repository and in older branches of the HID Linux source tree, most working with the older protocol A. See How to use... below.
  • report to How to compile... below

  • How to report a new device (new procedure)


    Automated procedure

  • Download this script
  • run, as root (or sudo), and follow the instructions: python report.py > descriptors.txt
  • send descriptors.txt to chatty at enac dot fr and benjamin dot tissoires at gmail dot com.


    Manual procedure

    1. Locate the device in USB/HID

  • go to /sys/bus/usb/drivers/usbhid
  • use the Sysfs lines from /proc/bus/input/devices to identify which file names of the form 2-1:1.0 correspond to your device.

    2. Release the device from USB/HID
  • for every of these, do echo 2-1:1.0 > unbind. Of course, 2-1:1.0 is just an example. Be careful not to include any trailing / in the file name.
  • check that your device has disappeared from the directory

    3. Retrieve the description of the device
  • type lsusb -v > /tmp/descriptors.txt

    4. Get raw events from the device
  • type the following commands:
    $ git clone https://github.com/bentiss/hid-replay.git
    $ cd hid-replay
    $ ./autogen.sh
    $ ./configure
    $ cd src
    $ make hid-recorder
    $ sudo ./hid-recorder | tee log.hid
  • There, you have to choose your touchscreen, and then you will have to make input on the device. Please follow these instructions to make a coherent file in our db:
    (all these has to be done in the same capture)
    - drag one finger on the screen from one corner to the opposite
    - release your finger
    - land one finger
    - land a second finger far enough from the first
    - move your two fingers
    - release the first finger
    - release the second finger
    - then, move your ten fingers on the screen and release them
    - in the end, draw sth on the screen with the pen
  • Hit Ctrl-C to end the capture and send us the files log.hid and descriptors.txt to chatty at enac dot fr and benjamin dot tissoires at gmail dot com.
  • If everything went fine, the terminal should display a lot of lines starting with 'E:' and followed by a lot of hexadecimal values.

  • How to hasten support for a new device

  • If you are the owner of a device that is not listed in our list of known multitouch devices, please report it as described above.
  • If you are a hardware maker or integrator, please contact us. Sending the hardware to us usually makes things much faster.

    More generally, please bear in mind that we are a research laboratory working on theories of interactive systems, and that we are providing this service as a practical exercise. Sometimes we also have articles to write, theories to work on, PhDs to defend, other developments to continue. We are willing to keep providing this service, but everything you can do to make our life easier will be gratefully accepted.

  • Disclaimer

    We are currently actively working on an autodetection of the different multitouch panels upstream. This autodetection has been partially included in 3.4, and is finalized in 3.5.
    We strongly advice our users to test the 3.5 kernel version as everything should work out of the box.

    How to get the drivers and prepare for compilation

    We favor a compilation method where drivers are compiled from within a full Linux kernel source tree, because in any case you will need to modify kernel sources. Consequently, the first step is to have a source tree ready. Then, several options are available to you: using pre-prepared patches, copying source files from our git repository, or using our git repository to generate patches yourself.

    Preparing kernel sources

  • fetch the latest tar.bz2 archive for your kernel version from www.kernel.org (the Full Source link)
  • extract it somewhere on your computer. In the following, '/' means the root of the Linux source tree and '//' the root of your file system.

    Then, depending on your goals and preferences, you may use several methods for getting the driver version you need.


    Getting the code, option 1: from pre-prepared patches

    We have prepared patches to make it easier for users of recent kernels to use the latest release of the unified hid-multitouch driver.
    Be aware that the old releases of the kernel have not been compiled, and may fail then. If it's the case, simply send a mail to us.

    0. Requirements
    These patches are only working for these kernels:

  • 2.6.35.10 to 2.6.35.14
  • 2.6.36.2 to 2.6.36.4
  • 2.6.37.5 to 2.6.37.6
  • 2.6.38.1 to 2.6.38.8
  • 2.6.39 to 2.6.39.4
  • 3.0.18 to 3.0.35
  • 3.1.1 to 3.1.10
  • 3.2.2 to 3.2.20
  • 3.3 to 3.3.8
  • 3.4 to 3.4.3
  • In addition, you will need the command git or patch, and the tools needed to recompile a kernel.

    1. Get the patch
    Choose the patch for 2.6.35, the patch for 2.6.36, the patch for 2.6.37, the patch for 2.6.38, the patch for 2.6.39, the patch for 3.0, the patch for 3.1, the patch for 3.2, the patch for 3.3, the patch for 3.4.

    2. Patch the kernel
  • go to the root of your source tree
  • apply the patch (git apply 2.6.3X-devel_YEAR_MONTH_DAY.patch or patch -p1 < 2.6.3X-devel_YEAR_MONTH_DAY.patch)


    Getting the code, option 2: making your own patches

    This method is for those who have special situations (device-specific driver, older kernels, etc) and are comfortable enough with making and applying patches.

  • clone our drivers.git base
  • select the appropriate branch
  • make a diff with the corresponding kernel version tag
  • apply the resulting patch to your kernel tree

    Getting the code, option 3: copying code from the git repositories

    This method is for those who have special situations (device-specific driver, older kernels, etc), are uncomfortable with making and applying patches, and are ok with editing source files themselves.

    1. fixes for 2.6.32 and older

  • if your kernel is older than 2.6.33, in /include/linux/hid.h change the end of the macro IS_INPUT_APPLICATION to (a >= 0xd0002 && a <= 0xd0006).
  • if your kernel is older than 2.6.30, you're in trouble. You might succeed by applying Henrik Rydberg's patches from 2009 to the input system.

    2. obtain driver code
    You can use code from:
  • the HID Linux source tree. Select a version and fetch drivers/hid/hid-core.c, drivers/hid/hid-ids.h, and drivers/hid/hid-{yourpanel}.c
  • from our development repository. See How to use drivers.git... below.


  • 3. incorporate the driver
  • in the drivers/hid/hid-core.c file you just retrieved, take the lines that refer to your hardware (eg. look for 3M if your hardware is 3M) and put them at the same place in your /drivers/hid/hid-core.c.
  • same in /drivers/hid/hid-ids.h
  • same in /drivers/hid/Kconfig
  • same in /drivers/hid/Makefile
  • put the hid-{yourpanel}.c file in /drivers/hid/

    Configure the kernel


  • make oldconfig
  • make menuconfig or make xconfig
  • configure HID as a module
  • go to Device Drivers ---> HID Devices ---> Special HID Drivers
  • mark 'HID Multitouch panels' as module (hit space or m)
  • Quit menuconfig (don't forget to save your changes)


  • You are ready to compile


    Refer to How to compile... below.

    How to use our drivers.git repository

    The drivers.git repository at http://git.lii-enac.fr works as follows. The master branch tracks the evolutions of the mainstream kernel. It is meant as a reference that allows you to produce patches. All other branches correspond to drivers that were never committed upstream or to preparation work that is not yet committed upstream but can be useful to others.

    Available branches

  • hid-multitouch-work: our work on the hid-multitouch driver, synchronised from time to time with the upstream kernel.
  • hid-multitouch-for-vX.Y: branches aimed at helping you to port the most recent hid-multitouch driver to older kernels.
  • hid-multitouch-for-vX.Y-android: same as above, with an additional patch to convert the driver from protocol B to protocol A' for Android pre-4.0.

  • diamondtouch: driver for the DiamondTouch multiuser tablet.
  • cypress-truetouch: device-specific driver that was never committed upstream. Made obsolete by hid-multitouch.
  • generaltouch: device-specific driver that was never committed upstream. Made obsolete by hid-multitouch.
  • pixcir: device-specific driver that was never committed upstream. Made obsolete by hid-multitouch.

  • How to compile and install

    We propose two methods. The first is simple but implies long compilation times, the second is useful when you want to iterate on your driver.

    Option 1. Making the whole kernel


    1. Compile and install the kernel
  • make (you can append '-j4' to use your multicore CPU at full speed)
  • take a coffee...
  • take a 2nd coffee... (yes, it can be very long)
  • sudo make modules_install
  • sudo make install

    2. Test your newly installed kernel
  • now it's time to reboot. Check that your grub as been updated (file '/boot/grub/menu.lst') and contains your freshly compiled kernel.
  • After the reboot and the plug-in of your multitouch device, you should see that the module hid-multitouch has been loaded by calling the command 'lsmod'.
  • It's time to play with your touchscreen.

  • Option 2. Making only your driver


    This option supposes that you already have a compiled tree and that you just want to propagate your modifications

    1. compile
  • make sure that /Module.symvers exists. Otherwise, recompile your kernel.
  • in /drivers/hid, type make -C ../.. SUBDIRS=`pwd` modules

    2. install and test the driver
  • copy the files hid-{yourpanel}.ko and hid.ko into your OS modules, that is in //lib/modules/2.6.xxx/kernel/drivers/hid. If you don't have hid.ko, this means that hid is not configured as a module but as a static part of the kernel; you will need to change this or compile and install the whole kernel.
  • load the new module hid-{yourpanel}.ko for the first time: insmod /lib/modules/2.6.xxx/kernel/drivers/hid/hid-{yourpanel}.ko
  • recompute the modules map with depmod -a

    3. check that your driver is loaded
  • first, check if there is a driver loaded: lsmod | grep YOUR_MODULE
  • find the CRC of your new driver by calling the command:
    modinfo PATH_TO_YOUR_MODULE/YOUR_MODULE.ko | \
    grep srcversion | awk -F": *" '{print $2}'
  • Then check the CRC of the loaded module with:
    cat /sys/module/YOUR_MODULE/srcversion
  • If the two outputs are equals, you are sure that you loaded the right driver.

    4. test and start again
  • test your device. See How to test... below.
  • if you need to modify your code, you need to re-load the modules each time you modify and compile them. For this, you need to unload them (rmmod hid-{yourpanel}, for instance) then reload them (modprobe hid-{yourpanel}). You need to do it at least once for hid; for this, you need to unload all modules that use it (rmmod hid-{yourpanel} usbhid hid) then load them again ('modprobe hid', 'modprobe usbhid', 'modprobe hid-mosart').

    Warning: in some distros, hid.ko is loaded from the initramfs image and not from /lib/modules/2.6.xxx at boot time. In order to use your new hid.ko there are two options (thanks to Francois Jaouen for this):
  • rebuild initramfs ('update-initramfs -u'). Beware that this option requires that initramfs be rebuilt each time hid.ko is updated.
  • replace MODULES=most with MODULES=dep in /etc/initramfs-tools/initramfs.conf and rebuild initramfs ('update-initramfs -u'). This option will remove hid.ko and many useless modules from initramfs and will allow easier modification of hid.ko (no need to rebuild initramfs after each update)

  • How to test your device and report problems

    We assume here that you just compiled/installed a driver, or that you have problems with a panel that is supposed to work. I you are just looking for demos to check the full potential of your multitouch panel, this is probably not the best place.

    Option 1: mtdiag


  • get mtdiag from our development repository
  • refer to our mtdiag page

    Option 2: manual diagnostic


    1. Is the device properly handled by USB/HID?
  • read /proc/bus/usb/devices and retrieve the section that corresponds to the device
  • look at the end of the lines that start with I, and check that Driver=usbhid is there.
  • note the port number from the line that starts with T, and the Vendor and Product IDs from the line that starts with P
  • check that one or more symbolic links in /sys/bus/hid/devices contain the above VendorID and ProductID in their name
  • go to the the directory(ies) pointed to by the above symlink(s), and look at where the symbolic link driver points to. Check that this is the desired driver.

    2. Is the device registered with the Linux input system?
  • check that one or more section corresponds to your device in /proc/bus/input/devices
  • from the line(s) that start with H, retrieve the number(s) allocated to the device by the input system. Let's call the number N.

    3. Is the output of the kernel correct?
  • install evtest (from http://cgit.freedesktop.org/~whot/evtest/ if you do not find a package for your distribution)
  • from a console, launch evtest /dev/input/eventN > /tmp/evtest.txt, then move one finger then two or more fingers (depending on your panel). Then type Ctrl-C to interrupt.
  • check the beginning of evtest.txt. You should see event codes 330, 0, 1, 53 and 54 in the list of supported events
  • (to be continued)

  • How to force hid-multitouch to manage your device

    It can happen that your device is not managed by hid-multitouch but you'd think it should. It can be because your device is in the table of supported hardware and tests show that hid-multitouch is not loaded. Or it can be because you have a new device that is not known to work but you just want to try. You can try this:

  • download load_hid_multitouch.sh and put it in /etc/udev.
  • chmod 744 /etc/udev/load_hid_multitouch.sh
  • download 41-hid-multitouch.rules and put it in /etc/udev/rules.d.
  • chmod 644 /etc/udev/rules.d/41-hid-multitouch.rules
  • Edit /etc/udev/rules.d/41-hid-multitouch.rules (insert your idVendor and idProduct, do not forget to remove the stars '*')
  • reload udev rules or reboot
  • enjoy!
  • Send us a mail to notify your device so that we can include it in the next kernel.

  • Contact: chatty at enac.fr, benjamin.tissoires at enac.fr
    Updated Sep 17, 2011.