Manuals/SHR

From Openmoko

Revision as of 17:04, 23 September 2011 by Panta (Talk | contribs)

Jump to: navigation, search

Contents

SHR Introduction

Welcome to SHR, a community driven distribution for (not only) Openmoko, HTC Dream, PalmPré and Nokia n900 phones.


SHR

SHR (Stable Hybrid Release) is here to provide you with Root FileSystem images that you can easily install into your device to use as a daily phone and PDA. There are many prepackaged programs available 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 (SHR-U) is a testing environment before software gets stabilized and it is the main testing ground for FSO releases. SHR testing (SHR-T) images provide as much stability as possible for day-to-day usage. Some users find the SHR-U releases preferable for everyday use. [1]

Installation

Use Qi as bootloader to avoid GPS problems on suspend/resume. Switch off you freerunner (if necessary) and start NOR uBoot by pressing AUX and Power-On at the same time and then start dfu-util on your computer with the following parameters for GTA2:

 # dfu-util -a u-boot -R -D qi-s3c2442-master-hist_3b8513d8b3d9615e.udfu

See Flashing the Neo FreeRunner or Flashing the Neo 1973 for more details on flashing your phone.

Getting SHR

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 the microSD card, you need to either get .jffs2 file for NAND or .tar.gz file for microSD.

- Get the latest kernel from the below linkpages. Starts with uImage-...

- Get the root filesystem, for NAND: full-om-gta0_.jffs2, for µSD: full-om-gta0_.tar.gz

The above are full images. You can also choose images with less packages, marked as lite.

GTA02 Neo FreeRunner
GTA01 Neo 1973
Image lite to image full

If you flashed a lite image and want to upgrade to the full image run:

opkg update
opkg install task-shr-apps task-shr-games task-shr-gtk
Kernel modules

The images of the filesystems mentioned above (.jffs2, .tar.gz), already contain the newest kernel modules.

Get the new kernel modules if you only want to flash a new kernel, but not a whole new file system. From the same page as the kernel download the modules to match your kernel (their dates should be the same). Use sftp to put that file on the FreeRunner via the usb connection. Run gzip to unwrap the modules:

# gzip -dc modules-...tar.gz | tar -xf - -C /

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.

Please visit Flashing the Neo FreeRunner for more details about flashing and see Dfu-util for detailed information about the dfu-util.

NOTE: Your battery must be charged (sufficiently) before NAND flashing. Symptom of insufficient charge: Your progress bar "####" stops while flashing. If so, you must charge, and later you should be able to make the complete flash.


Commands to flash the filesystem and the kernel:

for the GTA02 Neo FreeRunner:

# dfu-util -d 0x1d50:0x5119 -a rootfs -R -D full-om-gta02.jffs2
# dfu-util -d 0x1d50:0x5119 -a kernel -R -D uImage-om-gta02-latest.bin

for the GTA01 Neo 1973:

# dfu-util -d 0x1457:0x5119 -a rootfs -R -D full-om-gta01.jffs2
# dfu-util -d 0x1457:0x5119 -a kernel -R -D uImage-om-gta01-latest.bin

Installation on the microSD Card

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

In simple words, the difference between both systems resides on how you must prepare your microSD Card and files you use to fill them:

uBoot and SHR on microSD Card

If you use uBoot, you need to create two partitions. First partition, not so big, in FAT16 or ext2 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).

Qi and SHR on microSD Card

If you use Qi, you only need an ext2 partition (e.g. with fdisk) into your µSD Card.

 # mkfs.ext2 /dev/sde1

