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.

Abstract

There are many different needs for sending an audible signal from one location to another. The technology that works in one use case may not work well in another. We can divide the applications into two main categories:

The applications in the first category are aimed for enabling conversations over long distances. Telephone calls and teleconferences are perfect examples. Within this category the sound quality is not the top priority, but low latency can be considered a must. Both closed and open source software solutions exist, the most well-known being Skype.

The applications in the second category are aimed for broadcasting an audio signal from a single source to a larger audience, which in general does not need to be able to communicate back to the source (i.e. the audience listens only). Within this category the sound quality is an important enabler for long listening periods, whereas long latency can be usually tolerated well. Both closed and open source software solutions exist, for example Shoutcast and Icecast.

The setup described in this article is intended to be a one-way pipe for high quality live audio signal. Therefore, these instructions are likely useful in use cases that fall to the second category.

Introduction

In this article, audio streaming over the Internet network is applied to a radio station that needs to send its program to a remote transmitter tower. This new setup will replace current expensive ISDN connection with a lower cost version as follows: An old PC will be located in the radio tower’s cabin and used as a server computer that receives live audio stream over an Internet connection, and plays it back. The audio signal from the server PC’s sound card is routed to a radio transmitter device and further to an antenna. The program source comes from a client computer that sends the audio signal to the server over the Internet. It can be for example a laptop equipped with a microphone and a CD/MP3 player software.

As Internet radio is nowadays a rather well established concept, it is not a surprise that mature software solutions exist for setting up own Internet radio station. One of them is Icecast, an open source server software for streaming multimedia. In this article, Icecast is used in the server computer as a connection point where audio content can be streamed to from other locations. However, instead of sharing the audio stream to hundreds of listeners via the Internet – as is usually done with Icecast – here it is played back immediately on the server computer’s own sound card and further routed as an analog audio signal. In order to play the audio with the server computer, also an Icecast compatible client software needs to be running on the server, here Ogg123 is used as a player. This way, whatever audio content is streamed to the server, it can be immediately and automatically played back to the audience. Ices2 and Edcast are examples of applications that can be used as a the streaming source, running on the client computer. Both support Ogg Vorbis and MP3 encoding, among others. There are in fact quite many packing algorithms. Ogg Vorbis is used in this article because it is both free and provides very good audio quality.

This kind of setup makes transmitting radio program from various local events simple: one can setup the equipment at the radio tower so that the devices can be turned on remotely e.g. with an SMS from a mobile phone, then open a connection to the server computer from a laptop over the Internet, and begin broadcasting real radio program to the listeners from wherever one happens to be.

What is needed

The main building blocks of the system are these:

1. An old PC that can be dedicated to act as an audio link server computer in the receiving end
2. Ubuntu Linux 8.04 Server as an operating system for the server computer
3. Icecast 2 as a streaming software backend for the server computer
4. Ogg123 as an audio stream player for the server computer
5. Ogg Vorbis audio encoder and decoder for audio data packing (client side) and unpacking (server side)
6. A Linux or a Windows computer to act as the client computer in the sending end
7. Ices2 (Linux) or Edcast (Windows) as audio streaming application for the client computer

Naturally also broadband network connection is needed for both the server and the client computer. Various audio equipment, such as microphones, mixers, CD players, headphones and monitors might be necessary, depending on your use case.

The Setup

1. Selecting the server computer

One should begin with selecting and acquiring a PC that will be used as the backend server for the Internet audio link. This computer does not need to be a new, fancy dream machine with all the latest and greatest – on the contrary; it should be a simple, decent and reliable work horse that can be dedicated to this one task. What we are looking for is a typical home or office PC made somewhere 1997 or later. You can probably find one for free either from your own garage, or by asking your friends and relatives. I got a suitable computer from my sister’s husband, who was going to throw it away. As an example of adequate machine, see the specifications of that computer below.

• Intel Pentium MMX 166 MHz processor
• 64 MB memory
• 2 GB hard drive
• ATI Rage II+ display adapter
• Creative SB Live sound card
• CD-ROM drive

2. Preparing the server computer hardware

The first task is to check that the computer is adequate for the purpose we are going to use it. The requirements are somewhat dependent on the chosen Linux version. Since we are using Ubuntu 8.04 Server in this article, I think the computer should have at least 120 MHz Pentium processor (tested to work), 64 megabytes of RAM (tested to work) and a gigabyte or more of hard drive space (Ubuntu installation alone will require ~400 megabytes). It must have a sound card and a network card. Note that keyboard, display and CD-ROM drive are useful only during the initial setup phase, as the computer can be managed remotely over the network connection later on. Mouse is not needed at all, nor is the horse power for running a graphical desktop environment.

If the computer is to be placed into a remote location where it cannot be easily accessed after the initial setup is done, I think it is reasonable to clean it now while it is available. I also recommend taking notes and photographs of the components, especially how they are connected, as this information may turn invaluable later on when you are doing some remote management over an Internet connection. For example, the preparation tasks might include these:

• Turn power off from the rear power source switch, remove all external cords from the computer and open the computer case.
• Remove dust e.g. with a vacuum cleaner (be careful), then make sure that all parts and cables are firmly attached inside and that there are no loose parts.
• Organize cables etc. so that the air can flow through the case with ease and check that all fans work properly by temporarily attaching power cord and turning the computer on for a short period (then turn it off and remove the power cord again).
• Take a few photographs of the interior (in case you need to check something later or give guidance to someone else from a remote location) – try to get pictures where one can see some details of the components and how they are attached, for example to which IDE ports hard drive and CD-ROM drives are connected to and whether there is room for upgrades (empty slots on motherboard and case).
• Make a list of all parts and their models (motherboard, processor, memory…), that will help during installation and later if you need to solve problems.
• Put all the pieces back together, then plug in the keyboard, display and power cords for setup phase.

As an example, this is my list of the components:

