Tutorial presentation about embedded development on the Openmoko platform. Presented at the fosslc.org event "Free/Open Source Mobile Development: An Introduction" in Waterloo, Canada

1. Getting started with
open mobile
development on the
Openmoko platform
Presented at osbootcamp YYZ1 (Mobile embedded development
conference ­ Waterloo, Canada)
by Jean­Michel Bouffard
<jean­michel.bouffard@crc.ca>

2. Summary
Setting up the development environment
✔
OM toolchain
✔
OpenEmbedded build system
✔
Creating a simple first project for the platform
✔
Running the application
✔
Openmoko emulator
✔
FreeRunner device
✔
Packaging a custom distribution
✔
Adding new hardware components
✔
2

3. Introduction
Openmoko OM2008.x distribution build environment is
✔
using:
OpenEmbedded (http://wiki.openembedded.net)
✔
Examples from this tutorial are done using:
✔
Ubuntu 8.10 i686 host system
✔
Official OM2008.x Openmoko distributions
✔
3

4. Introduction
Choose your development toolkit
✔
4

5. Introduction
Choose your build system
✔
Toolchain
✔
✔ Installs only a cross­compiler and basic libraries for
application development
✔ Can build applications only
Unstable and less recommended
✔
OpenEmbedded
✔
✔ Install the complete build system for Openmoko
distributions
✔ Can build applications and full OS images
More stable and recommended
✔
5

6. Setting up the development environment
­ Toolchain
Requirements
✔
autotools build system
✔
default packages:
✔
✔ autoconf, automake, binutils, gcc, gcc­c++, libtool, ccache,
intltool
distro dependent packages (Ex. Ubuntu 8.10):
✔
✔ libglib2.0­dev libxrender­dev libmokoui2­dev libgconf2­dev
mtools fakeroot alien check uboot­mkimage
Complete list available on the openmoko wiki at
✔
http://wiki.openmoko.org/wiki/Toolchain
6

7. Setting up the development environment
­ Toolchain
Installation
✔
download toolchain archive from
✔
http://downloads.openmoko.org/toolchains
extract archive to /
✔
Prepare environment variables
✔
use “setup­env” script
✔
> wget
http://downloads.openmoko.org/toolchains/openmoko­i686­arm­linux­gnueabi­toolchain.tar.bz2
> cd /
> tar ­xjvf ~/openmoko­i686­arm­linux­gnueabi­toolchain.tar.bz2
> . /usr/local/openmoko/arm/setup­env
7

8. Setting up the development environment
­ Toolchain
The clean toolchain is like a Linux system without any
✔
development libraries, so dependencies related to the
new software project must be installed
Preparation of environment
✔
Modifications of the toolchain must be done as a “super user”
✔
Set environment with the “setup­env” script
✔
Installation of libraries
✔
Update packages list with “opkg­target”
✔
Search and install packages with “opkg­target”
✔
> sudo bash
> . /usr/local/openmoko/arm/environment­setup
> opkg­target update
> opkg­target list | grep gtk+­dev
> opkg­target install gtk+­dev
8

9. Setting up the development environment
­ Toolchain
Application development can be done on the host
✔
system with desktop development tools
Building for the target platform using the toolchain
✔
Preparation of environment
✔
✔ Application development can be done as a “normal user”
✔ Set environment with the “setup­env” script
Building applications
✔
✔ Configure application with “om­conf”
✔ Build application as usual with “make”
> . /usr/local/openmoko/arm/environment­setup
> cp ­r /usr/local/openmoko/source/openmoko­sample2 ~/
> om­conf openmoko­sample2
> cd openmoko­sample2
> make
9

10. Setting up the development environment
­ OpenEmbedded
Install required packages
✔
Default packages:
✔
✔ subversion, texi2html, texinfo, help2man
✔ ncurses, zlib (or libz), OpenSSL, GTK++
Complete list can be found at
✔
http://wiki.openmoko.org/wiki/MokoMakeFile#Required_software
Download MokoMakefile
✔
http://www.rwhitby.net/files/openmoko/Makefile
✔
> mkdir ~/moko; cd ~/moko
> wget http://www.rwhitby.net/files/openmoko/Makefile
10

11. Setting up the development environment
­ OpenEmbedded
Start build:
✔
make setup
✔
To accelerate the build on a multi­core computer, add these two
✔
lines in the file “build/conf/local.conf”
✔ PARALLEL_MAKE = quot;­j 4quot;
✔ BB_NUMBER_THREADS = quot;4quot;
make setup­machine­om­gta02
✔
make image
✔
Wait (6220 steps generate 10GB of data in ~10 hours!)
✔
> make setup
> make setup­machine­om­gta02
> make image
11

12. Setting up the development environment
­ OpenEmbedded
You will encounter build errors
✔
Check errors in log files
✔
For instance, compilation log files for the alsa­utils package
✔
can be found in ~/moko/build/tmp/work/armv4t­angstrom­linux­
gnueabi/alsa­utils­1.0.15­r1/temp/log.do_compile.xxxx
Correct errors if any
✔
Update environment, clean package and restart build
✔
make update­makefile setup update
✔
make clean­package­<pkg_error>; make image
✔
> tail ~/moko/build/tmp/work/armv4t­angstrom­linux­gnueabi/alsa­utils­1.0.15­
r1/temp/log.do_compile.25688
> make update­makefile
> make setup update
> make clean­package­alsa­utils
> make image
12

13. Setting up the development environment
­ OpenEmbedded
Add additional requirements for the development
✔
make build­package­<pkg_req>
✔
Newly built packages will be written to the deployment
✔
folder
~/moko/build/tmp/deploy/glibc/opk/armv4t/
✔
Missing packages are not part of the generated
✔
OM2008.x image, they need to be installed along with
the new application
> make build­package­libglade
13

14. Creating a simple first project for the platform
For this example, we will build a GTK+ application
✔
Anjuta development environment
✔
Glade Interface Designer
✔
14

15. Creating a simple first project for the platform
15

16. Creating a simple first project for the platform
16

17. Creating a simple first project for the platform
Glade interface designer lets you create an interface
✔
easily for your new application
Follow UI design recommendations
✔
✔ Instantaneous save, finger usage, efficient layout, etc
17

18. Creating a simple first project for the platform
An icon and desktop item must be
✔
added
/data/openmokocalc.png
✔
/data/openmokocalc.desktop
✔
/data/openmokocalc.png
/data/Makefile.am
✔
[Desktop Entry] #
Encoding=UTF­8 # desktop integration: .desktop file
Name=Openmoko Calc #
Comment=Simple calculator application desktopdir = $(datadir)/applications
Exec=openmokocalc dist_desktop_DATA = openmokocalc.desktop
Icon=openmokocalc
Terminal=false #
Type=Application # desktop integration: application icon
Categories=Application;Utilities; #
MimeType=text/x­vcard; appicondir = $(datadir)/pixmaps
SingleInstance=true dist_appicon_DATA = openmokocalc.png
StartupNotify=true
/data/openmokocalc.desktop /data/Makefile.am
18

19. Creating a simple first project for the platform
Build the application for the host computer
✔
19

20. Creating a simple first project for the platform
Test the application...
✔
...then create a source
✔
tarball
20

21. Creating a simple first project for the platform
BitBake is used to manage builds in OpenEmbedded
✔
A BitBake recipe is needed to identify how to build a
✔
package
DESCRIPTION = quot;Openmoko Calculatorquot;
AUTHOR = quot;Jean­Michel Bouffard <jean­michel.bouffard@crc.ca>quot;
HOMEPAGE = quot;http://www.crc.ca/mmbquot;
SECTION = quot;console/applicationsquot;
PRIORITY = quot;optionalquot;
LICENSE = quot;GPLquot;
DEPENDS = quot;quot;
RDEPENDS = quot;quot;
PN = quot;openmokocalcquot;
PV = quot;0.1quot;
PR = quot;r0quot;
EXTRA_OECONF += quot;quot;
SRC_URI = quot;file://openmokocalc­0.1.tar.gzquot;
inherit autotools
/openmokocalc.bb
21

22. Creating a simple first project for the platform
Build application for Openmoko using the “bitbake”
✔
command
configuration script is executed with flags for cross­compiler
✔
compiler and linker are executed
✔
application installation is validated
✔
ipk package is created
✔
application can be found in:
✔
~/moko/build/tmp/deploy/glibc/opk/armv4t/
✔
> cd ~/moko/build
> . ../setup­env
> bitbake ­b ~/workspace/openmoko_calc/openmokocalc.bb
> cp ~/moko/build/tmp/deploy/glibc/opk/armv4t/openmokocalc_0.1­r0_arm4t.ipk ~/.
22

23. Running the application
­ Emulator
An emulator base on the QEMU project is available
✔
The use of the emulator is not recommended
✔
The emulator supports the Neo 1973 only
✔
The latest ON2008.x distributions do not support the Neo
✔
1973
To use the emulator anyway:
✔
The MokoMakefile can build and install the emulator
✔
automatically
> cd ~/moko
> make qemu
23

24. Running the application
­ Device
Flashing the operating system into the device
✔
Two main partitions must be written into internal flash memory
✔
✔ The Linux kernel (kernel)
✔ The OS and applications files (rootfs)
Start the phone in flashing mode by holding the option button
✔
while pressing the power button
Use “dfu­util” (distributed with OpenEmbedded)
✔
✔ “dfu­util ­l“ confirms that the phone is working if listed
✔ “dfu­util ­a <partition> ­R ­D <image>” starts flashing
> ./dfu­util ­l
> sudo ./dfu­util ­a kernel ­R ­D ./uImage­2.6.24+gitr0­r2.01­om­gta02.bin (takes 1­2
minutes)
> sudo ./dfu­util ­a rootfs ­R ­D ./openMoko­asu­image­om­gta02.jffs2 (takes 10­15 minutes)
24

25. Running the application
­ Device
Boot Neo FreeRunner by pressing the power button
✔
Connect USB connector
✔
Activate networking
✔
By default, the usb0 interface is enabled on the FreeRunner at
✔
address 192.168.0.202
Use “ifconfig” to enable usb0 interface on host
✔
Add “route” to usb0 if host main address is 192.168.0.x
✔
> sudo ifconfig usb0 192.168.0.200 netmask 255.255.255.0
> sudo route add ­host 192.168.0.202 dev usb0 (required if host address is in 192.168.0.x
range)
25

26. Running the application
­ Device
Transfer application package to device
✔
Use Secure copy (scp) to root@192.168.0.202
✔
Connect to device
✔
Use secure shell (ssh) connection root@192.168.0.202
✔
Install application
✔
Use opkg package manager to install .ipk files
✔
host> scp *.ipk root@192.168.0.202:.
host> ssh root@192.168.0.202 (no password)
freerunner> opkg install libglade­2.0­0_2.6.2­r2_arm4t.ipk
freerunner> opkg install openmokocalc_0.1­r0_arm4t.ipk
freerunner> exit
26

27. Running the application
­ Device
Run application from OM2008.x menu using the
✔
installed icon
27

28. Packaging a custom distribution
Custom distribution can be generated by using the
✔
“local overlay” option from OpenEmbedded
Provides a local structure for custom code and build
✔
configurations
Create the following file structure in ~/moko
✔
local local/conf local/classes local/packages
✔
local/packages/images local/packages/tasks
> mkdir local local/conf local/classes local/packages local/packages/images
local/packages/tasks ­p
28

29. Packaging a custom distribution
Copy the main configuration file into the local overlay
✔
from “build/conf/site.conf” to “local/conf/site.conf”
✔
Edit these lines
✔
BBFILES := quot;${OMDIR}/openembedded/packages/*/*.bb $
✔
{OMDIR}/oe/packages/*/*.bb ${OMDIR}/local/packages/*/*.bbquot;
BBFILE_COLLECTIONS = quot;upstream local overlayquot;
✔
Add these lines
✔
BBFILE_PATTERN_overlay = quot; ^ ${OMDIR}/local/quot;
✔
BBFILE_PRIORITY_overlay = quot;20quot;
✔
> cp build/conf/site.conf local/conf/site.conf
> vi local/conf/site.conf
29

30. Packaging a custom distribution
Modify “~/moko/setup­env” script to take into account
✔
the new local overlay
export BBPATH=quot;${OMDIR}/local:${OMDIR}/build:$
✔
{OMDIR}/openembeddedquot;
The local overlay will now be taken into account when
✔
building packages
> vi ~/moko/setup­env
30

31. Packaging a custom distribution
Generate the new build configuration files
✔
local/packages/images/example­openmoko­devel­image.bb
✔
require creator­openmoko­image.bb
IMAGE_INSTALL += quot;task­openmoko­debugquot;
local/packages/images/example­openmoko­image.bb
✔
#­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­
# OpenMoko Image Recipe
#­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­
export IMAGE_BASENAME = quot;${PN}quot;
export IMAGE_LINGUAS = quot;quot;
export IMAGE_INSTALL = quot;
${MACHINE_TASK_PROVIDER}
task­openmoko­linux
task­openmoko­net
task­openmoko­ui
task­openmoko­base
task­openmoko­phone
task­openmoko­games
task­openmoko­pim
task­openmoko­example
quot;
inherit image
LICENSE = MIT
ROOTFS_POSTPROCESS_COMMAND += 'date quot;+%m%d%H%M%Yquot; >${IMAGE_ROOTFS}/etc/timestamp'
31

32. Packaging a custom distribution
local/packages/tasks/task­openmoko­creator.bb
✔
DESCRIPTION = quot;OpenMoko: Example of a custom configurationquot;
SECTION = quot;openmoko/basequot;
LICENSE = quot;originalquot;
PR = quot;r0quot;
inherit task
RDEPENDS_task­openmoko­example = quot;
libglade
openmokocalc
quot;
Start build operation
✔
Using the “bitbake” command
✔
> cd ~/moko/build
> . ../setup­env
> bitbake example­openmoko­devel­image
32

33. Adding new hardware components
Different connections are available to extend hardware
✔
capabilities:
USB
✔
SDIO
✔
Bluetooth
✔
I2C
✔
Serial interfaces
✔
USB port is available outside the case. Other
✔
connections would require further modifications
33

34. Adding new hardware components
­ USB peripherals
Internal USB test points can be
✔
used to integrate a USB component
Schematics available from
✔
http://openmoko.com
Marked on FreeRunner schematic as
✔
H­TP4901, H­TP4902, H­TP4903, H­
TP4904
Configuration
✔
USB port must be switched from
✔
device to host mode of operation
USB power mode can be selected to
✔
provide power to the device from the
FreeRunner battery
34

35. Conclusion
Application development for the Openmoko platform is
✔
comparable to desktop development
Many new improvements of the operating system and
✔
the available software are expected in the next months
Development tools need to be improved to offer better
✔
stability and ease of use
The toolchain should be the way to go for easy software
✔
development, but configuration issues make it difficult to use
The OpenEmbedded environment is not practical because of
✔
the large disk space and build time requirements
35

36. Conclusion
More information at:
✔
Openmoko ­ Open. Mobile. Free.
✔
http://wiki.openmoko.org
Openmoko developer guide
✔
http://wiki.openmoko.org/wiki/Openmoko_developer_guide
OpenEmbedded ­ Cross­compile environment to create a
✔
complete Linux Distribution for embedded systems.
http://wiki.openembedded.net/index.php/Main_Page
✔
36

37. THANK YOU
37