If your µSD Card drive has the device name /dev/sde1. Download shr-image-om-gta02.tar.gz. Uncompress the filesystem image file (shr-image-om-gta02.tar.gz) on the µSD Card (e.g. with a µSD-SD-Card-Adapter on your Linux Desktop Computer. Insert the µSD Card back into your Freerunner and boot your Neo.

In this case Qi Bootloader is going to look for the kernel image into the /boot directory for file named uImage-GTA02.bin .

Bootloaders

Make sure you have recent and correct versions of uBoot or Qi installed, please visit the links for detailed information and tips. For example Android uses modified Qi which can cause you troubles when using SHR.

SHR version

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

timestamp of image creation:

cat /etc/timestamp

latest shr version from opkg upgrade (this version is changed everytime someone builds task-base on shr buildhost):

cat /etc/shr-version
NOTE: Please note that this is true only for shr-u, with shr-t running opkg update;opkg upgrade does not change the SHR version. Only flashing or a new image download can change the SHR version. But this will be also merged to shr-t later.


Running SHR

First boot

SHR Boot Splash screen

First boot usually takes a bit longer as your phone's new software needs to do some initial setting up. It is recommended to reboot after this first boot (and after the initial setup), to make sure that all packages get initialized properly. The application switching shelve (shr_elm_softkey) doesn't show up during first boot when the initial wizards are at work, reboot is required and then application switching works as expected.

Initial Setup

During the first run, Setup is automatically initiated to walk the user through basic setup of the Enlightenment desktop environment. These steps vary as both Enlightenment desktop and SHR evolve, at this point preferred language and desktop profile options are available. The Profile offers to choose a preconfigured way of displaying the desktop. Illume2-SHR (with continuous development) and Illume-SHR (discontinued) profiles are available. Illume2-SHR is the recommended Profile.

language selection
theme selection
SHR Wizard

Note, you may need to ssh into the device and run /usr/bin/xinput_calibrator_once.sh if calibration is wrong. I found this using a Neo1973 and SHR images from around May 2010.

SHR Wizard

After the initial Setup, SHR Setting Wizard is launched to allow setting up your local phone settings and setting up root password. Sometimes a Please wait message is displayed for a long time, as the wizzard is waiting for the SIM card to be initialized.

First look

Desktop screen
Task switch buttons

Illume desktop

Illume desktop is the default home screen of the SHR desktop.

Application definition files located in /usr/share/applications are displayed here as icons. All applications are ran fullscreen and you can switch between them by using the the < left or right > arrows on sliding shelve available by tapping Top Shelf on any empty space. To close applications, choose X from the same sliding shelve.

If tapping Top Shelf on an empty space the sliding shelve doesn't appear then you can activate it opening a Terminal and giving this command:

killall soft_elm_softkey ; shr_elm_softkey &


Several icons (e-gadgets) are placed in the Top Shelve:

The L icon is to switch between left/right mouse click. By taping this icon the icon gets changed to R and next tap will be as right click. After the click, the behavior is automatically switched back to Left click so any following taps are left click again.

Mode Switch Icon allows to split the screen horizontally or vertically, thus allowing to display two applications at the same time.

Keyboard icon pops up or hides the Keyboard.

Illume Settings icon (represented by SHR logo) invokes the Illume desktop settings.

Home Icon allows quick go to the home desktop/application.

GSM and Battery status icons, as well as time are displayed by default, Bluetooth and WiFi status icons available in the setting of the Top Shelve content.


To reconfigure the Top Shelve itself, use the L/R click icon to Right click on the Top Panel and choose: Illume Indicator->Set Content to add or remove items from the Top Panel. Or, upon right click on the Top Panel you can also choose Illume Indicator->Begin Move/Resize to move your icons around. To escape this mode, you must click on the L/R gadget's edge, it will switch to L, then choose R again, right click on the Top Panel and select Illume Indicator->Stop Move/Resize.


Keyboard

Keyboard comes up automagically when a text field is tapped or you can also toggle the keyboard by it's icon in the Top Shelve. In the Keyboard, dictionary switcher is the arrow-up on left side, alternative keyboard layouts are under the ABC button on the right. The Default keyboard has English dictionary enabled. For Space quick slide left-to-right, for Enter, quick slide up-down, to quick change keyboard layout quick slide down-up. While typing with a dictionary enabled keyboard, possible word options start appearing in the keyboard's upper part or more word options are available under the arrow-up on the left. When happy with the word, tap it, it will be pasted into the text field with a space attached. The Keyboard and dictionary can easily be localized.

Problem with external USB keyboard mapping (arrows keys doesn't work) can be solved with this little script.

Copy and Paste

In E based applications, for example the phone suite (contacts, messages...), by tapping and holding down for over two seconds the Select-Paste menu will pop up. By pressing Select, you can now swipe through the text to select desirable part. Tap and hold down again, Copy-Cut-Cancel menu will appear to Copy to clipboard. Another long tap will provide Select-Paste for Paste.

In Gtk based application, you can use keyboard for Ctrl-C (Copy) and Ctrl-V (Paste) or items in Menu if provided.

In the Vala Terminal, you can select simply by swiping through the text and for Paste there is an icon in the menu bar of this application.

Copy & Paste between different toolkits has some limitations. See the table below. In Ventura, select is possible, but copy/paste doesn't seem to work at all.

From -> To to GTK to E to Terminal
from GTK Works Works Doesn't work
from E Doesn't work Works Works
from Terminal Doesn't work Works Works

Alarm

The Alarms application (installed by default) allows alarm presetting for single or repeatable alarms. If you set an alarm and turn your Openmoko FreeRunner off, at the time of the alarm the phone will be powered up and alarm will sound.

Phone applications

Besides other software, SHR comes with 4 main phone applications: Dialer, Contacts, Messages and Phone log.

Dialer
Contacts
Messages
Phone log


PIM data
Storage

PIM data (contacts, messages etc.) are stored through internal opimd storage mechanism into

/etc/freesmartphone/opim/pim.db

This database can easily be copied from one SHR installation to another, for example due to a need for reflashing. The Contacts application can display a picture of the contact. As the pim.db database contains a path to the picture files only but not the pictures themselves, therefore, in case of PIM data backup or transfer, these picture files need to be copied too.

SIM Contacts

SHR phone applications do not read SIM contacts by default but you can use SIM Manager to access your SIM contacts SHR Settings -> Others -> SIM Manager, which allows you to edit and import the SIM contacts into the internal storage. You can also use Pisi to import your SIM contacts into opimd.

Synchronization

Pisi is an application for synchronizing PIM data and can be used for import and export your contacts, calendar entries etc. between various sources, like VCF, LDAP, Google and more. To install Pisi:

opkg install pisi

After installation, edit Pisi configuration in .pisi/conf in your home directory. To have a correct opimd fields support, make sure field_support=TRUE is enabled in opimd section.

With the installed package you have a well-documented sample that is placed at

 /usr/share/doc/pisi/conf.example

You may copy the file and rename this file to

 /home/root/.pisi/conf

as a starting point - then edit this file in order to configure your PIM synchronization data sources. Look at section

[opimd]
description=OPIMD Contacts
module=contacts_opimd
field_support=TRUE
Idle screen
Idle Screen with GSM operator strength and name. GPS, WiFi, Display and CPU are requested, Battery status.

Upon press of the AUX button Idle Screens locks up the display. AUX press or a finger slide on the Slider unlocks the screen.

At the top, status icons are shown to indicate what is going on in the phone:

From left to right: GSM strength and operator. Requested Resources (GPS, Display etc., when for example Display is requested, the screen will not dim). Battery capacity.

Hardware Buttons

Power Button
Quick Settings

The PWR (Power) button is mapped to start Quick Settings screen (Illume System menu in older versions) on a short press.

Mapping of the PWR button be configured via the Illume Settings-> Input -> Key Bindings.

Pressing the Power button for longer then 8 seconds will force a complete power down of the device. This is hardconfigured in the kernel.

The Quick Settings screen provides several toggles: Airplane mode, Phone profiles, Power settings and Power buttons.

Auxiliary Button

The AUX (Auxiliary) button is mapped to toggle on/off the SHR Idle screen. Mapping of this button is configured in /etc/phonefsod.conf

idle_screen = aux,lock

You can configure the Idle Screen to come up even during active phone call by adding phone to the setting:

idle_screen = aux,lock, phone

The Idle Screen shows current date and time, missed calls and messages and also what FSO resources are currently being requested - used.

Replacing idle screen

If you wish to use the E simple LOCKED screen instead of the SHR Idle Screen, edit /etc/phonefsod.conf to this:

# when to show idle screen
# ...
# idle_screen = aux,lock
idle_screen =

You need to restart phonefsod to make the change happen.

Also, change key mapping for the AUX button by setting Illume Settings -> Input -> Key Bindings, bind the key XF86Phone to Desktop Simple Lock

Settings applications

Many desktop and phone settings are possible to do via graphical interface. SHR Settings provides access to most common phone personality settings and is accessible by tapping Settings icon on the desktop. Illume settings (and Enlightenment desktop settings) are accessible on Top shelve by tapping the "SHR Logo" icon. Also, FSO and SHR phoneui applications have configuration files in /etc where some of the above mentioned apps write and that can be edited manually.

First steps

Right after installation and first boot you might want to do a few initial steps like adjusting the call volume and some other tasks.

Audio - Call Volume

During the first phone call please use the Volume and Mic sliders on the Active Call Screen and adjust them to fit your preferences. The new improved settings will be used for all in/out-going calls thereafter.

Network Connection

Establish network connection and SSH into your phone. You can establish connection either via USB to your desktop and enable NAT or you can connect through Wifi.

Initializing the opkg database

Initialize the opkg database in order to install some applications from SHR repositories or from other sources, for example opkg.org. While being online, you need to 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

When the RAM is used up, applications get killed. This is particularly bad while doing opkg upgrade. Therefore you might want to create a swap space. Read SwapSpace article or the swap article on the SHR wiki.

Settings

SHR Settings

SHR Settings

SHR Settings is the main setting application of SHR. 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 section about a better way to manage preventing screen dim or suspend.

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

Main Screen

The main screen is divided into eight categories, which contain several modules. Every SHR Settings module has a specified task - for example controlling the GSM antenna power, setting the time etc.

Phone

Here you can set 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 a while, a list of operators should pop up.

You can't connect to operators marked [forbidden].

Selecting an operator from the 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")

Phoneutils

For the default SHR phone applications to be able to correctly parse incoming calls/messages and match them with your contacts, you will need to set the right country code for your location. (for example 420 for Czech republic) for more info, please go to: http://wiki.openmoko.org/wiki/Phone_Prefixes

SIM

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

Profiles

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

Current profile

Here you can adjust properties of the currently used profile.

To change the ring tone, click the "Change" button.

To use your own ring tone, place it in /usr/share/sounds directory.

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

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

gst-launch filesrc location=Arkanoid_PSID.sid ! siddec tune=2 ! alsasink

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

Profiles
Ringtones

Connectivity

Connectivity top
Connectivity bottom

WiFi

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

GPRS

To enter APN, login and password fields, just click on the actual value (default: "internet"). Your phone provider can provide the required configuration options.

NOTE: You can also use Mokonnect to manage your GPRS 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, switch the "Bluetooth radio" toggle to "On". After that, the "Visibility" toggle should arrive - set it to "On" if you want your FR to be visible by other Bluetooth devices on scanning.

Power

Battery

This module displays informations about battery state - charge, voltage, remaining time etc. To update the data, click the "Update" button.

Here you can also force enable 500mA charging.

Display

With this slider you can easily set the backlight brightness.

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


Power

Power
Timeouts

Timeouts

Timeouts are reached in this order: Busy state -> idle -> idle dim -> idle prelock -> lock -> suspend.

NOTE: Storing of this setting via D-bus calls is not supported in the new API of Vala rewrite of FSO2 and therefore SHR Settings doesn't have a functional setting for this.


You can set values of idle timeouts manually. The default parameters are stored in /etc/freesmartphone/conf/GTA02/fsodeviced.conf but customized .fsodeviced.conf file in your home directory will take precedence (if it exists, the one in /etc/... will be ignored, so you have to copy the whole file and tweak it):

[fsodevice.kernel_idle]
suspend = 20
lock = 2
idle_prelock = 12
idle = 10
idle_dim = 20

To turn off a timeout, set it to -1.

Appearance

Theming

Neo theme

The Apperance section allows you to change between installed themes. To install more themes, see also Installing themes.

You can change finger size - this will mainly effect vertical spacing between widgets.

Switching between engines:

E can be switched to use different engines. The default engine is x11. Alternative engine x11-16 is not supported and results in buggy behavior of several applications, for example the phone suite or Ventura browser. It's usage is not recommended.

Changing system boot Splash screen is also possible in this module. To install more splash screens, see also Installing splash themes.

Position

GPS
GPS Satelite details

GPS

By default, GPS is turned on only when requested by an application. 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. You either have to turn GPS on manually or start another application to enable the GPS.

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

Remove AGPS data If you experience problems with GPS, turn it off, click "Remove AGPS data" and reboot your Neo. Assisted GPS (aGPS) support GPS receiver to find position by non-satellite information.

Date/time

Date & Time

Time

Here you can view and set the time. By default, the time is just displayed, To adjust it, click on "Set time".

After finishing adjusting, click the "OK" button.

Date

This module displays the current date.

Others

Others

PIM

Pim data are stored in opimd domains. Every opimd domain has different backends to store its data to. The domain reads data from every backend and writes data to the default backend. This elector allows you to choose the backend that stores newly generated data, it doesn't copy or move existing data to a different backend.

Services

The services selector is listing scripts from /etc/init.d/ directory.

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

Services
Services debug screen


Userspace backups

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

Illume settings

The Illume desktop can be easily customized - tap the Settings icon (SHR Logo) on the Top Shelve.

Illume settings 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 view more options on the right hand side.

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


Localization

Localize SHR manually

Setting Language

Desktop environment

You can change the language of the SHR desktop environment by using the Settings of Illume. For Example, for Czech language: in the Illume top shelf go to Settings (SHR Logo) -> 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 eglibc-locale-

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

opkg install eglibc-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 of your desktop.

Applications

If you wish to have other applications localized, you need to install translation for each of them (presuming it is available):

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

opkg install libframeworkd-phonegui-efl-locale-cs shr-settings-locale-cs tangogps-locale-cs

Terminal environment

For localized terminal environment (ssh login) set lang variables in /etc/profile.d/locale.sh, example for Czech language:

export LANG=cs_CZ
export LC_ALL=cs_CZ

Illume keyboard and dictionaries

Dutch terminal virtual keyboard

→ more details on page Illume keyboard

Unlike other input methods for mobile devices, the Illume keyboard is corrective rather than predictive. It detects what you mean, even if some letters mistyped. If you accidently hit some keys next to the correct one Illume still recognizes the word. This kind of input method compensates for the small size of the keys. Keep a key pressed for a longer time to affirm you really mean it.

An English dictionary is used by default. A few dictionaries for other languages are included in the SHR distribution. In addition, every dictionary for myspell can be used.

You can install a different keyboard with a layout which fits your language or alternatives for the default keyboards like the numerical one. The localized Illume keyboards are available in the SHR repository under the name illume-keyboard-LANG.

German (and Austria) Language

See Configure_SHR_for_German-speaking_use for detailed customization for german speaking.

Date and time

NOTE: This needs a complete and correct rewrite.


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.

The local timezone is automatically retrieved from the GSM network.

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

[otimed]
# a list of time/zone sources to use or NONE
timesources = GPS,NTP
zonesources = GSM
# use an ip address here, otherwise DNS resolution will block
ntpserver = 134.169.172.1

To disable automatic date/zone settings, simply create an empty [otimed] section in /etc/frameworkd.conf

Timezone change

Create a symlink named /etc/localtime which points to the appropriate file in /usr/share/zoneinfo. For example, if you're in France., the following command will link the correct zoneinfo file to your /etc/localtime, giving you the correct time:

ln -sf /usr/share/zoneinfo/Europe/Paris /etc/localtime

Afterwards, edit /etc/timezone if necessary [?]

Local timezone work instantly for the current boot when:

TZ="Europe/Paris"
export TZ

For a permanent timezone change edit /etc/profile and change to:

TZ="Europe/Paris"


If you use UTC time, set UTC=yes in /etc/default/rcS.

Adjusting time manually:

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

From the Freerunner console:

date -s "YYYY-MM-DD hh:mm"

From linux based desktop:

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

The above does NOT work from Ubuntu as of 4/2/2010, the proper format is:

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

Set the hardware clock to the system time:

hwclock --systohc

Is this better?:

hwclock --utc --systohc

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 than running dbus commands)

opkg install fsoraw

Example of usage fsoraw:

fsoraw -r Display mokomaze

See FSO Resources for more details on using the following resources:

Wifi

Unless this resource is enabled you've no eth0 and wifi module is completely un-powered. Use the Mokonnect network manager to set up networks, it 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

While this resource is requested then suspend is disabled. Display will blank as normal.

Test

A test resource.

UsbHost

While this resource is requested the USB is turned into powered USB Host mode.

Accelerometer

You need to have this resource requested to have the Accelerometer module powered.

Networking

There are several ways of networking - Wifi, USB, Bluetooth and Gprs:

USB

By default, USB networking is enabled in /etc/network/interfaces, where enhanced configuration can be direct edited. The phone default IP address is 192.168.0.202. Some setup is required on the desktop side, please read USB Networking.

WiFi

WiFi manager iliwi is available by default for search/connect/making default a wifi connection. iliwi uses key only in hex format. The Wifi device is not required to be manually turned on via SHR-Settings as iliwi will automatically enable the device when needed and disable it after use. iliwi needs to stay running to keep the WiFi connection enabled.

When WiFi is connected, the Idle screen show the icon of the WiFi resource being occupied.

GPRS

GPRS Credentials are set during the first run in SHR Wizard and you may edit them at any time via SHR settings or direct editing of /etc/phonefsod.conf. GPRS connection can then be established/closed via SHR Settings or through SHR Quick Settings (available under the Power button). SHR Quick Settings - Network tab allows also connection sharing - this will share the GPRS connection with USB network and run DHCP server to provide the client with an IP address.

When GPRS is connected, the idle screen shows a small G above the signal strength indicator.

GPRS + Connection sharing
Iliwi WiFi scanning
Iliwi WiFi connecting

Bluetooth

Bluetooth can be used for several different applications - file transfer (OBEX), networking, input devices (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 than 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 the bluetooth headset is not around, making it quite difficult to use.

In the SHR repositories are applications ready to be installed (by opkg) that already do provide bluetooth support. This means that they request the bluetooth resource automatically, can search bluetooth devices around, help you with pairing and can perhaps even reconnect bluetooth headset upon resume from suspend. From applications that have some bluetooth support some are for example Launcher (home screen launcher and phone suite), Podboy (podcast player), Emtooth (bluetooth manager). In order to set up bluetooth for phone calls, some manual setup from bellow is still required.

Bluez3 - the manual non D-Bus way

If you want to use the bluetooth device directly, you need to turn the bluetooth radio on in SHR Settings -> Connectivity -> Bluetooth Radio: On. You can also make the bluetooth device visible here.

OBEX file transfer

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

opkg install obexpush

Default receiving path (editable in /etc/default/opd_args ) does not exist, so create it

mkdir /var/obexpush

Files are then received automatically, no notice, no confirmation... they just silently appear in /var/obexpush

To send some files, first scan for devices:

hcitool scan
Scanning ...
	00:16:41:F5:A5:BC	laptop

Then send the file onto bluetooth address found in the scan:

obextool push image.jpg 00:16:41:F5:A5:BC 10

Connect Bluetooth keyboard

hidd --search
Editors note: This is the old bluez3 way, but it works. New bluez4 way will replace this.

Bluez4 - D-Bus based way

SHR uses bluez4 which is 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 a list of supported devices.

Pairing

Emtooth is a bluetooth manager. It provides setting up bluetooth device name, pairing/unpairing, visibility setting and more. Install Emtooth:

opkg install emtooth2

It will discover nearby devices, double tapping on found device will initiate pairing process.

GSM with bluetooth headset

In order to use bluetooth headset for phone calls, several simple steps need to be done.

1). Your bluetooth headset device must be paired first.

2). Add your bluetooth headset into FSO configuration.