• Motherboard: Titanium P51430TX/IIB, Intel + Winbond chipset, 4xPCI, 4xISA, 4xSIMM, 2xDIMM
• Processor: Intel Pentium MMX 166 MHz Socket 7
• Memory: 4x 16MB (long) SIMM
• VGA: ATI Rage II+, chipset 3D Rage II+ DVD
• Sound: Creative SB Live, model CT-4750
• Hard drive: Seagate Medalist ST32122A, 4092 cyl, 2111 MB, 16 heads, 63 sectors (IDE1 master)
• Floppy: 3.5″ Teac FDD, model FD-235HF
• CD-drive: Toshiba 24x CD-ROM, model XM-6102B (IDE2 master)
• Case: Wings (ATX)
• PSU: Seventeam ST-200HRK (ATX)

Note: In case you want to start the computer remotely e.g. via SMS, you’ll need a device that can receive SMS messages and turn power on/off in its outputs (where you should connect your computer’s power cord). In addition, you probably need to modify the computer a little. Some PCs can be made to start automatically when they begin to receive power simply by configuring this behavior in the BIOS. Others need a small hardware modification. Old computers based on AT design have on/off type power switch, which you can simply leave “on” – it’s as simple as that. However, modern ATX form factor computers use a momentary power switch, which cannot be used like that. This can be solved by connecting two certain wires together in the big cord that comes from the PSU and is connected to the motherboard (google for instructions on which pins to connect). I had to go with the last option. For convenience, I even added a switch into the back of the computer so that I can enable/disable auto start feature with ease.

3. Configuring the BIOS

It is quite likely that there isn’t that much to tune in the BIOS. However, it may be a good idea to load “optimized default” settings just for sure, especially if you got the computer from someone else. Then check that all settings seems to be ok and the computer is working fine.

One thing to note is that since the computer may not have a keyboard attached to it in the remote location, you should check that it is not required during boot procedure. Typically there is a setting called “Halt on”, and a proper setting value might be for example “All but keyboard”.

Also, you might want to try to optimize the boot time to be as short as possible by removing some checks from the boot operation sequence. However, in general you should not try to tweak the computer to run as fast as possible e.g. via overclocking the processor or tweaking memory timings. There’s no use for this kind of tricks in our application, but they can make the computer hardware unreliable, which we definitely want to avoid.

To prepare for the next phase, you should check the BIOS settings for the boot media. Make sure that the computer can be booted from a CD. After installing the operating system, change the boot sequence so that it only starts from hard drive (C-drive). This will take a few seconds off from boot time.

4. Installing the operating system

If you don’t already have Ubuntu 8.04 Server CD, create it now (see instructions from Ubuntu website if you don’t know how to make it). When you’re done, put the CD into the server computer’s CD drive and turn the computer on. After a while, Ubuntu start menu should appear on your display.

• Select your language (I prefer English although it is not my native language).
• If you’ve just burned the CD, you should test it in order to avoid problems later. Select “Check CD for defects”. When you’re done, reboot from the CD.
• If you’re not sure that the computer hardware is OK, you should at least run the memory test. Select “Test memory”. When you’re done, reboot from CD.
• To begin installation, select “Install Ubuntu Server”.
• Choose your language (e.g. English)
• Choose country/territory/area (e.g. Finland)
• Choose keyboard layout (e.g. Finland). Wait a moment.
• Next the installer will try to detect your network card and configure it. This may either work or fail, but it doesn’t really matter at this point – you’ll probably need to configure it manually later anyway, as the server needs a static IP address and the installer waits for dynamic IP address to be assigned by a DHCP server in your network. In case the network detection fails, you are given a possibility to configure it manually. At this point, I chose not to (“Do not configure the network at this time).
• However, you should still give a hostname (the name of the computer), which is asked next. I wrote “RadioServer1″. Wait a moment.
• The hard drive needs to be partitioned next. I chose “Guided – use entire disk”. The wizard suggested to divide my 2 GB hard drive to one big 1.9 GB partition with ext3 filesystem, and another small 150 MB swap partition. This is fine, so I accepted it by choosing “Finish partitioning and write changes to disk”.
• Next, a summary of changes was shown together with a confirmation request. Ok’ed that.
• Wait a while – this time somewhat longer, up to several hours if your computer is low on memory.
• Write user name (full name and account name). Write password (use a good one!).
• Choose services to install. From the options presented in the list, you only need OpenSSH server for remote management. If you plan to use a web browser for controlling the server, I recommend not to install the full LAMP setup for this purpose; you can install a much more lightweight solution in a later phase. This is important especially if you are low on resources (old computer).
• Wait. When the installation is complete, the computer will eject the Ubuntu CD and ask your permission to reboot. Do it.

5. Booting the first time

After installing the operating system and booting the computer the first time, you should read the text that is printed to screen. Watch out for errors. For example, my computer printed this line:

ACPI: Bios age (1997) fails cutoff (2000), acpi=force is required to enable ACPI

It is not critical to have ACPI, and my computer does not support it. I got rid of the note as follows:

• When boot procedure is finished, login prompt is shown. Log in with your user account name and password that were created during operating system installation.
• Type sudo nano /boot/grub/menu.lst to begin editing boot options.
• Look for a commented line #defoptions=quiet splash and append to the end of the same line acpi=off apm=on. New kernels that will be installed along with future updates will get these boot options. Note: do not uncomment the line; these are used by debian update-grub script.
• Then look for the first line that begins kernel    /boot/vmlinuz … and append to the end of the same line acpi=off apm=on
• You might want to consider removing quiet splash options from both places mentioned above. This way you get more information on screen while booting, which is usually a good thing for a server computer.
• Save CTRL + O and exit CTRL+X.
• Reboot the computer by writing to console sudo reboot

After successfully logging in, I checked a few basic things:

