Calibrating the touch input

The idea of the touch screen is that the user interface objects presented on the screen can be directly pointed at, using a pen or a finger. Ideally, when user sees even a single pixel at, say coordinates 100, 150 and then pushes the screen with a pen at this point exactly, the touch screen / mouse driver should register exactly the same coordinates and report them to the windowing engine.

However, in practice things are a bit different. For example, the resistive touch panel used e.g. in LG L1730SF is placed on top of the display panel. In real life things are not perfect, so there will be some offset in the display component framing, in the touch panel component framing, and in their relative placement on top of each other. Every manufactured device ends up being slightly different.

The result is that there will be some offset between the actual/perceived location of the touch, and the location reported to the windowing system that draws the mouse cursor and processes points and clicks. This is bad. For example, it can be very annoying if you are trying to hit a link on a web page, but always seem to miss it just a little!

Fortunately, this error can be fixed fairly well with a proper calibration. Calibration is a procedure based on showing a known location to be touched on the screen e.g. with an X mark, and then sampling the actual location that was touched. The difference between screen coordinates and mouse coordinates tells what kind of offset the particular display has. For example, when the user thinks he has touched precisely coordinates 100, 150 we may have received 108, 145 as mouse coordinates. Thus the difference is +8, -5. In order to correct the error, the offset can be removed by manipulating the mouse coordinates with the offset values found via calibration. This will be done already at the driver level, e.g. (+8, -5) could be subtracted from all input reported by the touch panel. The X windowing system would then get slightly different mouse coordinates that should match much better with the screen coordinates and perceived touch location.

Note that proper calibration is always somewhat user dependent, as there is a small distance between the touch panel and the surface of the image in the display device. Depending on the way the display is mounted (e.g. on a wall or table), the taller the person is the more angled is her view to the display. As a result, the farther away she actually touches from the location that she thinks she touches. It is like with shadows: if the sun shines right on top of an object there will be no shadow at all (precise touch), but from another angle a shadow will be cast (offset). In addition, when fingers are used for touching, users may have different preference on which part of the finger is the “center” point that should be registered as the touch location. E.g. is it the center of the area of the finger that touches the display (finger tip touch), or perhaps the location at the top boundary of the touch (fingernail touch). Nevertheless, the touch control cannot be very precise without personal calibration.

For proper calibration, one pair of sample values (x offset, y offset) is not enough – these correction factors must be taken separately for different areas of the display. In small devices, such as PDAs and mobile phones, it is very common to use 5 samples: 4 corners and the center of the screen. However, Evtouch uses nine calibration samples, as also centers of the edges of the screen are sampled. Based on the samples it then calculates the proper correction factor (i.e. the actual x,y offset to be subtracted from touch input is some kind of approximation based on the distance to a few nearest sampled calibration points).

Next, we will begin to figure out how to apply proper calibration value pairs (the 9 samples) to the xorg.conf file. They will be eventually listed as Options in our touch screen section.

There are basically two methods. One is naturally manual trial and error based, where one tries to adjust a value and then tests whether it helped. However, due to large number of adjustable values (9 samples with two values = 18) and the approximation in the algorithm, this is laborious. The other method involves using a calibration tool, which is a simple software aimed for making the calibration as simple as touching a few spots on the screen. We’ll of course try the latter first and see whether it works for us.

Let’s first activate the calibration mode in Evtouch. In console, type

sudo nano /etc/X11/xorg.conf

Find the touchscreen section, and uncomment/write this:

Option   "Calibrate" "1"

This will turn calibration support on from evtouch driver module. You might want to remove “CorePointer” from touchscreen, and make sure that “Configured mouse” is enabled to allow mouse usage during calibration. Save and exit.

Next, we need to stop X:

sudo /etc/init.d/gdm stop

Continue in one of the consoles by pressing e.g. CTRL+ALT+F2. To begin calibration, first go here:

cd /usr/lib/xf86-input-evtouch

Before starting the calibration tool, we need to copy a bitmap file for empty cursor to file system root (!):

sudo cp /usr/share/xf86-input-evtouch/empty_cursor.xbm /

Then start the calibration tool as follows:

sudo ./calibrate.sh

A white screen with nine black crosses should appear. They are in the corners, middle of border lines, and in the center. Basic idea is that when you press the Enter key, one of the crosses turns red and you should click it as precisely as you can. Then the next one will turn red, and so on until all 9 have been tapped. Then the proper offset values will be printed, to be copied to your xorg.conf file.

However, as LG L1730SF has the touch panel mounted in rotated and swapped direction with respect to what is expected by Evtouch, the input data will not be what the calibration script expects. This is because our xorg.conf options Rotate and SwapX/SwapY do not seem to have effect here. As a result, when the calibration application marks left top X as red, and then you tap that position on the screen, the raw touch panel output will be very faw away from those screen coordinates. Thus, you cannot actually click the X mark that turns red, or you’ll get insanely large values that will never work.

One workaround is to simply click them in a different order. This is ok, as the calibration application only reports a list of offset values, which can be put to correct places in the xorg.conf file later. The expected tap order is this (i.e. left top corner first, right bottom corner last):

1    2    3
4    5    6
7    8    9

But you should instead click the crosses like this (i.e. right bottom corner first):

9    6    3
8    5    2
7    4    1

As you can see, this order is first Y swapped and then clockwise 90 degree rotated (which matches with Rotate cw, SwapY On, SwapX Off settings that we had to put in xorg.conf file for this display model).

Now you should get values that are close to zero, something like +-20 or lower. Just observe that when you tap, the red color moves to the next cross, but follow the order described above. It is a little confusing, I know! When you’re done, the calibration software shuts down and you can see the calibration values printed on the screen. You may need to do this a couple of times before you get it right. Now write down the values on a piece of paper or something.

After you’re done with the calibration tool, you can delete the cursor file:

sudo rm /empty_cursor.xbm

NOTE: In the calibration tool, you might have problems pressing the X marks because you cannot see them properly. You may need to adjust your display’s settings (to stretch the image) and setup the display configuration properly before calibration. In X, open terminal and write:

sudo displayconfig-gtk

Select Model list and find LG L1730SF. Check that the resolution is ok, then save to file by clicking the disk icon above, e.g. /etc/X11/xorg.conf.new. Then open the file in console, and check that everything seems to be fine – you might want to comment out some modes and modelines for resolutions that are not supported by this display, i.e. higher than 1280×1024, and uncomment Virtual resolutions, if any. Then make a backup copy and replace your current xorg.conf:

sudo cp /etc/X11/xorg.conf /etc/X11/xorg.conf.bak
sudo cp /etc/X11/xorg.conf.new /etc/X11/xorg.conf

Restart computer (or just X), and the display should be better configured and calibration now possible to do with the calibration tool.

You can copy the calibration values to your xorg.conf file to the touchscreen section as options, if they are reasonable they should look something like this:

Option          "x0"    "+15"
Option          "y0"    "-3"
Option          "x1"    "+6"
Option          "y1"    "-3"
Option          "x2"    "-12"
Option          "y2"    "-6"
Option          "x3"    "+12"
Option          "y3"    "-15"
Option          "x4"    "+6"
Option          "y4"    "-10"
Option          "x5"    "-8"
Option          "y5"    "-6"
Option          "x6"    "+6"
Option          "y6"    "0"
Option          "x7"    "0"
Option          "y7"    "-3"
Option          "x8"    "-6"
Option          "y8"    "-3"

Then change Calibration setting to 0 and restart the computer. Unfortunately, when you start to use X again you’ll likely notice that Rotate and SwapX/SwapY now work again and the calibration values got from the calibration script do not actually apply to the correct spots on the screen anymore (well, we expected that this would happen). With trial and error, I found this order to work with Rotate cw, SwapY On, SwapX Off settings (Y swapped with respect to how they were collected?):

2    5    8
1    4    7
0    3    6

Here o means x0, y0, 1 means x1, y1, and so on.

However, now that we have some pretty reasonable values and also know which of the nine calibration samples matches with which location on LG L1730SF’s screen, we can fine tune each spot separately via trial and error, as described next. Note that it is also possible to start from scratch with zero calibration by setting all calibration values in xorg.conf (x0-x8, y0-y8) to zero.

Begin with the corner marked 0 above (bottom left), and respective values x0, y0. Tap to center of the screen and then to corner 0 (left bottom corner) and observe where the cursor jumps. If the cursor is above the place you touched, you need to decrease x0 value (Rotate option swaps X and Y axels!). If the cursor is left to the place you touched, you need to decrease y0 value. The distance between the actual screen and the touch sensor is something like 5 mm, so you should try to look the screen as straight 90 degree angle as possible.