Please note: phonecalls are now always routed to the bluetooth headset. 
After startup and after every resume, the headset needs to be reconnected.
Configuring FSO

Now we must tell frameworkd that you have a bluetooth headset. Headset parameters should be set in

/etc/freesmartphone/opreferences/conf/phone/default.yaml

Parameters bt-headset-enabled and bt-headset-address (see opreferences/schema/phone.yaml for semantics).

You need to restart FSO for the changes to take effect.

# /etc/init.d/frameworkd restart

example of my /etc/freesmartphone/opreferences/conf/phone/default.yaml:

message-length: 7
message-tone: notify_message.wav
message-vibration: 1
message-volume: 10
ring-loop: 1
ring-tone: ringtone_ringnroll.wav
ring-vibration: 1
ring-volume: 10
bt-headset-enabled: 1
bt-headset-address: 00:09:DD:31:92:98
Re-Connecting the headset

You might need to get the bluetooth headset connected manually on the beginning and also after suspend:

mdbus -s org.bluez $BTADAPTER/dev_xx_xx_xx_xx_xx_xx org.bluez.Headset.Connect

where xx_xx_xx_xx_xx_xx is address of the device, for example:

mdbus -s org.bluez $BTADAPTER/dev_00_09_DD_31_92_98 org.bluez.Headset.Connect