• Write dmesg | more to read system messages and look for errors. I did not have anything alerting, just some minor nags.
• Write df -h to see how much free space is left on the hard drive after installing Ubuntu Linux. In my computer it took about 400 MB and thus left me with 1.4 GB of free space. That is more than enough for software required for an audio link setup.

6. Setting up networking

One of the first things after Ubuntu installation is setting up networking. I assume you have some kind of router box that has a DHCP service for providing automatic IP address and configuration for clients. I performed the following steps:

• Write lspci to console in order to list all found PCI devices. I could see that my network card, which is equipped with Realtek RTL-8139 chipset, was included in the list, so the computer found it. I also remember that when I printed system messages with dmesg | more in previous step I could see that network card driver was successfully loaded.
• Write sudo nano /etc/network/interfaces to edit network devices. Probably only the loopback devices is listed, so you should add eth0 first as follows:

auto eth0
iface eth0 inet dhcp

• Write it out CTRL+O and exit CTRL+X.
• Connect network cable, if not already connected.
• Write sudo ifup eth0. You should see that system is starting networking with eth0 interface and trying get IP address, gateway and DNS server addresses from DHCP.
• You can check out the success. Write ifconfig to see details about network interfaces. You should see eth0 with proper IP address and some RX and TX packets already sent/received. Next, write cat /etc/resolv.conf, you should see a printout of (likely two) domain name server IPs. Finally, write route to see that default gateway has been setup properly.
• You should test the network connection. For example, write ping www.google.com to see that a) your computer can resolve domain name www.google.com to an IP address, and b) your computer has access to Internet and it can send and receive data. If you have troubles, try writing sudo ifdown eth0 and then sudo ifup eth0 or reboot the computer. If this does not help, google for help on setting up network in Ubuntu Linux.
• At this point I got a minor problem. The computer updated its clock from the Internet time servers, and whenever I tried to use sudo for managing the computer, it replied sudo: timestamp too far in the future: [...time...]. I got rid of this problem simply by writing sudo -K
• When you get the network working, remember that it needs to be configured for server use. Write again sudo nano /etc/network/interfaces. Comment the line iface eth0 inet dhcp by adding # character, i.e. the line becomes #iface eth0 inet dhcp and then add manual IP configuration with following new lines:

iface eth0 inet static
address 192.168.1.11
netmask 255.255.255.0
gateway 192.168.1.1

• Of course, the addresses need to be adapted according to your own network.
• Write out CTRL+O and exit CTRL+X.
• To really apply the new settings, write sudo ifdown eth0, then sudo ifup eth0, and check that IP address has changed with ifconfig.
• You can use another computer in the same network to check that your server can be accessed. Use for example ping 192.168.1.11 (or whatever is your server’s IP address that you just set) to see that it replies to requests properly.
• When you move the computer to the actual remote location, you need to setup networking again! Change it back to DHCP first to get DNS server IPs and to check that networking in general in that location is ok. Then switch back to the manual configuration, and setup a proper IP address and gateway.
• You probably also need to edit your network router box’s settings, for example open the necessary ports and route request from the Internet to the server computer’s IP address.
• Note: another alternative to manual configuration is to continue using automatic configuration, and apply the permanent IP address by editing the router’s settings (IP – MAC address binding in the DHCP table). Depending on the network setup in the remote usage location, it might be even possible to configure the router box in advance and then simply move both the server and the router box to the remote location, without any on-site configuration.

7. Updating your Ubuntu Linux installation

Now that you have a working network connection, it’s time to update the operating system. Don’t leave this to a later phase, do it now!

• Write sudo apt-get update to update package source list first.
• Write sudo apt-get upgrade to upgrade your installation to newest available software packages (this can take a while and even require a reboot).

By the way, the reason for selecting Ubuntu 8.04 Server for this project is that it was a) latest release when writing this guide, b) popular Linux distribution, c) already familiar to me, and d) provides updates for 5 YEARS, starting from April 2008 – which is nice for a remote server computer that you do not wish to install again soon.

8. Setting up remote management

Since you now have a server computer in your network, set up with SSH server software, it is possible to now continue either locally (as done so far) or remotely. At least
you should try that the remote management works. Check it like this:

• Write ps aux | grep ssh to see list of processes with ssh in the name. You should see a line that says something like /usr/sbin/sshd on the right. It means that SSH server (daemon) is started.
• Go to another computer in the same network and write ssh [your server's IP address] -l [your user account name], e.g. ssh 192.168.1.11 -l trk. After accepting RSA key you should be logged in to the server. If you open the SSH port and forward the request properly in your network router, your server computer can be now safely and securely managed by you from wherever you can connect to the Internet!
• Note: if you only have Windows boxes, you can’t just type ssh … to the DOS box. Instead, you need an application for SSH. I recommend the free Putty.

9. Adding user accounts

You might wish to create more user accounts to the server, for example for remote management by multiple persons. This is easy in Ubuntu Linux:

• Write sudo useradd -d /home/newuser -m newuser, but replace newuser with proper user account name you wish to create.
• Write sudo passwd newuser (again, replace newuser) to set a password.
• If you trust admin (sudo) rights to the new user, write sudo adduser newuser admin (once again, replace newuser).
• You probably want that the shell works similar to the root account (bash). Write sudo nano /etc/passwd, then look for the name of the account you created (probably in the end of the file), and change the end of that line from /bin/sh to /bin/bash and then log in again with that account.

10. Setting up Icecast 2 server software

Installing Icecast is simple: write sudo apt-get install icecast2

After installation is finished, it needs to be configured. Write cat /etc/default/icecast2. This will print the defaults for Icecast, including path to server configuration file, and user id and group that are used for running the Icecast server. By default Icecast is disabled. Before enabling it, we must configure it correctly.

Write sudo nano /etc/icecast2/icecast.xml to begin editing configuration file. Then edit the settings as follows (only changes to be made are listed, section is named in parentheses to help locating the correct setting from the file):

(limits)

clients = 20

(authentication)

source-password = [your chosen password]

relay-password = [your chosen password]

admin-user = [your chosen admin username]

admin-password = [your chosen password]

hostname = RadioServer

<!-- My radio channel configuration -->
<mount>
<mount-name>/radioprogram.ogg</mount-name>
<public>0</public>
<on-connect>/home/radio/radioprogram-start.sh</on-connect>
<on-disconnect>/home/radio/radioprogram-end.sh</on-disconnect>
</mount>

<fileserver>0</fileserver>

(logging)

<loglevel>2</loglevel> <!-- 4 Debug, 3 Info, 2 Warn, 1 Error -->

(security)

<changeowner>

<user>icecast2>/user>

<group>icecast</group>

</changeowner>

Write out CTRL+O, and exit CTRL+X.

Now that we have configured Icecast, we can enable it. Write sudo nano /etc/default/icecast2. Change the line ENABLE=false to ENABLE=true. Write out CTRL+O, and exit CTRL+X.

Now you can try to start Icecast server. Command /etc/init.d/icecast2 will print usage guide. Now go ahead and start it as follows: sudo /etc/init.d/icecast2 start. Note that you can also start it manually and specify the configuration file as follows: sudo icecast2 -c /etc/icecast2/icecast.xml. Warning: for simplicity, these commands use sudo in this testing phase. However, in the long term you should not use sudo to run the server, but a separate user and group with properly set access rights.

If you don’t use sudo here you might get an error message saying I/O warning : failed to load external entity /etc/icecast2/icecast.xml, which means that your user account does not have rights to access the configuration file. Simply write sudo adduser newuser icecast (replace newuser with your username), log out, log in, and try again.

In a similar manner, if you get an error message nagging about log files (Permission denied), write sudo chmod 775 /var/log/icecast2/ to give your user account right to write to the log file directory. You may need to delete existing log files, if there is any! Then try again.

An error message saying Unable to set gid to [number] (Operation not permitted) means that in /etc/default/icecast2 file, user id and group id are set and we need admin rights to enable the group id for the process to be started, thus sudo needs to be used to make this effective.

If nothing seems to happen after writing the start command, then the server started. Press CTRL+C to get back to the prompt, and write sudo /etc/init.d/icecast2 stop to stop the server.

Write icecast2 -b -c /etc/icecast2/icecast.xml to make the Icecast server running in the background. This can be checked by writing ps aux | grep icecast2, then you should see two lines, the first one for the actual icecast2 process and the second one for the grep command you just wrote.

Now you can also try to reboot the computer, to check that Icecast2 server will start automatically. Write sudo reboot now, and observe the screen when the computer boots. You should see a few lines related to Icecast2, e.g. Starting icecast2 … When the computer has started, log in and check again with ps aux | grep icecast2 that the process is in fact running.

You can also check that there are no errors in the error log. Write cat /var/log/icecast2/error.log and check it out.

Make sure that admin interface works. Open a web browser from another computer in the same network, and type http://192.168.1.11:8000/ (change the IP address and port number to the ones that match your server setup). You should see a basic Icecast2 web interface in your browser. Now click the link Administration, and write the admin user name and password that you specified earlier into the Icecast2 configuration file. The admin web interface should load.

11. Setting up sound support and a player for incoming audio data

Ubuntu server installation does not include support for sound in vanilla installation. This is can be well understood, as many server setups simply don’t need any sound capabilities. However, in the audio link application the server must have sound, since we want that the server computer plays back the audio stream that it receives from the Internet via Icecast.

Begin by writing lspci to check that your sound card is recognized in Ubuntu Linux. For example, in my computer this created a list of devices and one of the printed lines tells that sound card is recognized: 00:0c.0 Multimedia audio controller: Ensoniq 5880 AudioPCI (rev o2).

Next, check that the drivers are loaded by writing lsmod | grep snd. In my computer, various modules were listed (11 lines, in fact).

Write sudo apt-get install alsa-utils. This will install sound support and some utilities, including volume control.

Write alsamixer to start newly installed volume control application. All volume levels are probably turned down and muted, so in order to hear anything, you need to crank up the volumes (use arrow keys) and unmute them (press ‘m’). Turn up at least Master and PCM lines, and check that they are not muted. Exit by pressing the ESC key. Then write sudo alsactl store to save the settings.

Next we will install a sound player application. It must be able to co-operate with Icecast2 software. You can find a list of media players that support Icecast2 streams from http://www.icecast.org/3rdparty.php. Since we are using an old computer without graphical X environment, command line based applications like ogg123 and mpg321 are natural choices. Install ogg123 and related packages by writing sudo apt-get install vorbis-tools. You can test ogg123 for example as follows: ogg123 http://www.vorbis.com/music/Epoq-Lepidoptera.ogg. You should see that ogg123 begins to stream a file from the Internet and hear it being played back. If you can’t hear anything but otherwise it seems to work, then go back to alsamixer and check that the correct channels are turned up and not muted. Then try again.

Install mpg321 and related packages by writing sudo apt-get install mpg321. You can test mpg321 for example as follows: mpg321 http://wahiduddin.net/troubleshooting/testing.mp3. You should see that mpg321 begins to stream a file from the Internet and hear it being played back. If you can’t hear anything but otherwise it seems to
work, then go back to alsamixer and check that you have correct channels turned up and unmuted. Then try again.

Now you should have sound working, and players that can stream ogg and mp3 files from the Internet – or, from your locally installed icecast software, as we plan to do.

12. Testing audio streaming with another computer as a source client

In this section we will finally create a working audio link. First we need to install a source client software to another computer in the same network. A list of compatible source clients can be found from http://www.icecast.org/3rdparty.php. For example, if you use Windows computer, install e.g. Edcast. If you use Linux computer, then install e.g. Ices. Here we use console-based Ices with Ubuntu 8.04 Desktop Linux computer as a client.

Go to the other computer in the same network, open console and write sudo apt-get install ices2. This will install a source client that is compatible with Icecast2 server and can stream audio with Ogg Vorbis lossy packing algorithm. Continue working with the client computer as follows.

Go to your home directory by writing cd ~. Then create a test directory mkdir icetest, and go there cd icetest. Copy example ices2 source configuration files from ices2 documentation folder to your test dir: cp /usr/share/doc/ices2/examples/ices-alsa.xml . (live capture) and cp /usr/share/doc/ices2/examples/ices-playlist.xml . (playlist).

You probably want to try playlist first, as it is a bit easier to get working. Edit the configuration as follows by writing nano ices-playlist.xml, i.e. change the following fields (use your own server’s IP address, port and password).

<param name="file">/home/[YOUR USER ID]/icetest/playlist.txt</param>
<hostname>192.168.1.11</hostaname>
<port>8000</port>
<password>password</password>
<mount>/test.ogg</mount>
<yp>0</yp>

Write out CTRL+O, and exit CTRL+X.

Open a web browser, go to http://www.vorbis.com/music/ and download some .ogg sample files. Save them to ~/icetest directory.

Create playlist from sample files: find ~/icetest -iname “*.ogg” > playlist.txt. Start source by writing ices2 ~/icetest/ices-playlist.xml. Open web browser and go to http://192.168.1.11:8000 and check Server status page, where you should be able to see that the server computer now receives data from the source computer – i.e. you should see that a new mount point has been created, called /test.ogg. In addition, if you go to the Administration page, you should see that there is now one source client and detailed information about the mount point.

Go to your server computer, open console, and use ogg123 (that you set up in the previous step) to begin listening the audio stream: ogg123 http://localhost:8000/test.ogg. You should quickly begin to hear the sound being played back. It comes from the other computer – you have now created a working audio link!

However, you probably do not plan to stick to playlists only – thus, we need to setup live capturing as well. Stop both audio player (ogg123) and source client (ices) by giving them CTRL+C. Then, edit the configuration file again as follows by writing nano ices-alsa.xml on the source client computer, i.e. change the following fields:

<hostname>192.168.1.11</hostaname>
<port>8000</port>
<password>password</password>
<mount>/test.ogg</mount>
<yp>0</yp>

Start source by writing ices2 ~/icetest/ices-alsa.xml. You can then test the source via web browser and ogg123 just like you did with playlist source. However, it is somewhat likely that in the web browser everything seems to be fine at first glance, but you still don’t hear anything. In the web browser, when you click the link Admin home and observe the /test.ogg mount point’s details, you might notice that total_bytes_read field grows rather slowly, especially when compared to previous test with playlist stream (refresh the page a few times to see it change). If you experience something like this, then open your sound mixer in the source client computer, and try to turn volumes and switches on until you find the right configuration. This is easier to do e.g. using Audacity application, by turning input monitoring on and observing when the volume bars begin to move. Then exit audacity to release sound capturing channel, and start ices again. Streaming from live source should now work!

13. Tuning the bandwith

The sound quality at default settings is rather poor (downsampled to single 22 kHz channel). You probably wan’t to adjust the setting for a) higher sound quality, and b) more reliable stream (ie. no drop-outs). Case a) is handled mainly in the source client’s settings, and case b) in the player’s settings.

