Manuals/SHR

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Main Screen)
(Reporting bugs)
Line 256: Line 256:
  
  
===Reporting bugs===
 
  
SHR is a work in progress. If you experience issues, please report them back to SHR. With your report provide logs from
 
 
/var/log/ophonekitd
 
/var/log/frameworkd
 
 
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.
 
  
 
==Settings==
 
==Settings==

Revision as of 21:03, 20 February 2010

Contents

SHR Introduction

Welcome to SHR, a community driven distribution for (not only) Openmoko Neo phones.

SHR

SHR (Stable Hybrid Release) is here to provide you with Root FileSystem images that you can easily install onto your phone to use as a daily phone. 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 is a testing environment before software get stabilized and it is the main testing ground for FSO releases. SHR testing images provide as much stability as possible for day-to-day usage.

SHR users, readers of this manual, please report improvements, discrepancies or missing features on this page to vanous @ penguin . cz. Thank you.

Installation

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.

For the GTA02 Neo FreeRunner you need to download the images of the:

- Get the latest kernel from the above linkpage. Starts with uImage-...

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

The above are full images. You can also choose images with less packages, marked as lite which can be upgraded to the full image by running

# Please note #opkg_upgrade_issues
opkg update
opkg install task-shr-apps task-shr-games task-shr-gtk

- Get the kernel modules. From the same page, download the modules to match your kernel (their dates should be the same). Put that file on the FreeRunner and run

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

Editors note: Running depmod should not be necessary, if it's needed, please report a bug. Recommending of the depmod command will be removed in near future.

GTA01 Neo 1973 images are at (20091130 future):

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:

Note that there are some issues using dfu-util with sudo.

Don't use sudo with dfu-util. Make sure you are root before using dfu-util!

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:

  • 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).
  • 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 .

Please visit the links below for detailed information and tips:

SHR version

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

cat /etc/shr-version
NOTE: Please note that running opkg update;opkg upgrade does not change the SHR version. Only flashing or a new image download can change the SHR version.



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, to make sure that all packages get initialized properly.

Initial Setup

During the first boot, 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 are available. The Profile offers to choose a preconfigured way of displaying the desktop. Please choose Illume-SHR if unsure.

language selection
theme selection

After this Setup, SHR Setting Wizzard is launched to allow setting up your local phone settings and setting up root password.


First look

Desktop screen

Illume desktop is the 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 shelf or by using the < left or right > arrows in the top shelf.

Phone applications

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

Dialer
Contacts
Messages
Phone log

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 phone. 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

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.

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 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

Main article: 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

Changing the root password

Recent images will show up a prompt to change the root password during the first boot wizard. If for some reason this prompt doesn't show up you can change the password by using the terminal emulator in your SHR installation.


Localization

Localize SHR manually

Setting Language

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 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 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. 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:

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

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

export LANG=cs_CZ
export LC_ALL=cs_CZ

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.

Dutch terminal virtual keyboard

Furthermore 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.

Note that sometimes after an upgrade of Illume has taken place, these keyboards have to be installed again before they become available again. Removing these packages will restore the availability of the respective original keyboards.

German (and Austria) Language

Find a hopefully stable SHR German language version with Austrian Maps here. The configuration can be used for any German speaking country. The Austrian maps for Navit can be replaced and Navit is "speaking" German. Navit is configured with a preselect of country "Austria" (see Navit), There are some differences between dictionary de_AT (Austria) and de_DE (Germany).

Date and time

The local timezone is automatically retrieved from the GSM network.

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"

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

Is this better?:

hwclock --utc --systohc

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



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 wiki page about a better way to manage preventing screen dim or suspend.

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

Settings: 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.

Settings: 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 42 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.

Settings: 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

Settings: 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.

Settings: 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

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 the 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 :

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

Settings: 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-166 is not supported and results in buggy behavior of several applications, for example the phone suite or Ventura browser.

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

Settings: 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.

Settings: 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.

Settings: 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 - slide the top shelf down and tap the Settings icon (SHR logo).

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

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

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.


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)

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 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. The Wifi device is not required to be manually turned on via SHR-Settings as Mokonnect will automatically enable the device when needed and disable it 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 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 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 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.

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 it onto bt 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.