Hopefully, your bluetooth headset now works. Good luck!

System Customizing

Command scheduling

The traditional at command in SHR is modified to work over dbus. This modified at_over_dbus will run scheduled task at required time - actually it will even automatically wake up the phone from suspend or start it if the phone was switched off.

To schedule a command to be executed at a particular time, one must:

Place commands in a script in /var/spool/at and name it like

TIMESTAMP.NAME.NUMBER

where

where TIMESTAMP is the seconds since 1970-01-01 00:00:00 UTC when the command should be run. The rest (NAME, NUMBER) is up to you. Finally you have to:

touch /var/spool/at/trigger

Also, make sure to have atd running. You are responsible to remove the script when unnecessary. It will run once more if you/other program write to the trigger file during the execution, so you may consider removing the executable flag of the script (if it is long running) or rename the script from within for example like this:

 mv "$0" "x$0.$$"

Installing splash screen themes

List available splash screen themes

opkg list | grep splash-theme

Install one of the available themes

opkg install shr-splash-theme-dontpanic

Then go to SHR Settings -> Appearance -> Splash settings. Here you can preview installed themes and change the default one.

Installing themes

Every theme is made of several components (a theme for illume, theme for the phone applications, theme for etk and so on). There is a SHR metapackage for each theme that allows installing the complete theme in one go.

List available SHR theme metapackages:

opkg list | grep shr-theme

Install one of the available themes

opkg install shr-theme-gry

Then go to SHR Settings -> Appearance -> Elementary Settings. Here you can preview installed themes and choose the preferred one.

The Illume screen requires to change theme via Settings (SHR Logo) -> Look -> Theme. Here you can preview installed themes and choose the preferred one.

Enable mouse cursor

edit line 143 of /etc/X11/Xserver and erase -nocursor

ARGS="$ARGS"


Random errors

No icons, no GSM functions etc. happen 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.

For reboot into nand and fix 1st partition of ext2 on your card

fsck.ext2 /dev/mmcblk0p1

GSM modem 1024 suspend bug

The calypso GSM modem suffers a known 1024 hardware bug that causes unreliable GSM function. To work around it, SHR by default doesn't suspend the modem completely. If you have undertaken a fix for this bug you can extend your battery time by enabling the modem to fully suspend when possible.

Edit the following in file:

For the new FSO2 edit /etc/freesmartphone/conf/GTA02/fsogsmd.conf

deep_sleep == "always"

Then kill fsogsmd and restart fsodeviced - or reboot the phone.


For old FSO (frameworks) edit /etc/frameworkd.conf

ti_calypso_deep_sleep = always

Then restart framework or reboot the phone.

Reporting bugs

SHR is a work in progress. If you experience issues, please report them back to SHR. With your report provide relevant logs from

/var/log/

To report a bug, please go to http://shr-project.org/trac/report

Check if the bug is already reported. If not, 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. If bug already exists, see if you can help fixing it by providing some fresh info.

More information

For SHR home page, source code and other resources, visit:

About this manual

This manual makes use of the updated SHR-Unstable distribution which means that for example SHR-Testing or not updated SHR-Unstable might behave differently then stated in this manual.