So in practise you open a console with CTRL+ALT+F2, login, load your xorg.conf file and then adjust one calibration value, and save the file. Then switch to GUI with CTRL+ALT+F7 and restart X with CTRL+ALT+BACKSPACE. Now you can test the new value. Then switch back to console, change the value, and test again in GUI. Repeat this until you are satisfied.

Hmm, it shouldn’t be too hard to make at least a simple Gnome/KDE based tool that would get these swaps and rotations correctly, and record the offsets so that they could be directly copied to xorg.conf. Of course even better would be a possibility to try them out “live” without hopping between console and X.

Nevertheless, with these instructions you should get the touch feature’s offsets calibrated, and the good news is that you only need to do it once.

Virtual keyboard

After calibration is done, basically the system should be pretty usable. However, it is very common that setups with touch screen do not include a keyboard. Instead, a virtual keyboard is used. We will setup that next.

The default virtual keyboard for Gnome is GOK, but in fact it is quite complicated and … downright ugly. It is intended to support people with many kinds of  disabilities, and here all we want is some buttons on the screen to touch to write letters etc. A much nicer option is Florence (http://florence.sourceforge.net/english.html). Unfortunately, there are no binaries available for Ubuntu, so we need to install it from source. First we need to satisfy some dependencies:

sudo apt-get install build-essential libxml2-dev libgconf2-dev libglade2-dev libatspi-dev libcairo2-dev libgnome2-dev librsvg2-dev

Now, let’s get the source code:

cd ~\Source
mkdir florence
cd florence
wget http://downloads.sourceforge.net/florence/florence-0.3.0.tar.bz2?modtime=1221508202&big_mirror=0

Extract, build and install:

tar -xjvf florence-0.3.0.tar.bz2
cd florence-0.3.0
./configure --prefix=/usr
make
sudo make install

To start it, click Applications->Universal Access->Florence Virtual Keyboard. Or, in X open console and write florence. Click OK to enable accessibility and restart Gnome. When Gnome loads, restart Florence. Virtual keyboard now appears.

Florence manual also describes autostart option:
“If you prefer that Florence is launched at GNOME startup, choose the menu item System->Preferences->Sessions, click on the Startup programs tab, then click Add and enter /usr/bin/florence so Florence is launched with GNOME at next boot.”

To enable mouse as well, in xorg.conf uncomment Configured Mouse and comment Core pointer from touch screen.

In the desktop’s notificators area, a new icon appears for Florence (blue smiley). Click it with mouse’s right key and select Preferences. Edit the virtual keyboard settings as you wish. I disabled Arrows keypad, Numpad and Function keys, then zoomed to 36.0. Note that you should zoom only to integer values, decimals will make the graphics distorted for mouse over effect. Leave Auto click to 0, or you will get doule clicks. Note: if you keep the virtual key pressed (not lift your finger), it will be repeated, as with physical keyboards.

You can also open console and run gconf-editor, then look for apps->florence, and edit settings. These are partially duplicate to what you can do from Florence’s Preferences dialog, but there’s more options! I set them as follows:

Behaviour:
- always_on_screen = selected
- auto_click = 0
Colours:
- activated = #F87F18
- key = #000000
- label = #D9C8A0
- mouseover = #E6A43F
- outline = #000000
Layout:
- extensions = Arrows
- file = empty, although it can be found from /usr/share/florence/florence.layout
Window:
- decorated = not selected
- shaped = selected
- zoom = 34

These settings remove the window frame and keyboard background, resulting to keyboard keys only floating on top of the desktop, which is nice. The only problem is that whenever you reboot, Florence relocates the virtual keyboard to top part of the desktop, and since you don’t have window frame to grab, it is impossible to move it. As Gnome does not support remembering window locations (and they consider it application’s task to do – which I strongly disagree), currently the only option is to modify Florence to relocate it to a suitable position on the desktop. Unfortunately, it does not have a setting for this, so the only option is to modify source code:

cd ~\Source\florence\florence-0.3.0\src
cp florence.c florence.c.bak
sudo nano florence.c

Go to the end of the file, look for main function and the following line:

 flo_screen_changed(GTK_WIDGET(florence->window), NULL, florence);

Then add these lines below it:

 // Set initial position of the window to the bottom of the screen:

 int screen_height=gdk_screen_get_height(gdk_screen_get_default());

 int screen_width=gdk_screen_get_width(gdk_screen_get_default());

 gtk_window_move(florence->window, (screen_width-florence->width)/2, screen_height-florence->height);

So these come just before this line:

gtk_widget_show(GTK_WIDGET(florence->window));

Now save and exit, then compile and install:

cd ..
./configure --prefix=/usr
make
sudo make install

Restart Florence, now the keyboard appears initially in the bottom of the screen. As holding your arm up makes your muscles ache rather quickly, I believe it is much better to organize the desktop so that user can keep her hand down in rest for most of the time, and even when typing with virtual keyboard the hand will not block the view to the other parts of the screen that are not covered by the virtual keyboard. Therefore, I prefer to have the keyboard located at the bottom of the screen.

Note: in case you don’t like that blue smiley icon, it is located in /usr/share/icons/florence.svg, you can create a new one with the same name. For example, in /usr/share/icons/Human/scalable/devices/input-keyboard.svg is a nice keyboard icon which you can take into use as follows:

cd /usr/share/icons/
cp florence.svg florence.svg.bak
sudo cp /usr/share/icons/Human/scalable/devices/input-keyboard.svg .
sudo mv input-keyboard.svg florence.svg

Tuning the timings

Modern desktops have been designed to be used with a keyboard and a mouse. A touch screen based setup typically has neither, as the keyboard can be replaced with a virtual keyboard (like we just did), and also the mouse can be emulated with touch. Well, almost! While a typical mouse nowadays has 2-dimensional pointing and at least 2 buttons and a scroll wheel, with touch there’s basically only a binary type input (pressure/no pressure) and its coordinates. This maps pretty well with a one-button mouse. How about the second mouse button? Scrolling? Dragging? These are all pretty much required capabilities, otherwise desktop usage becomes  somewhat handicapped.

The solution? Well, actually there isn’t any really good solution. Touch is touch, not a mouse, and you can’t get around that. The desktop should be designed again so that it can be easily used with touch, at finger tip level precision (not everyone likes the pen). In mobile phone size terminals this is already happening, but on Linux desktop we still need to wait a while to see what comes out of the netbook boom. Meanwhile, we have to manage somehow. One thing that we can utilize is time. An example: short press is left mouse click, long press is right mouse click. Or, long press enables dragging. Unfortunately, humans are not very good at timing at this level, so there really cannot be that much precision put into it. Forget multiple different length “buttons”, dealing with “short press” and “long press” is pretty much all you can get out of it.

This leads to an important decision: while the touch cannot properly emulate a mouse, we need to choose which features will be emulated and which will not be supported at all. Can your use case manage without the second mouse button? Without dragging? Does it still require scrolling, although not dragging? These can be pretty hard to decide some times.

Let’s take an example. Using a touch screen for drawing is quite obvious idea. And it can be fun, indeed – much more than drawing with a mouse. However, to be able to draw you must have a possibility to 1) move the pen without leaving a trail, and 2) move the pen leaving a trail. With touch screen, pretty much the only option is to emphasize dragging  type usage so that even very short presses quickly turn to dragging (=moving the pen leaving a trail). Then again, writing is almost always needed – you do want to save the picture and give it a name, don’t you? So you need to be able to use a virtual keyboard as well. When you press virtual keys, writing becomes difficult if the touch gestures are easily interpreted as dragging. When you need to write, you’d prefer that only very long presses turn dragging mode on. But these settings must be configured in xorg.conf, so you cannot change them for example whenever the virtual keyboard is brought visible (which would otherwise be a very good solution, by the way).

For typing with virtual keyboard, you could also consider high MoveLimit value in xorg.conf. For example, with ’100′, typing is easy as the touch feature’s mouse emulation mode will not easily switch from tap to drag even if the finger does not stay precisely still, because it takes a fairly big movement until the mouse coordinates will change (remember the jumpiness problem, caused by two large value in this setting).