Pairing

This comes from Manually_using_Bluetooth#Once_Again.2C_Bluetooth_Headset_on_Freerunner

Now, you must pair the bluetooth headset with your phone. 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:

/etc/init.d/bluetooth start

Now, to actually pair the bluetooth headset, you will need the simple-agent script. If you already have it, excellent. If you, like me, do not, then you can get it here: http://dl.getdropbox.com/u/453116/simple-agent

Put it in /usr/bin/ and run ===chmod a+x /usr/bin/simple-agent===

Now put your headset into pairing mode and run

hcitool scan

Find your headset and use its address in the command

simple-agent hci0 XX:XX:XX:XX:XX:XX

If you give a third parameter (what it is doesn't matter) to simple-agent, it will disconnect then reconnect to the headset (reset pairing).

GSM phone calls with bluetooth headset

Your bluetooth headset device must be paired first.

Configuring bluez

Older SHR releases you need to uncomment SCORouting=PCM setting in [General] section of

/etc/bluetooth/audio.conf

like this:

# SCO routing. Either PCM or HCI (in which case audio is routed to/from ALSA)   
# Defaults to HCI                                                               
SCORouting=PCM                                                                  

do not forget to restart bluetoothd after that.

# /etc/init.d/bluetooth stop
# /etc/init.d/bluetooth start

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 bt device

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

mdbus -s org.bluez /org/bluez/`pidof bluetoothd`/hci0/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 /org/bluez/`pidof bluetoothd`/hci0/dev_00_09_DD_31_92_98 org.bluez.Headset.Connect

Hopefully, your bluetooth headset now works. Good luck!

System Customizing

Installing splash themes

List available splash screen themes

opkg list | grep splash-theme

and 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

List availablethemes

opkg list | grep theme

Themes have usually files for several parts of the graphic interface:

e-wm-theme-illume-gry
shr-theme-gry
elementary-theme-gry


and install one of the available themes

opkg install e-wm-theme-illume-gry shr-theme-gry elementary-theme-gry

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

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

Enable mouse cursor

edit line 121 of /etc/X11/Xinit and erase -hide-cursor

ARGS="$ARGS -dpi ${DPI} -screen ${SCREEN_SIZE} -mouse tslib -root-ppm /usr/share/pixmaps/xsplash-vga.ppm vt1"
           


Disable the standard Lock Screen

And go back to the old LOCKED again

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.

In Illume Settings => Input => Key Bindings, bind the key XF86Phone to Desktop Simple Lock


opkg upgrade issues

NOTE:
Image unstable/testing december and previously:
Before upgrading (via opkg), you should go to "Settings"->"Power" and change "Auto-suspend" to "Off", or else your phone will suspend while upgrading.

Former images:
If "Auto-suspend" can not be found, you must prevent the phone from suspending while upgrading. Tap shortly (within 1-2 seconds?) on the just blackened screen to prevent suspending. After the upgrade the "Auto-suspend" settings will be available.

The unwanted suspending while upgrading can be avoided by using the below alias.


You can request the CPU resource (temporary non-suspend) while executing opkg by inserting this in file /etc/profile :

alias opkg="fsoraw -f -r CPU -- opkg"

To make the alias work at once for the current boot execute:

alias opkg="fsoraw -f -r CPU -- opkg"

Source: spaetz

As opkg had some issues recently, installation might get broken due to that. You can fix it or prevent by using the following scripts

Safe update packages:

#!/bin/sh

for pkg in `opkg list_upgradable | awk '!/(kernel|Multiple)/ {print $1}'`
do
	echo "installing pack $pkg"
	opkg install $pkg -force-reinstall
done

Force reinstall all installed packages:

#!/bin/sh

for pkg in `opkg list_installed | awk '!/(kernel|Multiple)/ {print $1}'`
do
	echo "installing pack $pkg"
	opkg install $pkg -force-reinstall
done

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.

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

fsck.ext2 /dev/mmcblk0p1


Installing Software

You can use opkg for installing software packages or you can try SHR Installer from http://git.shr-project.org/git/?p=shr-installer.git;a=summary . It requires packagekitd

opkg install packagekitd

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

killall packagekitd
Personal tools

Contents

SHR Introduction

Welcome to SHR, a community driven distribution for (not only) Openmoko Neo phones.

SHR

SHR (Stable Hybrid Release) is here to provide you with Root FileSystem images that you can easily install onto your phone to use as a daily phone. 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 is a testing environment before software get stabilized and it is the main testing ground for FSO releases. SHR testing images provide as much stability as possible for day-to-day usage.

SHR users, readers of this manual, please report improvements, discrepancies or missing features on this page to vanous @ penguin . cz. Thank you.

Installation

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.

For the GTA02 Neo FreeRunner you need to download the images of the:

- Get the latest kernel from the above linkpage. Starts with uImage-...

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

The above are full images. You can also choose images with less packages, marked as lite which can be upgraded to the full image by running

# Please note #opkg_upgrade_issues
opkg update
opkg install task-shr-apps task-shr-games task-shr-gtk

- Get the kernel modules. From the same page, download the modules to match your kernel (their dates should be the same). Put that file on the FreeRunner and run

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

Editors note: Running depmod should not be necessary, if it's needed, please report a bug. Recommending of the depmod command will be removed in near future.

GTA01 Neo 1973 images are at (20091130 future):

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:

Note that there are some issues using dfu-util with sudo.

Don't use sudo with dfu-util. Make sure you are root before using dfu-util!

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:

  • 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).
  • 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 .

