Manuals/SHR

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

'''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 <tt>vanous @ penguin . cz</tt>. Thank you.

[http://shr-project.org SHR Project page]

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

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

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

*testing line: http://build.shr-project.org/shr-testing/images/om-gta02/

*unstable line: http://build.shr-project.org/shr-unstable/images/om-gta02/

- 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

- '''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 depmon 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):

*http://build.shr-project.org/shr-unstable/images/om-gta01/

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

for the GTA02 Neo FreeRunner:

  sudo dfu-util -d [[USB Product IDs|0x1d50:0x5119]] -a rootfs -R -D full-om-gta02.jffs2

  sudo dfu-util -d [[USB Product IDs|0x1d50:0x5119]] -a kernel -R -D uImage-om-gta02-latest.bin

  sudo dfu-util -d [[USB Product IDs|0x1457:0x5119]] -a rootfs -R -D full-om-gta01.jffs2

  sudo dfu-util -d [[USB Product IDs|0x1457:0x5119]] -a kernel -R -D uImage-om-gta01-latest.bin

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

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

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

Please visit links below for detailed information and tips:

*For [[Booting from SD | uBoot]] and for [[Qi]].

{{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.}}

===Booting===

On the first boot, Setup is automatically initiated to walk the user through basic setup of the Enlightenment desktop environment. You are able to choose preferred language of the desktop environment and the theme. However both options are only offering one choice at the moment.

| [[Image:SHR-Setup-Profile.png|200px|thumb|choosing from two themes (from an older version of SHR)]]

|}

[[Image:SHR-SIM-Auth.png|200px|thumb|center|SIM Auth]]

SIM Pin is asked for upon start up.

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