But on the other hand, clicking links on a web page may become more difficult this way: if you don’t hit the link straight at the first try, you have to tap elsewhere first to go beyond the move limit so that coordinates change enough, then you can try again at the original spot (otherwise you’ll just be tapping inside the move limit area and no movement appears). Value ’50′ is a nice compromise, and allows also dragging more precisely, as MoveLimit is applied also during dragging! (I think the driver should be improved so that it applies only when you are beginning a drag gesture; then it should be immediately disabled to allow smooth movement and precise “drop”.

Evtouch supports timing based differentation in touch gestures. In xorg.conf you can define option LongTouchTimer. When it is set fairly long, such as ’200′, drag mode will not be easily activated even if the finger rests on the virtual key a bit long. For beginner users it can be even longer, as they get easily confused of different modes. Another xorg.conf option, TapTimer should be set to a small value, so that clicks come quickly after tapping, e.g. ’10′ ms  will make virtual keyboards seem very responsive. For beginners, a slightly longer value may be justified.

In addition to short vs. long presses, there’s another trick for creating additional input mechanism: one-and-a-half tap. This is like a double click with a mouse, except that you do not release the finger after the second tap. While long press activates dragging, one-and-a-half tap is mainly used as the right mouse button click. However, you cannot simulate right button clicks with one-and-a-half style tap if the TapTimer value is too small, as you don’t have time for that “half” tap before the first gets reported as single (left) mouse click. Value ’50′ makes a noticeable lag when writing with virtual keyboards, still it is not enough for that second tap. Value ’150′ allows second mouse button emulation with one-and-a-half tap, but you still have to be quick and on the other hand, writing becomes somewhat slow. Therefore, if you can manage without that second button, I suggest keeping TapTimer value very short and forgetting the one-and-a-half tap completely. It is also difficult for beginner users, who do not expect that such a thing even exists.

The settings presented above emphasize click style behaviour, and are quite nice for beginners. They are also suitable for normal desktop use, although if you need the second mouse button you have to sacrifice responsiveness via adjusting TapTimer to a longer value.

If you primarily use the touch feature with fingers, you have to keep MoveLimit rather high. If you primarily use a pen for touch, try to set it lower as pen is much more precise and easier to keep steady.

For drawing etc. analog style control, MoveLimit must be small (even down to ’1′) and you may need to set LongTouchTimer to a very small value, too – e.g. ’20′. TapTimer should be set to very low, e.g. ’10′. Clicking is still possible, but you’ll miss some of them quite often as they are interpreted as dragging. However, drawing with a painting program is quite nice, as you don’t have to first touch, then wait, then begin moving the finger/pen, but now you can pretty much draw like with a normal pen. However, although resistive touch panel like LG L1730 SF is quite precise and thus suitable for drawing, it requires some pressure and you need to learn to “keep the pen on the paper” steadily while drawing lines and curves, otherwise you’ll get dotted lines. These settings emphasize mouse drag style behaviour. The cursor follows the finger very rapidly and precisely, but clicking and typing is more difficult because you’ll miss some clicks much more often.

Note: I have set “Emulate3Buttons” option to “False”, as I don’t have any use for that and I believe that simplicity works better with touch feature; one should not try to emulate the mouse completely but focus on the benefit of direct pointing, with as little errors as possible, and with good preciseness and responsiveness.

As an example of some kind of compromize of the settings mentioned above, see my xorg.conf file, which is attached into the end of the text.

Automatic event channel mapping

When you reboot the computer, or change the touch screen’s USB cable from one USB port to another, the event channel that gets mapped to touch feature may change. As the event channel must be fixed in your xorg.conf file, at random boots the touch feature may or may not work.

This can be fixed by adding a udev rule, which will automatically map the touch input to a certain virtual event channel.

sudo nano /etc/udev/rules.d/69-touchscreen.rules

Add this content if it isn’t already there:

# udev.rules for touchscreens

# ITM Touchscreens

SUBSYSTEMS=="usb" ATTRS{idVendor}=="0403" ATTRS{idProduct}=="f9e9", SYMLINK+="input/touch"

Save and exit. Then edit xorg.conf and replace fixed event channel with this new automatically mapped event channel:

Option          "Device"        "/dev/input/touch"

Save and exit. Reboot, and the touchscreen should still work. Also, when you type ls /dev/input, you should see touch somewhere in the output.

Note: you can find out the vendor and product id for example via cat /proc/bus/input/devices, which should output something like this:

I: Bus=0003 Vendor=0403 Product=f9e9 Version=0100

N: Name="ITM Inc USB Touch Panel"

P: Phys=usb-0000:00:0f.4-1/input0

S: Sysfs=/devices/pci0000:00/0000:00:0f.4/usb1/1-1/1-1:1.0/input/input9

U: Uniq=

H: Handlers=mouse2 event9

B: EV=b

B: KEY=400 0 0 0 0 0 0 0 0 0 0

B: ABS=1000003

Another, more verbose source is udevinfo -a -p /class/input/input9, where input9 comes from the output of the previous command. Here is part of the output:

looking at parent device '/devices/pci0000:00/0000:00:0f.4/usb1/1-1':

    KERNELS=="1-1"

    SUBSYSTEMS=="usb"

    DRIVERS=="usb"

    ATTRS{dev}=="189:1"

    ATTRS{configuration}==""

    ATTRS{bNumInterfaces}==" 1"

    ATTRS{bConfigurationValue}=="1"

    ATTRS{bmAttributes}=="80"

    ATTRS{bMaxPower}=="100mA"

    ATTRS{urbnum}=="216"

    ATTRS{idVendor}=="0403"

    ATTRS{idProduct}=="f9e9"

    ATTRS{bcdDevice}=="0100"

    ATTRS{bDeviceClass}=="00"

    ATTRS{bDeviceSubClass}=="00"

    ATTRS{bDeviceProtocol}=="00"

    ATTRS{bNumConfigurations}=="1"

    ATTRS{bMaxPacketSize0}=="8"

    ATTRS{speed}=="12"

    ATTRS{busnum}=="1"

    ATTRS{devnum}=="2"

    ATTRS{version}==" 1.10"

    ATTRS{maxchild}=="0"

    ATTRS{quirks}=="0x0"

    ATTRS{authorized}=="1"

    ATTRS{manufacturer}=="ITM Inc"

    ATTRS{product}=="USB Touch Panel"

Tuning Firefox for touch based browsing

When you type text to Firefox’s address bar, it automatically (v. 3.0 onwards) shows a drop down list of possible matches. Unfortunately, this removes focus from virtual keyboard, and basically you need to type every letter twice to regain focus. Fix it as follows:

Write about:config into the address bar, press Enter. Press “I’ll be carefull. I promise!” button. Enter browser.urlbar in the Filter field. Change browser.urlbar.maxRichResults to 0. Change browser.urlbar.search.timeout to 3000. Restart firefox.

Other good firefox tweaks:

• Turn browser.urlbar.clickSelectsAll to True
• Turn general.smoothscroll to True

In addition to about:config properties, you can create two configuration files:

cd ~/.mozilla/firefox
ls

From list of files, check the one that ends .default and cd there. Then continue:

cd chrome
ls

This shows examples of configuration files.

cp userChrome-example.css userChrome.css
nano userChrome.css

Now edit the file, save, exit, restart Firefox and settings are enabled.

E.g. some possible settings for touch screen usage:

  /*

   * Make page URL font monospaced and bigger.

   */

  #urlbar{

      font-family: verdana !important;

      font-size: 15pt !important;

  }

  /*

   * Make bookmark sidebar font Verdana and bigger.

   */

  tree {

      font-family: verdana !important;

      font-size: 13pt !important;

  }

With these settings, it is easier to type new URL with virtual keyboard, and click existing bookmarks in the sidebar.

Gnome scrollbars

Scrollbars are much easier to use if you make them wider.

Create file .gtkrc-2.0 into your home directory, then add these lines:

style "wide-scrollbars"
{
    GtkRange       ::slider_width      = 30
    GtkRange       ::stepper_size      = 30
}
class "GtkRange"  style "wide-scrollbars"

Save. Log out, log in and all scrollbars should be wider now.

Miscellaneous tips

• In Gnome’s file manager, change to “Single click to open items”.
• Custom mouse pointer theme? Blank, except when you click -> blinks once, and
  when you drag -> visible hand.
• When you boot the computer, Ubuntu will show the login screen. How to log in, if there is no keyboard? Virtual keyboard is not started and available yet. The   easiest way is to create an unprivileged, common user and make it auto-login. To add/remove/modify users, select System->Administration->Users and Groups, and create a user with low privileges. To enable auto-login: System->Administration->Login Window, then select Security tab, and select Enable Automatic Login, select user to log in. Close, and reboot. The user you selected should be automatically logged in.

My xorg.conf file

Just for reference, this is my xorg.conf file:

# xorg.conf (X.Org X Window System server configuration file)
#
# This file was generated by dexconf, the Debian X Configuration tool, using
# values from the debconf database.
#
# Edit this file with caution, and see the xorg.conf manual page.
# (Type "man xorg.conf" at the shell prompt.)
#
# This file is automatically updated on xserver-xorg package upgrades *only*
# if it has not been modified since the last upgrade of the xserver-xorg
# package.
#
# If you have edited this file but would like it to be automatically updated
# again, run the following command:
#   sudo dpkg-reconfigure -phigh xserver-xorg