Please visit the links below for detailed information and tips:

SHR version

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

cat /etc/shr-version
NOTE: Please note that running opkg update;opkg upgrade does not change the SHR version. Only flashing or a new image download can change the SHR version.



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, to make sure that all packages get initialized properly.

Initial Setup

During the first boot, 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 are available. The Profile offers to choose a preconfigured way of displaying the desktop. Please choose Illume-SHR if unsure.

language selection
theme selection

After this Setup, SHR Setting Wizzard is launched to allow setting up your local phone settings and setting up root password.


First look

Desktop screen

Illume desktop is the 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 shelf or by using the < left or right > arrows in the top shelf.

Phone applications

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

Dialer
Contacts
Messages
Phone log

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 phone. 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

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.

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 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

Main article: 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

Changing the root password

Recent images will show up a prompt to change the root password during the first boot wizard. If for some reason this prompt doesn't show up you can change the password by using the terminal emulator in your SHR installation.


Localization

Localize SHR manually

Setting Language

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 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 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. 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:

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

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

export LANG=cs_CZ
export LC_ALL=cs_CZ

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.

Dutch terminal virtual keyboard

Furthermore 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.

Note that sometimes after an upgrade of Illume has taken place, these keyboards have to be installed again before they become available again. Removing these packages will restore the availability of the respective original keyboards.

German (and Austria) Language

Find a hopefully stable SHR German language version with Austrian Maps here. The configuration can be used for any German speaking country. The Austrian maps for Navit can be replaced and Navit is "speaking" German. Navit is configured with a preselect of country "Austria" (see Navit), There are some differences between dictionary de_AT (Austria) and de_DE (Germany).

Date and time

The local timezone is automatically retrieved from the GSM network.

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"

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

Is this better?:

hwclock --utc --systohc

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



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 wiki page about a better way to manage preventing screen dim or suspend.

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

Settings: 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.

Settings: 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 42 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.

Settings: 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

Settings: 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.

Settings: 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

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 the 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 :

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

Settings: 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-166 is not supported and results in buggy behavior of several applications, for example the phone suite or Ventura browser.

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

Settings: 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.

Settings: 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.

Settings: 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 - slide the top shelf down and tap the Settings icon (SHR logo).

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

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

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.


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)

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 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. The Wifi device is not required to be manually turned on via SHR-Settings as Mokonnect will automatically enable the device when needed and disable it 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 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 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 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.

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 it onto bt 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.

Pairing

This comes from Manually_using_Bluetooth#Once_Again.2C_Bluetooth_Headset_on_Freerunner