Go to source client computer and edit ices settings: nano ices-alsa.xml, then change the settings as follows:

<encode>
<quality>1</quality<
<samplerate>44100</samplerate>
<channels>2</channels>
</encode>
<downmix>0</downmix>
<resample>
<in-rate>44100</in-rate>
<out-rate>44100</out-rate>
</resample>

Write out CTRL+O, and exit CTRL+X. The stream contains now much higher quality sound, when you restart it: ices2 ~/icetest/ices-alsa.xml.

Go to server computer and start sound playback with longer buffering: ogg123 -b 256 -p 50 http://localhost:8000/test.ogg. You should now hear good quality, reliable sound playback. However, note that there is more than 20 second delay between the original sound and the playback. This is mainly due to long buffers. In my test, when I set -b and -p to 0 i.e. input buffer is set to minimum size (only 8 kb), there is still 9 second startup delay (and I get occasional drop-outs). If I re-configure ices-alsa.xml and upgrade quality from 1 to 8, then the delay is less than 3 seconds. This happens because higher quality means more bits per second and thus fixed size buffers will get flushed more quickly. However, drop-outs occur more easily.

Now you might wonder how fast Internet connection is needed in practise. The server needs to be able to download in average at least the amount of data that the encoded stream requires, whereas the client needs to be able to upload that fast. Usually download speed is faster than the upload speed, which you must take into account: in general, the client needs a faster Internet connection than the server.

Therefore, what is expected from the broadband Internet connection depends on a) parameters used for the encoder (sound quality), and b) the direction of the data flow. If the connection has problems in keeping the speed of the data stream constant then faster nominal connection is necessary, so we can add c) the quality of the connection.

As a result, if you use e.g. 64 kbit/s stream in the encoder, then 64 kbit/s theoretical upload speed will not be fast enough! TCP/IP stack adds many additional bits to the stream, which also need to be transferred.  Moreover, there will always be some hiccups in the transfer (i.e. for a short moment no data is transferred at all). In order to tolerate these, additional bandwidth is required so that buffering can handle the hiccups without any audible trace. To be on the safe side, double the speed of the encoder: 64 kbit/s encoder stream should work fine on 128 kbit/s upload link.

I have successfully sent data (client side) using a mobile phone in EDGE (EGPRS) network, but plain GRPS is not fast enough. EDGE should be about 4 times faster than GPRS and reach above 200 kbit/s in practise. This goes well with the theory above, EDGE should be fast enough but GPRS not.