Section "InputDevice"
        Identifier      "Generic Keyboard"
        Driver          "kbd"
        Option          "XkbRules"      "xorg"
        Option          "XkbModel"      "pc105"
        Option          "XkbLayout"     "fi"
EndSection

Section "InputDevice"
        Identifier      "Configured Mouse"
        Driver          "mouse"
        Option          "CorePointer"
EndSection

Section "InputDevice"
        Identifier      "TouchScreen"
        Driver          "evtouch"
        Option          "Device"        "/dev/input/touch"
        Option          "DeviceName"    "TouchScreen"
        Option          "MinX"  "340"
        Option          "MinY"  "200"
        Option          "MaxX"  "3850"
        Option          "MaxY"  "3950"
        Option          "x0"    "+15"
        Option          "y0"    "-3"
        Option          "x1"    "+6"
        Option          "y1"    "-3"
        Option          "x2"    "-12"
        Option          "y2"    "-6"
        Option          "x3"    "+12"
        Option          "y3"    "-15"
        Option          "x4"    "+6"
        Option          "y4"    "-10"
        Option          "x5"    "-8"
        Option          "y5"    "-6"
        Option          "x6"    "+6"
        Option          "y6"    "0"
        Option          "x7"    "0"
        Option          "y7"    "-3"
        Option          "x8"    "-6"
        Option          "y8"    "-3"
        Option          "ButtonNumber"  "2"
        Option          "ReportingMode" "Raw"
        Option          "Emulate3Buttons"       "False"
        Option          "Emulate3Timeout"       "50" #50
        Option          "DebugLevel"    "0"
        Option          "TapTimer"      "5"
        Option          "LongTouchTimer"        "200"
        Option          "MoveLimit"     "50"
        Option          "SendCoreEvents"        "On"
        Option          "Rotate"        "cw"
        Option          "SwapX" "Off"
        Option          "SwapY" "On"
        #Option         "ScreenNumber"  "0"
        #Option         "Calibrate"     "1"
EndSection

Section "InputDevice"
        Identifier      "dummy"
        Driver          "void"
        Option          "Device"        "/dev/input/mice"
EndSection

Section "Device"
        Identifier      "Configured Video Device"
        Boardname       "geode"
        Busid           "PCI:0:1:1"
        Driver          "geode"
        Screen  0
EndSection

Section "Monitor"
        Identifier      "Configured Monitor"
        Vendorname      "LG Electronics Inc."
        Modelname       "LG L1730SF"
        Horizsync       30.0-83.0
        Vertrefresh     56.0-75.0
  modeline  "640x480@60" 25.2 640 656 752 800 480 490 492 525 -vsync -hsync
  modeline  "640x480@72" 31.5 640 664 704 832 480 489 491 520 -vsync -hsync
  modeline  "640x480@75" 31.5 640 656 720 840 480 481 484 500 -vsync -hsync
  modeline  "800x600@56" 36.0 800 824 896 1024 600 601 603 625 +hsync +vsync
  modeline  "800x600@72" 50.0 800 856 976 1040 600 637 643 666 +hsync +vsync
  modeline  "800x600@75" 49.5 800 816 896 1056 600 601 604 625 +hsync +vsync
  modeline  "800x600@60" 40.0 800 840 968 1056 600 601 605 628 +hsync +vsync
  modeline  "832x624@75" 57.284 832 864 928 1152 624 625 628 667 -vsync -hsync
  modeline  "1024x768@75" 78.8 1024 1040 1136 1312 768 769 772 800 +hsync +vsync
  modeline  "1024x768@70" 75.0 1024 1048 1184 1328 768 771 777 806 -vsync -hsync
  modeline  "1024x768@60" 65.0 1024 1048 1184 1344 768 771 777 806 -vsync -hsync
  modeline  "1152x864@75" 108.0 1152 1216 1344 1600 864 865 868 900 +hsync +vsync
  modeline  "1280x1024@75" 135.0 1280 1296 1440 1688 1024 1025 1028 1066 +hsync +vsync
  modeline  "1280x960@60" 102.1 1280 1360 1496 1712 960 961 964 994 -hsync +vsync
  modeline  "1280x1024@60" 108.0 1280 1328 1440 1688 1024 1025 1028 1066 +hsync +vsync
  modeline  "1280x960@75" 129.86 1280 1368 1504 1728 960 961 964 1002 -hsync +vsync
#  modeline  "1400x1050@60" 122.61 1400 1488 1640 1880 1050 1051 1054 1087 -hsync +vsync
#  modeline  "1400x1050@75" 155.85 1400 1496 1648 1896 1050 1051 1054 1096 -hsync +vsync
#  modeline  "1600x1200@65" 175.5 1600 1664 1856 2160 1200 1201 1204 1250 +hsync +vsync
#  modeline  "1600x1200@60" 162.0 1600 1664 1856 2160 1200 1201 1204 1250 +hsync +vsync
#  modeline  "1792x1344@60" 204.8 1792 1920 2120 2448 1344 1345 1348 1394 -hsync +vsync
        Gamma   1.0
EndSection

Section "Screen"
        Identifier      "Default Screen"
        Monitor         "Configured Monitor"
        Device          "Configured Video Device"
        Defaultdepth    16
        SubSection "Display"
                Depth   16
                #Virtual        1792    1344
                Modes           "1280x1024@60"  "1280x960@75"   "1280x960@60"   "1280x1024@75"  "1152x864@75"   "1024x768@60"   "1024x768@70"   "1024x768@75$
        EndSubSection
EndSection

Section "ServerLayout"
        Identifier      "Default Layout"
  screen 0 "Default Screen" 0 0
        Inputdevice     "TouchScreen"   #"CorePointer"
        Inputdevice     "Configured mouse"
        #InputDevice    "dummy"
EndSection

Section "Module"
        Load            "glx"
        Load            "GLcore"
        Load            "v4l"
EndSection

Section "ServerFlags"
EndSection

Note: You should only read this through, you don’t need to repeat everything I did. The actual solution is in the end of the text, so there’s what you need to do.

Since we now have two drivers in the system for the touch feature, usbtouchscreen for the display device and evtouch for converting the input events to a suitable format for X, the first question that comes to mind is, which one of the drivers is causing the jumpiness? We should go to the source of the information first, i.e. usbtouchscreen.

When you move your finger on the screen, does the data that is output from the usbtouchscreen driver actually change continuously, or does it first stay the same and then suddenly change when the jump occurs? One test could be to type sudo cat /dev/input/eventX, where X represents the event number in your system (recall that you can use cat /proc/bus/input/devices to find it out), but its output is all gibberish. A better alternative is to use a tool that decrypts the event data to plain text. One suitable tool is evtest, which can be found in dvb-utils (yes, tools for watching TV!) package. That package is located in Ubuntu universe repository that we have already enabled. To install it, type

sudo apt-get install dvb-utils

Now you can observe the output of the driver as informative textual message by typing

sudo evtest /dev/input/eventX

(replace X with your event number).

This test reveals for example that 1) as long as you keep your finger on the screen, new data keeps coming in, 2) the display reports the pressure too, although it seems to me somewhat random, 3) when you keep your finger still, you’ll get mainly events with all fields zeros, whereas when you keep moving your finger, values seem to be more reasonable, and 4) the X and Y coordinate values are quite hard to pick from the information stream. Press CTRL+C to stop now.

To get a better idea of the actual coordinates, we can filter the output to only contain Y coordinates with the following command:

sudo evtest /dev/input/eventX/ | grep Y

(replace X with your event number). However, when you are testing, remember that X and Y axels are swapped! When tapping the left edge, the values are near 3950. Right edge yields 200. You can use the same technique to observe the X axel (grep X). When tapping the bottom edge, I got values near 340, and when tapping the top edge, it was somewhere near 3850. These values are very useful for calibration (you can use them in your xorg.conf file), but what is even more important is that when you move your finger, the values seem to grow gradually and continuously. Now we can be sure that usbtouchscreen driver is working just fine, and the jumpiness problem is somehow caused by evtouch.

