SHR Settings is the main setting application of SHR. In the background it uses [[FSO]] specific dbus calls as well as low level commands. The graphical interface is Elementary-Python based. It provides an easy way of setting up your phone to your liking - from phone related settings, to requesting resources in order to prevent screen dim or suspend (for example while using GPS).

SHR Settings is the main setting application of SHR. In the background it uses [[FSO]] specific dbus calls as well as low level commands. The graphical interface is Elementary-Python based. It provides an easy way of setting up your phone to your liking - from phone related settings, to requesting resources in order to prevent screen dim or suspend (for example while using GPS).

+

+

Please refer to [http://wiki.openmoko.org/wiki/FSO_Resources#Automatic_way this wiki page] about a better way to manage preventing screen dim or suspend.

SHR Introduction

Welcome to SHR, the world of community driven distribution for (not only) OpenmokoNeo phones.

SHR (Stable Hybrid Release) is here to provide you with Root FileSystem images that you can easily install onto your Freerunner to use as a daily phone. It's filled with prepackaged software that can be installed upon demand by users, it can also be used by developers as a base image for customized and flavored distribution or release. SHR unstable is a testing environment before software get stabilized and it is the main testing ground for FSO releases. SHR testing images (currently not available) provide as much stability as possible for day-to-day usage.

SHR has been evolving from a simple release of customized software into a full distribution. Therefore, in SHR you can choose from several different graphical toolkits (for example GTK or EFL), different phone managers (SHR or Zhone), web browsers and other programs.

The SHR Team is busy with system maintenance and software building so you can concentrate on programming, using and reporting bugs.

SHR Specific

At this point, there are some applications and procedures that are purely specific to SHR and would not run on another distribution. For example the phone applications (Dialer, Messages and Contacts) and SHR Settings depend heavily on the ophonekitd daemon.

As SHR is based on FSO, basically any application using FSO has a chance to run, should all required libraries be available.

Stability

While many people use SHR as their daily phone, there are still occasional glitches and issues. This hurts the most when GSM stops working but this happens less and less. We wish you to have the best experiences with SHR.

Installation

Getting SHR

First, determine which model of phone you have, the GTA01(neo1973) or the GTA02(FreeRunner).

You need to download two files for your version as above, kernel and root filesystem. Depending whether you will be installing into the internal NAND memory or on µSD card, you need to either get .jffs2 file for nand or .tar.gz file for µSD.

Installation on Flash

In order to install your SHR distribution directly to your Freerunner Flash memory (NAND), you need to get the desired filesystem file ( .jffs2 ) as described above and flash your device using the dfu-util tool.

Installation on µSD Card

Installing SHR on your µSD Card depends on the Bootloader you are using, uBoot or Qi.

In simply words, difference between both systems resides on how you must prepare your µSD Card and files you use to fill them:

If you use uBoot, you need to create two partitions. First partition, not so big, in FAT16 where you have to place the kernel file (uImage-om-gta02-latest.bin) and second partition in ext2 or ext3 where you have to uncompress the filesystem file (shr-image-om-gta02.tar.gz).

If you use Qi, you only need an ext2 partition into your µSD Card where you uncompress the filesystem image file (shr-image-om-gta02.tar.gz). In this case Qi Bootloader is going to look for the kernel image into the /boot directory for file named uImage-GTA02.bin .

SHR version

Should you ever later wonder what version of SHR you have actually installed, please run

cat /etc/shr-version

or check SHR Settings -> Other -> Image information

Running SHR

Booting

Press the power button shortly once to start the Freerunner. Booting splash screen will appear. First boot after new installation takes always a bit longer. Sometimes, it is recommended to reboot after this first boot, to make sure all packages got initialized properly.

SHR Boot Splash screen

Initial Setup

Initial setup

On the first boot, Setup is automatically initiated to walk the user through basic setup of the Enlightenment desktop environment. You are able to choose preferred language of the desktop environment, Illume SHR themed profile or select default menu (only one at the moment).

On the Add icon screen you can add icons for some application. If you add a terminal based application like mplayer, you will see an icon but no application running upon click, as it will run in the background.
Last screen allow settin up quick launch applications.

Theme profile

Menu

Add icons

Quick launch

SIM Auth

SIM Auth

SIM Pin is asked for upon start up.

First look

Desktop screen

Illume desktop is default home screen of the SHR desktop. Application files located in /usr/share/applications are displayed here. All applications are ran fullscreen and you can switch between them by using the Task switcher in the Top Shelve or by using the < left or right > arrows in the Top Shelve.

The Illume desktop can be easily customized - slide the Top Shelve down and tap the Settings icon (Wrench).

NOTE: TIP: for better access of the Settings icon, tap and hold the Settings icon, then drag it to the right.

Illume settings (the wrench) provides various options to alter the desktop environment. You can change sizes of elements, single or double click, wallpaper. To access all the various options, open Illume Settings and slide the visible icons to the left, to preview more options on the right hand side.

The little applets in the Top Shelve (for example Battery, GSM, Bluetooth etc.) are called Shelve gadgets and you can configure whether they are visible (on the front part of the top shelve) or hidden (you can access them by sliding the top shelve) through Illume Settings -> Display -> Shelve gadget.

Some screens are not resized properly to fit the Freerunner's display - for example the Wallpapper setting. This is a known bug already reported upstream.

Upon a missed call or an unread message there is a Notifier that presents a screen with button to run Messages or Phonelog application, or you can simply close the Notifier with the Top Shelve cross.

Post-Installation Script

After flashing your Openmoko Freerunner you can do some modification mentioned below in this manual. The shell commands are collected in a SHR post-installation that you can transfer to your Freerunner via scp and execute it with sh.
Please go through the script and check if the applications to be installed is that want you want. If do not understand, what is going on in the script, proceed with this manual and select every step manually. If understand the script it might save you some time:

Under the hood

SHR is based on linux kernel and Openembedded. XGlamo is providing X server environment and Illume (Enlightment window manager module for small devices) is providing comfortable finger controlled desktop environment. Under the hood of the pretty desktop there is FSO middleware talking to the GSM modem, GPS module as well as to the other bits of hardware. SHR ophonekitd daemon is run with X server start-up and it communicates with FSO via d-bus. SHR phone applications talk to ophonekitd and also to FSO so for example when you receive a phone call, the dialer is launched to provide a way of answering it. Dialer, Contacts and Messages applications are part of the SHR internal libframeworkd-phonegui-efl library, Phonelog is an extra application written in python-gtk.

First steps

Right after installation and first boot you might want to do a few initial steps:

Network Connection

Establish network connection and SSH into your Freerunner. The root account uses no password by default. You can establish connection either via USB to your desktop and enable NAT or you can connect through Wifi. If you use USB, some setup is required on the desktop side, please read USB_Networking. For Wifi, you can use Network Manager

GSM Network

Check if GSM is working correctly - observe the GSM gadget in the Top Shelve and see reported signal of your GSM operator. If GSM Gadget seems not be running, click Settings and later on Phone. Move GSM Antenna to On.

Audio: Volume

Check and set call volume - this is handled by alsa state files in /usr/share/shr/scenarii/ . To customize speaker volume edit /usr/share/shr/scenarii/gsmhandset.state and change control 4. Values between from 105 to 120 might be sufficient:

for area code it seems wise to use "179" here, though that's the GSM-network code, not the code of your geographical area.

area_code = 179

Alarm

The default alarm clock application elementary-alarm is not working properly. You may want to remove it and install working alarm application called ffalarms:

opkg remove -force-depends elementary-alarm
opkg install ffalarms

(obsolete as of 20090808 image. ffalarms is default)

Init opkg database

Initialize opkg database in order to install some applications from SHR repositories or from other sources, for example [opkg.org]. While still being online, you need to first run

opkg update

Searching in the opkg database can take a long time. You can speed things up by dumping the database into a file and grepping it through.

Do this only once or after every opkg update:

opkg list > packages.txt

Then you can search quickly for package name, for example for navit:

grep navit packages.txt

SwapSpace

The Freerunner has only 128mb ram, when this is used up applications get killed. This is particularly bad while doing opkg upgrade.

WARNING: this mights kill your sd card, since there might be a lot of read/writes to the same spot. (all recent tests failed to harm SDcards by torture write tests, so probably you just shouldn't worry)

dd if=/dev/zero of=/swapfile bs=1024 count=65536

Add a line to fstab so next time you boot there will be swap

echo "/swapfile swap swap defaults 0 0">> /etc/fstab

Make swap

mkswap /swapfile

Make the swap file work now:

swapon /swapfile

Changing root password

SHR is shipped without root password (just press enter)

This is very dangerous if you connect using wifi, or USB. You need to activate the root password:

passwd

then type your selected password (2 times)

A much more convenient way might be to install your public-key to ~/.ssh/known_hosts. For running

ssh root@neo anycommand

from your host this might be even mandatory, e.g if you want to pipe anything to the ssh.

Locate lost phone by GPS

To locate your freerunner in case of lost or theft by getting SMS with GPS location install sms-sentry:

opkg install sms-sentry

Then, upon sending an sms with text sentry:location to your Freerunner, the phone will turn on GPS, wait for a fix and send back sms with current location.

openBmap is a project with the objective to collect GPS location of GSM network cells. If this project is finished then sms-sentry could send the a rough GPS location just by identifying the current distances (strength of signal) to the available GSM network cells, even when the GPS satellites are not available (e.g. in a house).

Localization

Setting Language

You can change the language of the SHR desktop environment by using the Settings of Illume. For Example, for Czech language: in Illume Top Shelve go to Wrench (Settings) -> Language -> Language Settings -> and choose: Čeština. If your language is not in the menu you can install by using opkg.

You can list all available languages by running:

opkg list | grep glibc-locale-

And install the language of your choice (for example czech):

opkg install glibc-locale-cs

After this, the Language Settings of Illume will offer Czech.

This will localize the Illume environment and will also set correct lang environment variable. If you wish to have translations for other applications, you need to install them again (presuming they are available):

This will install czech localisation for SHR phone applications, SHR Settings and TangoGps:

The Illume keyboard offers english dictionary correction by default. You can list all the dictionaries available for installation:

opkg list | grep illume-dic

If your language is not available and english is bothering you, you can set an empty dictionary:

echo "" > /usr/lib/enlightenment/modules/illume/dicts/None.dic

By using it, it will get filled by the words you use and after time will start helping and correcting your typing.

Date and time

Timezone is automatically retrieved from the GSM network. Date and time are automatically set from GPS or Network. The easiest way of setting the time for the first time is to run TangoGps (GPS & Map icon) and obtaining GPS fix. Time will then be set automatically after several minutes.

Time can set time also manually.

Via SHR-Settings -> Date/time -> Set time

From linux based desktop:

ssh root@192.168.0.202 "date -u -s `date -u +%m%d%H%M%Y.%S`"

You can also set the hardware clock to the system time:

hwclock --systohc

It is possible to instruct framework on how to set the time and timezone in /etc/frameworkd.conf :

File transfer

After you have established network connection, it is very easy to access and transfer files. The easiest solution is to use Konqueror or Nautilus on your desktop computer and type the following on your location bar. This should provide you with a view of the client's file system on Konqueror or Nautilus and you can easily drag-drop and copy-paste files.

sftp://root@192.168.0.202

Data synchronization

PISI Contact Sync

PISI Calendar Sync

You can synchronize your contacts and appointments data with various sources. The sync can by done by program called PISI . SIM contacts and calendar entries are currently possible to sync on SHR. You can also synchronize OPIMD contacts, these data are however so far no used in the current shr phone applications, but are used by for example Litephone.

Check if the bug is already reported. If no, add a ticket, be as much precise as you can in the title and the description, in what circumstances the issue happened and so on.

Car Navigation

Navit is a car navigation system with routing engine. It can calculate a route and do on screen and voice road navigation. Maps need to be downloaded beforehand, please check Navit website. You can get Openstreetmaps through Navit map extractor, after you download the map it needs to be specified in the .navit/navit.xml file.

Add opkg feed

To install navit as a car navigation system on your freerunner you have to add the feed for the installer opkg

Install Maps

mark a rectangle for your map (e.g. for Germany) and click select the rectanglular map.

Download OpenStreetMaps

then click on download and save the file to country.bin (e.g. germany.bin) on your desktop computer.

copy the file to on your freerunner. Because of the size of the maps you copy map to the Micro-SD card on your freerunner. Create a directory for the maps and copy the files from desktop to freerunner:

Start Navit

No sound after installing Navit

Navit tends to depend on speech-dispatcher and after a suspend, the freerunner does not ring anymore for incoming calls or messages, it only vibrates. To correct this remove speech-dispatcher:

opkg remove -force-depends speech-dispatcher

SHR Settings

SHR Settings

SHR Settings is the main setting application of SHR. In the background it uses FSO specific dbus calls as well as low level commands. The graphical interface is Elementary-Python based. It provides an easy way of setting up your phone to your liking - from phone related settings, to requesting resources in order to prevent screen dim or suspend (for example while using GPS).

Please refer to this wiki page about a better way to manage preventing screen dim or suspend.

While some settings are persistent over reboots, other are not.

Main Screen

Main screen is divided into few categories, which contain modules. Every SHR Settings module has specified task - control GSM antenna power, set actual time etc.

Settings: Phone

Here you can check if the GSM antenna is on and if your phone number is shown when you call someone.

GSM
In GSM settings you can turn off and on GSM module. After turning off antenna, whole GSM modem is turned off.

To list available providers, click on Operators button. Scanning can take some time. After while, list of operators should pop up.

You can't connect to operators marked [forbidden]. After failed connect, message is displayed.

Selecting operator from list also changes modem registration mode to manual. It won't register to other network, even if some is available and has better signal strengh. To return to automatic mode, click "Automatic" button in operator list.

Call

Phone settings

List providers

You can set if your phone number should be displayed to other party. You can either depend on network decision ("By network") or force it manually ("Manual")

SIM

Here you can view some informations about your SIM card and clean phone and messagebooks.

Others

Profile

Here you can select current profile, which device should use to determine ring tone etc.

After selecting sid tune as ring tone, there are available controls to select tune number from file.

This is changing settings in /etc/freesmartphone/opreferences/conf/phone/default.yaml

ring-volume # Ring Volume control 0 (mini) to ? maxi)
ring-length # min time for ringtone. Must be greater than the duration of you ringtone
ring-loop # define the number of loop of ringtone to play
ring-tone: "ringtone_ringnroll.ogg" # .ogg example
ring-tone: "Arkanoid_PSID.sid" # .sid example, use default tune
ring-tone: "Arkanoid_PSID.sid;tune=2" # .sid example, plays the second tune of that

If you like to test a .sid you can play it using this command on the FR:

Note that it's a ! used and not a | to construct the gstreamer pipe command.

Profiles

Ringtones

Settings: Connectivity

Connectivity top

Connectivity bottom

WiFi

With "WiFi radio" toggle you can set, if wifi module should be powered. WiFi radio has to be turned on before trying to connect to WiFi network, unless you try to connect through Mokonnect which is capable of powering it up.

To connect to GPRS network, just click "Connect" button. Entered values will be saved after successful connection.

USB

With this toggle you can switch USB port between device (Neo to PC) or host (device to Neo) modes.

Bluetooth

To power up Bluetooth module, swith "Bluetooth radio" toggle to "On". After that, "Visibility" toggle should arrive - set it to "On" if you want your FR to be visible by other Bluetooth devices on scanning.

Settings: GPS

GPS

GPS Satelite details

GPS

By default, GPS is turned on only when requested (when you turn on TangoGPS, Navit, omgps or other GPS app). That state corresponds to "Auto" setting. After changing to "Manual", you can force set it to on or off.

GPS information

This page can be used to monitor GPS status. If some value isn't known, then "unknown" is displayed.

You can also view information about every visible satellite and check, which are used for getting fix. To do that, just click "Satellite details".

NOTE: This setting isn't permanent over sessions. At boot backlight is set back to 100%.

Power

Power

Timeouts

Here you can turn on or off automatic dimming or suspend after idle timeout (see: Timeouts module)

Timeouts

Here you can set up values of idle timeouts used by device. Timeouts are reached in this order: idle -> idle dim -> idle prelock -> lock -> suspend. Idle, idle prelock and lock aren't used by default in SHR at the moment. This setting changes parameters in /etc/frameworkd.conf :

Settings: Services

After clicking on some, you can either start, restart or stop service and view result.

Settings: Others

Others

Splash preview

Splash

With this selector you can select theme used by shr-splash at boot and shutdown. After clicking "Preview", selected boot image will be displayed for 5 seconds.

PIM

Module used by opimd developers. Doesn't have influence on behaviour of default SHR image.

Every opimd domain has different backends to store it's data. The domain reads data from every backend and writes data to the default backend. So with the selector in shr-settings you can choose the backend that stores newly generated data, it doesn't copy or move existing data to a different backend.

Userspace backups

Here you can either archive or restore your files and configurations.

Image information

This module contains basic information about installed image - name of buildhost, used revision, branch and time of build.

FSO Resources

FSO is in control of each device. These are called resources. If the software wanting to use the device is capable of requesting this resource via d-bus, FSO will do this, otherwise you might need to power the device manually. After the requested resource is released, FSO will power it down. Manual resource request can be done through SHR Setting or you can use fsoraw command. (Using fsoraw is faster and better then running dbus commands)

Unless this resource is enabled you've no eth0 and wifi module is completely un-powered. Use the network manager to set up networks, Mokonnect will power Wifi up automatically when needed.

Bluetooth

You need to have this resource requested to have bluetooth module powered.

GPS

The fso-gpsd is a daemon waiting for gsmd connections, automatically powering the device on and off. When a connection exists, it powers up the GSM. In SHR Settings you can switch GPS completely off SHR Settings -> GPS -> Manual > Off

GSM

You need to have this resource requested to have GSM module powered.

Display

While this resource is requested the display won't be blanked and suspend is disabled.

CPU

Default rules.yaml checks for this resource to disable automatic suspend when it's requested. While this resource is kept suspend is disabled (but screen can be blanked).

Test

A test resource

Network manager

While there are several ways of networking - Wifi, USB, Bluetooth and Gprs - By default, USB networking is enabled in /etc/network/interfaces.

Enhanced configuration is possible through direct editing of /etc/network/interfaces or through Mokonnect.

The connmand daemon with Mokonnect are the recommended user level applications for setting up networking. At the moment, Mokonnect can manage USB, Wifi and Gprs connections, as well as routing and NAT. Wifi device is not required to be manually turned on via SHR-Settings as Mokonnect will automatically enable the device when needed and disable after use.

Mokonnect

Mokonnect Wifi

Mokonnect Wifi Scan

Bluetooth

Bluetooth can be used for several different applications - file transfer, networking, HIDD, music playing (A2DP), calling etc. In some occasions, the devices need to be authorized - paired. At the moment, support for some bluetooth functions is better then for others - it is possible to do all mentioned above with the notice that phone calls with bluetooth headset are always routed to the bluetooth even if it is not around, making it quite difficult to use.

Don't forget you need to turn the bluetooth radio on in SHR Settings -> Connectivity -> Bluetooth Radio: On, where you can also make the bluetooth device visible.

SHR user bluez4 which completely different from bluez3. The bluetoothd is taking care of most of the bluetooth now. Please see Manually using Bluetooth for detailed information about using bluetooth and also for list of supported devices.

OBEX file transfer

There are several obex programs allowing file transfer, all in console at the moment. Obexpush installs obextool, and opd daemon:

Connect Bluetooth keyboard

Pairing

Now, you must pair the bluetooth headset with your Freerunner. Make sure the bluetooth chip is powered up (can be done through the Connectivity section in the SHR-Unstable settings manager) and that bluetoothd is running:

Additionally in the SHR-Unstable repositories there are theme packages optimized for 16bpp color. Both packages can be installed with the following command:

opkg install e-wm-theme-illume-sixteen elementary-theme-sixteen

You can then append the /etc/profile.d/set-elm-engine.sh with:

# Set Optimized theme
export ELM_THEME=sixteen

You can also then change Illume to use the sixteen theme by clicking the wrench->Look->Theme-illume-sixteen->OK. Then switch Illume to use the 16bpp Engine by clicking the wrench->Advanced(you will need to drag and slide the top menu)->Engine->Software_16->OK. This should give you a much faster interface without the low quality look the default SHR themes have at this lower color depth.

If you try to change Wallpaper or Theme and Illume keeps on crashing, it might be caused by the whole Illume running in Software_16 mode. Go to Illume Settings, slide the icon bar and select Advanced. There tap on Engine and select Software. After this, you can change your Wallpaper or Theme. Selecting Software_16 later on again will speed up the desktop's response (though causing it to be a bit uglier).

Speedup of suspend and wake up

I you are using Qi and installation on µSD card, you can change the kernel parameter loglevel=1 1 in /boot/append-GTA02 . For u-boot and installation in nand just type

klogd -c 1

into the console. This saves you from 3 seconds worth of console output on every resume.

If you like the effect of this command and want it to be executed at every startup, you just have to log into your phone and type the following:

Random errors

No icons, no GSM functions etc. - this is mostly due to errors on your µSD card. Remove your card and fix it in card reader or by booting to another partition (nand) or by reboot and mount read only, then run fsck.

You will get disconnected from the ssh session, wait until keys get generated and log in again.

NOTE:Remove old SSH Key from .ssh/known_hosts: On your Linux box you will find a file known_host in the subdirectory .ssh/ in you home directory. This contains a ssh key for the connection to your freerunner. If new keys are generated or if you flash your Freerunner with SHR then you have to remove the line with openmoko or the IP-address of your Freerunner from the file. Otherwise you might be able to login in again.

Installing Software

If you wan to use opkg after you used the installer, make sure packagekitd is not running

killall packagekitd

Cool applications

SHR comes with only few preinstalled applications but it's repository provides more cool stuff. Also, there are applications that are not in SHR repos at the moment but can still be installed. The following few examples are here just to spark your interest:

SHR Launcher

SHR Launcher

Launcher is elementary based alternative home screen application and event notifier for SHR. It displays current time, has a user tweak-able launcher with categories and features missed calls and messages applets.

GPE contacts saves the contacts in a SQLite database that can be synchronized with VCard files. Gpe-contacts don't allow you to dial directly via shr-dialer. Install gpe-contacts:

opkg install gpe-contacts

After installation you'll find to icons with MyVCard. If you want to remove it, delete the file /usr/share/applications/edit-vcard.desktop

Litephone

Litephone

Litephone is new alternative set of phone applications written in Qt. In it's single application interface it provides basic phone functionality (contacts, calls, messages, phone log, settings). It's main advantage is that it uses opimd for storage of the user data.

Mokomaze is an excelent eye-candy game using accelerators embedded in your device.

opkg install mokomaze

If you tweak the exec procedure in /usr/share/applications/mokomaze.desktop into this:

fsoraw -r Display mokomaze

the screen will not blank while playing.

Cellhunter is a game to collect information about mobile phone cells. This information can later be used to roughly determine your position without powering on the GPS chip. CellHunter homepage

opkg install cellhunter

OMGps and TangoGPS are GPS application showing you your position on a map (Openstreetmap, Google maps etc.). You can track your position, save it and use later, save and view points of interest, images or measure your trip. OMGps allows you to overlay different maps on top of each other, set GPS into different modes (walking, car, flying). Maps are downloaded online and used even in offline.

TangoGPS

C

OMGps

Mokomaze

Screenshots can be made with gpe-scap (available by default in SHR full image). To take a screenshot, run gpe-scan from shell while connected in via ssh.

Literki is full qwerty keyboard with configurable layout, always transparent, therefore applications don't need to redraw screens and popup is therefore very fast. The keys are big enough for everyday use with your fat fingers. To pop up the keyboard: slide your finger upwards from the bottom right corner. To hide the keyboard: slide your finger down on the keyboard. Opkg page

SHR Introduction

Welcome to SHR, the world of community driven distribution for (not only) OpenmokoNeo phones.

SHR (Stable Hybrid Release) is here to provide you with Root FileSystem images that you can easily install onto your Freerunner to use as a daily phone. It's filled with prepackaged software that can be installed upon demand by users, it can also be used by developers as a base image for customized and flavored distribution or release. SHR unstable is a testing environment before software get stabilized and it is the main testing ground for FSO releases. SHR testing images (currently not available) provide as much stability as possible for day-to-day usage.

SHR has been evolving from a simple release of customized software into a full distribution. Therefore, in SHR you can choose from several different graphical toolkits (for example GTK or EFL), different phone managers (SHR or Zhone), web browsers and other programs.

The SHR Team is busy with system maintenance and software building so you can concentrate on programming, using and reporting bugs.

SHR Specific

At this point, there are some applications and procedures that are purely specific to SHR and would not run on another distribution. For example the phone applications (Dialer, Messages and Contacts) and SHR Settings depend heavily on the ophonekitd daemon.

As SHR is based on FSO, basically any application using FSO has a chance to run, should all required libraries be available.

Stability

While many people use SHR as their daily phone, there are still occasional glitches and issues. This hurts the most when GSM stops working but this happens less and less. We wish you to have the best experiences with SHR.

Installation

Getting SHR

First, determine which model of phone you have, the GTA01(neo1973) or the GTA02(FreeRunner).

You need to download two files for your version as above, kernel and root filesystem. Depending whether you will be installing into the internal NAND memory or on µSD card, you need to either get .jffs2 file for nand or .tar.gz file for µSD.

Installation on Flash

In order to install your SHR distribution directly to your Freerunner Flash memory (NAND), you need to get the desired filesystem file ( .jffs2 ) as described above and flash your device using the dfu-util tool.

Installation on µSD Card

Installing SHR on your µSD Card depends on the Bootloader you are using, uBoot or Qi.

In simply words, difference between both systems resides on how you must prepare your µSD Card and files you use to fill them:

If you use uBoot, you need to create two partitions. First partition, not so big, in FAT16 where you have to place the kernel file (uImage-om-gta02-latest.bin) and second partition in ext2 or ext3 where you have to uncompress the filesystem file (shr-image-om-gta02.tar.gz).

If you use Qi, you only need an ext2 partition into your µSD Card where you uncompress the filesystem image file (shr-image-om-gta02.tar.gz). In this case Qi Bootloader is going to look for the kernel image into the /boot directory for file named uImage-GTA02.bin .

SHR version

Should you ever later wonder what version of SHR you have actually installed, please run

cat /etc/shr-version

or check SHR Settings -> Other -> Image information

Running SHR

Booting

Press the power button shortly once to start the Freerunner. Booting splash screen will appear. First boot after new installation takes always a bit longer. Sometimes, it is recommended to reboot after this first boot, to make sure all packages got initialized properly.

SHR Boot Splash screen

Initial Setup

Initial setup

On the first boot, Setup is automatically initiated to walk the user through basic setup of the Enlightenment desktop environment. You are able to choose preferred language of the desktop environment, Illume SHR themed profile or select default menu (only one at the moment).

On the Add icon screen you can add icons for some application. If you add a terminal based application like mplayer, you will see an icon but no application running upon click, as it will run in the background.
Last screen allow settin up quick launch applications.

Theme profile

Menu

Add icons

Quick launch

SIM Auth

SIM Auth

SIM Pin is asked for upon start up.

First look

Desktop screen

Illume desktop is default home screen of the SHR desktop. Application files located in /usr/share/applications are displayed here. All applications are ran fullscreen and you can switch between them by using the Task switcher in the Top Shelve or by using the < left or right > arrows in the Top Shelve.

The Illume desktop can be easily customized - slide the Top Shelve down and tap the Settings icon (Wrench).

NOTE: TIP: for better access of the Settings icon, tap and hold the Settings icon, then drag it to the right.

Illume settings (the wrench) provides various options to alter the desktop environment. You can change sizes of elements, single or double click, wallpaper. To access all the various options, open Illume Settings and slide the visible icons to the left, to preview more options on the right hand side.

The little applets in the Top Shelve (for example Battery, GSM, Bluetooth etc.) are called Shelve gadgets and you can configure whether they are visible (on the front part of the top shelve) or hidden (you can access them by sliding the top shelve) through Illume Settings -> Display -> Shelve gadget.

Some screens are not resized properly to fit the Freerunner's display - for example the Wallpapper setting. This is a known bug already reported upstream.

Upon a missed call or an unread message there is a Notifier that presents a screen with button to run Messages or Phonelog application, or you can simply close the Notifier with the Top Shelve cross.

Post-Installation Script

After flashing your Openmoko Freerunner you can do some modification mentioned below in this manual. The shell commands are collected in a SHR post-installation that you can transfer to your Freerunner via scp and execute it with sh.
Please go through the script and check if the applications to be installed is that want you want. If do not understand, what is going on in the script, proceed with this manual and select every step manually. If understand the script it might save you some time:

Under the hood

SHR is based on linux kernel and Openembedded. XGlamo is providing X server environment and Illume (Enlightment window manager module for small devices) is providing comfortable finger controlled desktop environment. Under the hood of the pretty desktop there is FSO middleware talking to the GSM modem, GPS module as well as to the other bits of hardware. SHR ophonekitd daemon is run with X server start-up and it communicates with FSO via d-bus. SHR phone applications talk to ophonekitd and also to FSO so for example when you receive a phone call, the dialer is launched to provide a way of answering it. Dialer, Contacts and Messages applications are part of the SHR internal libframeworkd-phonegui-efl library, Phonelog is an extra application written in python-gtk.

First steps

Right after installation and first boot you might want to do a few initial steps:

Network Connection

Establish network connection and SSH into your Freerunner. The root account uses no password by default. You can establish connection either via USB to your desktop and enable NAT or you can connect through Wifi. If you use USB, some setup is required on the desktop side, please read USB_Networking. For Wifi, you can use Network Manager

GSM Network

Check if GSM is working correctly - observe the GSM gadget in the Top Shelve and see reported signal of your GSM operator. If GSM Gadget seems not be running, click Settings and later on Phone. Move GSM Antenna to On.

Audio: Volume

Check and set call volume - this is handled by alsa state files in /usr/share/shr/scenarii/ . To customize speaker volume edit /usr/share/shr/scenarii/gsmhandset.state and change control 4. Values between from 105 to 120 might be sufficient:

for area code it seems wise to use "179" here, though that's the GSM-network code, not the code of your geographical area.

area_code = 179

Alarm

The default alarm clock application elementary-alarm is not working properly. You may want to remove it and install working alarm application called ffalarms:

opkg remove -force-depends elementary-alarm
opkg install ffalarms

(obsolete as of 20090808 image. ffalarms is default)

Init opkg database

Initialize opkg database in order to install some applications from SHR repositories or from other sources, for example [opkg.org]. While still being online, you need to first run

opkg update

Searching in the opkg database can take a long time. You can speed things up by dumping the database into a file and grepping it through.

Do this only once or after every opkg update:

opkg list > packages.txt

Then you can search quickly for package name, for example for navit:

grep navit packages.txt

SwapSpace

The Freerunner has only 128mb ram, when this is used up applications get killed. This is particularly bad while doing opkg upgrade.

WARNING: this mights kill your sd card, since there might be a lot of read/writes to the same spot. (all recent tests failed to harm SDcards by torture write tests, so probably you just shouldn't worry)

dd if=/dev/zero of=/swapfile bs=1024 count=65536

Add a line to fstab so next time you boot there will be swap

echo "/swapfile swap swap defaults 0 0">> /etc/fstab

Make swap

mkswap /swapfile

Make the swap file work now:

swapon /swapfile

Changing root password

SHR is shipped without root password (just press enter)

This is very dangerous if you connect using wifi, or USB. You need to activate the root password:

passwd

then type your selected password (2 times)

A much more convenient way might be to install your public-key to ~/.ssh/known_hosts. For running

ssh root@neo anycommand

from your host this might be even mandatory, e.g if you want to pipe anything to the ssh.

Locate lost phone by GPS

To locate your freerunner in case of lost or theft by getting SMS with GPS location install sms-sentry:

opkg install sms-sentry

Then, upon sending an sms with text sentry:location to your Freerunner, the phone will turn on GPS, wait for a fix and send back sms with current location.

openBmap is a project with the objective to collect GPS location of GSM network cells. If this project is finished then sms-sentry could send the a rough GPS location just by identifying the current distances (strength of signal) to the available GSM network cells, even when the GPS satellites are not available (e.g. in a house).

Localization

Setting Language

You can change the language of the SHR desktop environment by using the Settings of Illume. For Example, for Czech language: in Illume Top Shelve go to Wrench (Settings) -> Language -> Language Settings -> and choose: Čeština. If your language is not in the menu you can install by using opkg.

You can list all available languages by running:

opkg list | grep glibc-locale-

And install the language of your choice (for example czech):

opkg install glibc-locale-cs

After this, the Language Settings of Illume will offer Czech.

This will localize the Illume environment and will also set correct lang environment variable. If you wish to have translations for other applications, you need to install them again (presuming they are available):

This will install czech localisation for SHR phone applications, SHR Settings and TangoGps:

The Illume keyboard offers english dictionary correction by default. You can list all the dictionaries available for installation:

opkg list | grep illume-dic

If your language is not available and english is bothering you, you can set an empty dictionary:

echo "" > /usr/lib/enlightenment/modules/illume/dicts/None.dic

By using it, it will get filled by the words you use and after time will start helping and correcting your typing.

Date and time

Timezone is automatically retrieved from the GSM network. Date and time are automatically set from GPS or Network. The easiest way of setting the time for the first time is to run TangoGps (GPS & Map icon) and obtaining GPS fix. Time will then be set automatically after several minutes.

Time can set time also manually.

Via SHR-Settings -> Date/time -> Set time

From linux based desktop:

ssh root@192.168.0.202 "date -u -s `date -u +%m%d%H%M%Y.%S`"

You can also set the hardware clock to the system time:

hwclock --systohc

It is possible to instruct framework on how to set the time and timezone in /etc/frameworkd.conf :

File transfer

After you have established network connection, it is very easy to access and transfer files. The easiest solution is to use Konqueror or Nautilus on your desktop computer and type the following on your location bar. This should provide you with a view of the client's file system on Konqueror or Nautilus and you can easily drag-drop and copy-paste files.

sftp://root@192.168.0.202

Data synchronization

PISI Contact Sync

PISI Calendar Sync

You can synchronize your contacts and appointments data with various sources. The sync can by done by program called PISI . SIM contacts and calendar entries are currently possible to sync on SHR. You can also synchronize OPIMD contacts, these data are however so far no used in the current shr phone applications, but are used by for example Litephone.

Check if the bug is already reported. If no, add a ticket, be as much precise as you can in the title and the description, in what circumstances the issue happened and so on.

Car Navigation

Navit is a car navigation system with routing engine. It can calculate a route and do on screen and voice road navigation. Maps need to be downloaded beforehand, please check Navit website. You can get Openstreetmaps through Navit map extractor, after you download the map it needs to be specified in the .navit/navit.xml file.

Add opkg feed

To install navit as a car navigation system on your freerunner you have to add the feed for the installer opkg

Install Maps

mark a rectangle for your map (e.g. for Germany) and click select the rectanglular map.

Download OpenStreetMaps

then click on download and save the file to country.bin (e.g. germany.bin) on your desktop computer.

copy the file to on your freerunner. Because of the size of the maps you copy map to the Micro-SD card on your freerunner. Create a directory for the maps and copy the files from desktop to freerunner:

Start Navit

No sound after installing Navit

Navit tends to depend on speech-dispatcher and after a suspend, the freerunner does not ring anymore for incoming calls or messages, it only vibrates. To correct this remove speech-dispatcher:

opkg remove -force-depends speech-dispatcher

SHR Settings

SHR Settings

SHR Settings is the main setting application of SHR. In the background it uses FSO specific dbus calls as well as low level commands. The graphical interface is Elementary-Python based. It provides an easy way of setting up your phone to your liking - from phone related settings, to requesting resources in order to prevent screen dim or suspend (for example while using GPS).

Please refer to this wiki page about a better way to manage preventing screen dim or suspend.

While some settings are persistent over reboots, other are not.

Main Screen

Main screen is divided into few categories, which contain modules. Every SHR Settings module has specified task - control GSM antenna power, set actual time etc.

Settings: Phone

Here you can check if the GSM antenna is on and if your phone number is shown when you call someone.

GSM
In GSM settings you can turn off and on GSM module. After turning off antenna, whole GSM modem is turned off.

To list available providers, click on Operators button. Scanning can take some time. After while, list of operators should pop up.

You can't connect to operators marked [forbidden]. After failed connect, message is displayed.

Selecting operator from list also changes modem registration mode to manual. It won't register to other network, even if some is available and has better signal strengh. To return to automatic mode, click "Automatic" button in operator list.

Call

Phone settings

List providers

You can set if your phone number should be displayed to other party. You can either depend on network decision ("By network") or force it manually ("Manual")

SIM

Here you can view some informations about your SIM card and clean phone and messagebooks.

Others

Profile

Here you can select current profile, which device should use to determine ring tone etc.

After selecting sid tune as ring tone, there are available controls to select tune number from file.

This is changing settings in /etc/freesmartphone/opreferences/conf/phone/default.yaml

ring-volume # Ring Volume control 0 (mini) to ? maxi)
ring-length # min time for ringtone. Must be greater than the duration of you ringtone
ring-loop # define the number of loop of ringtone to play
ring-tone: "ringtone_ringnroll.ogg" # .ogg example
ring-tone: "Arkanoid_PSID.sid" # .sid example, use default tune
ring-tone: "Arkanoid_PSID.sid;tune=2" # .sid example, plays the second tune of that

If you like to test a .sid you can play it using this command on the FR:

Note that it's a ! used and not a | to construct the gstreamer pipe command.

Profiles

Ringtones

Settings: Connectivity

Connectivity top

Connectivity bottom

WiFi

With "WiFi radio" toggle you can set, if wifi module should be powered. WiFi radio has to be turned on before trying to connect to WiFi network, unless you try to connect through Mokonnect which is capable of powering it up.

To connect to GPRS network, just click "Connect" button. Entered values will be saved after successful connection.

USB

With this toggle you can switch USB port between device (Neo to PC) or host (device to Neo) modes.

Bluetooth

To power up Bluetooth module, swith "Bluetooth radio" toggle to "On". After that, "Visibility" toggle should arrive - set it to "On" if you want your FR to be visible by other Bluetooth devices on scanning.

Settings: GPS

GPS

GPS Satelite details

GPS

By default, GPS is turned on only when requested (when you turn on TangoGPS, Navit, omgps or other GPS app). That state corresponds to "Auto" setting. After changing to "Manual", you can force set it to on or off.

GPS information

This page can be used to monitor GPS status. If some value isn't known, then "unknown" is displayed.

You can also view information about every visible satellite and check, which are used for getting fix. To do that, just click "Satellite details".

NOTE: This setting isn't permanent over sessions. At boot backlight is set back to 100%.

Power

Power

Timeouts

Here you can turn on or off automatic dimming or suspend after idle timeout (see: Timeouts module)

Timeouts

Here you can set up values of idle timeouts used by device. Timeouts are reached in this order: idle -> idle dim -> idle prelock -> lock -> suspend. Idle, idle prelock and lock aren't used by default in SHR at the moment. This setting changes parameters in /etc/frameworkd.conf :

Settings: Services

After clicking on some, you can either start, restart or stop service and view result.

Settings: Others

Others

Splash preview

Splash

With this selector you can select theme used by shr-splash at boot and shutdown. After clicking "Preview", selected boot image will be displayed for 5 seconds.

PIM

Module used by opimd developers. Doesn't have influence on behaviour of default SHR image.

Every opimd domain has different backends to store it's data. The domain reads data from every backend and writes data to the default backend. So with the selector in shr-settings you can choose the backend that stores newly generated data, it doesn't copy or move existing data to a different backend.

Userspace backups

Here you can either archive or restore your files and configurations.

Image information

This module contains basic information about installed image - name of buildhost, used revision, branch and time of build.

FSO Resources

FSO is in control of each device. These are called resources. If the software wanting to use the device is capable of requesting this resource via d-bus, FSO will do this, otherwise you might need to power the device manually. After the requested resource is released, FSO will power it down. Manual resource request can be done through SHR Setting or you can use fsoraw command. (Using fsoraw is faster and better then running dbus commands)

Unless this resource is enabled you've no eth0 and wifi module is completely un-powered. Use the network manager to set up networks, Mokonnect will power Wifi up automatically when needed.

Bluetooth

You need to have this resource requested to have bluetooth module powered.

GPS

The fso-gpsd is a daemon waiting for gsmd connections, automatically powering the device on and off. When a connection exists, it powers up the GSM. In SHR Settings you can switch GPS completely off SHR Settings -> GPS -> Manual > Off

GSM

You need to have this resource requested to have GSM module powered.

Display

While this resource is requested the display won't be blanked and suspend is disabled.

CPU

Default rules.yaml checks for this resource to disable automatic suspend when it's requested. While this resource is kept suspend is disabled (but screen can be blanked).

Test

A test resource

Network manager

While there are several ways of networking - Wifi, USB, Bluetooth and Gprs - By default, USB networking is enabled in /etc/network/interfaces.

Enhanced configuration is possible through direct editing of /etc/network/interfaces or through Mokonnect.

The connmand daemon with Mokonnect are the recommended user level applications for setting up networking. At the moment, Mokonnect can manage USB, Wifi and Gprs connections, as well as routing and NAT. Wifi device is not required to be manually turned on via SHR-Settings as Mokonnect will automatically enable the device when needed and disable after use.

Mokonnect

Mokonnect Wifi

Mokonnect Wifi Scan

Bluetooth

Bluetooth can be used for several different applications - file transfer, networking, HIDD, music playing (A2DP), calling etc. In some occasions, the devices need to be authorized - paired. At the moment, support for some bluetooth functions is better then for others - it is possible to do all mentioned above with the notice that phone calls with bluetooth headset are always routed to the bluetooth even if it is not around, making it quite difficult to use.

Don't forget you need to turn the bluetooth radio on in SHR Settings -> Connectivity -> Bluetooth Radio: On, where you can also make the bluetooth device visible.

SHR user bluez4 which completely different from bluez3. The bluetoothd is taking care of most of the bluetooth now. Please see Manually using Bluetooth for detailed information about using bluetooth and also for list of supported devices.

OBEX file transfer

There are several obex programs allowing file transfer, all in console at the moment. Obexpush installs obextool, and opd daemon:

Connect Bluetooth keyboard

Pairing

Now, you must pair the bluetooth headset with your Freerunner. Make sure the bluetooth chip is powered up (can be done through the Connectivity section in the SHR-Unstable settings manager) and that bluetoothd is running:

Additionally in the SHR-Unstable repositories there are theme packages optimized for 16bpp color. Both packages can be installed with the following command:

opkg install e-wm-theme-illume-sixteen elementary-theme-sixteen

You can then append the /etc/profile.d/set-elm-engine.sh with:

# Set Optimized theme
export ELM_THEME=sixteen

You can also then change Illume to use the sixteen theme by clicking the wrench->Look->Theme-illume-sixteen->OK. Then switch Illume to use the 16bpp Engine by clicking the wrench->Advanced(you will need to drag and slide the top menu)->Engine->Software_16->OK. This should give you a much faster interface without the low quality look the default SHR themes have at this lower color depth.

If you try to change Wallpaper or Theme and Illume keeps on crashing, it might be caused by the whole Illume running in Software_16 mode. Go to Illume Settings, slide the icon bar and select Advanced. There tap on Engine and select Software. After this, you can change your Wallpaper or Theme. Selecting Software_16 later on again will speed up the desktop's response (though causing it to be a bit uglier).

Speedup of suspend and wake up

I you are using Qi and installation on µSD card, you can change the kernel parameter loglevel=1 1 in /boot/append-GTA02 . For u-boot and installation in nand just type

klogd -c 1

into the console. This saves you from 3 seconds worth of console output on every resume.

If you like the effect of this command and want it to be executed at every startup, you just have to log into your phone and type the following:

Random errors

No icons, no GSM functions etc. - this is mostly due to errors on your µSD card. Remove your card and fix it in card reader or by booting to another partition (nand) or by reboot and mount read only, then run fsck.

You will get disconnected from the ssh session, wait until keys get generated and log in again.

NOTE:Remove old SSH Key from .ssh/known_hosts: On your Linux box you will find a file known_host in the subdirectory .ssh/ in you home directory. This contains a ssh key for the connection to your freerunner. If new keys are generated or if you flash your Freerunner with SHR then you have to remove the line with openmoko or the IP-address of your Freerunner from the file. Otherwise you might be able to login in again.

Installing Software

If you wan to use opkg after you used the installer, make sure packagekitd is not running

killall packagekitd

Cool applications

SHR comes with only few preinstalled applications but it's repository provides more cool stuff. Also, there are applications that are not in SHR repos at the moment but can still be installed. The following few examples are here just to spark your interest:

SHR Launcher

SHR Launcher

Launcher is elementary based alternative home screen application and event notifier for SHR. It displays current time, has a user tweak-able launcher with categories and features missed calls and messages applets.

GPE contacts saves the contacts in a SQLite database that can be synchronized with VCard files. Gpe-contacts don't allow you to dial directly via shr-dialer. Install gpe-contacts:

opkg install gpe-contacts

After installation you'll find to icons with MyVCard. If you want to remove it, delete the file /usr/share/applications/edit-vcard.desktop

Litephone

Litephone

Litephone is new alternative set of phone applications written in Qt. In it's single application interface it provides basic phone functionality (contacts, calls, messages, phone log, settings). It's main advantage is that it uses opimd for storage of the user data.

Mokomaze is an excelent eye-candy game using accelerators embedded in your device.

opkg install mokomaze

If you tweak the exec procedure in /usr/share/applications/mokomaze.desktop into this:

fsoraw -r Display mokomaze

the screen will not blank while playing.

Cellhunter is a game to collect information about mobile phone cells. This information can later be used to roughly determine your position without powering on the GPS chip. CellHunter homepage

opkg install cellhunter

OMGps and TangoGPS are GPS application showing you your position on a map (Openstreetmap, Google maps etc.). You can track your position, save it and use later, save and view points of interest, images or measure your trip. OMGps allows you to overlay different maps on top of each other, set GPS into different modes (walking, car, flying). Maps are downloaded online and used even in offline.

TangoGPS

C

OMGps

Mokomaze

Screenshots can be made with gpe-scap (available by default in SHR full image). To take a screenshot, run gpe-scan from shell while connected in via ssh.

Literki is full qwerty keyboard with configurable layout, always transparent, therefore applications don't need to redraw screens and popup is therefore very fast. The keys are big enough for everyday use with your fat fingers. To pop up the keyboard: slide your finger upwards from the bottom right corner. To hide the keyboard: slide your finger down on the keyboard. Opkg page