Please help extending this manual by correcting typos or discussing proposals on the talk page or email vanous @ penguin . cz. Thank you.

Personal tools

Contents

SHR Introduction

Welcome to SHR, a community driven distribution for (not only) Openmoko, HTC Dream, PalmPré and Nokia n900 phones.


SHR

SHR (Stable Hybrid Release) is here to provide you with Root FileSystem images that you can easily install into your device to use as a daily phone and PDA. There are many prepackaged programs available 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 (SHR-U) is a testing environment before software gets stabilized and it is the main testing ground for FSO releases. SHR testing (SHR-T) images provide as much stability as possible for day-to-day usage. Some users find the SHR-U releases preferable for everyday use. [1]

Installation

Use Qi as bootloader to avoid GPS problems on suspend/resume. Switch off you freerunner (if necessary) and start NOR uBoot by pressing AUX and Power-On at the same time and then start dfu-util on your computer with the following parameters for GTA2:

 # dfu-util -a u-boot -R -D qi-s3c2442-master-hist_3b8513d8b3d9615e.udfu

See Flashing the Neo FreeRunner or Flashing the Neo 1973 for more details on flashing your phone.

Getting SHR

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 the microSD card, you need to either get .jffs2 file for NAND or .tar.gz file for microSD.

- Get the latest kernel from the below linkpages. Starts with uImage-...

- Get the root filesystem, for NAND: full-om-gta0_.jffs2, for µSD: full-om-gta0_.tar.gz

The above are full images. You can also choose images with less packages, marked as lite.

GTA02 Neo FreeRunner
GTA01 Neo 1973
Image lite to image full

If you flashed a lite image and want to upgrade to the full image run:

opkg update
opkg install task-shr-apps task-shr-games task-shr-gtk
Kernel modules

The images of the filesystems mentioned above (.jffs2, .tar.gz), already contain the newest kernel modules.

Get the new kernel modules if you only want to flash a new kernel, but not a whole new file system. From the same page as the kernel download the modules to match your kernel (their dates should be the same). Use sftp to put that file on the FreeRunner via the usb connection. Run gzip to unwrap the modules:

# gzip -dc modules-...tar.gz | tar -xf - -C /

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.

Please visit Flashing the Neo FreeRunner for more details about flashing and see Dfu-util for detailed information about the dfu-util.

NOTE: Your battery must be charged (sufficiently) before NAND flashing. Symptom of insufficient charge: Your progress bar "####" stops while flashing. If so, you must charge, and later you should be able to make the complete flash.


Commands to flash the filesystem and the kernel:

for the GTA02 Neo FreeRunner:

# dfu-util -d 0x1d50:0x5119 -a rootfs -R -D full-om-gta02.jffs2
# dfu-util -d 0x1d50:0x5119 -a kernel -R -D uImage-om-gta02-latest.bin

for the GTA01 Neo 1973:

# dfu-util -d 0x1457:0x5119 -a rootfs -R -D full-om-gta01.jffs2
# dfu-util -d 0x1457:0x5119 -a kernel -R -D uImage-om-gta01-latest.bin

Installation on the microSD Card

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

In simple words, the difference between both systems resides on how you must prepare your microSD Card and files you use to fill them:

uBoot and SHR on microSD Card

If you use uBoot, you need to create two partitions. First partition, not so big, in FAT16 or ext2 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).

Qi and SHR on microSD Card

If you use Qi, you only need an ext2 partition (e.g. with fdisk) into your µSD Card.

 # mkfs.ext2 /dev/sde1

