User:Radagast

From Openmoko

(Difference between revisions)
Jump to: navigation, search
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
<h1>Total Newbie's Getting Started Guide</h1>
+
<h1>Andrew's Total Newbie Guide</h1>
  
−
<h2>Introduction</h2>
+
These are my collected instructions for getting various FreeRunner features to work. I don't know much about FreeRunner or coding, so please forgive the numerous mistakes.
 +
 
 +
<h1>Getting the Freerunner working as a Phone</h1>
  
−
This guide is intended for people who just want to get their Freerunner working as a phone. I tried every distribution available in Jan 2009 and I will summarize my results for anyone who is interested.
+
date: Mar 2009
  
−
<h2>Getting the Freerunner working as a Phone</h2>
+
These guide is intended for people who just want to get their Freerunner working as a phone. I tried every distribution available in Jan 2009 and I will summarize my results for anyone who is interested.
  
−
<h3>Get a working SIM card</h3>
+
<h2>Get a working SIM card</h2>
  
 
First, make sure that your SIM card works with the Freerunner. Go to the [[Carriers]] page, find your country and carrier, and check what people have said about their SIM cards. My original SIM card did not work (Canada/Rogers) but Rogers kindly replaced it with a supported SIM.
 
First, make sure that your SIM card works with the Freerunner. Go to the [[Carriers]] page, find your country and carrier, and check what people have said about their SIM cards. My original SIM card did not work (Canada/Rogers) but Rogers kindly replaced it with a supported SIM.
  
−
<h3>Install Qt Extended</h3>
+
<h2>Install Qt Extended</h2>
  
−
Next is your choice of distribution. The great thing about the Freerunner is that you have lots of choices. The bad thing is that some choices are better than others for certain tasks, and it is not always clear what to use for each function. I have tested every distribution available in January 2009, and in my opinion the best distribution for using your Freerunner as a phone is [[Qtopia_/_Qt_Extended_on_FreeRunner|Qt Extended]], which is the Free version of Trolltech's QTopia (used on the Sharp Zaurus and some other devices).
+
The software that was on my FreeRunner when I received it was not functional as a phone. It wouldn't wake from suspend when it received a call. Sometimes it spontaneously rebooted. Often it just wouldn't turn on at all and I had to remove the battery. Fortunately there are many distributions available for the FreeRunner. This is one of the great things about open projects: you get to choose what software to run. The bad thing is that some choices are better than others for certain tasks, and it is not always clear what to use for each function. I have tested every distribution available in January 2009, and in my opinion the best distribution for using your Freerunner as a phone is [[Qtopia_/_Qt_Extended_on_FreeRunner|Qt Extended]], which is the Free version of Trolltech's QTopia (used on the Sharp Zaurus and some other devices).
  
−
You must download the kernel and rootfs and flash them to your Freerunner. First read through[[Flashing_the_Neo_FreeRunner]] page. Whatever OS you use on your desktop/laptop, you will need the dfu command line utility to copy the kernel and rootfs to your Freerunner. For most of my coding work I use Mac OS X, but for FreeRunner hacking I find it much easier to reboot into Ubuntu.  
+
You must download the Qt Extended kernel and rootfs and flash them to your Freerunner. First read through[[Flashing_the_Neo_FreeRunner]] page. Whatever OS you use on your desktop/laptop, you will need the dfu command line utility to copy the kernel and rootfs to your Freerunner. For most of my coding work I use Mac OS X, but for FreeRunner hacking I find it much easier to reboot into Ubuntu.  
  