It is also possible to chain multiple radio networks in serial. In one test, I used a laptop as a program source. It was connected to my N95 mobile phone via Bluetooth, which connected to the Internet via EDGE. The server computer was connected to the Internet via 450 MHz wireless broadband, and played back the audio signal. Then an FM radio transmitter was used to send the audio signal as FM radio program, which was finally received and played back by an FM radio receiver. All the equipment was located in the same room, but the signal travelled through 4 different radio networks and hundreds of kilometers! The sound quality was still very good.

Note that this kind of setup allows great flexibility: both the program source and the transmission tower can be wirelessly connected to the Internet and thus easily moved from one location to another. The program source can also be battery powered (at least for a while), e.g. a laptop and a mobile phone. With a suitable Icecast compatible client software, the program source could be in fact be no more than a mobile phone – one could play sound files from the phone’s memory, or use the built-in microphone or e.g. a Bluetooth microphone for live programs! Although that would be very cool, I’m not aware of any such client software for mobile phones – yet.  That would be an interesting hobby project to make one.

14. Auto-starting playback upon source client connection

Although the audio link is already working, there is still some tricks to be done. For example, to make the server better automated and more convenient to use, we can auto-start playback when a source client connects to it with a simple script. This way we can control the playback from the client, i.e. from only one point in the chain. Here an example of such a script is presented.

First we will add icecast2 user to audio group, so that the player can be started with a script run by icecast2 user: sudo usermod -a -G audio icecast2.

Next, create a directory for automation scripts: sudo mkdir /home/radio and go to that directory: cd /home/radio. Then create a new script for auto-starting playback: sudo nano radioprogram-start.sh and write the following content:

#!/bin/bash
# Script to be run when radio program begins

# Notify all users of beginning radio transmission.
wall < /home/radio/radioprogram-start_message.txt

# Remove potential program end flag, if any.
FLAGFILE=/tmp/program_end.flag
if [ -e $FLAGFILE ]
then
  rm -f $FLAGFILE
fi

# Start playing radio program.
/usr/bin/ogg123 -b 512 -p 100 http://127.0.0.1:8000/radioprogram.ogg &

# End of File

Save CTRL+O and exit CTRL+X.

Change permissions so that the script can be run by you and all users in the icecast group: sudo chown icecast2:icecast radioprogram-start.sh and sudo chmod 754 radioprogram-start.sh.

The script will print a short message to all users that have currently logged in, to notify of beginning of a radio transmission. Write a text file, which contains a message to be sent: sudo nano radioprogram-start_message.txt and type e.g. the following content:

RADIO TRANSMISSION BEGINS!!!

Save CTRL+O and exit CTRL+X.

Change permissions so that the message can be read by you and all users in the icecast group: sudo chown icecast2:icecast radioprogram-start_message.sh and sudo chmod 754 radioprogram-start_message.sh.

The script will also delete a flag file, if found from /tmp directory. This will be explained in the following chapter.

Playback will be initiated in the background, with 512 kb buffer size and 100% pre-buffering, using Icecast2 mount point named radioprogram.ogg.

In order to make Icecast2 server run the script when client opens a connection to the server (i.e. begins radio transmission), begin editing the Icecast2 server’s settings as follows: sudo nano /etc/icecast2/icecast.xml, then create/add the following section. Pay attention to <on-connect> line!

<!-- Radio program configuration -->
<mount>

<mount-name>/radioprogram.ogg</mount-name>

<public>0</public>

<on-connect>/home/radio/radioprogram-start.sh</on-connect>

<on-disconnect>/home/radio/radioprogram-end.sh</on-disconnect>

</mount>

Save CTRL+O and exit CTRL+X.

In order to test this, you need to go to the client computer and check that the mount point matches /radioprogram.ogg in your ices configuration file. Then you need to restart Icecast2 server software on the server computer so that the changed configuration file will be read: /etc/init.d/icecast2 stop and sudo icecast2 -b -c /etc/icecast2/icecast.xml. Finally, from the client computer, start sending content to the server: ices2 ~/icetest/ices-alsa.xml. The player should automatically start (in the background), and a notification be printed on the screen.

In case of troubles, write cat /var/log/icecast2/error.log and check it out. Also note that it is possible that the player was in fact started OK, but there is only a problem in writing the notification text on the screen and due to long buffering delay, you don’t here anything (yet). You can test that by writing ps aux and observing if a process with name /usr/bin/ogg123 is running (meaning that the script worked), or just wait a while until player’s buffer is filled and audio playback begins. For further testing, you can kill the player with sudo kill [PID], where [PID] is the ID of the player process (you can see that from ps aux output).

You have now probably figured out one problem in the script: it will try to create a new player instance every time the client makes a connection. That’s not good in case the connection breaks and you need to reconnect. We will handle this with another script and a flag file, see next chapter.

15. Shutting down server after source client disconnection

When it is time to end the radio transmission, we will likely want to shutdown the server computer in the radio transmission site. If you have set up a power on/off system with e.g. SMS from a mobile phone, this can be easily performed. However, one shouldn’t just cut the power off from any computer, these devices need to be prepared for shutdown. For more convenient use, this can be configured to happen automatically after the source client disconnects from the server (i.e. ends sending radio program content).

It is possible that the connection breaks by accident for a short moment, and in this case the server should not automatically shut itself down. We can solve this dilemma with a time delay: after the connection gets broken, a timer will be started. When the timer triggers, we will check if the connection has been opened again, or not. Then we can decide whether to go for shutdown, or to continue radio transmission. In practise, a flag file can be created for marking a potential shutdown, to be deleted when a connection returns. If the connection doesn’t return in time, the flag file will still be there when the shutdown timer triggers, and we know that we can proceed to shutdown. Necessary code for deleting an existing flag file was already written to on-connection script in the previous chapter, now will do the rest with the on-disconnection script.