If your µSD Card drive has the device name /dev/sde1. Download shr-image-om-gta02.tar.gz. Uncompress the filesystem image file (shr-image-om-gta02.tar.gz) on the µSD Card (e.g. with a µSD-SD-Card-Adapter on your Linux Desktop Computer. Insert the µSD Card back into your Freerunner and boot your Neo.

In this case Qi Bootloader is going to look for the kernel image into the /boot directory for file named uImage-GTA02.bin .

Bootloaders

Make sure you have recent and correct versions of uBoot or Qi installed, please visit the links for detailed information and tips. For example Android uses modified Qi which can cause you troubles when using SHR.

SHR version

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

timestamp of image creation:

cat /etc/timestamp

latest shr version from opkg upgrade (this version is changed everytime someone builds task-base on shr buildhost):

cat /etc/shr-version
NOTE: Please note that this is true only for shr-u, with shr-t running opkg update;opkg upgrade does not change the SHR version. Only flashing or a new image download can change the SHR version. But this will be also merged to shr-t later.


Running SHR

First boot

SHR Boot Splash screen

First boot usually takes a bit longer as your phone's new software needs to do some initial setting up. It is recommended to reboot after this first boot (and after the initial setup), to make sure that all packages get initialized properly. The application switching shelve (shr_elm_softkey) doesn't show up during first boot when the initial wizards are at work, reboot is required and then application switching works as expected.

Initial Setup

During the first run, Setup is automatically initiated to walk the user through basic setup of the Enlightenment desktop environment. These steps vary as both Enlightenment desktop and SHR evolve, at this point preferred language and desktop profile options are available. The Profile offers to choose a preconfigured way of displaying the desktop. Illume2-SHR (with continuous development) and Illume-SHR (discontinued) profiles are available. Illume2-SHR is the recommended Profile.

language selection
theme selection
SHR Wizard

Note, you may need to ssh into the device and run /usr/bin/xinput_calibrator_once.sh if calibration is wrong. I found this using a Neo1973 and SHR images from around May 2010.

SHR Wizard

After the initial Setup, SHR Setting Wizard is launched to allow setting up your local phone settings and setting up root password. Sometimes a Please wait message is displayed for a long time, as the wizzard is waiting for the SIM card to be initialized.

First look

Desktop screen
Task switch buttons

Illume desktop

Illume desktop is the default home screen of the SHR desktop.

Application definition files located in /usr/share/applications are displayed here as icons. All applications are ran fullscreen and you can switch between them by using the the < left or right > arrows on sliding shelve available by tapping Top Shelf on any empty space. To close applications, choose X from the same sliding shelve.

If tapping Top Shelf on an empty space the sliding shelve doesn't appear then you can activate it opening a Terminal and giving this command:

killall soft_elm_softkey ; shr_elm_softkey &


Several icons (e-gadgets) are placed in the Top Shelve:

The L icon is to switch between left/right mouse click. By taping this icon the icon gets changed to R and next tap will be as right click. After the click, the behavior is automatically switched back to Left click so any following taps are left click again.

Mode Switch Icon allows to split the screen horizontally or vertically, thus allowing to display two applications at the same time.

Keyboard icon pops up or hides the Keyboard.

Illume Settings icon (represented by SHR logo) invokes the Illume desktop settings.

Home Icon allows quick go to the home desktop/application.

GSM and Battery status icons, as well as time are displayed by default, Bluetooth and WiFi status icons available in the setting of the Top Shelve content.


To reconfigure the Top Shelve itself, use the L/R click icon to Right click on the Top Panel and choose: Illume Indicator->Set Content to add or remove items from the Top Panel. Or, upon right click on the Top Panel you can also choose Illume Indicator->Begin Move/Resize to move your icons around. To escape this mode, you must click on the L/R gadget's edge, it will switch to L, then choose R again, right click on the Top Panel and select Illume Indicator->Stop Move/Resize.


Keyboard

Keyboard comes up automagically when a text field is tapped or you can also toggle the keyboard by it's icon in the Top Shelve. In the Keyboard, dictionary switcher is the arrow-up on left side, alternative keyboard layouts are under the ABC button on the right. The Default keyboard has English dictionary enabled. For Space quick slide left-to-right, for Enter, quick slide up-down, to quick change keyboard layout quick slide down-up. While typing with a dictionary enabled keyboard, possible word options start appearing in the keyboard's upper part or more word options are available under the arrow-up on the left. When happy with the word, tap it, it will be pasted into the text field with a space attached. The Keyboard and dictionary can easily be localized.

Problem with external USB keyboard mapping (arrows keys doesn't work) can be solved with this little script.

Copy and Paste

In E based applications, for example the phone suite (contacts, messages...), by tapping and holding down for over two seconds the Select-Paste menu will pop up. By pressing Select, you can now swipe through the text to select desirable part. Tap and hold down again, Copy-Cut-Cancel menu will appear to Copy to clipboard. Another long tap will provide Select-Paste for Paste.

In Gtk based application, you can use keyboard for Ctrl-C (Copy) and Ctrl-V (Paste) or items in Menu if provided.

In the Vala Terminal, you can select simply by swiping through the text and for Paste there is an icon in the menu bar of this application.

Copy & Paste between different toolkits has some limitations. See the table below. In Ventura, select is possible, but copy/paste doesn't seem to work at all.

From -> To to GTK to E to Terminal
from GTK Works Works Doesn't work
from E Doesn't work Works Works
from Terminal Doesn't work Works Works

Alarm

The Alarms application (installed by default) allows alarm presetting for single or repeatable alarms. If you set an alarm and turn your Openmoko FreeRunner off, at the time of the alarm the phone will be powered up and alarm will sound.

Phone applications

Besides other software, SHR comes with 4 main phone applications: Dialer, Contacts, Messages and Phone log.

Dialer
Contacts
Messages
Phone log


PIM data
Storage

PIM data (contacts, messages etc.) are stored through internal opimd storage mechanism into

/etc/freesmartphone/opim/pim.db

This database can easily be copied from one SHR installation to another, for example due to a need for reflashing. The Contacts application can display a picture of the contact. As the pim.db database contains a path to the picture files only but not the pictures themselves, therefore, in case of PIM data backup or transfer, these picture files need to be copied too.

SIM Contacts

SHR phone applications do not read SIM contacts by default but you can use SIM Manager to access your SIM contacts SHR Settings -> Others -> SIM Manager, which allows you to edit and import the SIM contacts into the internal storage. You can also use Pisi to import your SIM contacts into opimd.

Synchronization

Pisi is an application for synchronizing PIM data and can be used for import and export your contacts, calendar entries etc. between various sources, like VCF, LDAP, Google and more. To install Pisi:

opkg install pisi

After installation, edit Pisi configuration in .pisi/conf in your home directory. To have a correct opimd fields support, make sure field_support=TRUE is enabled in opimd section.

With the installed package you have a well-documented sample that is placed at

 /usr/share/doc/pisi/conf.example

You may copy the file and rename this file to

 /home/root/.pisi/conf

as a starting point - then edit this file in order to configure your PIM synchronization data sources. Look at section

[opimd]
description=OPIMD Contacts
module=contacts_opimd
field_support=TRUE
Idle screen
Idle Screen with GSM operator strength and name. GPS, WiFi, Display and CPU are requested, Battery status.

Upon press of the AUX button Idle Screens locks up the display. AUX press or a finger slide on the Slider unlocks the screen.

At the top, status icons are shown to indicate what is going on in the phone:

From left to right: GSM strength and operator. Requested Resources (GPS, Display etc., when for example Display is requested, the screen will not dim). Battery capacity.

Hardware Buttons

Power Button
Quick Settings

The PWR (Power) button is mapped to start Quick Settings screen (Illume System menu in older versions) on a short press.

Mapping of the PWR button be configured via the Illume Settings-> Input -> Key Bindings.

Pressing the Power button for longer then 8 seconds will force a complete power down of the device. This is hardconfigured in the kernel.

The Quick Settings screen provides several toggles: Airplane mode, Phone profiles, Power settings and Power buttons.

Auxiliary Button

The AUX (Auxiliary) button is mapped to toggle on/off the SHR Idle screen. Mapping of this button is configured in /etc/phonefsod.conf

idle_screen = aux,lock

You can configure the Idle Screen to come up even during active phone call by adding phone to the setting:

idle_screen = aux,lock, phone

The Idle Screen shows current date and time, missed calls and messages and also what FSO resources are currently being requested - used.

Replacing idle screen

If you wish to use the E simple LOCKED screen instead of the SHR Idle Screen, edit /etc/phonefsod.conf to this:

# when to show idle screen
# ...
# idle_screen = aux,lock
idle_screen =

You need to restart phonefsod to make the change happen.

Also, change key mapping for the AUX button by setting Illume Settings -> Input -> Key Bindings, bind the key XF86Phone to Desktop Simple Lock

Settings applications

Many desktop and phone settings are possible to do via graphical interface. SHR Settings provides access to most common phone personality settings and is accessible by tapping Settings icon on the desktop. Illume settings (and Enlightenment desktop settings) are accessible on Top shelve by tapping the "SHR Logo" icon. Also, FSO and SHR phoneui applications have configuration files in /etc where some of the above mentioned apps write and that can be edited manually.

First steps

Right after installation and first boot you might want to do a few initial steps like adjusting the call volume and some other tasks.

Audio - Call Volume

During the first phone call please use the Volume and Mic sliders on the Active Call Screen and adjust them to fit your preferences. The new improved settings will be used for all in/out-going calls thereafter.

Network Connection

Establish network connection and SSH into your phone. You can establish connection either via USB to your desktop and enable NAT or you can connect through Wifi.

Initializing the opkg database

Initialize the opkg database in order to install some applications from SHR repositories or from other sources, for example opkg.org. While being online, you need to 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

When the RAM is used up, applications get killed. This is particularly bad while doing opkg upgrade. Therefore you might want to create a swap space. Read SwapSpace article or the swap article on the SHR wiki.

Settings

SHR Settings

SHR Settings

SHR Settings is the main setting application of SHR. 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 section about a better way to manage preventing screen dim or suspend.

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

Main Screen

The main screen is divided into eight categories, which contain several modules. Every SHR Settings module has a specified task - for example controlling the GSM antenna power, setting the time etc.

Phone

Here you can set 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 a while, a list of operators should pop up.

You can't connect to operators marked [forbidden].

Selecting an operator from the 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")

Phoneutils

For the default SHR phone applications to be able to correctly parse incoming calls/messages and match them with your contacts, you will need to set the right country code for your location. (for example 420 for Czech republic) for more info, please go to: http://wiki.openmoko.org/wiki/Phone_Prefixes

SIM

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

Profiles

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

Current profile

Here you can adjust properties of the currently used profile.

To change the ring tone, click the "Change" button.

To use your own ring tone, place it in /usr/share/sounds directory.

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

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

gst-launch filesrc location=Arkanoid_PSID.sid ! siddec tune=2 ! alsasink

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

Profiles
Ringtones

Connectivity

Connectivity top
Connectivity bottom

WiFi

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

GPRS

To enter APN, login and password fields, just click on the actual value (default: "internet"). Your phone provider can provide the required configuration options.

NOTE: You can also use Mokonnect to manage your GPRS 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, switch the "Bluetooth radio" toggle to "On". After that, the "Visibility" toggle should arrive - set it to "On" if you want your FR to be visible by other Bluetooth devices on scanning.

Power

Battery

This module displays informations about battery state - charge, voltage, remaining time etc. To update the data, click the "Update" button.

Here you can also force enable 500mA charging.

Display

With this slider you can easily set the backlight brightness.

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


Power

Power
Timeouts

Timeouts

Timeouts are reached in this order: Busy state -> idle -> idle dim -> idle prelock -> lock -> suspend.

NOTE: Storing of this setting via D-bus calls is not supported in the new API of Vala rewrite of FSO2 and therefore SHR Settings doesn't have a functional setting for this.


You can set values of idle timeouts manually. The default parameters are stored in /etc/freesmartphone/conf/GTA02/fsodeviced.conf but customized .fsodeviced.conf file in your home directory will take precedence (if it exists, the one in /etc/... will be ignored, so you have to copy the whole file and tweak it):

[fsodevice.kernel_idle]
suspend = 20
lock = 2
idle_prelock = 12
idle = 10
idle_dim = 20

To turn off a timeout, set it to -1.

Appearance

Theming

Neo theme

The Apperance section allows you to change between installed themes. To install more themes, see also Installing themes.

You can change finger size - this will mainly effect vertical spacing between widgets.

Switching between engines:

E can be switched to use different engines. The default engine is x11. Alternative engine x11-16 is not supported and results in buggy behavior of several applications, for example the phone suite or Ventura browser. It's usage is not recommended.

Changing system boot Splash screen is also possible in this module. To install more splash screens, see also Installing splash themes.

Position

GPS
GPS Satelite details

GPS

By default, GPS is turned on only when requested by an application. 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. You either have to turn GPS on manually or start another application to enable the GPS.

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

Remove AGPS data If you experience problems with GPS, turn it off, click "Remove AGPS data" and reboot your Neo. Assisted GPS (aGPS) support GPS receiver to find position by non-satellite information.

Date/time

Date & Time

Time

Here you can view and set the time. By default, the time is just displayed, To adjust it, click on "Set time".

After finishing adjusting, click the "OK" button.

Date

This module displays the current date.

Others

Others

PIM

Pim data are stored in opimd domains. Every opimd domain has different backends to store its data to. The domain reads data from every backend and writes data to the default backend. This elector allows you to choose the backend that stores newly generated data, it doesn't copy or move existing data to a different backend.

Services

The services selector is listing scripts from /etc/init.d/ directory.

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

Services
Services debug screen


Userspace backups

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

Illume settings

The Illume desktop can be easily customized - tap the Settings icon (SHR Logo) on the Top Shelve.

Illume settings 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 view more options on the right hand side.

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


Localization

Localize SHR manually

Setting Language

Desktop environment

You can change the language of the SHR desktop environment by using the Settings of Illume. For Example, for Czech language: in the Illume top shelf go to Settings (SHR Logo) -> 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 eglibc-locale-

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

opkg install eglibc-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 of your desktop.

Applications

If you wish to have other applications localized, you need to install translation for each of them (presuming it is available):

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

opkg install libframeworkd-phonegui-efl-locale-cs shr-settings-locale-cs tangogps-locale-cs

Terminal environment

For localized terminal environment (ssh login) set lang variables in /etc/profile.d/locale.sh, example for Czech language:

export LANG=cs_CZ
export LC_ALL=cs_CZ

Illume keyboard and dictionaries

Dutch terminal virtual keyboard

→ more details on page Illume keyboard

Unlike other input methods for mobile devices, the Illume keyboard is corrective rather than predictive. It detects what you mean, even if some letters mistyped. If you accidently hit some keys next to the correct one Illume still recognizes the word. This kind of input method compensates for the small size of the keys. Keep a key pressed for a longer time to affirm you really mean it.

An English dictionary is used by default. A few dictionaries for other languages are included in the SHR distribution. In addition, every dictionary for myspell can be used.

You can install a different keyboard with a layout which fits your language or alternatives for the default keyboards like the numerical one. The localized Illume keyboards are available in the SHR repository under the name illume-keyboard-LANG.

German (and Austria) Language

See Configure_SHR_for_German-speaking_use for detailed customization for german speaking.

Date and time

NOTE: This needs a complete and correct rewrite.


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.

The local timezone is automatically retrieved from the GSM network.

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

[otimed]
# a list of time/zone sources to use or NONE
timesources = GPS,NTP
zonesources = GSM
# use an ip address here, otherwise DNS resolution will block
ntpserver = 134.169.172.1

To disable automatic date/zone settings, simply create an empty [otimed] section in /etc/frameworkd.conf

Timezone change

Create a symlink named /etc/localtime which points to the appropriate file in /usr/share/zoneinfo. For example, if you're in France., the following command will link the correct zoneinfo file to your /etc/localtime, giving you the correct time:

ln -sf /usr/share/zoneinfo/Europe/Paris /etc/localtime

Afterwards, edit /etc/timezone if necessary [?]

Local timezone work instantly for the current boot when:

TZ="Europe/Paris"
export TZ

For a permanent timezone change edit /etc/profile and change to:

TZ="Europe/Paris"


If you use UTC time, set UTC=yes in /etc/default/rcS.

Adjusting time manually:

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

From the Freerunner console:

date -s "YYYY-MM-DD hh:mm"

From linux based desktop:

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

The above does NOT work from Ubuntu as of 4/2/2010, the proper format is:

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

Set the hardware clock to the system time:

hwclock --systohc

Is this better?:

hwclock --utc --systohc

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 than running dbus commands)

opkg install fsoraw

Example of usage fsoraw:

fsoraw -r Display mokomaze

See FSO Resources for more details on using the following resources:

Wifi

Unless this resource is enabled you've no eth0 and wifi module is completely un-powered. Use the Mokonnect network manager to set up networks, it 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

While this resource is requested then suspend is disabled. Display will blank as normal.

Test

A test resource.

UsbHost

While this resource is requested the USB is turned into powered USB Host mode.

Accelerometer

You need to have this resource requested to have the Accelerometer module powered.

Networking

There are several ways of networking - Wifi, USB, Bluetooth and Gprs:

USB

By default, USB networking is enabled in /etc/network/interfaces, where enhanced configuration can be direct edited. The phone default IP address is 192.168.0.202. Some setup is required on the desktop side, please read USB Networking.

WiFi

WiFi manager iliwi is available by default for search/connect/making default a wifi connection. iliwi uses key only in hex format. The Wifi device is not required to be manually turned on via SHR-Settings as iliwi will automatically enable the device when needed and disable it after use. iliwi needs to stay running to keep the WiFi connection enabled.

When WiFi is connected, the Idle screen show the icon of the WiFi resource being occupied.

GPRS

GPRS Credentials are set during the first run in SHR Wizard and you may edit them at any time via SHR settings or direct editing of /etc/phonefsod.conf. GPRS connection can then be established/closed via SHR Settings or through SHR Quick Settings (available under the Power button). SHR Quick Settings - Network tab allows also connection sharing - this will share the GPRS connection with USB network and run DHCP server to provide the client with an IP address.

When GPRS is connected, the idle screen shows a small G above the signal strength indicator.

GPRS + Connection sharing
Iliwi WiFi scanning
Iliwi WiFi connecting

Bluetooth

Bluetooth can be used for several different applications - file transfer (OBEX), networking, input devices (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 than 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 the bluetooth headset is not around, making it quite difficult to use.

In the SHR repositories are applications ready to be installed (by opkg) that already do provide bluetooth support. This means that they request the bluetooth resource automatically, can search bluetooth devices around, help you with pairing and can perhaps even reconnect bluetooth headset upon resume from suspend. From applications that have some bluetooth support some are for example Launcher (home screen launcher and phone suite), Podboy (podcast player), Emtooth (bluetooth manager). In order to set up bluetooth for phone calls, some manual setup from bellow is still required.

Bluez3 - the manual non D-Bus way

If you want to use the bluetooth device directly, you need to turn the bluetooth radio on in SHR Settings -> Connectivity -> Bluetooth Radio: On. You can also make the bluetooth device visible here.

OBEX file transfer

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

opkg install obexpush

Default receiving path (editable in /etc/default/opd_args ) does not exist, so create it

mkdir /var/obexpush

Files are then received automatically, no notice, no confirmation... they just silently appear in /var/obexpush

To send some files, first scan for devices:

hcitool scan
Scanning ...
	00:16:41:F5:A5:BC	laptop

Then send the file onto bluetooth address found in the scan:

obextool push image.jpg 00:16:41:F5:A5:BC 10

Connect Bluetooth keyboard

hidd --search
Editors note: This is the old bluez3 way, but it works. New bluez4 way will replace this.

Bluez4 - D-Bus based way

SHR uses bluez4 which is 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 a list of supported devices.

Pairing

Emtooth is a bluetooth manager. It provides setting up bluetooth device name, pairing/unpairing, visibility setting and more. Install Emtooth:

opkg install emtooth2

It will discover nearby devices, double tapping on found device will initiate pairing process.

GSM with bluetooth headset

In order to use bluetooth headset for phone calls, several simple steps need to be done.

1). Your bluetooth headset device must be paired first.

2). Add your bluetooth headset into FSO configuration.