Now, you must pair the bluetooth headset with your phone. 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:

/etc/init.d/bluetooth start

Now, to actually pair the bluetooth headset, you will need the simple-agent script. If you already have it, excellent. If you, like me, do not, then you can get it here: http://dl.getdropbox.com/u/453116/simple-agent

Put it in /usr/bin/ and run ===chmod a+x /usr/bin/simple-agent===

Now put your headset into pairing mode and run

hcitool scan

Find your headset and use its address in the command

simple-agent hci0 XX:XX:XX:XX:XX:XX

If you give a third parameter (what it is doesn't matter) to simple-agent, it will disconnect then reconnect to the headset (reset pairing).

GSM phone calls with bluetooth headset

Your bluetooth headset device must be paired first.

Configuring bluez

Older SHR releases you need to uncomment SCORouting=PCM setting in [General] section of

/etc/bluetooth/audio.conf

like this:

# SCO routing. Either PCM or HCI (in which case audio is routed to/from ALSA)   
# Defaults to HCI                                                               
SCORouting=PCM                                                                  

do not forget to restart bluetoothd after that.

# /etc/init.d/bluetooth stop
# /etc/init.d/bluetooth start

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 bt device

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

mdbus -s org.bluez /org/bluez/`pidof bluetoothd`/hci0/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 /org/bluez/`pidof bluetoothd`/hci0/dev_00_09_DD_31_92_98 org.bluez.Headset.Connect

Hopefully, your bluetooth headset now works. Good luck!

System Customizing

Installing splash themes

List available splash screen themes

opkg list | grep splash-theme

and 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

List availablethemes

opkg list | grep theme

Themes have usually files for several parts of the graphic interface:

e-wm-theme-illume-gry
shr-theme-gry
elementary-theme-gry


and install one of the available themes

opkg install e-wm-theme-illume-gry shr-theme-gry elementary-theme-gry

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

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

Enable mouse cursor

edit line 121 of /etc/X11/Xinit and erase -hide-cursor

ARGS="$ARGS -dpi ${DPI} -screen ${SCREEN_SIZE} -mouse tslib -root-ppm /usr/share/pixmaps/xsplash-vga.ppm vt1"
           


Disable the standard Lock Screen

And go back to the old LOCKED again

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.

In Illume Settings => Input => Key Bindings, bind the key XF86Phone to Desktop Simple Lock


opkg upgrade issues

NOTE:
Image unstable/testing december and previously:
Before upgrading (via opkg), you should go to "Settings"->"Power" and change "Auto-suspend" to "Off", or else your phone will suspend while upgrading.

Former images:
If "Auto-suspend" can not be found, you must prevent the phone from suspending while upgrading. Tap shortly (within 1-2 seconds?) on the just blackened screen to prevent suspending. After the upgrade the "Auto-suspend" settings will be available.

The unwanted suspending while upgrading can be avoided by using the below alias.


You can request the CPU resource (temporary non-suspend) while executing opkg by inserting this in file /etc/profile :

alias opkg="fsoraw -f -r CPU -- opkg"

To make the alias work at once for the current boot execute:

alias opkg="fsoraw -f -r CPU -- opkg"

Source: spaetz

As opkg had some issues recently, installation might get broken due to that. You can fix it or prevent by using the following scripts

Safe update packages:

#!/bin/sh

for pkg in `opkg list_upgradable | awk '!/(kernel|Multiple)/ {print $1}'`
do
	echo "installing pack $pkg"
	opkg install $pkg -force-reinstall
done

Force reinstall all installed packages:

#!/bin/sh

for pkg in `opkg list_installed | awk '!/(kernel|Multiple)/ {print $1}'`
do
	echo "installing pack $pkg"
	opkg install $pkg -force-reinstall
done

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.

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

fsck.ext2 /dev/mmcblk0p1


Installing Software

You can use opkg for installing software packages or you can try SHR Installer from http://git.shr-project.org/git/?p=shr-installer.git;a=summary . It requires packagekitd

opkg install packagekitd

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

killall packagekitd