Shutting down the server computer requires admin rights. Since Icecast2 server software will initiate the shutdown procedure, it needs to have the right to do that. Here we allow it to run (only) the shutdown script as follows: sudo visudo -f /etc/sudoers, then add icecast2 ALL=NOPASSWD: /sbin/shutdown, save and exit.

Now we can create a script that will be run when the client disconnects: cd /home/radio, then sudo nano radioprogram-end.sh and write the following content:

#!/bin/bash
# Script to be run when radio program ends.

# Write potential program end flag.
FLAGFILE=/tmp/program_end.flag
touch $FLAGFILE

# Wait a while (3 minutes) to see if the program begins again.
sleep 180

# Check if program has started again.
if [ -e $FLAGFILE ]
then
  # Notify all users of ending radio transmission.
  wall < /home/radio/radioprogram-end_message.txt

  # Shutdown computer.
  sudo shutdown -hP now > /var/log/icecast2/shutdown.log 2>&1
fi

# End of File

Save CTRL+O and exit CTRL+X.

Change permissions so that the script can be run by you and all users in the icecast group: sudo chown icecast2:icecast radioprogram-end.sh and sudo chmod 754 radioprogram-end.sh.

The script will print a short message to all users that have currently logged in, to notify of ending of a radio transmission. Write a text file, which contains a message to be sent: sudo nano radioprogram-end_message.txt and type e.g. the following content:

RADIO TRANSMISSION ENDS!!!

Save CTRL+O and exit CTRL+X.

Change permissions so that the message can be read by you and all users in the icecast group: sudo chown icecast2:icecast radioprogram-start_end.sh and sudo chmod 754 radioprogram-end_message.sh.

In order to make Icecast2 server run the script when client closes a connection to the server (i.e. ends radio transmission), edit the Icecast2 server’s settings as follows: sudo nano /etc/icecast2/icecast.xml, then create/add the following section. Pay attention to <on-disconnect> line!

<!-- Radio program configuration -->
<mount>

<mount-name>/radioprogram.ogg</mount-name>

<public>0</public>

<on-connect>/home/radio/radioprogram-start.sh</on-connect>

<on-disconnect>/home/radio/radioprogram-end.sh</on-disconnect>

</mount>

Save CTRL+O and exit CTRL+X.

In order to test this, you need to go to the client computer and check that the mount point matches /radioprogram.ogg in your ices configuration file. Then you need to restart Icecast2 server software on the server computer so that the changed configuration file will be read: /etc/init.d/icecast2 stop and sudo icecast2 -b -c /etc/icecast2/icecast.xml. Finally, from the client computer, start sending content to the server: ices2 ~/icetest/ices-alsa.xml. The player should automatically start (in the background), and a notification be printed on the screen. Then you can give CTRL-C to it, and the player on the server computer should stop as well. After the time delay, the computer should shutdown, unless you start sending content again. During the time delay, you should see the flag file already in place in /tmp folder and the sleep process running with ps aux command.

In case of troubles, write cat /var/log/icecast2/error.log and check it out. It is possible that the player stops after its internal buffer becomes empty, and the computer will shut itself down after the time delay. For easier testing, you don’t want the computer to shutdown all the time, so comment out that line from the script and re-enable it when you’re done.

16. Firewall

Since the server computer needs to be reachable from the Internet, some openness is required. However, you should deny all traffic exept what is absolutely necessary. This is achieved with a firewall, which can be either a separate hardware device, built-in to a network router, or implemented with software in the server computer itself. Here an example configuration is presented for using the sofware firewall included in the Ubuntu Linux distribution.

The firewall software is called iptables. It can be configured very precisely, but is known to be somewhat complex to set up. You can check current firewall rules by writing sudo iptables -L. By default, it should allow all traffic. Next we will configure it for audio link use by adding a few new rules. Note that the order of the following commands is very important.

• Allow loopback device: sudo iptables -I INPUT 1 -i lo -j ACCEPT
• Allow established sessions: sudo iptables -A INPUT -m state –state ESTABLISHED,RELATED -j ACCEPT
• Allow incoming traffic to SSH port for remote administration: sudo iptables -A INPUT -p tcp –dport ssh -j ACCEPT
• Allow icecast sources to send radio program, and web administration: sudo iptables -A INPUT -p tcp –dport 8000 -j ACCEPT
• Block all other incoming traffic: sudo iptables -A INPUT -i eth0 -j DROP

Check the rules by writing sudo iptables -L, you should see these rules printed out:

Chain INPUT (policy ACCEPT)

target     prot opt source               destination

ACCEPT     all  --  anywhere             anywhere

ACCEPT     all  --  anywhere             anywhere            state RELATED,ESTABLISHED

ACCEPT     tcp  --  anywhere             anywhere            tcp dpt:ssh

ACCEPT     tcp  --  anywhere             anywhere            tcp dpt:8000

DROP       all  --  anywhere             anywhere

Chain FORWARD (policy ACCEPT)
target     prot opt source               destination

Chain OUTPUT (policy ACCEPT)

target     prot opt source               destination

Save configuration now: sudo iptables-save, then save the firewall rules into a file: sudo sh -c “iptables-save > /etc/iptables.rules”

Finally we will enable the firewall rules by automatically loading them from the saved file when the network is brought up. Begin editing network configuration: sudo nano /etc/network/interfaces, then make the following adjustments:

auto eth0

iface eth0 inet static
address 192.168.1.11
netmask 255.255.255.0
gateway 192.168.1.1

pre-up iptables-restore < /etc/iptables.rules

Save CTRL+O and exit CTRL+X.

Now the server computer should only allow access to SSH server and Icecast server, blocking all other connection attemps outside.

17. Dynamic DNS

In case the broadband operator uses dynamic IP address, it can be difficult to know from which IP address the server can be accessed as it can change often. This problem can be solved by upgrading to static IP address (usually expensive), or by using a free Internet service called dynamic DNS. The service allows reserving a subdomain (xxxx.something.com) and updating your current IP address to the service, so that the traffic to your reserved subdomain can be forwarded to your current IP address. Thus you should be able to always access the server via the subdomain.