Please note: phonecalls are now always routed to the bluetooth headset. 
After startup and after every resume, the headset needs to be reconnected.
Configuring FSO

Now we must tell frameworkd that you have a bluetooth headset. Headset parameters should be set in

/etc/freesmartphone/opreferences/conf/phone/default.yaml

Parameters bt-headset-enabled and bt-headset-address (see opreferences/schema/phone.yaml for semantics).

You need to restart FSO for the changes to take effect.

# /etc/init.d/frameworkd restart

example of my /etc/freesmartphone/opreferences/conf/phone/default.yaml:

message-length: 7
message-tone: notify_message.wav
message-vibration: 1
message-volume: 10
ring-loop: 1
ring-tone: ringtone_ringnroll.wav
ring-vibration: 1
ring-volume: 10
bt-headset-enabled: 1
bt-headset-address: 00:09:DD:31:92:98
Re-Connecting the headset

You might need to get the bluetooth headset connected manually on the beginning and also after suspend:

mdbus -s org.bluez $BTADAPTER/dev_xx_xx_xx_xx_xx_xx org.bluez.Headset.Connect

where xx_xx_xx_xx_xx_xx is address of the device, for example:

mdbus -s org.bluez $BTADAPTER/dev_00_09_DD_31_92_98 org.bluez.Headset.Connect

