[lk] Linux multitouch howtos

Fri, 15 Jul 2011 23:12:01 -0700

http://lii-enac.fr/en/architecture/linux-input/multitouch-howto.html#hid-multitouch

Linux multitouch howtos

We get a lot of questions on how to use our Linux drivers or how to help us with the development of the drivers for new multitouch panels. Here are a few hints, under the form of a series of howtos. See our multitouch devices page for more information about known devices and their support.

How to choose the right driver for you

After providing specific drivers for several kinds of panels, we are curently deploying a new unified driver 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 three columns.
  • use uname -a to determine your kernel version number.
  • determine if you are using Android or a more classical Linux distro, if you care for multitouch or just getting your panel to work at all. If Android, the principles below apply except that you need special 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 Upstream column is empty, your device is not supported yet (if the cell to the left is yellow, we are working on it. If it is red, we are not. Refer to How to hasten... below).
  • if your kernel is more recent than the version number in the Upstream cell, your panel should be supported automatically and you can proceed to How to test... below. If the cell to the left contains Upstream, you have the unified hid-multitouch driver with the most recent multitouch protocol B. If not, you have the device-specific driver from the cell to the right; in most cases it only supports the old multitouch protocol A. If you have Android, you need protocol A' anyway.
  • if your kernel is older, you're in for some hacking. Download code from the appropriate source, then report to How to compile... below. 

    3. If necessary, download and compile the code
  • if you want an Android-specific driver (with protocol A') refer to our Android howto.
  • if you need the upstream hid-multitouch driver (with protocol B), you can go to the HID Linux source tree
  • if you need a development version of hid-multitouch (with protocol B), you need to use our development repository.
  • if you want a device-specific driver (with protocol A) you can go to the HID Linux source tree. Some device-specific drivers are also available in branches of our development repository.
  • report to How to compile... below

    • How to report a new device

    Automated procedure


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

    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
  • send descriptors.txt to chatty at enac dot fr and benjamin dot tissoires at enac dot fr

    • 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 might make things much faster.

    • How to compile a driver into your kernel

    Drivers for multitouch devices are integrated into the Linux source tree as they are produced, but they could take time to reach your favourite distribution. You may want to use code from the HID Linux source tree or from our development repository that is more recent than your own kernel. If your kernel is 2.6.35 or 2.6.36 and you want the unified hid-multitouch driver, refer to the specific How to get... below.

    1. Get prepared

  • have a source tree of your Linux kernel, ready for recompiling modules in it. As we'll have to make changes in the hid subsystem, you might want to make sure that hid is compiled as a module and not a static part of the kernel. In the following, '/' means the root of the Linux source tree and '//' the root of your file system. 

    2. patches 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 will applying Henrik Rydberg's patches from 2009 to the input system. 

    3. incorporate the driver
  • in the recent hid-core.c (from /drivers/hid/) take the lines that refer to your hardware (eg. look for 3M if your hardware is 3M) and put them in your/drivers/hid/hid-core.c.
  • same in hid-ids.h
  • put the hid-{yourpanel}.c file in /drivers/hid/
  • in drivers/hid/Makefile add a line with obj-m += hid-{yourpanel}.o 

    4. compile
  • make sure that /Module.symvers exists. Otherwise, the only solution we found is to compile the whole kernel and have the file produced during the process.
  • in /drivers/hid, type make -C ../.. SUBDIRS=`pwd` modules 

    5. install and test
  • 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 havehid.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
  • 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) 

    5. 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.

    • How to get and install hid-multitouch

    We have prepared patches to make it easier for users of kernel 2.6.35, 2.6.36, 2.6.37 2.6.38 and 2.6.39 to use the latest release of the unified hid-multitouch driver.

    Requirements

    This howto has only been tested for these kernels:

  • 2.6.35.10 to 2.6.35.13
  • 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.2
    • In addition, you will need the command git, and the tools needed to recompile a kernel.

    Get the sources and the patches

  • fetch the latest tar.bz2 for your kernel from www.kernel.org (the Full Source link)
  • extract it into your working dir ($WORKING_DIR in this howto)
  • get our patch for 2.6.35 or our patch for 2.6.36 or our patch for 2.6.37 or ourpatch for 2.6.38 or our patch for 2.6.39

    Configure the kernel

  • cd $WORKING_DIR/linux-2.6.3X.X
  • apply the patch ('git apply 2.6.3X-devel_YEAR_MONTH_DAY.patch)
  • make oldconfig
  • make menuconfig or make xconfig
  • Go to Device Drivers ---> HID Devices ---> Special HID Drivers
  • mark 'HID Multitouch panels' as module (hit space or m)
  • Quit the menuconfig (don't forget to save your changes)

    • Compile and install the kernel

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

    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.

    • What if hid-multitouch is not loaded?

    If you saw that your device should be supported by hid-multitouch in the table of supported hardware, or if your device is not listed in the table, you can try to force hid-multitouch to handle it.
  • 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.

    Warning

    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)

    Troubles?

    Check our 'testing and reporting' howto below, and send email to benjamin (dot) tissoires (at) enac (dot) fr if necessary.

    • 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)

    Reply via email to