There are multiple providers of dynamis DNS service. Here we use DynDns.com, which is probably the most famous of them. Go to www.dyndns.com with a web browser, create an account and store the information you get:

• username: XXXX
• password: XXXX
• domain: XXXX

The server computer needs a few adjustments to publish its IP address that it gets from broadband operator’s DHCP server to DynDns servers.

First install ipcheck tool: sudo apt-get install ipcheck.

Then continue as follows to create a place for IP publishing script: sudo su, cd /root, mkdir ipcheck, cd ipcheck. Then store the account information into a file: nano dyndns_account, write only one line: [dyndns username] [dyndns password] [dyndns subdomain], save CTRL+O and exit CTRL+X. Change file permissions: chmod o-r dyndns_account.

Create the IP publisher script by writing nano dyndns_update.sh and add the following content:

#!/bin/sh
cd /root/ipcheck/
if [ -f ipcheck.dat ]; then
   /usr/sbin/ipcheck -l -r checkip.dyndns.org:8245 --acctfile dyndns_account
else
   /usr/sbin/ipcheck --makedat -l -r checkip.dyndns.org:8245 --acctfile dyndns_account
fi

Save CTRL+O and exit CTRL+X. Change permissions: chmod +x dyndns_update.sh.

Type exit to exit from superuser login.

Finally we need to edit one of the system startup scripts to run our new IP publishing script: sudo nano /etc/rc.local. Add/change the file to look like this:

#!/bin/sh -e
#
# rc.local
#
# This script is executed at the end of each multiuser runlevel.
# Make sure that the script will "exit 0" on success or any other
# value on error.
#
# In order to enable or disable this script just change the execution
# bits.
#
# By default this script does nothing.

test -x /root/ipcheck/dyndns_update.sh && /root/ipcheck/dyndns_update.sh

exit 0

Save CTRL+O and exit CTRL+X.

After rebooting the server, you should be able to use http://[YOURSUBDOMAIN].dyndns.org:8000/ to access the server – provided that it is running, connected to Internet and properly routed/firewall to be accessible from the Internet.

18. Automatic disk scans on boot

As the server may need to be rebooted during live radio programme if something goes terribly wrong, it would be VERY annoying if this happened to be the 30th time the computer is booted and a long lasting disk scan would start. Or, if the computer is used after long period of time, it would also trigger the scanning. As we actually can live without this feature, we’ll just turn it off as follows: begin editing file system configuration table sudo nano /etc/fstab, then change the last column from 1 to 0 for main partition, save with CTRL+O and exit CTRL+X.

19. Cleaning up

Some reminders for things to be done before taking the server to production use:

Check:

• Icecast log level – what do you actually need to get logged. Also check that processes aren’t filling the hard disk with continuously growing log files (logs should be configured rorating).
• Activate shutdown feature again in the shutdown script, in case you commented it out for testing
• Check all passwords; they should not use any default values or otherwise bad passwords!
• Make sure you have documented the basics of the server setup, and stored passwords to a safe place. If everything goes fine, the computer will be almost forgotten and soon nobody remembers anything about its setup – so do document!

Test:

• Server start time (how many seconds after turning the power on you can start sending audio signal to the server)
• Playback start time (how many seconds after audio signal has started to arrive will the player begin to play it back)
• Playback stop time (how many seconds after audio signal has stopped to arrive will the player stop to play it back)
• Server stop time (how many seconds after the audio signal has stopped to arrive the server has shut itself down)
• That no hiccups occur with configured encoder settings
• That the speed of the broadband connection is fast enough for used encoder settings
• That network configuration is adjusted to the actual production network, and it works
• That remote administration can be performed via web interface and SSH

20. Enjoy

Take the server to production use and enjoy free audio link over the Internet!

Here is a photograph of the place where my setup is being used: Olostunturi in Muonio, Finland. The equipment is located in the cabin, and the antenna is attached to the mast on the left. On the right, you can see part of a wind mill’s tower.

Radio setup at Olostunturi, Muonio Finland

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!

So far, I have been reading books or playing with my Nokia N95 – ie. listening music, reading daily news, playing games etc. However, after 2 years all this feels quite passive – instead of reading/listening/playing/otherwise consuming some form of entertainment made by others, I would like to be able to create something myself and really make use of that time. A family man never has that much time for himself, so every bit counts.

I’ve been carrying my bulky work laptop occasionally with me, but I don’t really want to use that for my personal stuff. Besides, that old windows installation boots in 5+ minutes… so I bought my first mini laptop. The idea is that I can easily slip it inside my backbag, boot fast, and then do much more than I can with a mobile phone.

I ended up to choose Asus Eee PC 1000HE (black). It’s a typical mini laptop with Intel Atom processor, 1 GB of memory and 160 GB hard drive. However, this one’s got a battery with some extra juice: advertisments claim 9.5 hour usage time! In practise it is likely closer to 7 or 8 hours, but hey -  that triples the usage time I get with my HP workhorse.

I have just finished installing some basic stuff and configured Windows XP to my taste (well, up to the limit where you can tailor any Microsoft product). Of course, I will install Ubuntu on this machine and use primarily that. However, I made an exception and decided to let Windows stay for now too, as occasionally one cannot avoid using it (for example, to update new firmware to my Nokia phone).

So far my experience of this little machine have been very nice. It turned out to be a bit heavier than I thought, but that doesn’t really matter in the bus. Keyboard is nice (to write with), and although I was a bit skeptical about the display size, 10″ and 1024×600 resolution seems to be good enough for basic computing things – like writing this blog.

So perhaps there will be more updates to the blog in the future… I’ve already got a lot of material from my hacking projects that I’m planning to put here, it just needs to be edited and published. Stay tuned.

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.