Revision as of 22:03, 19 February 2009

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.