Hopefully, your bluetooth headset now works. Good luck!

System Customizing

Command scheduling

The traditional at command in SHR is modified to work over dbus. This modified at_over_dbus will run scheduled task at required time - actually it will even automatically wake up the phone from suspend or start it if the phone was switched off.

To schedule a command to be executed at a particular time, one must:

Place commands in a script in /var/spool/at and name it like

TIMESTAMP.NAME.NUMBER

where

where TIMESTAMP is the seconds since 1970-01-01 00:00:00 UTC when the command should be run. The rest (NAME, NUMBER) is up to you. Finally you have to:

touch /var/spool/at/trigger

Also, make sure to have atd running. You are responsible to remove the script when unnecessary. It will run once more if you/other program write to the trigger file during the execution, so you may consider removing the executable flag of the script (if it is long running) or rename the script from within for example like this:

 mv "$0" "x$0.$$"

Installing splash screen themes

List available splash screen themes

opkg list | grep splash-theme

Install one of the available themes

opkg install shr-splash-theme-dontpanic

Then go to SHR Settings -> Appearance -> Splash settings. Here you can preview installed themes and change the default one.

Installing themes

Every theme is made of several components (a theme for illume, theme for the phone applications, theme for etk and so on). There is a SHR metapackage for each theme that allows installing the complete theme in one go.

List available SHR theme metapackages:

opkg list | grep shr-theme

Install one of the available themes

opkg install shr-theme-gry

Then go to SHR Settings -> Appearance -> Elementary Settings. Here you can preview installed themes and choose the preferred one.

The Illume screen requires to change theme via Settings (SHR Logo) -> Look -> Theme. Here you can preview installed themes and choose the preferred one.

Enable mouse cursor

edit line 143 of /etc/X11/Xserver and erase -nocursor

ARGS="$ARGS"


Random errors

No icons, no GSM functions etc. happen 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.

For reboot into nand and fix 1st partition of ext2 on your card

fsck.ext2 /dev/mmcblk0p1

GSM modem 1024 suspend bug

The calypso GSM modem suffers a known 1024 hardware bug that causes unreliable GSM function. To work around it, SHR by default doesn't suspend the modem completely. If you have undertaken a fix for this bug you can extend your battery time by enabling the modem to fully suspend when possible.

Edit the following in file:

For the new FSO2 edit /etc/freesmartphone/conf/GTA02/fsogsmd.conf

deep_sleep == "always"

Then kill fsogsmd and restart fsodeviced - or reboot the phone.


For old FSO (frameworks) edit /etc/frameworkd.conf

ti_calypso_deep_sleep = always

Then restart framework or reboot the phone.

Reporting bugs

SHR is a work in progress. If you experience issues, please report them back to SHR. With your report provide relevant logs from

/var/log/

To report a bug, please go to http://shr-project.org/trac/report

Check if the bug is already reported. If not, 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. If bug already exists, see if you can help fixing it by providing some fresh info.

More information

For SHR home page, source code and other resources, visit:

About this manual

This manual makes use of the updated SHR-Unstable distribution which means that for example SHR-Testing or not updated SHR-Unstable might behave differently then stated in this manual.

Please help extending this manual by correcting typos or discussing proposals on the talk page or email vanous @ penguin . cz. Thank you.