−
Next download the kernel and rootfs to your workstation. Here's a link to the [http://other.lastnetwork.net/OpenMoko/qtextended-4.4.2-gta02-rootfs-release-working-with-SystemRingTones.jffs2 rootfs] created by Hypnotize. And here's the [http://qtextended.org/modules/mydownloads/visit.php?lid=91 mwebster flash image] containing the kernel. Boot your FreeRunner in dfu mode and use the dfu commands:
+
<b>Note: updated for Qt Extended 4.4.3. See the old section for qt extended 4.4.2 instructions</b>
 +
 
 +
Next download the kernel and rootfs to your workstation. Here's a link to the [http://triveros.go.dyndns.org/qtopia/Neo_rootfs_Backup_200902212230.jffs2 rootfs] created by Tomas Riveros Schober. And here's the [http://triveros.go.dyndns.org/qtopia/Neo_kernel_Backup_200902212230.bin kernel image]. Boot your FreeRunner in dfu mode and use the dfu commands:
  
−
  bash# dfu-util -d 0x1d50:0x5119 -a kernel -R -D  uImage-gta02-mwester-stable-d6f9fd270943fb22.bin
+
  desktop# dfu-util -d 0x1d50:0x5119 -a kernel -R -D  Neo_kernel_Backup_200902212230.bin
 
   
 
   
 
     ... stuff ...
 
     ... stuff ...
 
   
 
   
−
  bash# dfu-util -d 0x1d50:0x5119 -a rootfs -R -D  qtextended-4.4.2-gta02-rootfs-release-working-with-SystemRingTones.jffs2
+
  desktop# dfu-util -d 0x1d50:0x5119 -a rootfs -R -D  Neo_rootfs_Backup_200902212230.jffs2
 
   
 
   
 
     ... more stuff ...
 
     ... more stuff ...
 
   
 
   
 
<h2>Qt Extended isn't Perfect</h2>
 
<h2>Qt Extended isn't Perfect</h2>
 +
 +
<h3>Echo Cancellation Patch</h3>
 +
 +
<b>Echo cancellation should be in the 4.4.3 build</b>
  
 
<h3>The White Screen of Death (WSOD)</h3>
 
<h3>The White Screen of Death (WSOD)</h3>
  
−
Sometimes when Qt Extended recovers from suspend you see a bright white screen. You don't have a phone anymore - you have a flashlight. Hold the power button down for about five seconds to power down the phone, then power it back up.
+
<b>WSOD is fixed in the 4.4.3 build</b>
  
 
<h3>Official Documentation</h3>
 
<h3>Official Documentation</h3>
Line 40: Line 48:
  
 
Disconnect the USB cable before booting Qt Extended. Don't know why, but my FreeRunner often hangs if I boot with the USB cable plugged in.
 
Disconnect the USB cable before booting Qt Extended. Don't know why, but my FreeRunner often hangs if I boot with the USB cable plugged in.
 +
 +
<h3>Short Battery Life</h3>
 +
 +
My battery life is less than five hours which kinda sucks.
  
 
<h3>Adding New Media</h3>
 
<h3>Adding New Media</h3>
Line 45: Line 57:
 
Secure shell to the FreeRunner and create a Documents directory in /home/root. Then secure copy media files to /home/root/Documents. In Qt Extended use the File Manager to browse your Documents directory (might have to do a rescan from the options menu). If you have a working /media/card directory then you might be able to put files in there.
 
Secure shell to the FreeRunner and create a Documents directory in /home/root. Then secure copy media files to /home/root/Documents. In Qt Extended use the File Manager to browse your Documents directory (might have to do a rescan from the options menu). If you have a working /media/card directory then you might be able to put files in there.
  
−
As far as I can tell, Qt Extended plays ogg, wav and <b>some mp3</b>. Note that some of my mp3 files would not play, so I converted them to ogg using ogg2mp3.
+
As far as I can tell, Qt Extended plays ogg, wav and <b>some</b> mp3. Note that some of my mp3 files played but others didn't. I converted all my mp3s to ogg using ogg2mp3 just to be safe.
  
 
<h3>Wireless networking</h3>
 
<h3>Wireless networking</h3>
Line 51: Line 63:
 
You must secure shell to your Freerunner to configure wireless networking. Fix the /etc/wpa_supplicant/wpa_supplicant.conf and /etc/network/interfaces files then use <tt>ifup eth0</tt>.
 
You must secure shell to your Freerunner to configure wireless networking. Fix the /etc/wpa_supplicant/wpa_supplicant.conf and /etc/network/interfaces files then use <tt>ifup eth0</tt>.
  
−
<h2>Networking</h2>
+
<h1>Networking</h1>
  
−
<h3>Changing the Default Route</h3>
+
<h2>Changing the Default Route</h2>
  
−
Every time I connect the USB cable FreeRunner changes the default route to 192.168.0.200 interface usb0. Which is a pain in the butt, because I prefer to keep the wifi as my default gateway. I think this is caused by the line "gateway 192.168.0.200" in /etc/network/interfaces. The obvious fix is to remove that line. Here are the to change default route:
+
Every time I connect the USB cable FreeRunner changes the default route to 192.168.0.200 interface usb0. Which is a pain in the butt, because I prefer to keep the wifi as my default gateway. I think this is caused by the line "gateway 192.168.0.200" in /etc/network/interfaces. The obvious fix is to remove that line. If you default route is buggered up, here are the instructions to change default route:
 +
 +
freerunner# route delete default gateway 192.168.0.200
 +
freerunner# route add default gateway 192.168.3.1
  
−
bash# route delete default gateway 192.168.0.200
+
<h1>Qt Extended SDK</h1>
−
bash# route add default gateway 192.168.3.1
+
  
−
----
+
<h2>Introduction</h2>
  
−
<h1>Compiling Qt Extended SDK</h1>
+
It would be nice to write some custom apps. Also, there are Qtopia apps available on the interweb, but the binaries are all for Zaurus. It would be nice to compile them for FreeRunner.
  
−
These instructions are based on Jim Morris' [http://blog.wolfman.com/articles/2008/08/27/porting-xgps-to-qtopia-for-the-freerunner excellent article].
+
There is a VMWare image of the SDK available for 4.3.2, but not for 4.4.2. So I have to compile the Qt Extended SDK from source. These instructions are based on Jim Morris' [http://blog.wolfman.com/articles/2008/08/27/porting-xgps-to-qtopia-for-the-freerunner excellent article]. I know that doing everything as root is a grave sin, but I'm too busy fixing bugs in the Qt Extended build to fiddle with permissions too.
  
−
I downloaded the [http://qtextended.org/modules/mydownloads/visit.php?lid=97 SDK source] and [http://qtextended.org/modules/mydownloads/visit.php?lid=38  toolchain] from [http://qtextended.org qtextended.org]. Change directory to your machine's root directory then untar the toolchain - it will install itself to /opt/toolchains. Next create <tt>/opt/QtopiaSDK/qt-extended-4.4.2</tt> and <tt>/opt/QtopiaSDK/build</tt> directories. Unpack the Qt extended SDK source to <tt>/opt/QtopiaSDK/qt-extended-4.4.2</tt>. Set a pair of environment variables as follows:
+
My platform is a Macbook (Santa Rosa) running Ubuntu Intrepid.
  
−
  bash# export QTOPIA_DEPOT_PATH=/opt/QtopiaSDK/qt-extended-4.4.2
+
<h2>Compiling the Qt Extended SDK</h2>
−
  bash# export QPEDIR=/opt/QtopiaSDK/build/qt-extended-4.4.2
+
 
 +
Download the [http://qtextended.org/modules/mydownloads/visit.php?lid=97 SDK source] and [http://qtextended.org/modules/mydownloads/visit.php?lid=38  toolchain] from [http://qtextended.org qtextended.org]. Change directory to your machine's root directory then untar the toolchain - it will install itself to /opt/toolchains. Next create <tt>/opt/QtopiaSDK/qt-extended-4.4.2</tt> and <tt>/opt/QtopiaSDK/build</tt> directories. Unpack the Qt extended SDK source to <tt>/opt/QtopiaSDK/qt-extended-4.4.2</tt>. Set a pair of environment variables as follows:
 +
 
 +
  desktop# export QTOPIA_DEPOT_PATH=/opt/QtopiaSDK/qt-extended-4.4.2
 +
  desktop# export QPEDIR=/opt/QtopiaSDK/build/qt-extended-4.4.2
  
 
Next download a pair of patches from mwester's openmoko stuff: [http://moko.mwester.net/download/pkg-config-template.patch pkg-config-template.patch] and [http://moko.mwester.net/download/qmemoryfile_unix_open_args.patch qmemoryfile_unix_open_args.patch]. Copy these to the qt-extended-4.4.2 source directory and execute these commands:
 
Next download a pair of patches from mwester's openmoko stuff: [http://moko.mwester.net/download/pkg-config-template.patch pkg-config-template.patch] and [http://moko.mwester.net/download/qmemoryfile_unix_open_args.patch qmemoryfile_unix_open_args.patch]. Copy these to the qt-extended-4.4.2 source directory and execute these commands:
  
−
  bash# patch -p1 < qmemoryfile_uniz_open_args.patch
+
  desktop# patch -p1 < qmemoryfile_unix_open_args.patch
−
  bash# patch -p1 < pkg-config-template.patch
+
  desktop# patch -p1 < pkg-config-template.patch
  
 
Now change directory to the build directory. Execute the following:
 
Now change directory to the build directory. Execute the following:
  
−
  bash# cd $QPEDIR
+
  desktop# cd $QPEDIR
−
  bash# $QTOPIA_DEPOT_PATH/configure -device neo -D _FORTIFY_SOURCE=0
+
  desktop# $QTOPIA_DEPOT_PATH/configure -device neo -D _FORTIFY_SOURCE=0
−
  bash# make
+
  desktop# make
−
  bash# make install
+
  desktop# make install
  
−
The <tt>_FORTIFY_SOURCE=0</tt> turns off some extra error checking that is turned on by default in many linux distros but borks the qt extended build process.
+
The <tt>-device neo</tt> is good for both Neo and FreeRunner. The <tt>_FORTIFY_SOURCE=0</tt> turns off some extra error checking that is turned on by default in many linux distros but borks the qt extended build process.
  
−
There's still something wrong which will cause errors. I don't know exactly what is wrong, but googled a fix. Find the file <tt>  
+
There's still something wrong which will cause errors. I don't know exactly what is wrong, but I googled a fix. Find the file <tt>  
 
qt-extended-4.4.1/devices/neo/configure-common</tt> and change the line:
 
qt-extended-4.4.1/devices/neo/configure-common</tt> and change the line:
  
 
  -add-modules pim
 
  -add-modules pim
−
to
+
to
 
  #-add-modules pim
 
  #-add-modules pim
 +
 +
<h2>Compiling an Example Qt Extended App</h2>
 +
 +
First set those indispensable Qt environment variables:
 +
 +
desktop# export QTOPIA_DEPOT_PATH=/opt/QtopiaSDK/qt-extended-4.4.2
 +
desktop# export QPEDIR=/opt/QtopiaSDK/build/qt-extended-4.4.2
 +
 +
Next create a directory <tt>/opt/Qtopia/build/myapps</tt>. Copy the example app. Rename the example app to something that makes sense (how about "example"!). Create the <tt>Makefile</tt> and build the example.
 +
 +
desktop# mkdir /opt/Qtopia/build/myapps
 +
desktop# cd /opt/Qtopia/build/myapps
 +
desktop# cp -R $QTOPIA_DEPOT_PATH/examples/application .
 +
desktop# mv application example
 +
desktop# cd example
 +
desktop# $QPEDIR/bin/qtopiamake
 +
Finding Projects...
 +
Writing 1 Makefiles...
 +
desktop# make
 +
make: running qbuild default
 +
uic /opt/QtopiaSDK/build/myapps/application/examplebase.ui
 +
moc /opt/QtopiaSDK/build/myapps/application/main.cpp
 +
moc /opt/QtopiaSDK/build/myapps/application/example.h
 +
arm-linux-g++ /opt/QtopiaSDK/build/myapps/application/.moc/moc_example.cpp
 +
arm-linux-g++ /opt/QtopiaSDK/build/myapps/application/main.cpp
 +
moc /opt/QtopiaSDK/build/myapps/application/example.cpp
 +
arm-linux-g++ /opt/QtopiaSDK/build/myapps/application/example.cpp
 +
arm-linux-g++ /opt/QtopiaSDK/build/myapps/application/example
 +
 +
Now you have an executable <tt>example</tt>. Of course, it won't execute on your workstation, you must secure copy it to your FreeRunner. Then secure shell into the FreeRunner, import the Qtopia environment variables and execute the app:
 +
 +
desktop# scp example root@freerunner:/home/rootroot@192.168.3.111's password:
 +
example                                      100%    33KB  33.4KB/s  00:00   
 +
desktop# ssh 192.168.3.111
 +
root@freerunner's password:
 +
freerunner:~# . /opt/Trolltech/Qtopia/qpe.env
 +
freerunner:~# ./example
 +
 +
You should see a message on FreeRunner's LCD.
 +
 +
[[Image:Qt_extended_sdk_example_screenshot.png]]
 +
 +
<h1>Creating up a Qtopia Feed</h1>
 +
 +
A qtopia feed is just a web directory containing package files and a packages.list file. I will assume that you already have a web server set up with <tt>DocumentRoot /var/www</tt>. The real trick is building packages and a packages.list file. As usual, we start by defining our environment variables.
 +
 +
desktop# export QTOPIA_DEPOT_PATH=/opt/QtopiaSDK/qt-extended-4.4.2
 +
desktop# export QPEDIR=/opt/QtopiaSDK/build/qt-extended-4.4.2
 +
desktop# export HTTPDIR=/var/www/neo
 +
desktop# mkdir /var/www/neo
 +
 +
We need another variable, HTTPDIR, to tell the tools where our feed will be located. And we need to make the directory. Next build the package for our example:
 +
 +
desktop# cd /opt/QtopiaSDK/build/myapps/example
 +
desktop# make packages
 +
desktop# /opt/QtopiaSDK/qt-extended-4.4.2/bin/mkPackages $HTTPDIR
 +
 +
Woohoo! That's it!
 +
 +
Now you can go to the Software Package setup tool and create a new feed. My feed's URL is [http://radagast.bglug.ca/neo http://radagast.bglug.ca/neo].
 +
 +
<h1>Old</h1>
 +
 +
<h2>Qt Extended 4.4.2 Install Instructions</h2>
 +
 +
Next download the kernel and rootfs to your workstation. Here's a link to the [http://other.lastnetwork.net/OpenMoko/qtextended-4.4.2-gta02-rootfs-release-working-with-SystemRingTones.jffs2 rootfs] created by Hypnotize. And here's the [http://qtextended.org/modules/mydownloads/visit.php?lid=91 mwebster flash image] containing the kernel. Boot your FreeRunner in dfu mode and use the dfu commands:
 +
 +
desktop# dfu-util -d 0x1d50:0x5119 -a kernel -R -D  uImage-gta02-mwester-stable-d6f9fd270943fb22.bin
 +
 +
    ... stuff ...
 +
 +
desktop# dfu-util -d 0x1d50:0x5119 -a rootfs -R -D  qtextended-4.4.2-gta02-rootfs-release-working-with-SystemRingTones.jffs2
 +
 +
    ... more stuff ...
 +
 +
<h3>Fix Echo Cancellation</h3>
 +
 +
<b>Note: Echo cancellation should be in the 4.4.3 build - this is old doc for version 4.4.2</b>
 +
 +
On his [http://www.csamuel.org/2009/01/08/echo-suppression-fix-for-qt-extended-442-on-openmoko-neo blog] Chris Samuel explained how to turn on echo cancellation for qt extended 4.4.2. First you need to download an updated [http://www.csamuel.org/wp-content/uploads/2009/01/libneovendor.so neo plugin]. Secure copy the libneovendor.so file to your Freerunner, then secure shell to the FreeRunner and do this:
 +
 +
freerunner# cd /opt/Trolltech/Qtopia/plugins/phonevendors/
 +
freerunner# mv libneovendor.so libneovendor.so.orig
 +
freerunner# mv /home/root/libneovendor.so .
 +
 +
The change should take effect immediately.
 +
 +
<h3>The White Screen of Death (WSOD)</h3>
 +
 +
<b>Note: WSOD is fixed in 4.4.3, this is old info for version 4.4.2</b>
 +
 +
Sometimes when Qt Extended recovers from suspend you see a bright white screen. You don't have a phone anymore - you have a flashlight. Hold the power button down for about five seconds to power down the phone, then power it back up.
 +
 +
<h1>Porting a command line debian app</h1>
 +
 +
First download the tarball. My example will be the <tt>at</tt> package. Unpacked it at <tt>/opt/QtExtended/build/at-3.1.10.2</tt>.
 +
 +
root# PATH=/opt/toolchains/arm920t-eabi/bin:$PATH ./configure --host=arm-angstrom-linux-gnueabi

Latest revision as of 03:16, 12 March 2009

Contents

Andrew's Total Newbie Guide

These are my collected instructions for getting various FreeRunner features to work. I don't know much about FreeRunner or coding, so please forgive the numerous mistakes.

Getting the Freerunner working as a Phone

date: Mar 2009

These guide is intended for people who just want to get their Freerunner working as a phone. I tried every distribution available in Jan 2009 and I will summarize my results for anyone who is interested.

Get a working SIM card

First, make sure that your SIM card works with the Freerunner. Go to the Carriers page, find your country and carrier, and check what people have said about their SIM cards. My original SIM card did not work (Canada/Rogers) but Rogers kindly replaced it with a supported SIM.

Install Qt Extended

The software that was on my FreeRunner when I received it was not functional as a phone. It wouldn't wake from suspend when it received a call. Sometimes it spontaneously rebooted. Often it just wouldn't turn on at all and I had to remove the battery. Fortunately there are many distributions available for the FreeRunner. This is one of the great things about open projects: you get to choose what software to run. The bad thing is that some choices are better than others for certain tasks, and it is not always clear what to use for each function. I have tested every distribution available in January 2009, and in my opinion the best distribution for using your Freerunner as a phone is Qt Extended, which is the Free version of Trolltech's QTopia (used on the Sharp Zaurus and some other devices).

You must download the Qt Extended kernel and rootfs and flash them to your Freerunner. First read throughFlashing_the_Neo_FreeRunner page. Whatever OS you use on your desktop/laptop, you will need the dfu command line utility to copy the kernel and rootfs to your Freerunner. For most of my coding work I use Mac OS X, but for FreeRunner hacking I find it much easier to reboot into Ubuntu.

Note: updated for Qt Extended 4.4.3. See the old section for qt extended 4.4.2 instructions

Next download the kernel and rootfs to your workstation. Here's a link to the rootfs created by Tomas Riveros Schober. And here's the kernel image. Boot your FreeRunner in dfu mode and use the dfu commands: 

desktop# dfu-util -d 0x1d50:0x5119 -a kernel -R -D  Neo_kernel_Backup_200902212230.bin

    ... stuff ...

desktop# dfu-util -d 0x1d50:0x5119 -a rootfs -R -D  Neo_rootfs_Backup_200902212230.jffs2

    ... more stuff ...

Qt Extended isn't Perfect

Echo Cancellation Patch

Echo cancellation should be in the 4.4.3 build

The White Screen of Death (WSOD)

WSOD is fixed in the 4.4.3 build

Official Documentation

The official documentation for Qt Extended is at Trolltech's website. But it is mostly about how to develop applications, it doesn't have much info on how to actually use qtopia.

Booting Qt Extended

Disconnect the USB cable before booting Qt Extended. Don't know why, but my FreeRunner often hangs if I boot with the USB cable plugged in.

Short Battery Life

My battery life is less than five hours which kinda sucks.

Adding New Media

Secure shell to the FreeRunner and create a Documents directory in /home/root. Then secure copy media files to /home/root/Documents. In Qt Extended use the File Manager to browse your Documents directory (might have to do a rescan from the options menu). If you have a working /media/card directory then you might be able to put files in there.

As far as I can tell, Qt Extended plays ogg, wav and some mp3. Note that some of my mp3 files played but others didn't. I converted all my mp3s to ogg using ogg2mp3 just to be safe.

Wireless networking

You must secure shell to your Freerunner to configure wireless networking. Fix the /etc/wpa_supplicant/wpa_supplicant.conf and /etc/network/interfaces files then use ifup eth0.

Networking

Changing the Default Route

Every time I connect the USB cable FreeRunner changes the default route to 192.168.0.200 interface usb0. Which is a pain in the butt, because I prefer to keep the wifi as my default gateway. I think this is caused by the line "gateway 192.168.0.200" in /etc/network/interfaces. The obvious fix is to remove that line. If you default route is buggered up, here are the instructions to change default route: 

freerunner# route delete default gateway 192.168.0.200
freerunner# route add default gateway 192.168.3.1

Qt Extended SDK

Introduction

It would be nice to write some custom apps. Also, there are Qtopia apps available on the interweb, but the binaries are all for Zaurus. It would be nice to compile them for FreeRunner.

There is a VMWare image of the SDK available for 4.3.2, but not for 4.4.2. So I have to compile the Qt Extended SDK from source. These instructions are based on Jim Morris' excellent article. I know that doing everything as root is a grave sin, but I'm too busy fixing bugs in the Qt Extended build to fiddle with permissions too.

My platform is a Macbook (Santa Rosa) running Ubuntu Intrepid.

Compiling the Qt Extended SDK

Download the SDK source and toolchain from qtextended.org. Change directory to your machine's root directory then untar the toolchain - it will install itself to /opt/toolchains. Next create /opt/QtopiaSDK/qt-extended-4.4.2 and /opt/QtopiaSDK/build directories. Unpack the Qt extended SDK source to /opt/QtopiaSDK/qt-extended-4.4.2. Set a pair of environment variables as follows: 

desktop# export QTOPIA_DEPOT_PATH=/opt/QtopiaSDK/qt-extended-4.4.2
desktop# export QPEDIR=/opt/QtopiaSDK/build/qt-extended-4.4.2

Next download a pair of patches from mwester's openmoko stuff: pkg-config-template.patch and qmemoryfile_unix_open_args.patch. Copy these to the qt-extended-4.4.2 source directory and execute these commands: 

desktop# patch -p1 < qmemoryfile_unix_open_args.patch
desktop# patch -p1 < pkg-config-template.patch

Now change directory to the build directory. Execute the following: 

desktop# cd $QPEDIR
desktop# $QTOPIA_DEPOT_PATH/configure -device neo -D _FORTIFY_SOURCE=0
desktop# make
desktop# make install

The -device neo is good for both Neo and FreeRunner. The _FORTIFY_SOURCE=0 turns off some extra error checking that is turned on by default in many linux distros but borks the qt extended build process.

There's still something wrong which will cause errors. I don't know exactly what is wrong, but I googled a fix. Find the file qt-extended-4.4.1/devices/neo/configure-common and change the line: 

-add-modules pim

to 

#-add-modules pim

Compiling an Example Qt Extended App

First set those indispensable Qt environment variables: 

desktop# export QTOPIA_DEPOT_PATH=/opt/QtopiaSDK/qt-extended-4.4.2
desktop# export QPEDIR=/opt/QtopiaSDK/build/qt-extended-4.4.2

Next create a directory /opt/Qtopia/build/myapps. Copy the example app. Rename the example app to something that makes sense (how about "example"!). Create the Makefile and build the example. 

desktop# mkdir /opt/Qtopia/build/myapps
desktop# cd /opt/Qtopia/build/myapps
desktop# cp -R $QTOPIA_DEPOT_PATH/examples/application .
desktop# mv application example
desktop# cd example
desktop# $QPEDIR/bin/qtopiamake
Finding Projects...
Writing 1 Makefiles...
desktop# make
make: running qbuild default
uic /opt/QtopiaSDK/build/myapps/application/examplebase.ui
moc /opt/QtopiaSDK/build/myapps/application/main.cpp
moc /opt/QtopiaSDK/build/myapps/application/example.h
arm-linux-g++ /opt/QtopiaSDK/build/myapps/application/.moc/moc_example.cpp
arm-linux-g++ /opt/QtopiaSDK/build/myapps/application/main.cpp
moc /opt/QtopiaSDK/build/myapps/application/example.cpp
arm-linux-g++ /opt/QtopiaSDK/build/myapps/application/example.cpp
arm-linux-g++ /opt/QtopiaSDK/build/myapps/application/example

Now you have an executable example. Of course, it won't execute on your workstation, you must secure copy it to your FreeRunner. Then secure shell into the FreeRunner, import the Qtopia environment variables and execute the app: 

desktop# scp example root@freerunner:/home/rootroot@192.168.3.111's password: 
example                                      100%    33KB  33.4KB/s   00:00    
desktop# ssh 192.168.3.111
root@freerunner's password: 
freerunner:~# . /opt/Trolltech/Qtopia/qpe.env 
freerunner:~# ./example

You should see a message on FreeRunner's LCD.

Qt extended sdk example screenshot.png

Creating up a Qtopia Feed

A qtopia feed is just a web directory containing package files and a packages.list file. I will assume that you already have a web server set up with DocumentRoot /var/www. The real trick is building packages and a packages.list file. As usual, we start by defining our environment variables. 

desktop# export QTOPIA_DEPOT_PATH=/opt/QtopiaSDK/qt-extended-4.4.2
desktop# export QPEDIR=/opt/QtopiaSDK/build/qt-extended-4.4.2
desktop# export HTTPDIR=/var/www/neo
desktop# mkdir /var/www/neo

We need another variable, HTTPDIR, to tell the tools where our feed will be located. And we need to make the directory. Next build the package for our example: 

desktop# cd /opt/QtopiaSDK/build/myapps/example
desktop# make packages
desktop# /opt/QtopiaSDK/qt-extended-4.4.2/bin/mkPackages $HTTPDIR

Woohoo! That's it!

Now you can go to the Software Package setup tool and create a new feed. My feed's URL is http://radagast.bglug.ca/neo.

Old

Qt Extended 4.4.2 Install Instructions

Next download the kernel and rootfs to your workstation. Here's a link to the rootfs created by Hypnotize. And here's the mwebster flash image containing the kernel. Boot your FreeRunner in dfu mode and use the dfu commands: 

desktop# dfu-util -d 0x1d50:0x5119 -a kernel -R -D  uImage-gta02-mwester-stable-d6f9fd270943fb22.bin

    ... stuff ...

desktop# dfu-util -d 0x1d50:0x5119 -a rootfs -R -D  qtextended-4.4.2-gta02-rootfs-release-working-with-SystemRingTones.jffs2

    ... more stuff ...

Fix Echo Cancellation

Note: Echo cancellation should be in the 4.4.3 build - this is old doc for version 4.4.2

On his blog Chris Samuel explained how to turn on echo cancellation for qt extended 4.4.2. First you need to download an updated neo plugin. Secure copy the libneovendor.so file to your Freerunner, then secure shell to the FreeRunner and do this: 

freerunner# cd /opt/Trolltech/Qtopia/plugins/phonevendors/
freerunner# mv libneovendor.so libneovendor.so.orig
freerunner# mv /home/root/libneovendor.so .

The change should take effect immediately.

The White Screen of Death (WSOD)

Note: WSOD is fixed in 4.4.3, this is old info for version 4.4.2

Sometimes when Qt Extended recovers from suspend you see a bright white screen. You don't have a phone anymore - you have a flashlight. Hold the power button down for about five seconds to power down the phone, then power it back up.

Porting a command line debian app

First download the tarball. My example will be the at package. Unpacked it at /opt/QtExtended/build/at-3.1.10.2. 

root# PATH=/opt/toolchains/arm920t-eabi/bin:$PATH ./configure --host=arm-angstrom-linux-gnueabi
Retrieved from "http://wiki.openmoko.org/index.php?title=User:Radagast&oldid=67617"
Personal tools

Total Newbie's Getting Started Guide

Introduction

This guide is intended for people who just want to get their Freerunner working as a phone. I tried every distribution available in Jan 2009 and I will summarize my results for anyone who is interested.

Getting the Freerunner working as a Phone

Get a working SIM card

First, make sure that your SIM card works with the Freerunner. Go to the Carriers page, find your country and carrier, and check what people have said about their SIM cards. My original SIM card did not work (Canada/Rogers) but Rogers kindly replaced it with a supported SIM.

Install Qt Extended

Next is your choice of distribution. The great thing about the Freerunner is that you have lots of choices. The bad thing is that some choices are better than others for certain tasks, and it is not always clear what to use for each function. I have tested every distribution available in January 2009, and in my opinion the best distribution for using your Freerunner as a phone is Qt Extended, which is the Free version of Trolltech's QTopia (used on the Sharp Zaurus and some other devices).

You must download the kernel and rootfs and flash them to your Freerunner. First read throughFlashing_the_Neo_FreeRunner page. Whatever OS you use on your desktop/laptop, you will need the dfu command line utility to copy the kernel and rootfs to your Freerunner. For most of my coding work I use Mac OS X, but for FreeRunner hacking I find it much easier to reboot into Ubuntu.

Next download the kernel and rootfs to your workstation. Here's a link to the rootfs created by Hypnotize. And here's the mwebster flash image containing the kernel. Boot your FreeRunner in dfu mode and use the dfu commands: 

bash# dfu-util -d 0x1d50:0x5119 -a kernel -R -D  uImage-gta02-mwester-stable-d6f9fd270943fb22.bin

    ... stuff ...

bash# dfu-util -d 0x1d50:0x5119 -a rootfs -R -D  qtextended-4.4.2-gta02-rootfs-release-working-with-SystemRingTones.jffs2

    ... more stuff ...

Qt Extended isn't Perfect

The White Screen of Death (WSOD)

Sometimes when Qt Extended recovers from suspend you see a bright white screen. You don't have a phone anymore - you have a flashlight. Hold the power button down for about five seconds to power down the phone, then power it back up.

Official Documentation

The official documentation for Qt Extended is at Trolltech's website. But it is mostly about how to develop applications, it doesn't have much info on how to actually use qtopia.

Booting Qt Extended

Disconnect the USB cable before booting Qt Extended. Don't know why, but my FreeRunner often hangs if I boot with the USB cable plugged in.

Adding New Media

Secure shell to the FreeRunner and create a Documents directory in /home/root. Then secure copy media files to /home/root/Documents. In Qt Extended use the File Manager to browse your Documents directory (might have to do a rescan from the options menu). If you have a working /media/card directory then you might be able to put files in there.

As far as I can tell, Qt Extended plays ogg, wav and some mp3. Note that some of my mp3 files would not play, so I converted them to ogg using ogg2mp3.

Wireless networking

You must secure shell to your Freerunner to configure wireless networking. Fix the /etc/wpa_supplicant/wpa_supplicant.conf and /etc/network/interfaces files then use ifup eth0.

Networking

Changing the Default Route

Every time I connect the USB cable FreeRunner changes the default route to 192.168.0.200 interface usb0. Which is a pain in the butt, because I prefer to keep the wifi as my default gateway. I think this is caused by the line "gateway 192.168.0.200" in /etc/network/interfaces. The obvious fix is to remove that line. Here are the to change default route:

bash# route delete default gateway 192.168.0.200 bash# route add default gateway 192.168.3.1

Compiling Qt Extended SDK

These instructions are based on Jim Morris' excellent article.

I downloaded the SDK source and toolchain from qtextended.org. Change directory to your machine's root directory then untar the toolchain - it will install itself to /opt/toolchains. Next create /opt/QtopiaSDK/qt-extended-4.4.2 and /opt/QtopiaSDK/build directories. Unpack the Qt extended SDK source to /opt/QtopiaSDK/qt-extended-4.4.2. Set a pair of environment variables as follows: 

bash# export QTOPIA_DEPOT_PATH=/opt/QtopiaSDK/qt-extended-4.4.2
bash# export QPEDIR=/opt/QtopiaSDK/build/qt-extended-4.4.2

Next download a pair of patches from mwester's openmoko stuff: pkg-config-template.patch and qmemoryfile_unix_open_args.patch. Copy these to the qt-extended-4.4.2 source directory and execute these commands: 

bash# patch -p1 < qmemoryfile_uniz_open_args.patch
bash# patch -p1 < pkg-config-template.patch

Now change directory to the build directory. Execute the following: 

bash# cd $QPEDIR
bash# $QTOPIA_DEPOT_PATH/configure -device neo -D _FORTIFY_SOURCE=0
bash# make
bash# make install

The _FORTIFY_SOURCE=0 turns off some extra error checking that is turned on by default in many linux distros but borks the qt extended build process.

There's still something wrong which will cause errors. I don't know exactly what is wrong, but googled a fix. Find the file qt-extended-4.4.1/devices/neo/configure-common and change the line: 

-add-modules pim
to
#-add-modules pim