You are on page 1of 99

Ubuntu Mobile Guide

1 / 99

Ubuntu Mobile Guide

Ubuntu Mobile Guide


2 / 99

Copyright 2004, 2005, 2006 Canonical Ltd. and members of the Ubuntu Documentation Project

Credits and License This document is maintained by the Ubuntu documentation team (https://wiki.ubuntu.com/DocumentationTeam). For a list of contributors, see the contributors page This document is made available under the Creative Commons ShareAlike 2.5 License (CC-BY-SA). You are free to modify, extend, and improve the Ubuntu documentation source code under the terms of this license. All derivative works must be released under this license. This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE AS DESCRIBED IN THE DISCLAIMER. A copy of the license is available here: Creative Commons ShareAlike License.

Ubuntu Mobile Guide


3 / 99

COLLABORATORS TITLE : Ubuntu Mobile Guide ACTION NAME DATE SIGNATURE REFERENCE :

WRITTEN BY

October 15, 2007

REVISION HISTORY NUMBER DATE DESCRIPTION NAME

Ubuntu Mobile Guide


4 / 99

Contents

1 2

Introduction Developer Blueprints 2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9

12 13

Application Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Possible User Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Mobile User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Window Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Mobile Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Image Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Mobile Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Mobile Hardware Decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Gnome Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.10 Screen Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 2.11 Mobile Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 2.12 Mobile Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 2.13 Power Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 2.14 Power Thermal Optimizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 2.15 Power Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 2.16 Media Player . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 2.17 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 2.18 USB Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 3 Setting up the Development Environment and Creating Images 3.1 3.2 3.3 3.4 3.5 51

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Supported devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Install and Run Image Creator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 3.5.1 3.5.2 Instalation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Creating an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 3.5.2.1 Using the GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Ubuntu Mobile Guide


5 / 99

3.5.2.1.1 3.5.2.1.2 3.5.2.1.3 3.5.2.1.4 3.5.2.1.5 3.5.2.1.6 3.5.2.2 3.6 3.7 4

Start the image creator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Create the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Wait for the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Create the target system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Choose a functional set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Generate image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Using the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Speeding Up Image-Creator by using a local mirror server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Test the target image UI on the Workstation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 65

What is Hildon Desktop? 4.1

Hildon Desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 4.1.1 4.1.2 4.1.3 4.1.4 4.1.5 4.1.6 4.1.7 4.1.8 4.1.9 hildon-desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 hildon-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 hildon-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 hildon-thumbnail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 libhildonmime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 gnomevfs-obex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 gnome-vfs-lechooser-backend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 gtklesystemmemory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 hildon-thumbnail-libid3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

4.1.10 hildon-theme-plankton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4.1.11 sapwood . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4.1.12 hildon-theme-cacher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4.1.13 hildon-theme-layout-4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4.1.14 hildon-theme-tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4.1.15 libosso . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.16 hildon-home-webshortcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.17 hildon-control-panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.18 clipboard-manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.19 maemo-launcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.20 hildon-initscripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.21 osso-af-startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.22 hildon-help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.23 mce-dummy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.24 osso-af-settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.25 osso-af-utils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.1.26 osso-app-killer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 4.1.27 posix-locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 4.1.28 gazpacho-hildon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 4.1.29 hail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Ubuntu Mobile Guide


6 / 99

Anatomy of a Python Application in UME 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9

69

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Application les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Application Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Application auto-discovery via the .desktop le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Executable le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Main Python le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Glade user interface le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Icon le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Sample make le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 73

Using Glade and Python to create an Application for Ubuntu Mobile 6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Using Glade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 This Python programs structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Creating the Hildon Program and Hildon Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Importing the .glade le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Reparenting to Hildon Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

6.10 Getting the menu and making it a Hildon Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 6.11 Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 6.11.1 main.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 6.11.2 Makele . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 7 Porting Python Applications to Ubuntu Mobile 7.1 7.2 7.3 7.4 7.5 8 79

Objective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Assumed Knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Get the Source Code and try it out on UME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Hildonize Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Hildonize Step 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 85

Porting C Applications to Ubuntu Mobile 8.1 8.2 8.3 8.4 8.5

Objective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Assumed Knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Get the source and try to compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Hildonizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 8.5.1 Now on to the menu functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Ubuntu Mobile Guide


7 / 99

Application Development for UME - An Example 9.1

91

Showing the User Relevant Information Based on their Location . . . . . . . . . . . . . . . . . . . . . . . . . . 91 9.1.1 9.1.2 Flash UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 The GeoClue backend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 98

10 Theming and Customization of UME

10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 11 API References 99

11.1 D-Bus API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 11.2 GTK API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 11.3 Hildon API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 11.4 Gnome Developer Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Ubuntu Mobile Guide


8 / 99

List of Figures

2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9

Hildon Desktop Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Mobile Internet Device UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Mobile Internet Device UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Project Builder GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Overview of Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Deliverables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 GNOME Mobile components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

2.10 Frequency Optimised Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 2.11 Mobile Wireframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 2.12 Thermal Control Software Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 2.13 Power Policy Management Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 2.14 API Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 3.1 3.2 3.3 3.4 3.5 3.6 7.1 7.2 7.3 8.1 8.2 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Functional Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Default HTML UI with User Selected background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 gPodder on Desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 gPodder UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 gPodder UME Hildon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Liferea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Liferea Hildonized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Ubuntu Mobile Guide


9 / 99

List of Tables

2.1 2.2

Energy Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Power Events Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Ubuntu Mobile Guide


10 / 99

About This Guide


Conventions
The following notes will be used throughout the book:
Note A note presents interesting, sometimes technical, pieces of information related to the surrounding discussion.

Tip A tip offers advice or an easier way of doing something.

Caution A caution alerts the reader to potential problems and helps avoid them.

Warning A warning advises the reader of a hazard that may arise in a given scenario.

Cross-reference conventions for print will be displayed as follows: Links to other documents or websites will look like this.
Note PDF, HTML, and XHTML versions of this document will use hyperlinks to handle cross-referencing.

Type conventions will be displayed as follows: File names or paths to directories will be shown in monospace. Commands that you type at a Terminal command prompt will be shown as:
command to type

Options that you click, select, or choose in a user interface will look like this.

Ubuntu Mobile Guide


11 / 99

Menu selections, mouse actions, and keyboard short-cuts: A sequence of menu selections will be displayed as follows: File Open Mouse actions shall assume a right-handed mouse conguration. The terms click and double-click refer to using the left mouse button. The term right-click refers to using the right mouse button. The term middle-click refers to using the middle mouse button, pressing down on the scroll wheel, or pressing both the left and right buttons simultaneously, based on the design of your mouse. Keyboard shortcut combinations will be displayed as follows: Ctrl-N .Where the conventions for Control, Shift, and Alternate keys will be Ctrl, Shift, and Alt, respectively, and shall mean the rst key is to be held down while pressing the second key.

Contributing and Feedback


This book is developed by the Ubuntu Documentation Team. You can contribute to this document by sending ideas or comments to the Ubuntu Documentation Team mailing list. Information about the team, its mailing lists, projects, etc. can be found on the Ubuntu Documentation Team Website. If you see a problem with this document, or would like to make a suggestion, you can simply le a bug report at the Ubuntu Bugtracker. Your help is vital to the success of our documentation! Many thanks, -Your Ubuntu Documentation Team

Ubuntu Mobile Guide


12 / 99

Chapter 1

Introduction
Welcome to the Ubuntu Mobile Guide It contains information on how to use and how to develop software for the Ubuntu Mobile Edition The Ubuntu Mobile and Embedded (UME) project aims to derive an operating system for mobile internet devices using Ubuntu as a base. UME will extend Ubuntu by providing an infrastructure for mobile development, with all of the necessary components integrated into the Ubuntu package archive, ready to install and run, or to tailor for custom mobile applications. This guide assumes you have a basic understanding of your Ubuntu system. If you need detailed help installing Ubuntu, refer to the Ubuntu Installation Guide. The Mobile Teams area on Launchpad ishere

Ubuntu Mobile Guide


13 / 99

Chapter 2

Developer Blueprints
Blueprints followed by Ubuntu Mobile developers during the creation of Ubuntu Mobile 7.10 Gutsy Edition. They provide an insight into the thoughts and challenges they faced and are provided here as a historical record. Please consult the other chapters in this manual for up-to-date instructions on any of the techniques they describe

2.1

Application Framework

Our major goal is to make it easy for distributions to package Hildon Desktop so that developers can have a quick-to-setup environment for the development of plugins which do not need to be built against ARM such as Python plugins Ubuntu Mobile and Embedded (UME) uses the Hildon Application Framework found in the Maemo project as the application framework for the UME project. Mobile internet devices and tablets for which this distribution is targeted need an application framework that can provide a way to create applications with a very consistent look and feel and be prepared to run and interface nicely using restricted resources found on small devices like small resolution, little CPU power and storage. In addition, applications should be designed for touchscreen use, nger-friendly navigation, gestures, etc. Thus a specic UI framework, prepared for this kind of demand is necessary.

Figure 2.1: Hildon Desktop Architecture

Ubuntu Mobile Guide


14 / 99

The Hildon Application Framework is one of a few existing frameworks designed for small devices and is a good candidate for tablet use. It has strong support from Nokia and has been separated from Maemo to become part of GNOME Mobile. This has allowed the Ubuntu community and others to contribute in a way that benets all users. This is the step-by-step procedure to have the Hildon Desktop that will be used in the Ubuntu Mobile and Embedded project. Warning: Having the mobile system running in a normal Gutsy installation is likely to cause problems, especially in this early stage of development therefore, its safer to have a chroot environment, which is what is described below. Prepare a gutsy chroot in ${DIR}:
$ $ $ $ sudo sudo sudo sudo debootstrap --arch i386 gutsy ${DIR} http://archive.ubuntu.com/ubuntu mount --bind /tmp ${DIR}/tmp mount -t proc none ${DIR}/proc mount --bind /sys ${DIR}/sys

Everything should be ready, so:


$ sudo chroot ${DIR}

The meta-package ubuntu-mobile provides all the necessary packages and its dependencies so, inside the chroot: Add the universe repository to /etc/apt/sources.list:
deb http://gb.archive.ubuntu.com/ubuntu/ gutsy main restricted universe

Update the repositories and install ubuntu-mobile:


$ sudo apt-get install ubuntu-mobile

Those are packages that are likely to be used when developing applications using the environment above so you can have the hildon desktop shown in your normal desktop.
xserver-xephyr

Create a normal user inside the chroot


sudo adduser ume

Prepare the script that the user just created will use to start hildon desktop.
#!/bin/bash PREFIX=/usr THEME=${PREFIX}/share/themes/plankton export DISPLAY=:1 export GTK2_RC_FILES=${THEME}/gtk-2.0/gtkrc:${THEME}/gtk-2.0/gtkrc. maemo_af_desktop export LANG=en_GB.UTF-8 export LC_ALL=en_GB.UTF-8 export LANGUAGE=en_GB.UTF-8 /usr/lib/libgconf2-4/gconfd-2 & ${PREFIX}/bin/matchbox-window-manager -display ${DISPLAY} \ -theme ${THEME}/matchbox/theme.xml \ -use_titlebar yes \ -use_desktop_mode plain \ -use_lowlight no \ -use_cursor yes \

Ubuntu Mobile Guide


15 / 99

-use_super_modal yes & ${PREFIX}/lib/sapwood/sapwood-server & exec ${PREFIX}/bin/hildon-desktop

Edit /etc/hildon-desktop/desktop.conf and remove or comment out the [Statusbar] session if necessary. Enter the chroot start dbus
/etc/init.d/dbus restart

and su - to the user created above. Outside the chroot execute Xephyr like this:
Xephyr :1 -host-cursor -screen 800x480x16 -dpi 96 -ac

Execute the hildon-desktop script as the user you created above.

2.2

Possible User Applications

For the browser, Firefox will be used. There is already efforts to reduce its footprint and currently we are running an internal version. If we need to t the browser into a very small prole machine a possible alternative is Opera. In a operational level, both are equivalent and can carry the same plugins. The Maemo project just released a new browser, based on the gekko engine which is fully integrated into the hildon environment. However we need a full xul-based solution so we are doing our own work on our own Firefox Embedded browser with: Adobe Flash Player 9 Adobe PDF Reader Java Runtime Environment(JRE) For the Media player. Currently its being considered Helix. Possible option: mplayerThe player going to support both helix and gstreamer simultaneously For the Dictionary: Stardict seems to be the best option so far: Small Fast Flexible Bidirectional Lots of languages available. The interface needs work for usability and to better t into Hildon. For E-mail: The specication asks for Thunderbird which is a great email application but I think that a better alternative is Clawswhich is a improved version of Sylpheed. Lightweight Fairly complete Its already packed for Maemo so its easy for us to integrate.

Ubuntu Mobile Guide


16 / 99

Theres a lot of plugins that we already have packaged like news feed baesian lter spamassassin acpi notier (to blink a led if an email arrives, for instance) smime clamav Disadvantages None that I can see at this time. Recently we were pointed to a new email client called Modest which will become (but, as far as I can tell, theres no ofcial position on that) the new email application for Maemo. Advantages It was created for Maemo so should be fairly easy for us to integrate. Its still under heavy development; It was created to be very light, adequate to a more limited hardware platform; It Doesnt have all the possibilities as with Thunderbird or Claws and I understand that it will never have as its not the project target. For the Media Player It is to be provided by Intel. It will use a simple frontend that will talk with Helix and gstreamer working as backends. For the Camera There are video capture applications (like xawtv, camE), programs that can read, record and process V4L devices like mplayer and videolan which can also be used to process the stream in realtime using lters and programs like EffecTV, GePhexand snapshot applications like Camorama. I couldnt nd a single application that could do what we want, so I think that we could use something like Camorama as base and add continous video processing. Maemo uses gstreamer as the backend and their camera applications (which is closed) talks to it. Possible applications: many (xawtv, camE, Camorama, mplayer, videolan). There is one application being developed for the Google Summer of Code called Cheese that could be very handy. A Launchpad project was created and the latest version available (0.13) was pushed. It can capture video streams and stills. Have a plugin system that can be used, and already is, to apply effects. Uses gstreamer as the backend. Its written in GTK. Its far from complete. It has severe bugs in interface with v4l2 and does not work at all with V4l. As a matter of fact, so far I wasnt able to make it work with 3 different cameras.

Ubuntu Mobile Guide


17 / 99

Ebook reader Theres one FOSS champion: fbreader which is the one used by Maemo. It can read a several formats like: fb2 e-book format (style attributes are not supported yet). HTML format (tables are not supported). CHM format (tables are not supported). plucker format (embedded images are supported, tables are not supported). Palmdoc (aportis doc). zTxt (Weasel format). TCR (psion text) format. RTF format (stylesheets and tables are not supported). OEB format (css and tables are not supported). OpenReader format (css and tables are not supported). Non-DRMed mobipocket format (tables are not supported). Plain text format. Disadvantages Cant read DRMed books which can be a problem to commercial applications. MikhailSobolev: DRM formats are mostly proprietary and their specications are usually very well closed A proprietary one, Mobipocket, seems to be an interesting option. They have a closed java lib that needs an UI. Thats the way its used on the PepperPad. It can handle DRMed ebooks. Theres a limited number of formats supported. Currently only OpenEBook (OEB) besides itself. Only for CHM there is alternatives like xchm and kchmviewer. Not very useful anyway. Theres others like dotReader but mostly based on its own format or use Palmdoc/plucker only. For IM Pidgin (formerly known as Gaim) covers the specication out of the box with one exception, the Myspace IM protocol. There is a plugin in the works, still alpha quality but it is already able to: Send and receive instant messages Buddy list support (basic support only) Look up user information (in Get Info and tooltip text) (Some) formatting of incoming instant messages For Video Conferencing Ekiga is the preferred application in the specication. It covers the specication already. Its a gnome application, so should not be difcult to integrate. Supports STUN.

Ubuntu Mobile Guide


18 / 99

Its know to be problematic sometimes. wengophone A current option for Ekiga is wengophone It can also work also as a IM client. Using the Wengo service, calls to landlines and cellphones can be done. Interface is based on Qt. For an Ofce document viewer Excluding PDF that can be read by Evince for instance, there is no FOSS software available to this kind of task but some very old lters or format converters that only could be used with very old Microsoft formats. At this moment I can foresee 2 possibilities related to FOSS software. Include the appropriate lters into evince Evince would become an universal viewer of sorts, handling all the viewing necessities in one place. Disadvantage It would be quite some work to integrate, say, the Abiword lters into it. Modify the Ofce package of choice to have a simplied, read only mode, therefore using the same application for view and edit les Advantage I guess that would be an easier task than modify Evince. Disadvantage Its inconvenient to load the ofce application just to view a le. TextMaker Viewer There will be a commercial product called TextMaker Viewer that ts very nicely but it does not exists yet and looks like to be based on Qt. For Casual Games The specication asks for more action-packed games. Some suggestions, depending on the prole: All-time favorites Pingus SuperTuxCart SuperTux Tux Racer Frozen Bubble Card games PySol Educational Games

Ubuntu Mobile Guide


19 / 99

GCompris If the machine can handle Open Arena Thunder&Lightning Emulator ScummVM There is a huge selection available. It is just a matter of choosing. RSS reader Theres plenty of them available. The more suitable ones for our needs are Liferea and Straw. Both are quite equivalent but Liferea is starting to make incursions to integrate with blogs which is an interesting feature. A second option is to use the one integrated into the email reader. Both Thunderbird and Claws suggested above can do it. For the Clock This item is just a matter of choosing what gadget would t best into the current home applet environment as the requirements are quite common except for the fact that it requires the clock to run full screen but this should not be difcult to achieve. The original Maemos panel clock or this clock applet can do that. Another option is GPEs clock that is be an interesting option if the GPE PIM described below is chosen. For PIM The GPEcan provide all the PIM needs easily. Some of the projects we can make use are: Contacts Calendar Sketchbook Voice Recorder Today Todo List Time Tracker Another option is Pimlico For a Remote desktop client Currently, we have tsclient which is a wrapper that actually runs rdesktop and vncviewer on demand. This covers the specication with the exception of the listed functions: Scaling an panning: needs to be implemented on the clients but, despite not being in upstream, this has been done before. Stylus to Mouse click conversion is a matter of choosing input methods. There is no consensus around this yet and some additional work might be necessary to give to the user a better visual feedback. Other suggestions - TBD Simple image manipulation Should this be integrated with the media player? Ofine blogging client

Ubuntu Mobile Guide


20 / 99

Simple html-capable wysiwyg editor and posting tool (ftp and common blogging APIs) Voip client Should be the same used for video conference? Ekiga Twinkle OpenWengo GPS software / Navigation software GeoClue seems to be a good starting point and there is a Maemo port already. Quick voice/audio recorder/audio notetaker [...] Image posting client (ickr/windows image posting wizard) [...] Packaging status fbreader - pushed. Cheese - pushed.

2.3

Mobile User Interface

Given the similarities in function and system characteristics to Nokia N-level hand-held devices, Nokias Hildon Application Framework was selected as the underlying application/UI framework. The UME user interface will look markedly different and be designed with user and OEM customization in mind.

Figure 2.2: Mobile Internet Device UI System Characteristics Low-power, hand-held mobile device

Ubuntu Mobile Guide


21 / 99

Screen dimension: 4.5" to 7" Screen resolution: 800x480 up to 1024x600 (expected) @512MB SSD, @512MB RAM (depending on model) Limited or unknown hardware controls (UI needs to be able to do it all) Mobile devices are not general purpose desktops. Generally they will have fewer applications than a desktop (~20 instead of 100s). It is assumed that the primary applications would be: Browser Multimedia apps (music, movie, photo) Chat Email Camera Location/GPS Games Conguration applets Design The core components are those found in GNOME Mobile, including GTK, matchbox window manger, and the Hildon Application Framework. The UME Home Screen consists of one or more panels containing panel widgets/applets, and a large open area containing home widgets/applets. The panel at the top is called the "Marquee". It is present when applications are running and contains the application menu applet and close application applet. The number of panel and home widgets is restrained by space only. It will be possible to congure the order and location of widgets. The Maemo UI also has these elements. Below is an image showing these pieces:

Ubuntu Mobile Guide


22 / 99

Figure 2.3: Interface Mobile Internet Device UI

Figure 2.4: Mobile Internet Device UI Hide the task navigator (a panel). (/etc/hildon-desktop/desktop.conf le change) Create a new panel and place it at the top. (/etc/hildon-desktop/desktop.conf le change) Add new plugins to our top panel (application menu and statusbar)

Ubuntu Mobile Guide


23 / 99

Change the theme Create a home area plugin for navigation.

2.4

Window Manager

Mobile devices have smaller screens and usually do not have mice, so the normal WIMP (windows, icons, menus, pointer) paradigm isnt a great t. We therefore have to use a different window manager than usual. A detailed description of the goals and guidelines have been compiled in the UI Application Design Guide

2.5

Mobile Architecture

The new architecture name is lpia, this needs to be put into archtable in dpkg and apt. Architecture needs to be added to soyuz and buildds set up. Spec/default compilation ags to be provided by Intel. -mtune=pentium and gcc-4.1 is appropriate and gets us the needed optimisations. The toolchain, including the headers from the kernel, is built and uploaded (usual two-stage bootstrapping procedure). Since its binary compatible with ia32 we will use that as a base rather than cross-compiling. Architecture is hooked into the normal build system and packages built there as usual. Packages-arch-Specic needs to have lpia added to it for packages that we want on lpia. A number of source packages require changes to debian/control to have lpia added to their Architecture line, as well as adjustments to debian/rules.

2.6

Image Creation

The development process for a mobile device tends to be different from the normal process used for workstation/laptops/servers, where the developer would not normally use the mobile device for their development environment, and where there is need to generate a complete OS image from the developers working environment that is then installed on the target device. In the case of the Ubuntu Mobile project, a complete set of built packages is available to the developer, so a lot of the complexities associated with existing build-your-own-os-from-scratch project are just not needed. To bridge the remaining gap between Ubuntu-Mobile development we use a new tool called project-builder Features There are three fundamental features that project-builder provides: The creation of a platform specic build environment The creation of platform specic target le-systems A user selectable "feature sets" (or fsets) to install bundles of packages that provide some high-level functionality It also offers some additional advantages such as: The choice of a fully functional graphical user interface or a purely command line interface Wrappers for chrooting into a buildroot or target le-system(i.e. bind mounting important system directories and copying over network conguration les) Wrappers for opening Xephyr windows for testing target le-systems

Ubuntu Mobile Guide


24 / 99

Utilities for creating live USB images of target le-systems for easy testing of multiple target le-systems Developer uses project-builder to start a new project Here we assume that: The project is congured to work with a mccaslin type of device The project is given a name myproject for future reference The project is given a description of "My Samsung Q1 Ultra project" The project creates a complete buildroot in /usr/src/myproject
$ sudo project-builder -c create-project \ --platform-name mccaslin \ --project-name "myproject" \ --project-path "/usr/src/myproject" \ --project-description "My Samsung Q1 Ultra project"

Developer uses project-builder to create a new target lesystem Developer creates a new initial target device lesystem: Since a project can create multiple target lesystems, the target is named target1 The new target lesystem is rooted at /usr/src/myproject/targets/target1/fs
$ sudo project-builder -c create-target --project-name "myproject" \ --target-name "target1" \

Developer installs the Ubuntu-Mobile default set of packages for a full UI Developer installs the "full-mobile-stack" functional set (fset) The "full-mobile-stack" is a meta fset that depends on the Core, Infrastructure, GNOME-Mobile, Mobile-Applications, and Power-Management fsets After installing this fset, the target lesystem has enough functionality such that once installed on the target device, the device can boot to the ubuntu-mobile installation and automatically startup into the hildon desktop with the standard set of ubuntumobile applications
$ sudo project-builder -c install-fset --project-name myproject \ --target-name target1 \ --fset-name "full-mobile-stack" \

Developer tweaks the target lesystem as desired The developer has the choice of building new mobile software from the project buildroot (which comes with the basic ubuntumobile development packages installed), or building from their Gutsy host The software will then need to be installed in the target lesystem. If building from the buildroot, then the target lesystem is located at /targets/target1/fs, and if building from a Gutsy host, then the target lesystem is located at /usr/src/myproject/targets/target1/fs Developer builds test the target lesystem on host system Developer installs the Xephyr server in their workstation and starts a new Xephyr window

Ubuntu Mobile Guide


25 / 99

The "full-mobile-stack" is a meta fset that depends on the Core, Infrastructure, GNOME-Mobile, Mobile-Applications, and Power-Management fsets
$ sudo apt-get install xserver-xephyr $ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac &

Developer uses project-builder to chroot inside the target lesystem Bind mounting /proc, /sys/, and /tmp Copying over host network conguration les Starting target daemons like dbus Creating a fresh environment such that applications are not broke with host specic settings
$ sudo project-builder -c chroot-target --project-name myproject \ --target-name target1 Password: XXXXX # \

Developer launches the hildon-desktop


# start-hildon-desktop &

Developer Creates an Installation Image Project-builder provides several mechanisms for installing the new target lesystem on the device, including: USB Install (boot a USB key that installs the target lesystem on the device) Live USB (boot a working live image off a USB key) Live RW USB (boot a working live image off a USB key that persist changes to the key) ISO Install (user boots off a USB CD that installs the target lesystem on the device) Live ISO (boot a working live image off a CD) For this usage case, the developer creates an "Install USB" image and then writes the image to a USB key that shows up as /dev/sdb on the developers workstation
$ sudo project-builder -c create-install-usb \ --project-name myproject \ --target-name target1 \ --image-name live-usb.img $ sudo dd if=/usr/src/myproject/targets/target1/image/live-usb.img of=/dev/sdb

Developer Installs the target lesystem on the device Developer plugs in the USB key to the device and then boots device and enters the BIOS conguration and congures the boot options to boot off a USB key The device boots, automatically installs the target lesystem, and then shutdown The developer unplugs the USB key and boots the device to see the running ubuntu-mobile stack

Ubuntu Mobile Guide


26 / 99

Build system generates an image for a given device The build system uses the project-builder command line capabilities to create target images
# Inside the build script.... # $PLATFORM is the name of the platform # $BUILDROOT is the build working directory # $DEST is the directory to place the target image # Delete any existing build project project-builder -c delete-project --project-name build 2> /dev/null || true # Kick off a clean project project-builder -c create-project --platform-name $PLATFORM \ --project-name build \ --project-path $BUILDROOT \ --project-description "Build system" # Install a new target in the project project-builder -c create-install-usb --project-name build \ --target-name buildtarget \ --image-name install.img

# Install the standard mobile stack in the target project-builder -c install-fset \ --project-name build \ --target-name buildtarget \ --fset-name "full-mobile-stack" # generate the an install USB image project-builder -c create-install-usb --project-name build \ --target-name buildtarget \ --image-name install.img

mv $BUILDROOT/targets/buildtarget/image/live-usb.img $DEST

Implementation The project-builder tool can be used as either a command line tool, or as a GUI if no command line arguments are provided. For a list of available command line arguments, use the --help argument:
$ project-builder --help Usage: project-builder [options] Options: -c CMD, --command=CMD Where CMD is one of: chroot-project, chroot-target, create-install-iso, create-install-usb, create-liveiso, create-live-usb, create-project, create-target, delete-project, delete-target, install-fset, listfsets, list-platforms, list-projects, list-targets, update-project, or update-target --platform-name=PLATFORM_NAME Platform name --project-name=PROJECT_NAME Project name --project-description=PROJECT_DESC Project description --project-path=PROJECT_PATH Project path

Ubuntu Mobile Guide


27 / 99

-t TARGET_NAME, --target-name=TARGET_NAME Target name --fset-name=FSET_NAME Feature set identifier --image-name=IMAGE_NAME Name to use for target image file -q, --quiet dont print status messages to stdout -d, --enable-debug Enable additional debug package while installing fsets -h, --help show this help message and exit

Examples: <Adding a new project> project-builder --command=create-project \ --platform-name=mccaslin \ --project-name=MyProject \ --project-desc=Example project \ --project-path=/usr/src/projects/myproject <Delete a project> project-builder --command=delete-project \ --project-name=MyOtherProject <Adding a new target to an existing project> project-builder --command=create-target \ --project-name=MyProject \ --target-name=MyTarget <Delete a target> project-builder --command=delete-target \ --project-name=MyProject \ --target-name=MyOtherTarget <installing an fset into a given target> project-builder --command=install-fset \ --platform-name=mccaslin \ --project-name=MyProject \ --target-name=MyTarget \ --fset=Core \ <change into a given project buildroot filesystem> project-builder --command=chroot-project \ --project-name=MyProject \ <change into a given projects target filesystem> project-builder --command=chroot-target \ --project-name=MyProject \ --target-name=MyTarget \ <updating a given target inside a project> project-builder --command=update-target \ --project-name=MyProject \ --target-name=MyTarget \ <updating a given project> project-builder --command=update-project \ --project-name=MyProject

GUI

Ubuntu Mobile Guide


28 / 99

Figure 2.5: Project Builder GUI

Ubuntu Mobile Guide


29 / 99

2.7

Mobile Kernel

This kernel will specify a kernel conguration optimized for the smaller and more restricted hardware that is typically used by mobile and embedded devices. The generic kernel conguration is intended to cater for the wide variety of hardware devices found on desktop and laptop systems. As such, the conguration species a large variety of devices and subsystems (e.g. ATM, SCSI drivers, lesystems) which are not necessary for the UME project. Design and Implementation A reduced-cong UME avour will be added to the i386 avour. This avour will have all unnecessary or impossible cong options stripped out of it. A new "lpia" arch will be added to the linux-image, linux-ubuntu-modules and linux-restricted-modules packages. The UME avour will be added to these for the "lpia" arch specically customized for the initially targeted devices. Flavour-specic congurations will be added to the linux-image, linux-ubuntu-modules, and linux-restricted-modules package, in order to make it easier to build device-specic out of tree code for only one avour. Various third party patches may need to be applied for specic congs, for example from http://www.linuxpowertop.org/ or to add SDIO support to the mmc layer. These will be assessed by the Kernel Team on a case-by-case basis.

2.8

Mobile Hardware Decode

Future chipsets will have the ability to do hardware accelerated video decode of MPEG-2, MPEG-4 (part 2), H.264 (MPEG-4 part 10) and VC-1 (WMV)

Ubuntu Mobile Guide


30 / 99

Figure 2.6: Overview of Architecture Implementation of this spec will require a new package to provide the generic VA API in the form of libva. This library communicates with the X server to nd out which hardware specic driver will be needed and will then load that hardware specic driver to do the actual work. libva will be open source licensed under a MIT style license.

Ubuntu Mobile Guide


31 / 99

Figure 2.7: Deliverables The hardware specic driver that libva will open will be provided as part of the graphics driver.

2.9

Gnome Components

GNOME Mobile is a SW stack that is a subset of the GNOME Desktop platform. The components were put together by Nokia and other companies involved in creating embedded systems. Details of their work is here: Gnome Mobile

Ubuntu Mobile Guide


32 / 99

Figure 2.8: GNOME Mobile components Matchbox: Window Manager Pango: Text Layout Cairo: 2D Rendering ATK: Accessibility Toolkit Gnome VFS: Virtual FS BlueZ: Bluetooth Telepathy: IM/Presence GConf: Conguration DBUS: IPC GStreamer: Multimedia E-D-S: Contacts / Calendar Avahi: Service Discovery

2.10

Screen Keyboard

For text input on the go, Ubuntu mobile and embedded edition features a highly congurable on-screen keyboard. The following mock-ups are examples of what can be done with the onBoard code, not direct suggestions for nal layouts. QWERTY As boring and inefcient as it is, Qwerty is something people will expect. To reduce the space requirements numbers and symbols should be moved to a separate layer. Qwerty keyboards on small devices are usually best used with the stylus as the keys tend to be small. Mobile phone inspirate A keyboard that looks and works like a mobile phone keypad takes up much less space but is also less efcient in use. As on a mobile phone, there are several letters on each key. Press a key several times in a row or for a certain interval to get the second and third letters. The advantage is many people are already highly skilled at this form of text input.

Ubuntu Mobile Guide


33 / 99

Full sidepad This 5x7 key keypad contains all the letters in a typical alphabet plus some symbols and modier keys. As with Qwerty this keypad will likely require use of the stylus.

Figure 2.9: Keyboard Frequency optimised sidepad This 4x5 keypad only has the 20 most commonly used letters of a given language in this case English. The remaining 6 letters combined are only needed once every 5 keystrokes. These can be found on the sym layer along with numbers and punctuation. Combinations of sym and shift yields 4 layers with 80 characters (of which 52+ are lower and upper case alphabet). The advantage of this keyboard is that it is small but can still be operated efciently with the thumb on one hand.

Ubuntu Mobile Guide


34 / 99

Figure 2.10: Frequency Optimised Keyboard

2.11

Mobile Browser

The Mobile Internet Browser for UME will be a nger-navigable browser based on Mozilla. We will start with a recent version of the Mozilla libraries using a recent Firefox 2.0+ tag. The browser will be re-chromed to match the look and feel of other UME applications according to the UI Style Guide Rationale A xul-based browser with high-standards compliance and a strong community is desireable. Mozilla is the most obvious choice. The only concern with a Mozilla-based solution is the performance on a resource-constrained device. Goals for the browser include the following: xul-based strong community strong adherence to standards standard for all mobile internet devices supports plugins supports extensions nger-navigable user interface based on best-of-breed existing solution (Firefox)

Ubuntu Mobile Guide


35 / 99

Minimo was investigated but after discussions with the maintainer (Doug Turner) we agreed that a Firefox-Mozilla base would be appropriate given our constraints and device characteristics. The Mobile Internet Browser will be based on Gecko 1.8+. Mozilla will release a new version based on Gecko (1.9) in the late part of the year (Oct or November). At that time we can consider the steps to move the browser to this base. Mozilla engineers have suggested that there may be some form of "Mozilla Mobile" solution down the road. This will be interesting to track, contribute to, and leverage. Mozilla can not offer engineering help on the browser work but they are supportive of the effort. Ideally we would get a solution that would be embraced by the Mozilla community and eventually adopted as the "Firefox Mobile" solution. However, Firefox brand sharing is not something that happens in the short term. Scope The project encompasses all of the tasks needed to get a Mozilla-based browser ported to the Hildon framework and included in Ubuntu-mobile distribution. Design Browser design is a mix of existing Firefox features, Hildon application framework constraints, and UI Style Guide recommendations. The browser user interface will be redesigned to accomodate nger navigation and the small mobile device screen (800x480 to 1024x600). Design wireframes include the following. These are recommendations. Actual implementation can vary somewhat and also be progressive -- changing and improving in time.

Ubuntu Mobile Guide


36 / 99

Figure 2.11: Mobile Wireframe Implementation The following are the steps to completion of the mobile browser: Selecting a branch of the Mozilla tree to use as the base browser. (Firefox 2.0.0.4 selected) Build the project. Re-brand and re-theme the browser, removing all reference to Firefox and all copyright material (e.g. help les). Make sure that we are legally compliant with Mozilla guidelines. Get the newly-named browser into Ubuntu-gutsy. (see Outstanding Issues below) Begin porting to Hildon Menu ported to top-left menu (replace Gtk calls) Top-level window uses Hildon classes Status bars and tabs at the bottom of the screen (hard task) re-chrome other features improve scrolling feature to be like wireframes with large thumb track

There is a lot of opportunity to divide and conquer the browser. We welcome help from any experts.

Ubuntu Mobile Guide


37 / 99

2.12

Mobile Graphics

X11 2D User Mode Driver Mesa/DRI 3D User Mode Driver Generic DRM kernel module with new memory management code DRM chipset specic kernel driver module Design The drivers will be dependent on the the new DRM Video Memory Manager as described by: Video Memory Manager Also the driver will therefore be dependent on Mesa 7, recently made available in Gutsy. Meas 3D The drivers require X Server 1.3 or newer.

2.13

Power Management

Power optimization for PC Architecture is vastly different from that for embedded systems such as ARM based PDAs or Cell phones. This is because each embedded chipset has its own unique set of power management features that require a custom avor of linux built from the ground up. PC based chipsets already have a well established code base in linux, with existing hardware interfaces such as ACPI and HAL; and as they have evolved from desktops into smaller, more portable systems, a wealth of software packages have been created to optimize power. Each of these packages can be thought of as a power micro-policy controller for a specic subsystem on a linux based platform. For instance cpufreq manages power for the CPU supsystem, or the iwcong interface manages device specic power for the Network (WLAN) subsystem. Currently all these micro-policy managers function independantly of one another and with little or no information from the user domain. Thus there are two things lacking in linux with regard to power. The rst is a centralized policy manager which can gather input from ACPI, the user, and running applications to generate a complete picture of how the device is being used. This information can be used to create macro-policies which can selectively tune or override the systems micro-policy managers to achieve far greater power optimization. The second piece missing is a scheme to create micro-policy managers for all power-hungry subsystems that dont currently support any form of control. Architecture usage model Where is the user and device (e.g. stationary vs moving, near to vs from from a power source, inside or outside When is the device being used (e.g. night vs day) How is the device being used (e.g. is the user listening to it, looking at it, controlling it) What is the device being used for (e.g. using network, playing audio, displaying video, high vs low performance) Micro-policy focus is on the subsystem and driver level Groupings by power optimization capability CPU (single or multi-core) Network (LAN, WLAN, WWAN) Storage (Harddisk, Flashdisk, DVDROM) Human Interface Devices (Mouse, Keyboard, Touchscreen) Video (LCD, Graphics card Audio (Speakers, Headphones, AC97, HD Audio) Wireless Connections (Bluetooth, GPS)

Ubuntu Mobile Guide


38 / 99

Architecture The power policy manager for linux is meant to be a universal, cross-platform framework for reducing power consumption in linux based devices; with particular focus on handhelds. It is implemented in three parts: a conguration data layer, a micro policy engine control layer, and a daemon that ties the two together. Conguration Layer: Provides conguration element messages from a GUI, applications, and system agents which describe the optimization potential in the system. e.g. user focus, device position, handling, and movement, and application needs. The Conguration Element Interface (CEI), will be based on Dbus and can be used by applications or a GUI to provide usage model information to our power manager daemon. Usage model info is intended to help us understand where, when, how, and for what purpose the device is being used. These attributes can help us intelligently regulate power and performance to match the users neds and expectations. MPE Layer: Provides tunable element control access to all the subsysems on the platform. e.g. LCD brightness, Audio codec, etc. The MPE Interface (MPI), will be used to control any subsystem micro-policy managers which are already available to us. Subsystems are determined as a collection of devices which serve some common purpose that can be optimized for power cleanly. Micro-policy engines will exist for each subsystem we intend to control. PPM Daemon: Denes what groupings of conguration elements are conguratble from the GUI, and the mappings between conguration and tunable elements. Constraints No dependence on knowledge of specic applications or drivers Should exist entirely in user space so theres no kernel dependency Use C as the default programming language Leverage established linux protocols and interfaces wherever possible No dependence on knowledge of specic applications or drivers Should communicate with applications and GUI through a Dbus interface Should use ACPI for system event notication Conguration Input Layer Conguration Element Interface (CEI) The CEI will be implemented as a simple DBUS function call using the glib-dbus; wrappers. With this strategy, an xml le is created which describes the function:
<node name="/PPM"> <interface name="com.intel.cei"> <method name="SendConfigurationElement"> <arg type="s" name="config_element" direction="in" /> <arg type="s" name="target" direction="in" /> <arg type="s" name="svalue" direction="in" /> <arg type="i" name="ivalue" direction="in" /> </method> </interface> </node>

Using the dbus-binding-tool provided by glib we can then create a server and client header le that enables the usage of this function. The function will look like this:
gboolean send_config_element(DBusGProxy *proxy, char *element, char *target, char *svalue, int ivalue);

Ubuntu Mobile Guide


39 / 99

Element: is the string name of a predened cong element that the PPM Daemon will accept.vers target: is the specic hardware target of the cong element (hda1 for instance if there are more than one hd) svalue: is the string data value, which is designed to be general and user friendly (like low, med, high) ivalue: is the numerical data value, which is designed to be very specic (like X percent or X kbps) The PPM Daemon will act as the server and the single receiver of the function call, and any number of applications or a GUI can act as clients by sending elements out through this function. The ppmd server is called through the DBUS server connection, and therefore must have the proper conguration les in place for the DBUS daemon to allow it to run. Conguration Element List These data points represent very specic conditions which may affect power or performance. Some can be used immediately for obvious purposes, but some are just there as placeholders for some future benet. The user will likely never provide this information manually at this level. Usage model data at this granularity will be provided by the system (ACPI, HAL, Applications, or the GUI in the form of a macro). Each type of input can be broken down into a set of specic "conguration elements" which are what is actually sent across DBUS. User Focus These refer to how the user will interact with the MID. These represent the only things that the user MUST tell us. Visual Attention no visual (e.g. listening to a playlist of music) intermittent visual (listening to music and picking songs) constant visual (e.g. watching a video, playing a game) Aural Attention no audio (e.g. without headphones in a public place) intermittent audio (e.g. waiting for IM alert) constant audio (e.g. listening to music or watching a video) Device control no interaction (e.g. watching a movie, or listening to a playlist of music) intermitent interaction (e.g. browsing the web, pausing to read) constant interaction (e.g. playing a game) Target Battery Life 1 hour (e.g. just enough for a meeting or class) 2 hours (e.g. just enough to watch a movie) 4 hours (e.g. just enough for a plane ride) 8 hours (e.g. enough for a work day) maximum (as much as possible) Device Position These refer to the physical position and state of the MID. They are things that for the most part the user will have to enter, but we can work to make most of these automatically detected Device movement stationary moving

Ubuntu Mobile Guide


40 / 99

Cong Element(string) videofocus audiofocus userinput tgtbattlife

Target(string) Value(string) Value(int) lcdmon,extmon,exttv none,rare,intermittent,often,constant (reaction time needed) X ms speakers,headphones,ext none,rare,intermittent,often,constant (reaction time needed) X ms keypad,mouse,touchscr,cameranone,rare,intermittent,often,constant (reaction time needed) X ms all 1hour,2hour,4hour,8hour,max X minutes til off Table 2.1: Energy Focus

* slowly (e.g. walking, jogging) * intermittent high speed (e.g. in a car driving and stopping) * constant high speed (e.g. in a plane or train) Proximity/Accesstime to power source or wi connectionDevice movement Plugged in (ACPI Event) * * * * * AC wall socket DC Car jack DC Aeroplane jack DC Solar Charger External Battery

X minutes until power source/wi available (ETA) * * * * * * immediately (e.g. in a car, at home, airport terminal) less than 20 (e.g. in transit between home and work) less than 120 (e.g. general mobile usage) less than 240 (e.g. a standard plane ride in coach) less than 480 (e.g. a standard college school day) very large (e.g. on a camping trip)

Device handling is in a stable position (e.g. on a desk or on someones lap) is being jostled (e.g. held while walking, or in a backpack) Geographic Location (user input or GPS detection) Country e.g. for cellular standards, radio freq ranges Rural vs Urban e.g. likelihood of cell tower or recharge Proximity to cell towers e.g. if one had a tower map On Land vs Water e.g. likelihood of cell tower or recharge Elevation e.g. too high for cellular

2.14

Power Thermal Optimizations

The platform thermal solution depends on the kernel framework for controlling the device performing state and monitor thermal sensor for the platform. The kernel thermal monitoring and controlling mechanism is spread across acpi thermal driver and non acpi thermal sensor driver, and the thermal algorithm are embedded in the kernel driver. The proposed patch is to extend the thermal driver and unify various thermal sensing/controlling property through sysfs interface so that platform level thermal related decision can be made at user space. The current thermal zone driver is modied to expose thermal properties of platform through Sysfs. A new thermal Sysfs driver is introduced which will export two interface for the platform specic sensor driver and component throttle driver. The cpu thermal driver will work as it is, but will interface with the thermal Sysfs driver.

Ubuntu Mobile Guide


41 / 99

Linux notebooks today use a combination of ACPI and native-device thermal control. System uses ACPI CRT/HOT trip point for critical system shutdown, since on a handheld, shutdown and hibernate to disk (if one even exists) are likely to be synonymous. Active trip points are of no use on systems which have no fans. That leaves the single PSV trip point. ACPI 2.0 can associate (only) a processor throttling device with a trip point. But the processor is not expected to always be the dominant contributor to thermal footprint on handhelds like it often is on notebooks. ACPI 2.0 includes the _TZD method to associate devices with thermal zones. However, ACPI does not say anything about how to throttle non-processor devices so that must be handled by native device drivers. Design Thermal monitoring will be done using inexpensive thermal sensors polled by a low-power EC. Thermal management policy decisions will be made from user space, as the user has a comprehensive view of the platform. The kernel provides only the mechanism to deliver thermal events to user space, and the mechanism for user space to communicate its throttling decisions to native device drivers.

Figure 2.12: Thermal Control Software Stack The thermal management policy control application sits on top. It receives netlink messages from the kernel thermal zone driver. It then implements device-specic thermal throttling via sysfs. Native device drivers supply the throttling controls in sysfs and implement device-specic throttling functions. The thermal zone module has two components a thermal zone sysfs driver and thermal zone sensor driver The thermal zone sysfs driver is platform-independent, and handles all the sysfs interaction. The thermal zone sensor driver is platform-dependent. It works closely with the platform BIOS and sensor driver, and has knowledge of sensor information in the platform. The thermal sysfs driver exports two interfaces

Ubuntu Mobile Guide


42 / 99

(thermal_control_register()

and
thermal_control_deregister())

to component drivers, which the componentdrivers can call to register their control capability to the thermal zone sysfs driver. The thermal sysfs drier also exports two interfaces:
* thermal_sensor_register() * thermal_sensor_deregister()

to the platform-specic sensor drivers, where the sensor drivers can use this interface to register their sensor capability. This driver is responsible for all thermal Sysfs entries. It interacts with all the platform specic thermal sensor drivers and component drivers to populate the sysfs entries. The thermal zone driver also provides a notication-of-temperature service to a component driver. The thermal zone sensor driver as part of registration exposes its sensing and thermal zone capability. Thermal Zone sensor driver The thermal zone sensor driver provides all the platform-specic sensor information to the thermal sysfs driver. It is platformspecic in that it has prior information about the sensors present in the platform. The thermal zone driver directly maps the ACPI 2.0 thermal zone denition. The thermal zone sensor driver also handles the interrupt notication from the sensor trips and delivers it to user space through netlink socket. Component Throttle driver All the component drivers participating in the given thermal zone can register with the thermal driver, each providing the set of thermal ops it can support. The thermal driver will redirect all the control requests to the appropriate component drivers when the user programs the throttling level. Its is up to the component driver to implement the thermal control. For example, a component driver associated with DRAM would slow down the DRAM clock on throttling requests. Thermal Zone Sysfs Property The intent is that any combination of ACPI and native thermal zones may exist on a platform, but the generic sysfs interface looks the same for all of them. Thus, the syntax of the les borrows heavily from the Linux hwmon subsystem. Each thermal zone provides its current temperature and an indicator that can be used by user-space to see if the current temperature has changed since the last read. If a critical trip point is present, its value is indicated here, as well as an alarm indicator showing whether it has red. If a passive trip point is present, its value is indicated here, as well as an alarm indicator showing whether it has red. There are symbolic links to the device nodes of the devices associated with the thermal zone. Those devices will export their throttling controls under their device nodes. Throttling Sysfs Properties Devices that support throttling will have two additional properties associated with the device nodes: throttling and throttling_max. A value of 0 means maximum performance, though no throttling. A value of throttling_ max means maximum power savings in the deepest throttling state available before device state is lost. Events will be passed from the kernel to userspace using the Linux netlink facility. Interrupts from the sensor or EC are delivered to user-space through a netlink socket. sysfs temp1_input temp1_alarm temp1_crit temp1_crit_alarm temp1_passive temp1_passive_alarm device_name1 device_name2 _CRT _PSV ACPI _TMP Description Current temerature Temperature change occurred Critical alarm temperature Crtical alarm occurred Passive alarm termperature Passive alarm occurred Link to device 1 associated with zone Link to device 2 associated with zone Table 2.2: Power Events Focus R/W RO RW RO RW RO RW RO RO

Ubuntu Mobile Guide


43 / 99

2.15

Power Policies

Power optimization for PC Architecture is vastly different from that for embedded systems such as ARM based PDAs or Cell phones. This is because each embedded chipset has its own unique set of power management features that require a custom avor of linux built from the ground up. PC based chipsets already have a well established code base in linux, with existing hardware interfaces such as ACPI and HAL; and as they have evolved from desktops into smaller, more portable systems, a wealth of software packages have been created to optimize power. Each of these packages can be thought of as a power micro-policy controller for a specic subsystem on a linux based platform. For instance cpufreq manages power for the CPU supsystem, or the iwcong interface manages device specic power for the Network (WLAN) subsystem. Currently all these micro-policy managers function independantly of one another and with little or no information from the user domain. Thus there are two things lacking in linux with regard to power. The rst is a centralized policy manager which can gather input from ACPI, the user, and running applications to generate a complete picture of how the device is being used. This information can be used to create macro-policies which can selectively tune or override the systems micro-policy managers to achieve far greater power optimization. The second piece missing is a scheme to create micro-policy managers for all power-hungry subsystems that dont currently support any form of control. Macro-policy focus is on the usage model Where is the user and device (e.g. stationary vs moving, near to vs from from a power source, inside or outside When is the device being used (e.g. night vs day) How is the device being used (e.g. is the user listening to it, looking at it, controlling it) What is the device being used for (e.g. using network, playing audio, displaying video, high vs low performance) Micro-policy focus is on the subsystem and driver level Groupings by power optimization capability CPU (single or multi-core) Network (LAN, WLAN, WWAN) Storage (Harddisk, Flashdisk, DVDROM) Human Interface Devices (Mouse, Keyboard, Touchscreen) Video (LCD, Graphics card Audio (Speakers, Headphones, AC97, HD Audio) Wireless Connections (Bluetooth, GPS) Architecture The power policy manager for linux is meant to be a universal, cross-platform framework for reducing power consumption in linux based devices; with particular focus on handhelds. It is implemented in three parts: a conguration data layer, a micro policy engine control layer, and a daemon that ties the two together. Conguration Layer: Provides conguration element messages from a GUI, applications, and system agents which describe the optimization potential in the system. e.g. user focus, device position, handling, and movement, and application needs. The Conguration Element Interface (CEI), will be based on Dbus and can be used by applications or a GUI to provide usage model information to our power manager daemon. Usage model info is intended to help us understand where, when, how, and for what purpose the device is being used. These attributes can help us intelligently regulate power and performance to match the users neds and expectations. MPE Layer: Provides tunable element control access to all the subsysems on the platform. e.g. LCD brightness, Audio codec, etc. The MPE Interface (MPI), will be used to control any subsystem micro-policy managers which are already available to us. Subsystems are determined as a collection of devices which serve some common purpose that can be optimized for power cleanly. Micro-policy engines will exist for each subsystem we intend to control.

Ubuntu Mobile Guide


44 / 99

PPM Daemon: Denes what groupings of conguration elements are conguratble from the GUI, and the mappings between conguration and tunable elements.

Figure 2.13: Power Policy Management Diagram Constraints No dependence on knowledge of specic applications or drivers Should exist entirely in user space so theres no kernel dependency Use C as the default programming language

2.16

Media Player

The media viewer application for mobile devices. This is not the spec for the underlying engine (e.g. gstreamer, helix, etc). The media player for UME will have a nger-navigable UI capable of viewing photos, playing music and videos, and using either the gstreamer or helix media engines with a common interface to them. The UI will follow the recommendations in the UI Style Guide Rationale There are some existing media applications but none seem to cover all of the features needed and be tailored for a MID, so a new UI is being written. The goal is to simplify the media management on the MID and provide a single place for viewing and listening to media.

Ubuntu Mobile Guide


45 / 99

Gstreamer and Helix media engines will be supported with dynamic discovery of the content types supported by whichever engine is present at runtime. Helix support is being included primarily for DRM solutions. The entire scope of media management is large, from the rst time a user obtains some content to consuming it on the device. The following section describes the full spectrum with the ones outside the scope of this application shown in red. Additional functionality may be added as time and resources permit. Comments welcome. Functional Specication PC = non-mobile device, such as a Linux or Windows desktop MID = Mobile Internet Device. Content = music les (mp3, etc), movies (.mpg, etc), photos (.jpg, etc) Media viewer = Multimedia application on MID 1. Content Management on the PC (Currently not planned) There are a few choices for music management on the PC (e.g. Windows Media Player, ITunes, Banshee). For movie and photo management, users often use the lesystem directly. Eventually a new "MID Content Manager" application could be written. 2. Getting content to the device 2.1 Syncing * Auto-sync with an application that manages content on the PC. This involves writing a new plugin or application that pushes the content from one of the following applications to the MID when the MID is plugged in via USB.

* Only sync down (all content is pushed to MID. Any MID content changes are lost * Sync in both directions: content is merged on PC and MID. Conicts are resolved by asking user for preference. * Auto-sync with a le directory on the PC (just le system). Application registered when MID is plugged in to USB to auto-sync contents. Manual-sync: Plug MID into USB port. MID le system exposed to PC. User drags/drops les from PC to the MID le system. * Sharing * Auto-detect other MIDs in area via bluetooth. Connect. Display shared content from each MID on other MID. User can download content to their MID. Receive email with content. Save content to MID lesystem. User Download on MID On MID, download content from internet via the browser On MID, download/upload content from wired or wireless connection to remote lesystem over network Content Management on MID User can: View content name, artist, album, length, genre, music format, times played, last played date/time

Ubuntu Mobile Guide


46 / 99

View content as list View content as thumbnails (album art for music, cover-art for movies or frame from movie, small image for photos) View content as resizable thumbnails View 3D-ipping album art Select content Select multiple les at the same time Organize content folders, create new folders, name folders, move content between folders * Assign content metadata: Name, Artist, Album, genre, cover art * Auto-lookup music metadata online from CDDC: Name, artist, album, cover art Create, delete, edit playlists Sort music by: Name, Date, length, Artist, Album, genre, type (mp3, wav, etc) Slideshow Create a slideshow of photos Assign a music le to play when slideshow is started Assign a music playlist to play when slideshow is started Set the time delay between photo transitions Set transition effect between pictures (fade, slide, etc) Content Playback on MID User can: Play content Pause content Play content at double speed forward and backward Play content at variable speed forward and backward Jump to beginning of content Jump to end of content Stop content View progress of content playback View time content has been playing Jump to location within the content by moving the progress thumb to a new location Video Play full screen video Pause and restart full screen video without leaving full screen Audio Show visualizations while playing audio Show visualizations full screen while playing audio

Ubuntu Mobile Guide


47 / 99

Start audio and play it in the background while performing other tasks Easily pause audio that is playing in the background Photo Show photos full screen. Navigate to next and previous photos Play slideshow Pause full screen slideshow and restart without leaving full screen Internet Radio User can: Create, edit, and delete internet radio stations Select a station and listen to streaming audio Add a new internet radio station from inside the browser. Content Plugins Media viewer will support mechanism for applications to register for certain content types and show buttons to launch these applications when the content of the registered type is selected. Plugin applications will be started with the paths to all the content as command-line parameters. Examples include internet upload, email, or any application to manipulate content. Theme / Skin Media viewer will use the system theme for all standard Hildon and GTK controls such as buttons, scrollbars, and dialogs. User can change the skin of the MID media viewer Media Engine Media viewer will be capable of using gstreamer or helix media playback engines User can select which media engine to use rst, or exclusively Media viewer will dynamically discover what content types each media engine supports and attempt to playback content on the correct engine Media viewer will show a symbol on content that is not supported by any media engines

2.17

Utilities

This spec describes the conguration utilities and control panel for UME. The user interface is built using the Hildon Application Framework. The framework provides for a control panel and control panel applets (or plugins). Each conguration utility will need to create a dialog-based conguration UI and a control panel applet to launch the UI. The use of the Hildon Application Framework directs the work and simplies it at the same time. The process of creating conguration utilities will be well-documented and straight forward. Use Cases The user wants to calibrate the screen. They go to Control Panel and select "Screen Calibration" The "Screen Calibration conguration tool pops up. The user congures the screen and exist the Screen Calibration tool. Scope This spec does not cover the details for each of the conguration utilities. However, the following conguration utilities must be created. (Ownership needs to be assigned):

Ubuntu Mobile Guide


48 / 99

Date and Time Screen Calibration Sound conguration System information (name, system specs (mem, disk space tot/avail, etc) Language Design The Hildon Control Panel displays icons for plugins that are used to congure system settings. The control panel implements a model for dynamic discovery. Correctly created, congured, and located plugins are automatically detected and displayed. Implementation - Creating a control panel applet/plugin The process of creating a control panel plugin is straight forward and entails creating a library with certain predened methods, creating a corresponding .desktop le, and placing both in the right place on the system. This [attachment:howto_write_control_panel_plugin.pdf] is a rst-draft describing the process. Outstanding Issues Hildon control panel is not yet functional in Ubuntu. Nokia has some new "refactoring" code for control panel. This needs to be packaged and added to gutsy.

2.18

USB Client

USB client controller driver, two gadget drivers of le-backed storage and CDC-EEM/RNDIS will be provided to end-user. Filebacked storage gadget provides the host with an access to disk image on the client platform. CDC-EEM/RNDIS gadget makes the client platform appear as a network adapter from the host stand point. Both Windows and Linux host system are supported. API Framework

Ubuntu Mobile Guide


49 / 99

Figure 2.14: API Framework The design is based on Linux USB gadget API framework. The peripheral controller driver implements the following functions according to Poulsbo USB client controller hardware: Initialize/de-initialize the PCI resources (memory, interrupt and DMA) Handle the USB device enumeration and USB bus events Transmit the data packets through USB endpoints Call back the upper level USB client device driver whenever necessary Mass storage gadget driver follows the protocol USB Mass Storage Bulk-Only Transport. It handles SCSI commands from host and USB requests bypassed from controller for device/cong/interface descriptor setting. CDC-EEM/RNDIS gadget driver follows Microsoft Remote NDIS Specication. It is responsible for the following operations: Provide the media state information to the host network stack by answering the RNDIS messages Works as an Ethernet interface device from remote host stand point of view, transmit the encapsulated 802.3 frames between host and the simulated Ethernet network in the format of the RNDIS messages

Ubuntu Mobile Guide


50 / 99

Monitor the USB bus events including connect, disconnect, suspend, resume, reset, and remote wakeup, and translate those events to corresponding actions to the Showwell NDIS stack Communicate through the PCI Network Interface, which provides the network adapter instance to the upper network stack on the client side OS Utility provides end-user an easy way to use exposed device by gadget drivers. It will use samba service to mount shared image le and DHCP to set IP address.

Ubuntu Mobile Guide


51 / 99

Chapter 3

Setting up the Development Environment and Creating Images


Creating an UME Image for your Device

Warning This procedure was tested and worked as described. All efforts will be taken to keep it up-to-date but please be aware that its based on software currently in development so your mileage may vary.

3.1

Summary

This document walks through the process of creating a working image for your mobile device using the Moblin Image Creator utility, described in detail here. Running this image on a device will boot the Linux kernel, load the appropriate drivers, start X, show the UI, and allow you to launch applications.

3.2

Supported devices

The Image Creator currently allows you to create an image for a Samsung Q1 Ultra. However, having this device is not necessary for application development. For application or driver development, or to simply test run the UI, you can run everything using Xephyr on your Linux workstation.

3.3

Development Environment

As described above, having the target device is not really necessary. Just a PC workstation running a GNU/Linux will be enough. Theoretically, any recent Linux distribution should work but this procedure was tested on Ubuntu Gutsy Gibbon (future 7.10) and 7.04. As a series of packages from the Gutsy repositories are need to build the project, a connection to the internet is required. To transfer the nal image to the device, one will need a RW-CD or USB Pen Drive (>= 512MBytes).

3.4

Concepts

The Image Creator uses the concept of Projects that are linked to Platforms and one or more Targets that is comprised of one or more "functional sets" or fsets. The Image Creator uses these elements to create an image. Each element is described below.

Ubuntu Mobile Guide


52 / 99

Project A project is a platform-specic build environment with one or more targets. When you create a project, Image Creator creates a full Linux lesystem in the directory you specify. Chrooting into this directory creates an isolated environment where you can develop software for your device. The environment includes apt tools, so you can install packages of the tools you need. The project directory includes one or more targets which are located in the <project location>/targets directory. Platform The platform is your target device. You select a platform when you create a project. This determines the kernel, system conguration, and device drivers that are made available as part of the targets you create within a project. Target The target is a platform-specic Linux lesystem, created in the /targets directory of your project. You create an image from a target. One or more targets can exist for each project. Like projects, you can also chroot into this environment to congure it or copy applications from your project before making an image. Function/Feature Set (fset) A functional (or feature) set is a group of packages representing some functional area that Image Creator can install on the target. An fset can have dependencies on other fsets. If you select to install an fset that depends on another fset, the prerequisite fset will automatically be selected and installed on the target rst. Image An image is a large (around 350MB) le created from a target. You can specify its name. An image can then be copied to a device using a USB pen drive or CD.

3.5
3.5.1

Install and Run Image Creator


Instalation

Just run
apt-get install moblin-image-creator

3.5.2

Creating an Image

As described above, the image is the nal result of the process. Its whats going to be used to install the le system that will run at the target device. There is two ways to create the image: using the GUI or using the command line. Both are described bellow.
3.5.2.1 3.5.2.1.1 Using the GUI Start the image creator

$ sudo image-creator

You will be presented with the main interface:

Ubuntu Mobile Guide


53 / 99

Figure 3.1: Interface What matters for now at this moment is the Platform Project session. The three buttons are use to Add a project, Delete a project or to open a terminal chrooted into the project selected in case any manual changes are needed.

Ubuntu Mobile Guide


54 / 99

3.5.2.1.2

Create the Project

Click the button Add and ll the options Name - Name of the project Desc - Description of this project (optional) Path - Where the projects and all related les will be placed Platform - Choose the target platform

Ubuntu Mobile Guide


55 / 99

Figure 3.2: Options

Ubuntu Mobile Guide


56 / 99

3.5.2.1.3

Wait for the installation

Tip It can take a long time to download and set up your project.It can be advantageous to set up a local cache which is explained at the end of this document

3.5.2.1.4

Create the target system

The next step is to create the target and add one or more functional sets. In this session of the interface we see the buttons Add, to add a target to the current project, Add Functional Set, to include a functional set or more to the selected target, Delete, to delete a target from the list, Terminal, to open a chrooted terminal inside the target le system and Kernel cmdline that can be used to add command line parameters to be used when the target kernel is executed. Name the target

Ubuntu Mobile Guide


57 / 99

Figure 3.3: Target


3.5.2.1.5 Choose a functional set

Moblin calls a bundle of packages an fset, where fsets can have dependencies on other fsets, and installing an fset will automatically install dependent fsets. For example

Ubuntu Mobile Guide


58 / 99

[Core] DESC=Fundamental fset that provides a root filesystem PKGS=linux-image-386 DEBUG_PKGS=gdb man-db manpages DEPS=

[Hildon-Application-Framework] DESC=Hildon Application Framework for enabling Mobile Applications PKGS=ubuntu-mobile sdk-default-icons DEBUG_PKGS= DEPS=core

Here the "core" fset provides additional packages to make it possible to boot a target lesystem and get to a command line prompt, and a "hildon-application-framework" fset that will install additional package (on top of core) to enable running a Hildon desktop.

Ubuntu Mobile Guide


59 / 99

Figure 3.4: Functional Set After the process is done, we will have a le system ready to be transfered to the target device or we can use the Terminal button to open a chrooted terminal and run the hildon environment directly in a Xephyr session.

Ubuntu Mobile Guide


60 / 99

3.5.2.1.6

Generate image

The last step, which can be optional, is to create the image for the target. There are ve different image styles that can be created, attached to the ve rst buttons in this session of the interface: Live USB - Create a live USB image that can be burned to a USB drive. You can boot and run directly from it. Nothing is written to the target device. Live RW USB - Same as the above but it supports data persistence. Every change made on the system while running this image will be saved on the USB drive. Install USB - The image will be suitable to install on an actual device.

Ubuntu Mobile Guide


61 / 99

Figure 3.5: Image Currently, only the Install USB image type is supported. Once the generation of the image is done, use the Write USB Image button to write it to your USB drive.

Ubuntu Mobile Guide


62 / 99

3.5.2.2

Using the command line

As stated before, the same steps above can be done using the command line. This is very handy once the parameters are already dened as we can process the whole projects in batch. The steps taken can be as simple as follows: 1. Create the Project
$ sudo image-creator -c create-project \ --platform-name mccaslin \ --project-name "myproject" \ --project-path "/home/user/myproject" \ --project-description "My Samsung Q1 Ultra project"

2. Create the target system


$ sudo image-creator -c create-target \ --project-name "myproject" \ --target-name "target1"

3. Install the functional set.


$ sudo image-creator -c install-fset \ --project-name myproject \ --target-name target1 \ --fset-name "samsung-full-mobile-stack-with-proprietary"

4. Create the image


$ sudo image-creator -c create-install-usb \ --project-name myproject \ --target-name target1 \ --image-name myproject_target1_install-usb.img

Once nished, a le called myproject_target1_install-usb.img will have the image ready to be burn to a USB drive and be installed in the target. Another option is to chroot to the generated le system with:
$ sudo project-builder -c chroot-target \ --project-name myproject \ --target-name target1

And from there run the hildon-desktop pointing to a Xephyr instance.

3.6

Speeding Up Image-Creator by using a local mirror server

This information is for LPIA (Low Power Intel Architecture) based builds. ** In order to use this, you must have a local mirror of LPIA Ubuntu Gutsy. debmirror is a useful command for mirroring a Debian type archive ** Setup a root strap mirror server

Ubuntu Mobile Guide


63 / 99

Create a directory ~/.image-creator/ Create a le called ~/.image-creator/image-creator.cfg containing:


[platform] buildroot_mirror = http://<path_to_a_local_mirror_of_ubuntu_gutsy_for_lpia>/ target_mirror = http://<path_to_a_local_mirror_of_ubuntu_gutsy_for_lpia>/

You can look at the le: /usr/share/pdk/default_cong/defaults.cfg for more info on what can go in the: ~/.image-creator/imagecreator.cfg le. Setup sources.list* rewrite rules Create a le called ~/.image-creator/sources_cfg containing:
sources_regex = [ # For the Ubuntu Gutsy LPIA binaries (rhttp://ports.ubuntu.com/ubuntu-ports gutsy, http://< path_to_a_local_mirror_of_ubuntu_gutsy_for_lpia>/ gutsy), # For the Ubuntu sources, since they are not at ports.ubuntu.com (rhttp://archive.ubuntu.com/ubuntu gutsy, http://< path_to_a_local_mirror_of_ubuntu_gutsy>/), # For the Moblin.org files (rhttp://www.moblin.org/apt gaston, http://<path_to_a_local_mirror_of_moblin.org>/ gaston), ]

The purpose of this le is to rewrite the sources.list and sources.list.d/* les while they are being copied into the rootstrap. It will replace the search expression with the replacement expression. Delete current rootstraps You have to delete your current rootstraps for this to take affect by doing:
sudo image-creator --command clear-rootstraps

Warning This will only affect new projects and new targets. If you do NOT delete your rootstraps after doing the above then it will NOT work.

3.7

Test the target image UI on the Workstation

Enable access to the display on your workstation (outside the target). The following command enables access only to the root user of your local system
# xhost +SI:localuser:root

Inside the target, launch the UI inside Xephyr window


# ume-xephyr-start

The ume-xephyr-start script shown above does the following # apt-get install xserver-xephyr # export DISPLAY=:0

Ubuntu Mobile Guide


64 / 99

# /etc/init.d/dbus start # xinit /etc/X11/xinit/xinitrc -- /usr/bin/Xephyr :2 -host-cursor -screen 1024x600x32 -dpi 96 -ac You should now see a working UI running in the Xephyr Window (here the default HTML UI with a user selected Palm Tree background)

Figure 3.6: Default HTML UI with User Selected background

Ubuntu Mobile Guide


65 / 99

Chapter 4

What is Hildon Desktop?


Mobile internet devices and tablets need a desktop framework that can provide a way to create applications with a very consistent look and feel and be prepared to run and interface nicely using restricted resources found on small devices like small resolution, little CPU power and storage. In addition, applications should be designed for touchscreen use, nger-friendly navigation, gestures, etc. The Hildon Application Framework is one of a few existing frameworks designed for small devices and is a good candidate for tablet use. It has strong support from Nokia and is a part of GNOME Mobile. This allows the Gnome community and others to contribute in a way that benets all users.

4.1

Hildon Desktop

Our major goal is to make it easy for distributions to package Hildon Desktop so that developers can have a quick-to-setup environment for the development of plugins The following is in somewhat prioritized order (from top down) to reach what is known as the Hildon UI. .

4.1.1

hildon-desktop

Hildon Desktop is the main UI component of the Maemo UI. It consists of two panels and the Home area. Each panel can house plugins and basically function like on an ordinary desktop environment except for that this user interface was designed for touch screen use on mind and was originally developed to Nokia 770 Internet tablet. Build-Depends: libhildon1-dev, libosso-dev, osso-af-settings, libhildonfm2-dev, libhildonhelp-dev Very closely tied with hildon-theme-plankton. .

4.1.2

hildon-1

The Hildon widgets. Contains generic application window as well as several specialized widgets designed for internet tablets. Very closely tied with hildon-theme-plankton. .

4.1.3

hildon-1

File management widgets. Implementation of GtkFileChooser designed for internet tablets. Build-Depends: libosso-dev, maemo modied gtk+ (for exporting parts of GtkFileSystem), libhildon-thumbnail-dev, osso-gwconnect-dev, mce-dev, libhildon1-dev, libhildonmime-dev .

4.1.4

hildon-thumbnail

API for getting thumbnails for les. Similar to GnomeThumbnailFactory but asynchronous, designed for low memory low performance devices. Includes thumbnailer plugin for les supported by GdkPixbuf. Build-Depends: libosso-dev .

Ubuntu Mobile Guide


66 / 99

4.1.5

libhildonmime

API for activating applications to handle certain MIME types. Similar to gnome_vfs_url_show() but uses X-Osso-Service eld in .desktop les and activates applications with DBus directly. Includes hildon-update-category-database which is update-mimedatabase (from shared-mime-info) modied to recognize additional elements. .

4.1.6

gnomevfs-obex

obex:// module for gnome-vfs Build-Depends: libopenobex1-dev, libgwobex-dev, osso-gwconnect-dev .

4.1.7

gnome-vfs-lechooser-backend

gnomevfs backend for GtkFileChooser .

4.1.8

gtklesystemmemory

GtkTreeStore which can be used as a in-memory le system backend for hildon-fm. Build-Depends: maemo modied gtk+ (for exporting parts of GtkFileSystem) .

4.1.9

hildon-thumbnail-libid3

hildon-thumbnail plugin for audio les (as supported by libid3.) (This is actually abusing the thumbnailing API by using the thumbnail for passing metadata about the audio les.) Build-Depends: libhildon-thumbnail-dev .

4.1.10

hildon-theme-plankton

The plankton theme (matchbox + gtk) Contains one big png which when built with the layout and tools produces a standalone theme package. Build-Depends: hildon-theme-layout-4, hildon-theme-tools .

4.1.11

sapwood

The theme engine. Similar to pixbuf engine but uses client-server design and pixmaps rather than pixbufs. Faster and more memory efcient than pixbuf engine, but doesnt do scaling or gradients. .

4.1.12

hildon-theme-cacher

A tool for generating a bytecode-ish cache le for gtkrc les to improve application startup time. Depends on maemo modied gtk+ (though the support for caching is actually missing at the moment.) .

4.1.13

hildon-theme-layout-4

gtkrc template for themes. The idea is that we maintain single gtkrc template (which is closely tied with the code) and implement different themes by only drawing a single png le. Build-Depends: hildon-theme-tools .

4.1.14

hildon-theme-tools

Tools for handling the theme building process. .

Ubuntu Mobile Guide


67 / 99

4.1.15

libosso

DBus convenience wrappers and hardware related callbacks. Build-Depends: mce-dev .

4.1.16

hildon-home-webshortcut

Plugin for hildon-desktop, shows a an image and opens a URL in browser when clicked. Build-Depends: libhildon1-dev, libossodev, osso-af-settings, libconic0-dev, libhildonfm2-dev, libhildonmime-dev, libhildondesktop-dev, hildon-desktop-dev .

4.1.17

hildon-control-panel

Control panel shell roughly similar to gnome-control-center. Control panel plugins are shared libraries rather than executables to save memory. Build-Depends: libhildon1-dev, libosso-dev, osso-af-settings, libhildonhelp-dev .

4.1.18

clipboard-manager

Subset of gnome-settings-daemon functionality, namely the cliboard manager to retain the clipboard contents after application exit and GConf-Xsettings bridge for a couple of settings .

4.1.19

maemo-launcher

Application startup time optimizer, a bit similar to kdeinit. Taking advantage of maemo-launcher doesnt require code changes, merely recompile. .

4.1.20

hildon-initscripts

Startup script, settings and environment variables for running gtk and matchbox with proper look and feel. Depends: osso-afstartup .

4.1.21

osso-af-startup

Startup scripts for for target device. Depends: osso-af-utils, osso-core-cong .

4.1.22

hildon-help

API for integrating with help UI. (The UI is closed source, but it may be possible to use yelp instead.) Build-Depends: libossodev, libhildon1-dev .

4.1.23

mce-dummy

Dummy package to satisfy package dependencies for mce. .

4.1.24

osso-af-settings

Contains pkgcong le providing directories where to put application, task navigator, status bar, home .desktop les, etc. .

4.1.25

osso-af-utils

Small utilities, for booting up and periodically cleaning up temporary les. Includes transparent cursor theme to hide the pointer.

Ubuntu Mobile Guide


68 / 99

4.1.26

osso-app-killer

Scripts for clearing user data and settings, resetting factory settings, shutting down application before running restore..

4.1.27

posix-locales

Locale data for languages

4.1.28

gazpacho-hildon

Hildon support for Gazpacho UI builder

4.1.29

hail

Accessibility support for hildon-1 and hildon-fm Build-Depends: hildon-libs-dev, hildon-fm-dev

Ubuntu Mobile Guide


69 / 99

Chapter 5

Anatomy of a Python Application in UME


5.1 Purpose

This chapter describes the les and directories you need to know about to add a Python application to the UME Hildon Desktop (Applications) > Extras menu. The rst section lists the les an application needs to be discovered, presented, and launched by the Desktop. The next section explains the "application directory" that contains source code and other application-specic les. The complete set of les that makeup a sample Python application is detailed. A sample make le is provided.

5.2

Application les

Each Python application requires the following les: Desktop le -- Describes the application to the UME Desktop. The presence of this le in the right location informs the Desktop that the application exists and provides information necessary to display it in a menu and launch it. Executable le -- The le the Desktop runs to execute the application. For Python applications, this is a shell script that launches the Python interpreter and is passed the applications main Python le. Main Python code le -- The main python le for the application Additional optional les may include the following: Additional Python or other application-specic les Glade user interface le(s) -- The XML le(s) produced with Glade and imported into Python that describes the applications user interface objects Icon -- The icon displayed in menus to represent the application before it is launched. Before taking a closer look at these les, lets take note of an applications dedicated "application directory."

Ubuntu Mobile Guide


70 / 99

5.3

Application Directory

"Core" application-specic les (those that are not related to registering the application with the Desktop or displaying it in the user interface prior to launching) reside in a dedicated "application directory." The application directory contains: The main Python le Any other application-specic les your code may need, such as other Python les or your Glade user interface description le(s) The application directory is a subdirectory of: /usr/share In the example explained here, the applications directory is named pyglade, as follows; /usr/share/pyglade For the sample application considered in this wiki page, this directory contains the following: main.py -- the main Python le pygladeui.glade -- the Glade user interface description le Now, lets take a tour of the actual les, starting with the critical .desktop le.

5.4

Application auto-discovery via the .desktop le

The Desktop automatically discovers applications that have a .desktople in the /usr/share/applicationsdirectory. This le always starts with "[Desktop Entry]" and continues with a number of key value pairs that dene the application to the Desktop, including: the le name of the applications executable -- the Execkey the name of the the application to display in the applications menu -- the Namekey the le name (without the le extension) of the icon to display along with the name in the applications menu, if any -- the Iconkey Heres a sample .desktop le:
[Desktop Entry] Version=1.0.0 Encoding=UTF-8 Name=PyGlade Type=Application Exec=/usr/bin/pyglade Terminal=false Icon=pyglade_26 Categories=Applications

Currently, applications with a valid .desktop le are presented to the user in the (Applications) > Extras menu. The executable and icon les are described below.

Ubuntu Mobile Guide


71 / 99

5.5

Executable le

The Desktop doesnt launch Python les directly. Instead, the Desktop launches the executable specied with the Execkey in the .desktop le. This executable is usually a simple shell script that does two things: it switches to the applications directory it launches Python and passes it the applications main Python le (which resides in the applications directory). Here are details: Run time location: /usr/bin File name extension: Can be anything Example: /usr/bin/pyglade Type: For Python applications, this is generally an executable shell script. Sample:
#!/bin/sh cd /usr/share/pyglade python main.py

Key points: /usr/share/pygladeis the application directory that contains the applications Python code Note: as with all other run-time paths, this path is relative to the UMEs root (or the chroot when working in an ImageCreator target). python main.pylaunches the Python interpreter and passes it the applications Python le, namely main.py

5.6

Main Python le

This is the applications main Python le. Run time location: The ApplicationDirectory File name extension: Can be anything, typically is .py Example: /usr/share/pyglade/main.py Type: Python le

5.7

Glade user interface le

This optional le denes the applications GTK user interface objects. Such les are created using Glade and imported into your Python code, after which its GTK objects can be accessed and used in Python. Run time location: The ApplicationDirectory File name extension: .glade Example: /usr/share/pyglade/pygladeui.glade Type: Glade denition le

Ubuntu Mobile Guide


72 / 99

5.8

Icon le

This is the optional icon that is displayed in the UME applications menu next to the application name. Run time location: /usr/share/icons/hicolor/22x22/ File name extension: .png Example: /usr/share/icons/hicolor/22x22/pyglade_26.png Type: PNG, SVG

5.9

Sample make le

Heres the make le I used to install the sample application referred to in this page. (Setting up a build environment with an external source directory mounted to the target is beyond the scope of this page.)
BINDIR = ${DESTDIR}/usr/bin/ APPDIR = ${DESTDIR}/usr/share/pyglade all: install: @mkdir -p ${BINDIR} @mkdir -p ${APPDIR} @install -m 755 -D main.py ${APPDIR}/main.py @install -m 755 -D pygladeui.glade ${APPDIR}/pygladeui.glade @install -m 755 -D executable.txt ${BINDIR}/pyglade @install -m 755 -D desktop.txt ${DESTDIR}/usr/share/applications/pyglade.desktop @install -m 755 -D pyglade_26.png ${DESTDIR}/usr/share/icons/hicolor/22x22/apps/ pyglade_26.png

clean: @rm @rm @rm @rm @rm -f -f -f -f -f ${APPDIR}/main.py ${APPDIR}/ui.glade ${BINDIR}/pyglade ${DESTDIR}/usr/share/applications/pyglade.desktop ${DESTDIR}/usr/share/icons/${THEME}/22x22/apps/pyglade_26.png

Ubuntu Mobile Guide


73 / 99

Chapter 6

Using Glade and Python to create an Application for Ubuntu Mobile


6.1 Purpose

This chapter explains how to import an applications user interface that was made with Glade into Python in order to make a UME/Hildon application. In particular, it covers: How to import a Glade user interface denition le into Python How to access objects dened in Glade and give them local Python names How to reparent Glade widgets to the required Python Hildon Window How to get a GTK Menu dened in Glade and set it as the Hildon Program menu in Python Terminology: Whats "reparenting"? The top level window in a UME application is - by denition - a Hildon Window. However, Glade can only create a GTK Window, not the Hildon Window you need. (When using Glade, you need a GTK Window as a top-level widget so that you can add other child widgets to it). To deal with this mismatch, you create a real Hildon Window in your Python and then "reparent" the GTK Windows direct children to it.

6.2

Prerequisites

Glade A UME development/build/run environment Understanding of the les and directories required by a UME Desktop Python application -- see Anatomy of a Python Application in UME

6.3

Prerequisites

Basic Python knowledge

Ubuntu Mobile Guide


74 / 99

6.4

Packages

You will need the following packages installed in the UME target python-gtk2 python-hildon-1.2 python-glade2 You can install each by entering the target UME root directory (the target chroot when working from Image-Creator) and executing the usual apt-get install (package name) command.

6.5

Using Glade

This how-to assumes basic knowledge of how to use Glade. However, even if youve never used it before, rest assured that its quite easy. Glade is a graphical tool for creating a GTK user interface by dragging widgets onto a canvas or into other widgets (in which case they become children) and then optionally selecting widgets and modifying their properties. The result is an XML le with the .gladeextension that contains a description of the user interface that can be imported into various languages, including Python. After importing the .glade le, you can access the widgets using the names you gave them in Glade and then use them programmatically. As noted, one important point is how to deal with the fact that Glade cannot create a Hildon Window. It can only create a GTK Window, and indeed it requires one as a parent for most other widgets (but not menus). So, in Glade, you create the GTK Window and add widgets to it, then, in your Python you "reparent" the GTK Windows child widgets to your real Hildon Window. To minimize reparenting, this example programs root window has only one child, a GTK VBox widget, which in turn contains child widgets. So, this VBox must be reparented from the GTK Window to a Hildon Window. Lets take a look at these steps in a little more detail, but rst lets review the Python programs basic structure.

6.6

This Python programs structure

Note: Please see main.py sourceat the end of this page. This is a simple Python program. Among the usual imports at the top is: import gtk.glade, which is required to import the .glade le. The program has one class, GladeTestApp, whose constructor creates the Hildon Program and Hildon Window, imports the .glade le, assigns Glade objects local names, reparents a widget, sets the Hildon program menu from a Glade-dened menu, sets up signal handlers for user events, and other things. The class is instantiated as an object named app, and its run()method is executed. Lets start by examining how the constructor creates the Hildon Program and Hildon Window.

6.7

Creating the Hildon Program and Hildon Window

Heres the top of the GladeTestAppclass, showing the beginning of its constructor.
class GladeTestApp(): """pygtk-glade-hildon demo project"""

def __init__(self):

Ubuntu Mobile Guide


75 / 99

#make the hildon program self.program = hildon.Program() self.program.__init__() #make the hildon window and add to program self.window = hildon.Window() self.window.set_title("PyGlade") self.program.add_window(self.window

As you can see, the Hildon Program is created and assigned to self.program. And, the Hildon Window is created and assigned to self.window. Pretty straightforward. Next, well import the .glade le.

6.8

Importing the .glade le

The .glade le is imported inside GladeTestApps constructor. The code looks like this:
self.glade_file = "pygladeui.glade" self.wTree=gtk.glade.XML(self.glade_file)

The rst line denes a variable ( self.glade_file) and assigns it the le name of the .glade le, in this case pygladeui.glade. The second line actually imports all user interface objects from the specied .glade le into a new variable named self.wTree. Now, all the objects dened in the .glade le can be retrieved from self.wTreeand can be assigned local names for programmatic use. They are retrieved using the names they were given (or assigned by default) when using Glade, as shown next.

6.9

Reparenting to Hildon Window

As noted, the GTK window made with Glade contains a GTK VBox widget that contains all other application widgets (except for the menu, discussed below). When making this VBox widget with Glade, I gave it the following name: vbox1. (The widgets name is viewed/set in Glade by selecting it and looking at its "properties" in the Properties window.) Heres the Python code that fetches the VBox from the imported glade le:
#reparent the vbox1 from glade to self.window self.vbox1 = self.wTree.get_widget("vbox1") self.reparent_loc(self.vbox1, self.window)

The rst non-comment code line gets the specied GTK VBox and assigns it to the self.vbox1variable. The second reparents the VBox from the GTK window made in Glade to the Hildon Window made in Python thats named self.windowwith the reparent_loc()function. Thats it for reparenting! Lets take a look at importing the GTK menu made in Glade and setting it as the applications Hildon menu.

Ubuntu Mobile Guide


76 / 99

6.10

Getting the menu and making it a Hildon Menu

In Hildon, you create a GTK menu and add it to the Hildon Program with the set_common_menu(GTK.menu)function, as mentioned previously. The following Python code shows how to get the imported the GTK menu thats named menu1, assign it to self.menuGlade, and then set the Hildon Program to use this as its common menu.
#get menu from glade and reparent as common menu in hildon program self.menuGlade = self.wTree.get_widget("menu1") self.program.set_common_menu(self.menuGlade)

6.11
6.11.1
import import import import

Source
main.py
pygtk gtk hildon gtk.glade

class GladeTestApp(): """pygtk-glade-hildon demo project"""

def __init__(self):

#make the hildon program self.program = hildon.Program() self.program.__init__() #make the hildon window and add to program self.window = hildon.Window() self.window.set_title("PyGlade") self.program.add_window(self.window) #receive signal to close window from framework close button if (self.window): self.window.connect("destroy", gtk.main_quit) #import the glade file and assign to self.wTree self.glade_file = "pygladeui.glade" self.wTree = gtk.glade.XML(self.glade_file) #reparent the vbox1 from glade to self.window self.vbox1 = self.wTree.get_widget("vbox1") self.reparent_loc(self.vbox1, self.window) #get menu from glade and reparent as common menu in hildon program self.menuGlade = self.wTree.get_widget("menu1") self.program.set_common_menu(self.menuGlade) #get quit menu item and connect signal self.menuItem_quit = self.wTree.get_widget("quit1") self.menuItem_quit.connect("activate", gtk.main_quit)

Ubuntu Mobile Guide


77 / 99

#get hbox1 in order to modify contents based on user actions self.hbox1 = self.wTree.get_widget("hbox1")

#get label1 for use self.label1 = self.wTree.get_widget("label1")

self.controlBar = hildon.Controlbar() self.controlBar.set_min(0) self.controlBar.set_max(50) self.controlBar.set_value(15) self.controlBar.connect("value-changed", self.control_changed, self.label1) self.menuItem_controlBar = self.wTree.get_widget("controlBar") self.menuItem_controlBar.connect("activate", self.controlBar_pressed, self.hbox1, self.controlBar, self.label1)

self.dateEditor = hildon.DateEditor() self.dateEditor.set_year(2006) self.dateEditor.set_month(4) self.dateEditor.set_day(20) self.menuItem_dateEditor = self.wTree.get_widget("dateEditor") self.menuItem_dateEditor.connect("activate", self.dateEditor_pressed, self.hbox1, self.dateEditor, self.label1) #get button1 and connect a signal handler self.button1 = self.wTree.get_widget("button1") if (self.button1): self.button1.connect("pressed", self.button1_pressed, self.label1) #destroy the gtk window imported from glade self.gtkWindow = self.wTree.get_widget("window1") self.gtkWindow.destroy() #display everything self.window.show_all()

def run(self): gtk.main()

# signal handlers def menuItem_quit1_pressed(self, widget): gtk.main_quit

def button1_pressed(self, widget, label): label.set_label("new label") # controlBar

def controlBar_pressed(self, widget, hbox, controlBar, label): self.dechild_hbox(hbox) hbox.add(controlBar) controlBar.show()

Ubuntu Mobile Guide


78 / 99

label.set_text("ControlBar")

def control_changed(self, widget, label): label.set_text(" %s of %s" % (widget.get_value(), widget.get_max()))

# dateEditor

def dateEditor_pressed(self, widget, hbox, dateEditor, label): self.dechild_hbox(hbox) hbox.add(dateEditor) label.set_text("DateEditor") dateEditor.show()

#utility

def dechild_hbox(self, hbox_widgets): children = hbox_widgets.get_children() for child in children: hbox_widgets.remove(child)

def reparent_loc(self, widget, newParent): widget.reparent(newParent)

if __name__ == "__main__": app = GladeTestApp() app.run()

6.11.2

Makele

BINDIR = ${DESTDIR}/usr/bin/ APPDIR = ${DESTDIR}/usr/share/pyglade all: install: @mkdir -p ${BINDIR} @mkdir -p ${APPDIR} @install -m 755 -D main.py ${APPDIR}/main.py @install -m 755 -D pygladeui.glade ${APPDIR}/pygladeui.glade @install -m 755 -D executable.txt ${BINDIR}/pyglade @install -m 755 -D desktop.txt ${DESTDIR}/usr/share/applications/pyglade.desktop @install -m 755 -D pyglade_26.png ${DESTDIR}/usr/share/icons/hicolor/22x22/apps/ pyglade_26.png

clean: @rm @rm @rm @rm @rm -f -f -f -f -f ${APPDIR}/main.py ${APPDIR}/pygladeui.glade ${BINDIR}/pyglade ${DESTDIR}/usr/share/applications/pyglade.desktop ${DESTDIR}/usr/share/icons/${THEME}/22x22/apps/pyglade_26.png

re.

Ubuntu Mobile Guide


79 / 99

Chapter 7

Porting Python Applications to Ubuntu Mobile


This follows on from the tutorial Using a Glade UI with Python to create a UME/Hildon app For more background info also read the excellent maemo tutorialfor porting python applications to the Hildon framework. This is the canonical URL for this tutorial.

7.1

Objective

This shows how to port an application (gPodder) to Ubuntu Mobile. gPodder media aggregator is a podcast receiver/catcher written in Python utilizing PyGTK for its graphical interface. gPodder is very lightweight and doesnt have many dependencies. A great part of the porting effort is spent making an application use and obey the Hildon UI style of windows and menus

7.2

Assumed Knowledge

You have set up the UME development environment as show here. Also that you can change the Flash UI as explained here. Dependencies Needed gPodder has the following dependencies on Ubuntu: python-glade2 python-feedparser apt-get install both of them in the target lesystem.

7.3

Get the Source Code and try it out on UME

Download and extract the source package from the projects page. The code changes are made in the gpodder-0.8.0/src/gpodder/gpodder.p le. On the target lesystem change the UI so that it displays the gpodder image and move the expanded gpodder folder to the target lesystem (I renamed it to gpodder-orig) like this:
user@machine:~/Dev/Ume/ports$ sudo cp -R gpodder-orig /home/ian/Dev/Ume/olpcimage/targets/ metahacker/fs/home/

Maybe gpodder will be ok without too many changes so lets install it by:

Ubuntu Mobile Guide


80 / 99

user@machine:/home/gpodder-orig# python setup.py install

In the target lesystem terminal:


export DISPLAY=:0 (to save typing this every time you open a target filesystem shell from moblin you can add this line to .bashrc) /etc/init.d/dbus start xinit /etc/X11/xinit/xinitrc -- /usr/bin/Xephyr :2 -host-cursor -screen 1024x600x32 -dpi 96 -ac

executing gpodderin the terminal gave an error of from xml.sax.saxutils import DefaultHandlerso in the terminal apt-get install python-xmlAfter this executes it executes OK in the terminal so lets test it by clicking the gpodder image and see what happens

Figure 7.1: gPodder on Desktop this presents the gpodder UI

Ubuntu Mobile Guide


81 / 99

Figure 7.2: gPodder UI It seems ok but it is not Hildonized yet

7.4

Hildonize Step 1

The rst code change in the porting exercise is to make gPodder use HildonProgramand HildonWindowclasses instead of the GtkWindowclass. Start by modifying the gpodder.py le (in the gpodder-orig/src/gpodder directory). To use Hildon elements, you have to import its module. The following illustrates the import:
from libipodsync import gPodder_iPodSync from libipodsync import ipod_supported

# ****** start of the added code ****** import hildon # ****** end of the added code ******

# for isDebugging: import libgpodder

Note: if this errors apt-get install python2.5-hildon python2.5-hildon-dev Next, add a HildonProgram(self.app)and a HildonWindow(self.window):

Ubuntu Mobile Guide


82 / 99

if libgpodder.isDebugging(): print "A new %s has been created" % self.__class__.__name__

#****** start of the added code ****** self.app = hildon.Program()

self.window = hildon.Window() self.window.set_title(self.gPodder.get_title()) self.app.add_window(self.window) self.vMain.reparent(self.window) self.gPodder.destroy() self.window.show_all() #****** end of the added code ******

#self.gPodder.set_title( self.gPodder.get_title()) #self.statusLabel.set_text( "Welcome to gPodder! Suggestions? Mail to: thp@perli.net ") # set up the rendering of the comboAvailable combobox

The gPodder class (self)has its close_gpoddermethod connected to the destroy signal from the original gPodderGtk window. In the glade le remove the connection: Original version
user@machine:/home/gpodder-orig/data# nano gpodder.glade

<property name="gravity">GDK_GRAVITY_NORTH_WEST</property> <property name="focus_on_map">True</property> <property name="urgency_hint">False</property> <signal name="destroy" handler="close_gpodder" last_modification_time="Sat, 29 Oct 2005 11:54:40 GMT"/>

Hildon Version
user@machine:/home/gpodder-hildon/data# nano gpodder.glade

<property name="gravity">GDK_GRAVITY_NORTH_WEST</property> <property name="focus_on_map">True</property> <property name="urgency_hint">False</property>

and put it in the new Hildonwindow(self.window)that was just created in gpodder.py like this :
self.window = hildon.Window() self.window.set_title(self.gPodder.get_title()) #****** start of the added code ****** self.window.connect("destroy", self.close_gpodder) #****** end of the added code ****** self.app.add_window(self.window)

self.vMain.reparent(self.window)

Note: above you can see two different versions gpodder-orig and gpodder-hildon in the target lesystem. To install a different version just remove the old version by;

Ubuntu Mobile Guide


83 / 99

user@machine:/home/gpodder-hildon/src/gpodder# cd /usr/lib/python2.5/site-packages/ user@machine:/usr/lib/python2.5/site-packages# rm -R gpodder-0.8.0.egg-info gpodder

and then do a python setup.py install on the new version (also remember to change the le /usr/share/gpodder/gpodder.glade if you need to for things like dialogues etc)

7.5

Hildonize Step 2

To use Hildons title area as its menu bar, instead of using the GTK+ menu (a GTKMenuBarobject) alter gpodder.py again. Before doing this have a look in the gpodder.glade le, you can see that the gPodderwindow has a menu bar (a GTKMenuBarobject) called mainMenuThe code below moves all its children ( menuPodcasts, menuChannels and menuHelp) to the HildonWindowsmenu and then destroys the empty mainMenumenu
self.vMain.reparent(self.window) self.gPodder.destroy() #****** start of the added code ****** menu = gtk.Menu() for child in self.mainMenu.get_children(): child.reparent(menu) self.window.set_menu(menu)

self.mainMenu.destroy() #****** end of the added code self.window.show_all()

Gives the nal version

Ubuntu Mobile Guide


84 / 99

Figure 7.3: gPodder UME Hildon

Ubuntu Mobile Guide


85 / 99

Chapter 8

Porting C Applications to Ubuntu Mobile


This uses some information from upstream. If you are feeling really brave do this rst.

8.1

Objective

This shows how to port an application written in C (liferea) to Ubuntu Mobile. Liferea is an aggregator for online news feeds written in C utilizing GTK for its graphical interface.

8.2

Assumed Knowledge

You have set up the UME development environment as show here. Also that you can change the Flash UI as explained here. You should be familiar with or have the desire to learn C programming, including the auto tools. A good tutorial on automake is here Dependencies Needed

aptitude install libgtkhtml2-0 libgtkhtml2-dev libxml-perl libxslt1-dev libglade2-0 libglade2-dev libsqlite3-0 libsqlite3-dev libhildondesk dev xulrunner

8.3

Overview

Porting applications basically comes down to two things: 1. Use HildonProgram and HildonWindowclasses instead of the GtkWindow class. 2. Use the HildonWindow menu bar instead of the GTKMenuBar

8.4

Get the source and try to compile

user@machine:/home/ian/Dev/Ume/ports/src# apt-get source lifereathis downloads the source


liferea-1.4.2 liferea_1.4.2.orig.tar.gz liferea_1.4.2-0ubuntu1.diff.gz liferea_1.4.2-0ubuntu1.dsc

this gives some ./autoconf errors like:

Ubuntu Mobile Guide


86 / 99

No package libxslt found No package sqlite3 found No package libglade-2.0 found

which are the applications dependencies, so install the packages needed if you have not already done so: aptitude install libgtkhtml2-0 libgtkhtml2-dev libxml-perl libxslt1-dev libglade2-0 libglade2-dev libsqlite3-0 libsqlite3-dev libhildondesktop-dev xulrunner this passed autoconf but running make gave an error of:
gtkhtml2.c: In function gtkhtml2_launch_url: gtkhtml2.c:458: error: too many arguments to function update_request_new gtkhtml2.c:458: warning: assignment from incompatible pointer type gtkhtml2.c:459: error: dereferencing pointer to incomplete type gtkhtml2.c:460: error: dereferencing pointer to incomplete type gtkhtml2.c:461: error: dereferencing pointer to incomplete type gtkhtml2.c:462: error: dereferencing pointer to incomplete type gtkhtml2.c:463: error: dereferencing pointer to incomplete type gtkhtml2.c:465: error: too few arguments to function update_execute_request make[4]: *** [liblihtmlg_la-gtkhtml2.lo] Error 1 make[4]: Leaving directory /home/ian/Desktop/liferea-1.4.2/src/gtkhtml2

It seems to be hitting by this bug. So downloaded the latest bugx stable release 1.4.2b and this compiled successfully and also ran make ok so now it is time to Hildonize it.

8.5

Hildonizing

It is useful to know that the default location for C header les is in /usr/include. Inside this directory we have another directory hildon-1 and inside this directory we have hildon, so the full path to the hildon header les is: /usr/include/hildon-1/hildon First modify the le congure.ac Around line 42 add the line: AC_ARG_ENABLE(hildon, AS_HELP_STRING([--enable-hildon],[compile for Hildon environment @<:@default=no@:>@]),,enable_hildon=no) and then on lines 212 - 225 add:
dnl ******** dnl Hildon dnl ******** if test "x$enable_hildon" = "xyes"; then dnl AC_MSG_CHECKING([for GtkHTML2 support]) PKG_CHECK_MODULES([HILDON], hildon-1 >= 1.0.5,enable_hildon=yes,enable_hildon=no) AC_SUBST(HILDON_CFLAGS) AC_SUBST(HILDON_LIBS) else enable_hildon=no fi

AM_CONDITIONAL(WITH_HILDON, test "x$enable_hildon" = "xyes")

and then nally on line 548 echo the information back so that there is visual conrmation to the user that Hildon is enabled: echo "Build Hildon support............ : $enable_hildon"

Ubuntu Mobile Guide


87 / 99

these changes enable the passing of the argument --enable-hildon on the command line like: ./configure --enable-hildon After making these changes run autoreconf: user@machine:~/Dev/Ume/liferea-1.4.2b$ autoreconf This step is necessary because autoreconf runs autoconf, autoheader, aclocal, automake, libtoolize, and autopoint (when appropriate) to update the Build System in the specied directories and their subdirectories. In other words it registers the changes made to congure.ac
Note It is not necessary for this application but other changes that can be made to congure.ac include: Hildon File Management The new hildon le manager is now called hildon-fm-2, so in congure.ac, if there is the following line it should be updated. PKG_CHECK_MODULES(..., [hildon-fm]) --> PKG_CHECK_MODULES(..., [hildon-fm-2]) Hildon Help The new hildon help is changing from libossohelp to hildon-help, so in congure.ac, if there is the following line it should be updated. PKG_CHECK_MODULES(..., [libossohelp]) --> PKG_CHECK_MODULES(..., [hil-

don-help])

Next change Makele.am This is located in the liferea-1.4.2b/srcdirectory. On line 67 add the Hildon libraries $(HILDON_LIBS)to liferea_bin_LDADD
liferea_bin_LDADD = net/liblinet.a \ parsers/libliparsers.a \ fl_sources/libliflsources.a \ notification/liblinotification.a \ ui/libliui.a \ $(PACKAGE_LIBS) $(X_LIBS) $(X_PRE_LIBS) -lX11 $(X_EXTRA_LIBS) $( DBUS_LIBS) $(NM_LIBS) $(INTLLIBS) $(GNUTLS_LIBS) $(HILDON_LIBS)

this enables liferea to link against the Hildon libraries. Next change the Makele.am inside the liferea-1.4.2b/src/ui directory. On line 11 add: libliui_a_CFLAGS = $(PACKAGE_CFLAGS) $(DBUS_CFLAGS) $(HILDON_CFLAGS) this passes the $(HILDON_CFLAGS)to the compiler These are all the changes needed to be made to autotools. Next copy the liferea.glade le which is in the root liferea-1.4.2b directory and rename it to liferea_hildon.glade This means that if the --enable-hildon ag is passed at compile time the liferea_hildon.glade le is used and if not liferea.glade is used. Here are the differences between the two les:
user@machine:/home/user/liferea-1.4.2b$ diff -Nu liferea.glade liferea_hildon.glade --- liferea.glade 2007-08-19 13:56:50.000000000 -0400 +++ liferea_hildon.glade 2007-09-25 14:17:38.000000000 -0400 @@ -2,11 +2,8 @@ <!DOCTYPE glade-interface SYSTEM "glade-2.0.dtd"> <!--*- mode: xml -*--> <glade-interface> - <widget class="GtkWindow" id="mainwindow"> <property name="title" translatable="yes">Liferea</property> <property name="default_width">640</property> <property name="default_height">480</property> <property name="icon_name">liferea</property> + <widget class="GtkVBox" id="mainwindow"> + <property name="visible">True</property> <child> <widget class="GtkVBox" id="vbox1"> <property name="visible">True</property>

Ubuntu Mobile Guide


88 / 99

In short the mainwindow is a GtkVBoxin the hildon version and a GtkWindownormally. This change is explained in this tutorial in the section Hildonizing Main View Now liferea needs to know to pull in the appropriate glade le depending on whether it is compiled for hildon or not. In the le liferea-1.4.2b/src/ui/ui_shell.cinside the function static void liferea_shell_init (LifereaShell *ls)line 113 now looks like:
#ifdef MAEMO_CHANGES ls->priv->xml = glade_xml_new (PACKAGE_DATA_DIR G_DIR_SEPARATOR_S PACKAGE G_DIR_SEPARATOR_S "liferea_hildon.glade", "mainwindow", GETTEXT_PACKAGE); #else ls->priv->xml = glade_xml_new (PACKAGE_DATA_DIR G_DIR_SEPARATOR_S PACKAGE G_DIR_SEPARATOR_S "liferea.glade", "mainwindow", GETTEXT_PACKAGE); #endif

Also the le liferea-1.4.2b/src/ui/ui_dialog.cinside the function GtkWidget *liferea_dialog_new (const gchar *filename, const gchar *name)line 139 now looks like:
#ifdef MAEMO_CHANGES ld->priv->xml = glade_xml_new (PACKAGE_DATA_DIR G_DIR_SEPARATOR_S PACKAGE G_DIR_SEPARATOR_S "liferea_hildon.glade", name, GETTEXT_PACKAGE); #else ld->priv->xml = glade_xml_new (PACKAGE_DATA_DIR G_DIR_SEPARATOR_S PACKAGE G_DIR_SEPARATOR_S "liferea.glade", name, GETTEXT_PACKAGE); #endif

All the other changes to Liferea are in liferea-1.4.2b/src/ui/ui_mainwindow.c On line 34 add the header le include:
#ifdef MAEMO_CHANGES # include <hildon/hildon-program.h> #endif

On line 66 in the function static struct mainwindowcreate the HildonProgramstructure like:


#ifdef MAEMO_CHANGES HildonProgram GtkWidget GtkWidget #else GtkWindow #endif *program; *container; *window; *window;

On line 536 in the function static struct mainwindow *ui_mainwindow_new(void)make an instance of a HildonProgramlike:
#ifdef MAEMO_CHANGES mw->program = HILDON_PROGRAM(hildon_program_get_instance()); mw->container = window; mw->window = hildon_window_new(); gtk_container_add(GTK_CONTAINER(mw->window), GTK_WIDGET(mw->container)); hildon_program_add_window(mw->program, HILDON_WINDOW(mw->window)); #else mw->window = GTK_WINDOW (window); #endif

Also the maemo tutorial mentioned above notes Also remove functions accel_set_func and accel_edited_callback so on line 1255 add:

Ubuntu Mobile Guide


89 / 99

#ifndef MAEMO_CHANGES accel_group = gtk_ui_manager_get_accel_group (ui_manager); gtk_window_add_accel_group (mw->window, accel_group); #endif

Figure 8.1: Liferea

8.5.1

Now on to the menu functions.

This blog post provided the inspiration for this. Trying to use the GtkUIManager caused a problem. The reason is that hildon_window_set_menu expects a GtkMenuas second argument, but the GtkUIManager gives a GtkMenuBar Adding an utility function to the code that converts from a GtkMenuBarto a GtkMenu solves this. The very nice thing is that it still uses the denitions in the glade le. On line 1269 add:
#ifdef MAEMO_CHANGES GtkWidget *main_menu; GList *iter;

/* Create new main menu */ main_menu = gtk_menu_new();

iter = gtk_container_get_children (GTK_CONTAINER (mw->menubar)); while (iter) {

Ubuntu Mobile Guide


90 / 99

GtkWidget *menu;

menu = GTK_WIDGET (iter->data); gtk_widget_reparent(menu, main_menu);

iter = g_list_next (iter); }

hildon_window_set_menu(HILDON_WINDOW(mw->window), GTK_MENU(main_menu)); #endif

That is all the changes made so now move the project to the target lesystem and run:
./configure --enable-hildon --prefix=/usr/ --libdir=/usr/lib make make install

and then start the UI for the target lesystem. Click on the shell image and run
export DISPLAY=:2 liferea

Figure 8.2: Liferea Hildonized

Ubuntu Mobile Guide


91 / 99

Chapter 9

Application Development for UME - An Example


Location based services will be provided by MID devices. This example demonstrates one possible use case scenario.

9.1

Showing the User Relevant Information Based on their Location

This is a work in progress and pulls from upstream code such as Moblin and GeoClue.

9.1.1

Flash UI

Begin by checking the UI out from the repo:


user@host:~$ mkdir flash;cd flash

user@host:~/flash$

user@host:~/flash$ git clone rsync://moblin.org/repos/projects/mobile-basic-flash.git

[you need git-core if you do not have it ... apt-get install git-core] the above commands create a folder mobile-basic-ash:
user@host:~/flash$ cd mobile-basic-flash

This folder has the structure: autogen.sh congure.ac content COPYING debian Makele.am po src Inside the src folder are the source .a and Action Script .as les. Inside the content folder are the compiled .swf les, the HTML page which embeds the ash movie (called ash_home.html), and backgrounds and icons folders which should be obvious. There is also the le conf.xml which is read at compile time and congures the ash movie. For my plugin I changed this le to look like this.

Ubuntu Mobile Guide


92 / 99

....snip

<app id="8" title="TBD Camera" desc="Camera App" icon="icons/camera.png" path="" />

<app id="9" title="Control Panel" desc="Control Panel" icon="icons/controlpanel.png" path ="/usr/bin/controlpanel" />

<app id="10" title="Location Services" desc="" icon="icons/geoclue.png" path="/usr/bin/ geoclue" />

...snip

We are telling Flash to make an XML socket call and execute the le /usr/bin/geoclue. We will to create this le later on Put you application icon inside the icons folder and run:
user@host:~/flash/mobile-basic-flash$ ./autogen.sh

this loads the conf.xml into the ash movie then we need to copy the movie, the conf.xml le and the icon to the correct place inside moblin
user@host:~/flash/mobile-basic-flash/content$ sudo cp conf.xml flash_home.swf /home/vern/ moblin/image/targets/target/fs/usr/share/mobile-basic-flash/

Password:

user@host:~/flash/mobile-basic-flash/content/icons$ sudo cp geoclue.png /home/vern/moblin/ image/targets/target/fs/usr/share/mobile-basic-flash/icons/

The UI now looks like this with our Location Services icon:

Ubuntu Mobile Guide


93 / 99

9.1.2

The GeoClue backend.

GeoClue is a D-Bus API and library and it uses several backends to get geographic data from various sources and abstracts the differences of those data sources as much as possible, so applications can just ask for e.g. current coordinates and not care where the coordinates come from (current options for coordinates are GPS and hostip.info). The following APIs (and backend types) are supported or planned: * Positioning * Routing * Geocoding * Map * Track Logs For this example we will use a backend called hostip.info which returns a city based on your IP.
(need git-core)

user@host:~$ git clone git://anongit.freedesktop.org/git/geoclue

user@host:~$ cd geoclue

user@host:~/geoclue$

sudo ./autogen.sh

configure: error: Install gpsd Debian package or its source-code equivalent:

a quick apt-cache search reveals:

Ubuntu Mobile Guide


94 / 99

gpsd - GPS (Global Positioning System) daemon

so:
user@host:~/geoclue$ sudo apt-get install gpsd

try again:
user@host:~/geoclue$ sudo ./autogen.sh

checking for HTTPXML... configure: error: Package requirements (libsoup-2.2 libxml-2.0) were not met:

No package libsoup-2.2 found

Consider adjusting the PKG_CONFIG_PATH environment variable if you

installed software in a non-standard prefix.

Alternatively, you may set the environment variables HTTPXML_CFLAGS

and HTTPXML_LIBS to avoid the need to call pkg-config.

See the pkg-config man page for more details.

It seems like we are missing some development libraries:


user@host:~/pyphantom_b4Brazil/geoclue$ sudo apt-get install libglib2.0-dev libgtk2.0-dev libsoup2.2-dev libgconf2-dev libxml++2.6c2a

and now it works:


user@host:~/geoclue$ sudo ./autogen.sh

user@host:~/geoclue$ sudo make

user@host:~/geoclue$ sudo make install

Fire up pyphantom the hildon desktop IDE and create the following plugin:

Ubuntu Mobile Guide


95 / 99

import gtk

import pygtk

import hildondesktop

import dbus

import os

class GeocluePlugin(hildondesktop.StatusbarItem):

def __init__(self):

hildondesktop.StatusbarItem.__init__(self)

# Start with getting position from GeoClue

bus = dbus.SessionBus()

# TODO: Get the GeoClue interface to use from /schemas/apps/geoclue/position/ defaultpath

# and /schemas/apps/geoclue/position/defaultserviceGConf keys

proxy_obj = bus.get_object(org.foinse_project.geoclue.position.hostip, /org/ foinse_project/geoclue/position/hostip)

geoclue_iface = dbus.Interface(proxy_obj, org.foinse_project.geoclue.position)

# Get the coordinates from the service

coordinates = geoclue_iface.current_position()

#location = geoclue_iface.current_location()

# We can also use hardcoded

Ubuntu Mobile Guide


96 / 99

#coordinates[0] = 60.158806494564

#coordinates[1] = 24.9426341056824

print "According to GeoClue you are in %s %s." % (coordinates[0], coordinates[1])

def hd_plugin_get_objects():

plugin = GeocluePlugin()

return [plugin]]

and this will show user coordinates in the Debug I/O (you may need to try a few times as there is a parsing bug in the hostip API):

Inside the plugin src folder there will be 2 les: geoclue.py and geoclue.desktop and we need to copy these to the correct areas inside our image.
user@host:~/geoclue/src$ sudo cp geoclue.py /home/vern/moblin/image/targets/target/fs/usr/ lib/hildon-desktop/

user@host:~/geoclue/src$ sudo cp geoclue.desktop /home/vern/moblin/image/targets/target/fs/ usr/share/applications/hildon-marquee

in the le:
/etc/hildon-desktop/marquee.conf

add the following line:


/usr/share/applications/hildon-marquee/geoclue.desktop

Now we need to create our /usr/bin/geoclue le:


#!/bin/sh

cd /usr/lib/hildon-desktop/

Ubuntu Mobile Guide


97 / 99

python geoclue.py

and then do:


chmod +x geoclue.py

we then need to start moblin and choose our application in the UI. It executes and presents the user with some info about their current location.

Ubuntu Mobile Guide


98 / 99

Chapter 10

Theming and Customization of UME


Changing the look of Ubuntu Mobile.

10.1

Overview

The hildon user interface thats powering Ubuntu Mobile is themable (skinable) and the look can be customized. An artist can develop their own skin and ship it in a stand-alone package for others to install and use. Currently a pixmap-based theming is used for performance reasons. Pixmap-based theming means that widget looks are being assembled from individual bitmap images used in different congurations. Hildon theming overview

Ubuntu Mobile Guide


99 / 99

Chapter 11

API References
11.1 D-Bus API

D-Bus is a system for interprocess communication (IPC). D-Bus API

11.2

GTK API

GTK (GIMP Toolkit) is a library for creating graphical user interfaces GTK API Glib API

11.3

Hildon API

Hildon application framework introduces a new desktop for handheld devices. Hildon FM API Hildon Libs API API documentation for Hildon Status bar, Home Applets and Navigator API documentation for Hildon Control Panel API documentation for python bindings for Hildon API documentation for Python bindings for Libosso

11.4

Gnome Developer Documentation

Gnome Libraries