When using the values from the previous step for calibration settings in the xorg.conf file (instead of the max range values 0, 4095), I got better coverage of the whole screen area with the touch control, although it is still jumpy. I calculated that there are 20 locations along X axel and also 20 locations along Y axel, or 20×20 grid of which intersections the mouse cursor will stop. This is interesting: same amount of stops for both axels, although the screen is not square! Another thing is that when you draw back and forth for a couple of times, possibly sometimes lifting your finger for a while, the cursor does not return to exactly same spots on the screen (you can test that easily with a piece of paper, do not use a marker pen on your screen . In other words, the grid is not fixed but seems to drift a little. This also means that it does not start from 0 coordinate points at the sides of the screen. So, what is going on here? We need to dive in to evtouch…

Evtouch torn open

Next, we can try to find out more about the evtouch driver to learn why it makes the cursor to jump. In console, type command

sudo updatedb

and then

locate evtouch

to find out what files have been installed to the system that include the term evtouch. This reveals for example that there is some readme files in /usr/share/doc/xserver-xorg-input-evtouch folder, which describe the calibration procedure etc. – we will get back to that later. It also reveals that the Debian style package that contained the driver has been cached in the system here: /var/cache/apt/archives/xserver-xorg-input-evtouch_0.8.7-3ubuntu1_i386.deb. The package itself can be manipulated with dpkg-deb tool to list its contents:

dpkg-deb --contents /var/cache/apt/archives/xserver-xorg-input-evtouch_0.8.7-3ubuntu1_i386.deb

This reveals that in addition to readme etc. informational files, the driver package contains these files:

• calibrate.sh and ev_calibrate scripts in /usr/lib/xf86-input-evtouch
• evtouch_drv.so driver in /usr/lib/xorg/modules/input
• empty_cursor.xbm image in /usr/share/xf86-input-evtouch

However, anything in these files could not reveal what is causing the jumpiness. So, once again, let’s look at the source code.

You can download source code for evtouch driver from http://www.conan.de/touchscreen/evtouch.html. At the bottom of the page, there are many download links. Use this one: X driver sources V0.8.7      xf86-input-evtouch-0.8.7.tar.bz2. Download the package and extract it somewhere so that you can look at the files that it contains. There are a lot of files, but only a few with .h and .c filename extensions; these are the source files. As files related to calibration are not necessary for normal operation, you are left with these four files: evtouch.h, evtouch.c, libtouch.h, and libtouch.c. So, there are basically two modules: one is the actual driver, the other contains a state machine for converting taps to mouse clicks. Also, there is INSTALL.txt file that describes a) how to compile the driver and install it, and b) how to turn debug printing on. Let’s do these steps next, so that we can begin testing and modifying the driver.

First, because we’re going to compile the driver, we need the build tools:

sudo apt-get build-essential

Let’s also download and extract the driver source package to a suitable folder:

cd ~

mkdir Source

cd Source

mkdir evtouch

cd evtouch

wget http://www.conan.de/touchscreen/xf86-input-evtouch-0.8.7.tar.bz2

tar -xjf xf86-input-evtouch-0.8.7.tar.bz2

cd xf86-input-evtouch-0.8.7

INSTALL.txt, which contains instructions for compiling and installing from source, says that we need to have sources also for XFree86. However, in Ubuntu we have X.org, which is a newer fork of XFree86 (you can read more about this here: http://ubuntuforums.org/showthread.php?t=87794). The installation instructions seem somewhat outdated, so we will not follow them exactly. To check X.org version, you can type this:

cat /var/log/Xorg.0.log | grep "X.Org X Server"

I got this line: X.Org X Server 1.4.0.90. Note that the debug output of the driver will go to this same file, /var/log/Xorg.0.log – we’ll come back to that later. Assuming you are still in the folder that contains the driver source files, type

./configure

to prepare for building the driver. You may get errors, for example: No package ‘xorg-server’ found, No package ‘xproto’ found. To solve these, you need to install related source packages and try to configure the driver again:

sudo apt-get install xserver-xorg-dev
./configure

This time I got no errors and a ready makefile as output:
config.status: creating Makefile
config.status: creating config.h
config.status: executing depfiles commands

Next, let’s compile the driver with debug output and raw packets output turned on:

make DEBUG=y LOGRAW=y

Unfortunately, I got compilation errors: evtouch.c: In function ‘DeviceOn’: evtouch.c:495: error: invalid use of void expression. If you google around, you’ll notice that other people have had the same problem, apparently because the driver is compatible with Xorg 6.8.x and we have 7.3 in Ubuntu Hardy Heron. Someone even went on to create a new driver (http://www.plop.at/en/touchscreen.html), I haven’t tested that as currently I prefer to get the most common driver, evtouch to work.

So, let’s fix the error. Line 495 contains this text:

DBG (9, XisbTrace (priv->buffer, 1));

We can see that it is used for debugging with a debug macro. If you run

grep DGB *

in the driver’s source folder, you can see that DBG macro is defined in libtouch.c file:

 #define DBG(lvl, f) {if ((lvl) <= debug_level) f;}

This means that if the given number is at most the same contained in debug_level variable, we should run the given function f. We don’t need to debug the contents of the buffer, so we can safely comment it out as follows:

// #define DBG(lvl, f) {if ((lvl) <= debug_level) f;}

Now we can compile again:

make DEBUG=y LOGRAW=y

and it succeeds without errors. Next, type

sudo make install

to install the newly compiled driver.

We need to make sure that X will begin to use our own, compiled driver. Recall that we installed the binary release already, evtouch_drv.so driver located in /usr/lib/xorg/modules/input. We will rename that as follows:

cd /usr/lib/xorg/modules/input
sudo mv sudo mv evtouch_drv.so evtouch_drv.so.orig

Then press CTRL+ALT+F7 to go to X, and restart it with CTRL+ALT+BACKSPACE. In my case, the touch feature stopped working now, so I checked the errors:

cat /var/log/Xorg.0.log | grep EE

Which revealed this:

(EE) Failed to load module "evtouch" (module does not exist, 0)
(EE) Failed to load module "void" (module does not exist, 0)

(EE) No Input driver matching `evtouch'

(EE) No Input driver matching `void'

Apparently, the installation script did not install the driver to correct location. With

sudo updatedb

locate evtouch_drv.so

you can see that it went to here: /usr/local/lib/xorg/modules/input/evtouch_drv.so. So, lets copy that to correct place:

 sudo mv /usr/local/lib/xorg/modules/input/evtouch_drv.so /usr/lib/xorg/modules/input/evtouch_drv.so

Now, try to restart X again. For some reason, Ubuntu switched to safe mode in graphics, and began to use usbtouchscreen without evtouch. Apparently, there is something wrong with the driver, although the source code is supposed to be the latest version. To get rid of the safemode, I had to boot the computer. I wanted to see if DEBUG=y LOGRAW=y parameters had any problems, so I built the driver again and tested it without them as follows:

 make clean
 ./configure
 make
 sudo make install
 sudo mv /usr/local/lib/xorg/modules/input/evtouch_drv.so /usr/lib/xorg/modules/input/evtouch_drv.so

In X, CTRL+ALT+BACKSPACE restulted again to failsafe mode. Apparently, the driver that is compiled directly from source does not work properly as-is. This is getting pretty laborious now.

Get patched

Next, I found out that there are many patches available for the driver in Debian’s (Ubuntu is based on Debian) packages: http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-input-evtouch.git;a=tree;f=debian/patches;hb=HEAD

The file series contains this information:

 1 #02-buttonless-device.patch

 2 #03_fix_compile_warns.patch

 3 04_include_xf86_ansic_h.patch

 4 #05_build_with_1_4.patch

 5 06_xf86-input-evtouch-0.8.7-misc.patch

 6 07_random_fixes_for_06.patch

So I decided to merge the patches 04, 06 and 07 to the source code that I loaded from evtouch module’s home page, after reviewing the comments in patch files. Especially patch 06 seemed promising with this comment in it: Changed code to compile a working driver for both XInput ABI 0.x and 2.0 (Xorg 1.4.0). Recall that Hardy Heron’s X server version is 1.4.0.90. I loaded the raw patch files with a web browser, copied them to evtouch driver’s source folder and applied them like this:

patch -p1 < debian_patches_04_include_xf86_ansic_h.patch
patch -p1 < debian_patches_06_xf86-input-evtouch-0.8.7-misc.patch

Now I got an error saying: 1 out of 22 hunks FAILED — saving rejects to file evtouch.c.rej. With cat evtouch.c.rej I saw that this change was related to that one line with improper DBG macro usage, which we commented out ourself. No problem, continue:

patch -p1 < debian_patches_07_random_fixes_for_06.patch

After applying the patches, I recompiled and tried again. I also learned from Debian packages that I don’t need to manually copy the driver to correct location, if I give the path in configuration step as follows:

 make clean
 ./configure --prefix=/usr
 make
 sudo make install

In X, give CTRL+ALT+BACKSPACE. This time it did not go to failsafe mode, and the touchscreen worked just like with the pre-built driver version – jumpy.

Now that we have a working setup for building the driver, we can begin modifying it. First thing is to rebuild with debug and raw output:

make clean
 ./configure --prefix=/usr
 make DEBUG=y LOGRAW=y
 sudo make install

In X, give CTRL+ALT+BACKSPACE. The touchscreen works as earlier, and there is no debug information. Apparently, because I did not raise the debug level! Do it like this: in evtouch.c, line 109:

static int debug_level = 3;

i.e. use higher value than 0, at least 2. The higher the value, the more information you get into the log file. However, after recompilation the debug information still did not appear! It seems that the parameters DEBUG=y and LOGRAW=y do now work and INSTALL.txt really is outdated. For example, if you do grep LOGRAW *, you’ll see that the parameter is only mentioned in INSTALL.txt file – so how could it work. However, the DBGOUT macros are in place in the source files, so we can manually turn the debug printing and raw logging on as follows: in file evtouch.h, just below line #define _evtouch_H_, add these two lines:

 #define EVDBG
 #define LOG_RAW_PACKET

Recompile, install and test as usual. This time, debug information appears into the log file. You can view it easily like this:

less /var/log/Xorg.0.log

Reading the log

As you use the touchscreen, new information is added to the file, and this command prints it on the screen so that you can view it easily:

 tail -f /var/log/Xorg.0.log

Let’s see if we can find out anything from debug information. I could see that the screen resolution and desktop size were recognized correctly, and the viewport was initialized ok. To observe if jumpiness is already in the input, I used this command:

tail -f /var/log/Xorg.0.log | grep FIRST

and swiped the screen slowly with my finger from left to right – and I could clearly see how the number first stayed the same and then suddenly jumped! The other alternative would have been input is ok, but calibration goes wrong. Anyway, I moved my finger slowly up, then back down, observing and writing down the numbers. The jump was about 200, most typically 198 (these are not screen pixels, but values from the touch screen. This appeared to be the same for both X and Y axels. Warning: the size of the file /var/log/Xorg.0.log grows pretty fast to tens of megabytes with logging, don’t play around too long (it grows mostly when you touch the screen).

Next question is: what happens to the data before this step? It was alright in the event channel where data was pushed from usbtouchscreen. This debug print comes from function ConvertProc, and these are parameter values that are printed directly, without modification. Thus they are wrong before given to ConvertProc. So, who calls ConvertProc function? Its interesting that in the original, unpatched driver version it does not seem to be called at all in evtouch.c file’s functions. However, in the patched version, there are new functions in the end of the file, and it is called from there. Since there are 4 functions and I don’t know which one is called, I added

DBGOUT(2, "EVTouch: %s\n", __FUNCTION__);

in the beginning of each of these functions, and rebuild the driver. It turned out that when you tap the screen, many one of these gets called. And when you trace the data path
backwards, next you get ReadInput function. There is a debug print function that prints the input event’s basic information: type, code and value. When you do this

tail -f /var/log/Xorg.0.log | grep ReadInput

you can observe what data comes in. When you tap the screen, many lines are printed onto the screen:

EVTouch: ReadInput type:01 code: 0x014a value:1
EVTouch: ReadInput type:03 code: 0×0000 value:2086
EVTouch: ReadInput type:03 code: 0×0001 value:2153
EVTouch: ReadInput type:03 code: 0×0018 value:214
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:215
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:216
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:217
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:218
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:219
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:220
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:221
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:222
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:223
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:224
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:226
EVTouch: ReadInput type:00 code: 0×0000 value:0
EVTouch: ReadInput type:03 code: 0×0018 value:227
…

When I looked at the data, I noticed the first 3 lines: the first one probably is some kind of initiator (screen tapped), the next two are the coordinates from the touch sensor. What is the rest of the data? Why there is so much of it? Then I got it: the values close to 200 are the pressure data. There are many of them because you can keep pressing the same spot on the screen, but alter the pressure. Sampling is fast, so even from a short tap you get many, many samples. Next, try this:

tail -f /var/log/Xorg.0.log | grep "ReadInput type:03 code: 0x0000"

When you move your finger across the screen, the values are changing just fine – no jumpiness. Then why doesn’t the cursor move as it should?

Move limit!

When looking at the code, I noticed that the EVTouchProcessAbs function does not store the X and Y values, if they don’t differ enough from previously set values, and there is a variable for this limit, it is called move_limit in the code. This did not exist in the original driver, it was added in one of the patches (that otherwise made the driver to work with this Xorg version). In function EVTouchPreInit, this value is initialized in code to 180, and it stays in that value UNLESS you configure it differently in your xorg.conf file. Of course, you need to KNOW that such a value exist. And you need to KNOW that the version of the driver that you get with Ubuntu is NOT the original one, but a patched version where many new features have been added. This is just one of them.

Now you can set the debug_level back to 0, and remove debug definitions from evtouch.h file to disable debugging. Recompile and apply.

So, finally to fix the issue: you do not need to compile the driver at all, just use the one provided with Ubuntu, and edit your xorg.conf file as follows:

sudo nano /etc/X11/xorg.conf

Then go to the touch screen section and add this parameter:

Option         "MoveLimit"     "180"

But change the value to smaller! In fact, I found the original patch from the web and there in comments the author explains his xorg.conf file and has used value 18 (!) there, but in code it is set to 180! And, I even found a bug created for Debian about too high default value: http://lists.debian.org/debian-x/2008/06/msg01287.html

So, in the end, the solution was really simple, it was just a configuration bug. But it took quite a lot of work and some crazy stubbornness to find this out.

In part 3, we will finally continue to fine-tuning the calibration of the touch feature.

Installing Eagle on Ubuntu Linux

Obviously the first step is to install Eagle on your Ubuntu Linux computer.

The easiest way to install Eagle in Ubuntu is via Applications->Add/Remove…, where you can simply type “Eagle” in the search box to find Eagle from Ubuntu software repository. In Ubuntu 8.04, Eagle is located in the multiverse repository, which must be enabled before installation.

Unfortunately, the version in Ubuntu repository is rather old: 4.16r2-1. You probably want to install the latest version, which can be downloaded with a web browser directly from Cadsoft: http://www.cadsoft.de/download.htm. You should choose the Linux version, right click the download link, and select “Save Link As…”. After downloading is finished, you can install the package (the file you downloaded, e.g. “eagle-lin-5.6.0.run”) by opening a console and running the installation script as follows:

sh eagle-lin-5.6.0.run

Extracting the package contents takes a while, then a graphical installation wizard appears. You can accept the defaults and begin installation, unless you want to change the installation directory first. After copying the files the wizard requests a license file. Just select “Run as Freeware”, and the setup is then complete.

For your convenience, you might want to add a shortcut in the Ubuntu application menu as follows:

• Select System->Preferences->Main Menu
• Select Applications->Programming
• Click button “New Item”
• Settings: For Name type “Eagle 5.6.0″, for Command click Browse… and go to [Eagle installation directory]\bin, then select file named eagle
• Click OK
• New item should be visible now, and even the Eagle icon in place
• Click Close

Now you can start using Eagle by simply selecting Applications->Programming->Eagle 5.6.0.

Creating schematics for Arduino projects

When you start Eagle, first a window titled “Control Panel” opens. To draw a new schematic, select File->New->Schematic. Another window opens, this is the place to draw your circuit design.

The basic idea is to add components from different component libraries, organize them on the drawing area and make the necessary wiring connections.

You can add new items into your design by clicking the Add button in the toolbar on your left. For Arduino projects, you should be able to use a chip from Atmel category. However, I couldn’t find Atmega168 that is used in Arduino Diecimila, although Atmega169 was there.

You can get a suitable model from Rob Faludi: http://www.faludi.com/2008/10/07/arduino-avr-library-for-eagle-layout-editor/. Download the model with a web browser, and extract it to [Eagle installation directory]\lbr. Then back in Eagle, select Library->Use, browse for Arduino-AVR.lbr file, and open it. Now you can click Add button from the Eagle toolbar again, new Arduino-AVR section is visible in the component list and Atmega168 variants are there. Select the model you want to use, and click OK. Place the component in the center of the design area, and continue adding more components and wiring them together.

Happy designing!

In August 2008 I went through it all again after updating to Ubuntu Linux 8.04 Hardy Heron. However, this time I was better prepared, having a few years of experience on Ubuntu. This article brings the instructions more up-to-date and answers some questions I didn’t have a clue about at the first time. Although Hardy is already a year old and major computer manufacturers are publishing computers with built-in multi-touch capabilities almost daily, I still think these instructions should be valid for all DIY guys for a few years, since it is a long term support (LTS) version of Ubuntu.

Note: I have written this article 8 months later from my memos. It was not straightforward to get the touch feature working, thus some unnecessary adventures had to be made. However, I decided to include them all here so that others can learn from my mistakes. Moreover, with a complex issue like this I think it is better to elaborate too much than too little – you can easily skip the chapters you don’t care about. I have also tried to explain what I am trying to do and why at each step, as many Linux/Ubuntu newbies need these things to be explained so that they can learn (I went through that myself a few years ago). As a result, the article is quite long and you don’t actually need to perform all the steps that I describe. These steps are marked in the text.

Introduction

In this article I assume that you have already setup Ubuntu Linux 8.04 Hardy Heron to your computer using keyboard, mouse and another display device. I will focus on explaining how to configure the system to operate with LG L1730SF display and its touch feature. Note that a keyboard and a mouse should be connected to the computer when you are going through the setup according to this guide. After you’re finished you can use the computer without them via the touch feature and virtual keyboard.

First boot

Make sure that the computer is shut down and remove the power cables from both the computer and the display device. LG L1730SF touch screen display has three cables: a power cable, an analog VGA cable for graphics, and a serial/USB cable for the touch feature. Connect the VGA cable to the computer, but do not connect the USB cable yet. Attach the power cables again, and start the computer.

You should see some textual messages on the screen while the computer is loading the Ubuntu Linux operating system. In case the display contains mainly garbage, you need to adjust the screen resolution and refresh rate for the Linux console to values that are suitable for your display. Usually the default settings work fine, but I have found that with LG L1730SF some tuning is needed. If this is the case, read on – otherwise you can skip the rest of this chapter.

Adjusting console screen resolution

Before the computer begins to load Ubuntu Linux operating system, a boot loader is run (usually Grub). In order to change console settings so that they become effective before the operating system is booted, you need to edit the boot loader’s configuration file, and then reboot the computer. Here’s how to do it.

First, you need console access to the computer having problems with its display. In case the computer eventually loads normal Linux desktop, you can access console from there. If not, you have a couple of options. For example, in case you have already setup an SSH server, you can SSH it from another computer. If you don’t have remote access, the easiest way is to simply use another display temporarily, i.e. reboot the computer with the other display connected to it.

When you have gained access to the console, type this to open the Grub configuration file in a text editor:

sudo nano /boot/grub/menu.lst

Look for a line that begins like this:

# defoptions=

Add the following to the end of the line:

vga=791

This number is a code given for a specific console screen resolution (1024×768). For other alternatives, see http://en.wikipedia.org/wiki/VESA_BIOS_Extensions. You may also delete the word splash if you wish to get textual messages during boot procedure instead of a progress bar.

Note: Do not uncomment the line! Whenever a new kernel is released and you update your computer with Update Manager, a script called update-grub will be run. It modifies this file to include a new boot option for the new kernel (and in fact makes that the default in the list, if not prevented by settings). Despite of the comment character, the settings listed here will become effective for the new kernel configuration.

In case you want to apply the settings to only some boot alternatives in the boot menu, you can instead do this:

Look for a line that describes that boot configuration. It might be something like this:

 kernel /boot/vmlinuz-2.6.24-19-generic root=/dev/sda1 ro quiet splash

Add another parameter to set the screen resolution. I have successfully used vga=0×317 or vga=791 (they are the same thing) with LG L1730SF to setup console to 1024×768 resolution. Here’s an example of what you need to do. This is what I used to have there:

title Ubuntu 8.04.1, kernel 2.6.24-19-generic
root (hd0,0)
kernel /boot/vmlinuz-2.6.24-19-generic root=/dev/sda1 ro quiet splash
initrd /boot/initrd.img-2.6.24-19-generic quiet

I changed the line that begins with the word kernel to look like this:

 kernel /boot/vmlinuz-2.6.24-19-generic root=/dev/sda1 ro quiet splash vga=0x317

Note that if you configure this only for a specific item in the boot list, whenever the kernel gets updated you may need to apply the setting again! To avoid that, use the option described above (defoptions).

When you’re done editing the file, save it by pressing CTRL+O, and exit by pressing CTRL+X. Reboot the computer with LG L1730SF connected to it. The console screens should appear nicely now.

USB connection

Now we will begin to configure the system for the touch feature. Note that the tricks explained here may be helpful with troubleshooting other hardware problems too. First, we need to find out if and how the computer recognizes the display device via the USB interface.

Begin by logging in to Ubuntu. Then open console, and write this command:

lsusb

You should see a list of USB devices currently attached to the computer, for example your USB mouse and keyboard should be there.

Connect the USB cable of the touch screen display to the computer, wait 10 seconds, and write the command lsusb again. Now you should see an additional line in the list. In the case of LG L1730SF, it is something that includes text Future Technology Devices International, Ltd. This device is the touch screen part of your display, now connected to your computer via the USB bus.

Try touching the display now. You’ll probably notice that whenever you tap the screen, the mouse pointer moves – but not quite as you expect it to: X and Y axles are swapped! For example, if you drag your finger on the screen from left side to right side, the mouse cursor will move from down to up. And if you drag from down to up, cursor will move from left to right.

Nevertheless, now we know that the touch hardware is found by Ubuntu Linux and the touch panel itself works. Of course, the software side still needs some work before the system becomes usable.

Driver name

In console, type this command to get a list of all input devices in the system:

 cat /proc/bus/input/devices

The list contains various information about each input device. One of them should have this name: ITM Inc USB Touch Panel. When you have found that from the list, check the line below it that begins with Sysfs=… In the end of that line, you should see something like /input/input14 (the number may vary). Write down that number, it tells to which input channel/file the touch screen is currently mapped to.

Now we can find out the name of the driver with these commands:

udevinfo -a -p /class/input/input14 | grep DRIVER

NOTE: replace the number “14″ with the number you wrote down in the previous step. You’ll see a chain of drivers attached to that input device (your touch screen). In the old days, the driver was called itmtouch. Now it is usbtouchscreen, a combined driver that includes support for many brands and models. You should see that driver listed here.

Another method to find out the driver is to look for a kernel module (driver) by its name. Still in console, you could type

lsmod | grep touch

As a result, you should see something like this:

usbtouchscreen        11652 0

usbcore            146028 5 usbtouchscreen,usbhid,ehci_hcd,ohci_hcd

Basically all computer hardware needs a driver. A driver communicates with the hardware equipment, and provides applications access to the device via the operating system’s kernel. In Linux, most of the device drivers are implemented as dynamically loadable kernel modules. Above, the command lsmod lists currently loaded modules, and the rest of the line | grep touch filters this list by passing through only lines that contain the word touch. We can filter the list like this because we are looking for touch screen drivers only and guessed that the word touch is likely included in the name of the driver module.

Now we know that the driver associated with the touch screen is called usbtouchscreen and it is currently loaded.

Swapping X and Y

NOTE: This is a dead end – read this chapter through without doing anything!

Our first problem is to somehow swap X and Y axels, as they seem to be reversed. First place to look for is the driver, usbtouchscreen. Maybe it can be configured?

Many kernel modules have parameters that can be set when the module is loaded. In order to find out if usbtouchscreen module has some, we can for example check it from the source code! A very helpful site for tasks like this is http://lxr.linux.no/, which hosts The Linux Cross Reference. By clicking through to the correct category, you’ll find the source code for usbtouchscreen module in an easily readable format. Here’s a direct link for usbtouchscreen.c source code file used in kernel version 2.6.27.4: http://lxr.linux.no/linux+v2.6.27.4/drivers/input/touchscreen/usbtouchscreen.c.

From the source code file you can find this line (line 60):

module_param(swap_xy, bool, 0644);

It means that usbtouchscreen module has a parameter called swap_xy, of boolean type (on/off). Clearly it can be used for swapping X and Y axles – isn’t this exactly what we need?

We can try to use the parameter. In console, type this to unload the driver module:

sudo rmmod usbtouchscreen

After executing this command, the driver module gets unloaded and the touch feature does not work anymore. You can check that by tapping the screen (the mouse cursor won’t move), and also with command lsmod | grep touch, which yields nothing.

In order to reload the module with some new parameters, we first need to know where the module is located in the file system. Begin with this command:

sudo updatedb

It updates the database that is used in searching for files. After it has finished, look for the driver from the file system:

locate usbtouchscreen

In response, you should get something like this:

/lib/modules/2.6.24-19-generic/kernel/drivers/input/touchscreen/usbtouchscreen.ko

This is the location of the driver module. Now that we know where it is, we can reload it with swap_xy parameter by typing this command (modify the path to reflect yours):

sudo insmod /lib/modules/2.6.24-19-generic/kernel/drivers/input/touchscreen/usbtouchscreen.ko swap_xy=1

Now, when you tap the screen, you should notice a couple of things. First, the mouse cursor moves again. Second, it moves differently than it used to: when you drag your finger from left side to right side, the cursor moves along the horizontal direction, not vertical as it used to. The swap parameter worked!

Unfortunately, it doesn’t seem to help enough. Now we’ll notice that the axles are mirrored, i.e. when you tap the left side of the display, the cursor appears to the right side, and when you tap up, cursor goes down. Moreover, if you try to tap in the center of the screen, you’ll notice that there’s quite a lot of offset in the cursor’s location. As this does not seem to work well enough, you can now simply reboot the computer to get rid of the swap_xy parameter.

What next?

Since the usbtouchscreen module does not have enough parameters to allow proper configuration, we need something more. Basically there are two options:

Option 1: we could modify the driver to accept more parameters, i.e. not only swapping the axles but also mirroring them, as well as support for some kind of basic calibration. This alternative involves programming. Moreover, it does not seem to be a very good solution to begin configuring a driver like this. For example, consider what happens if you have multiple touch screen devices connected to the same computer – you should be able to calibrate them separately, but this is not possible with kernel module parameters if the displays happen to use the same driver package (note that usbtouchscreen module contains support for multiple models and brands). The benefits of this option are that the system would be simple (just one driver module) and the configuration would be rather easy to do (i.e. find working parameters with some simple calibration tool or trial and error, then put the parameters to a configuration file that is used for setting parameters to kernel module that will be automatically loaded).

Option 2: use some middleware component in between the driver and X windowing system. I.e. do not map the output of the touch screen driver directly to mouse movements, but use another layer in between, which can be configured properly and easily. Since we are in the open source world, of course that has been already done: Evtouch, the Linux touchscreen driver for X, does exactly that. Here’s a link to its homepage: http://www.conan.de/touchscreen/evtouch.html

Evtouch – touchscreen driver for X

Installation

Unlike the driver usbtouchscreen, Evtouch is not automatically installed when you first plug in the USB cable of the touch screen. That must be done before we can continue. The easiest way to install it would be from Ubuntu’s software repositories, in case it is there. We can check that easily by going to http://packages.ubuntu.com, and entering evtouch to the search field. Remember to change “Distribution” to “Hardy” before you click the search button, as we want to search for a package intended to Ubuntu 8.04 Hardy Heron. The result of the search:

hardy (x11): Touchscreen-Driver for X.Org/XFree86 server [universe] 0.8.7-3ubuntu1: amd64 i386

This means that version 0.8.7 exists in the universe repository for i386 and amd64 systems. From the search results you can also see that it is called there xserver-xorg-input-evtouch. But is this the newest version? We can check that from evtouch home page: http://www.conan.de/touchscreen/evtouch.html.  (At the time I did my setup, it was the newest version.)

Not all Ubuntu’s software repositories are enabled by default. You must enable universe repository, if you haven’t already done that. In console, type

sudo nano /etc/apt/sources.list

Then uncomment all lines that end with the word “universe”. Save (CTRL+O) and exit (CTRL+X).

To sync your local cache with the repositories, type

sudo apt-get update

Now you should be able to install software from universe repository.

To finally install evtouch, give this command in the console:

sudo apt-get install xserver-xorg-input-evtouch

If everything goes fine, evtouch is now installed.

Configuring X

Next we need to configure X to use evtouch for the touch feature, instead of the default mouse driver. This requires editing X windowing system’s configuration file. As it is possible to make mistakes that prevent X from working, before continuing make a backup copy of the current X configuration file:

sudo cp /etc/X11/xorg.conf /etc/X11/xorg.conf.bak

Basic instructions on how to configure X to use evtouch can be found from evtouch module’s home page (recall http://www.conan.de/touchscreen/evtouch.html). To begin editing X configuration file, in console type

sudo nano /etc/X11/xorg.conf

Search the file for Section “InputDevice”, which contains a line Identifier “Configured Mouse”. After this section, add these new lines:

Section "InputDevice"
   Identifier "touchscreen"
   Driver "evtouch"
   Option "Device" "/dev/input/event1"
   Option "DeviceName" "touchscreen"
   Option "MinX" "98"
   Option "MinY" "43"
   Option "MaxX" "940"
   Option "MaxY" "925"
   Option "ReportingMode" "Raw"
   Option "Emulate3Buttons"
   Option "Emulate3Timeout" "50"
   Option "SendCoreEvents" "On"
EndSection

Then, look for Section “ServerLayout”. Add this line inside that section:

InputDevice "touchscreen" "CorePointer"

Then save (CTRL+O) and exit (CTRL+X).

Now we have added a new input device, which controls the mouse pointer in X. The device is called touchscreen and it uses evtouch driver. In addition, multiple options are used to configure it.

In order to test the new settings, you need to restart X. The easiest way to do that is to first save all open files and then press these buttons together: CTRL+ALT+BACKSPACE. X will restart, and then you can log in again. After logging in, you’ll probably notice two things: you’re mouse doesn’t work  anymore, and when you tap the touch screen, the pointer seems to disappear and the Trash folder opens! If you look carefully, you might see part of the pointer on top of the trash can icon in the lower right corner of the screen – that explains why the Trash folder opens after tapping the screen! If you move your finger near the lower right corner of the screen, you should see the mouse cursor moving on the desktop. However, X and Y axles are swapped. In addition, when you begin moving your finger on the screen,  the cursor first doesn’t move at all, and then jumps several hundred pixels forward.

Clearly we need to adjust the settings from the given defaults. Now that the pointer is out of control with touch (and mouse doesn’t work either), the easiest way to do the editing is with one of the text based consoles. Press together CTRL+ALT+F2 to open one of them, then log in and begin editing X configuration file by typing

sudo nano /etc/X11/xorg.conf

Go to the touch screen section you added earlier, and add a new option after other touch options:

Option "Rotate" "ccw"

This will swap X and Y axels by making evtouch think that the display is pivoted 90 degrees counter-clockwise. Write changes with CTRL+O, but do not exit from the editor. Instead, press CTRL+ALT+F7 to return to X, and then press CTRL+ALT+BACKSPACE to restart it. When the login screen appears, you do not necessarily need to log in – you can test the touch feature right away by tapping the login screen. When you tap near the lower right corner, you can see that X and Y axles are now correct, but Y axle is mirrored.

Go back to xorg.conf file by pressing CTRL+ALT+F2. In case you use value cw instead of ccw, evtouch assumes that the screen is pivoted 90 degrees clockwise, and then X axle will be mirrored… We need to use another option to purposely mirror one of the axles. You can leave rotation to ccw and try to fix the Y axle by adding another option in the end of our options list:

Option "SwapY" "On"

However, now you’ll see that in fact it swapped the X axle! This is due to the order in which Rotate and SwapY commands are applied. To make it really work, you can use for example cw in Rotate option and SwapY, but ccw in Rotate and SwapX should be fine too.

Calibrating touch

Now we’ve got X and Y configured as they should be, but the calibration is still way off target. You probably already noticed the calibration settings within the list of options we added to the X configuration file. In order to have some idea what the values to be used for calibration might be, we can go back to look at the source code of usbtouchscreen.c driver (http://lxr.linux.no/linux+v2.6.27.4/drivers/input/touchscreen/usbtouchscreen.c). Search for text [DEVTYPE_ITM], and you’ll find that for X axel the minimum configuration values are set to 0 and the maximum values to 0xFFF. The latter means that 12 bits are used per axel, which yields 4096 different values. However, as 0 is also included to the range, you can actually set the calibration value somewhere between 0 and 4095. Compared to this, the setting values  found from evtouch modules home page seem rather small.

Try to set the calibration values in xorg.conf as follows: use 0 for MinX and MinY, and 4095 for MaxX and MaxY. These are the bounds for the calibration values. With these values, you should see that the touch feature becomes almost usable! The pointer appears pretty close to the spot you tap everywhere on the screen. However, calibration is not yet precise, and there seems to be one major hurdle left: when you drag your finger on the screen, the cursor first doesn’t move, and then jumps forward. This problem has not disappeared, although the jumps are now much shorter as in our previous attempts. It seems like there’s some kind of a grid, and the cursor gets attached to the nearest invisible grid line.

In case you are planning to build somekind of a simple user interface with only a few buttons, you could basically work around the problem by hiding the mouse cursor and using some very big buttons. However, I want to be able to control the cursor precisely, so that it can be used for example for drawing. Before going through more precise calibration, this “jumpiness” issue needs to be resolved.

Read the 2nd part to solve the jumpiness issue from here.