{| class="wikitable" cellspacing="0" cellpadding="0" style="padding: 0%; margin:0em 0em 1em 0em; border:1px solid #c0c0c0; background:#eeeeee; floating="center";width:100%; "

! style="background:#fcfcfc;border-left:1px solid #9999cc;border-right:1px ; border-top:2px solid 75d806; border:0px solid #222222; width:25% " | 

! style="background:#fcfcfc;border-left:1px solid #9999cc;border-right:1px ; border-top:2px solid 75d806; border:0px solid #222222; width:25% " |

[[Image:SHR-Messages-Options.png|200px|thumb|Messages options]]

[[Image:SHR-Message-View.png|200px|thumb|View message]]

[[Image:SHR-Message-View-chars.png|200px|thumb|Unicode support]]

! style="background:#fcfcfc;border-left:1px solid #9999cc;border-right:1px ; border-top:2px solid 75d806; border:0px solid #222222; width:25% " |

! style="background:#fcfcfc;border-left:1px solid #9999cc;border-right:1px ; border-top:2px solid 75d806; border:0px solid #222222; width:25% " |

[[Image:SHR-Dialer-Active.png|200px|thumb|Active call]]

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

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

''Establish network connection'' and SSH into your phone. The <tt>root</tt> account uses no password by default. You can establish connection either via USB to your desktop and enable NAT or you can connect through Wifi. If you use USB, some setup is required on the desktop side, please read [[USB_Networking]]. For Wifi, you can use [[#Network manager|Network Manager]]

====GSM Network====

====Audio: Volume====

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

vi /usr/share/shr/scenarii/gsmhandset.state

Control 48: internal mic of the tel (set to 2 or 3)

Control 4 : internal speaker (set from 110 to 120)

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

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

  grep navit packages.txt

====SwapSpace====

====Changing root password====

Recent images will show up a prompt to change the root password during the first boot wizard.

SHR is shipped without root password (just press enter)

A much more convenient way might be to install your public-key to ~/.ssh/authorized_keys. You can find your public-key of you host at location:

  /path/file

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

===Localization===

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.

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:

export LANG=cs_CZ

export LC_ALL=cs_CZ

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.

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 keyboard]]s 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 the become available again. Removing these packages will restore the availability of the respective original keyboards.

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

 

 

 

 

 

 

TZ="Europe/Paris"

 

 

TZ="Europe/Paris"

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

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.

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

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

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

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

====Settings: Profiles====

Here you can adjust properties of the currently used profile. Available settings: ring tone, ring volume, ring vibration, ring loop, ring length, message tone, message volume, message vibration, message loop, message length.

====Settings: Connectivity====

To enter APN, login and password fields, just click on the actual value (default: "internet"). Keyboard will pop up.

If you don't know APN, login and passwork, ask your provider.}}

====Settings: Power====

{{Note|This setting isn't permanent over sessions. At boot backlight is set back to 100%.}}

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 :

opkg list | grep theme-illume

http://opkg.org has a very fast theme called nEo

opkg install http://www.opkg.org/packages/e-wm-theme-neo_0.2_armv4t.ipk

opkg install http://www.opkg.org/packages/elementary-theme-neo_0.2_armv4t.ipk

opkg install -force-overwrite http://www.opkg.org/packages/libframeworkd-phonegui-efl-theme-neo_0.2_armv4t.ipk

 

 

 

 

 

 

 

====Settings: Position====

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

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

 

 

 

 

====Settings: Date/time====

====Settings: Others====

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

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

{{Note|TIP: for better access of the Settings icon, tap and hold the Settings icon, then drag it to the right.}}

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

The little applets in the top 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.

<!-- [[Image:SHR-Top-Shelve.png|200px|thumb|Top Shelf]] -->

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 <tt>d-bus</tt>, 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 <tt>fsoraw</tt> command. (Using fsoraw is faster and better then running dbus commands)

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

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

A test resource

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

The <tt>connmand</tt> 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.

[[Image:SHR-Mokonnect.png|200px|thumb|Mokonnect]]

[[Image:SHR-Mokonnect-Wifi.png|200px|thumb|Mokonnect Wifi]]

[[Image:SHR-Mokonnect-Wifi-Scan.png|200px|thumb|Mokonnect Wifi Scan]]

 

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

Then send it onto bt address found in the scan:

===Connect Bluetooth keyboard===

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

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

 

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

  /etc/init.d/bluetooth stop

  /etc/init.d/bluetooth start

====Configuring FSO====

  /etc/init.d/frameworkd restart

====Re-Connecting the bt device====

  mdbus -s org.bluez /org/bluez/`pidof bluetoothd`/hci0/dev_xx_xx_xx_xx_xx_xx org.bluez.Headset.Connect

  mdbus -s org.bluez /org/bluez/`pidof bluetoothd`/hci0/dev_00_09_DD_31_92_98 org.bluez.Headset.Connect

===Changing the splash screen===

and install one of the available themes

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"

===Speedup of suspend and wake up===

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

Opimd utils is a set of several testing scripts to play with the new opimd backends. It also provides opimd-messages program and mainly new opimd-notifier

For further Information refer to the corresponding [[Opimd|Wiki Page]].

'''NOTE 2:''' In order to have sound and vibration on incoming message when using opimd interface, you have to patch oeventsd with patch available at [http://openmoko.opendevice.org/~dos/opimd/oeventsd/]

'''NOTE 3:''' For testing and development opimd recommended distribution is ''upgraded'' SHR unstable.

===opkg upgrade issues===

{{Note|<br>Image unstable/testing december and previously:<br>Before upgrading (via opkg), you should go to "Settings"->"Power" and change "Auto-suspend" to "Off", or else your phone will suspend while upgrading.<br><br>Former images:<br>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.<br><br>If your phone suspends while upgrading you will:<br>*loose your current network connections.<br>*your NAND flash or MicroSD cards normally will be inconsistent.<br>*Even EXT3 partitions will need a full consistency check.<br>*Symptom of inconsistency: Phone can not boot properly or some of your icons are missing.

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

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

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

#!/bin/sh

for pkg in `opkg list_upgradable | awk '!/(kernel|Multiple)/ {print $1}'`

opkg install $pkg -force-reinstall

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.

  echo "192.168.0.202 neo neo" >> /etc/hosts

You can then access your phone like this:

  ssh root@192.168.0.202

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

 

 

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

 

'''[[Paroli]]''' is available in SHR images, you can install it:

 

 

fix the conf files that the paroli installer messes with (might get fixed in the next couple of days.)

cp /etc/old_frameworkd.conf /etc/frameworkd.conf

cp /etc/freesmartphone/oevents/old_rules.yaml /etc/freesmartphone/oevents/rules.yaml

/etc/X11/Xsession.d/89notifier and /etc/X11/Xsession.d/80ophonekitd

if you want the bind-home to ease upgrades add this line to fstab.

You should now have a functional paroli on SHR setup. Once you have a working setup I would advise against doing opkg upgrades and only upgrade specific packages when needed.