Firefox OS for Raspberry Pi

Author: Philipp Wagner <mail@philipp-wagner.com>
Last update of this guide: 2013-04-13

Table of Contents

  1. Introduction
    1. Required Hardware
    2. Limitations
    3. Credits
    4. Contribute
  2. System Overview
  3. Get it: Download pre-built images
  4. Build it: Compile your own Firefox OS for Raspberry Pi
    1. System Requirements
    2. Initialize Your Build Environment
    3. Get the Code
    4. Initialize OpenEmbedded
    5. Compile everything
  5. Flash it: Put an image on a SD card
  6. Run it
    1. Displaying a Web Site
    2. Displaying a WebApp
    3. Connect to your Raspberry Pi
  7. Develop Firefox OS

Introduction

A quickly booting operating system and a user interface which can be programmed easily using well-known web technologies like HTML, JavaScript and CSS, all running on an inexpensive yet powerful device – sounds like a great fit for one of your pet projects? Then you can stop your search, and look at the solution: Firefox OS for Raspberry Pi. It adapts Mozilla's Firefox OS to run on Raspberry Pi devices and gives you all the possibilities of the web on a small and inexpensive device. What's your use case?

This documentation describes how you can build, use, and extend Firefox OS for Raspberry Pi. It assumes, depending on the section, basic (to use) to advanced (to develop) Linux and programming knowledge. In any case I tried to describe the required steps as clearly as possible. If you have trouble following any of the guides in this document, please feel free to contact me.

Please note that all of this is still in an early stage of development, you will experience some problems and should be prepared to invest some time if you find a problem. The section Limitations describes some of the largest limitations that Firefox OS for Raspberry Pi currently has.

Required Hardware

To get started with your Firefox OS device, you need some hardware. Nothing in the list below should surprise you, just check you got everything together before you start.

Limitations

Credits

Firefox OS for Raspberry Pi integrates many software components into one whole solution. Only a tiny part was written by myself (Philipp), most of the hard work was done by others. All credit and thanks goes to them!

Most of the work in the LinuxGL layer, interfacing the Gecko rendering engine with the hardware, was done by Oleg "romaxa" Romashin, who also brought us (among many other things) the Gecko-based browser on Nokia's N900 phone.

Building a Linux distribution for the Raspberry Pi got really easy thanks to the work of John Willis and Andrei Gherzan, who developed the meta-raspberrypi layer for OpenEmbedded.

Finally, a great thanks goes to all developers of the used components, without their great work none of this would be possible.

Contribute

If you use Firefox OS for Raspberry Pi and put some work into it, please consider contributing your changes to the corresponding upstream projects to help all others with the same problem.

Since many projects are integrated, "upstream" depends much on where you did your changes:

System Overview

Firefox OS for Raspberry Pi reuses and integrates many components developed by others into a complete distribution. At first, have a look at the following figure.

The layers of the software stack.

On the left, the "usual" Firefox OS (formerly known as Boot 2 Gecko, or B2G) software stack is shown, as it is used by the Firefox OS phones you'll be able to buy soon. The basis is the a layer called "Gonk". It consists of an Android Linux kernel and Android device drivers, and the Android Hardware Abstraction Layers (e.g. for input handling). All graphics rendering is done using OpenGL ES 2.0 (no X11 is used).

On top of that Gecko can be found. It is the same rendering engine that powers Firefox on the desktop or on the mobile phone and essentially transforms HTML pages with CSS, JavaScript and all the other web technologies into drawing operations that are then given to your graphics card.

The topmost layer is the only one that is visible to the end user: the user interface. The default user interface for Firefox OS, which you can see on all the great pictures of Firefox OS phones, is called "Gaia".

For more detailled information about the architecture of Firefox OS have a look at the B2G Architecture document by Mozilla.

For the use on Raspberry Pi, some changes to this software stack are necessary. First of all, no Android kernel is used, but a plain (vanilla) Linux kernel. The same is true for the hardware abstraction layer. The changed layer got the name "LinuxGL", a mixture of Linux and OpenGL. As the name implies, graphics rendering is again done using OpenGL without X11 (this is the main difference to the usual way Firefox runs on Linux).

On top of the LinuxGL layer sits again the Gecko rendering engine.

Finally, the user interface part is up to you. Depending on the use case for your Raspberry Pi, you might choose to use the Gaia interface as well, or to write your own UI. In all cases, it's just plain HTML, CSS and JavaScript.

All those components need to be integrated and built. This job is done by Yocto/OpenEmbedded. Based on a set of rules, a full SD card image containing Linux, all device drivers and Firefox OS is built.

Get it

You can either build your own Firefox OS for Raspberry Pi image, or you can download a pre-built image from the list below:

Build it

System Requirements

Building a whole Linux distribution with Firefox OS takes a lot of CPU power and also requires quite some space on your hard disk. For a pleasant development experience, your PC should have Compiling in a virtual machine is considerably slower and not recommended.

Initialize Your Build Environment

Before you can start building everything, you need to have a working build environment on your PC. Since we use OpenEmbedded, the requirements are quite low (everything else is built by OpenEmbedded itself), but still, some tools are required. These are: Install those tools using your distribution's package manager. In openSUSE, you can do that by running
sudo zypper install git mercurial diffstat chrpath python-curses

Get the Code

In the following we assume that you will have all your code inside your home directory in a folder called "src". If you choose another location you'll need to adjust the commands below accordingly.
cd ~/src
git clone git://git.yoctoproject.org/poky
cd poky
git clone git://git.yoctoproject.org/meta-raspberrypi
git clone git://git.openembedded.org/meta-openembedded
git clone git://github.com/imphil/meta-b2g.git

Initialize OpenEmbedded

First, you need to initialize the OpenEmbedded build environment. Run
cd ~/src/poky
. ./oe-init-build-env rpi-build
to create the build directory. Now you need to edit two configuration files inside the conf directory: bblayers.conf and local.conf. The first one contains information about the enabled OpenEmbedded Layers, the latter one information adjusts the build process to your system.

bblayers.conf

We'll start with bblayers.conf. Open the file in your preferred editor and edit it to add the bold-printed layers. You need to use absolute paths, adjust them to fit your environment.

# LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
LCONF_VERSION = "6"

BBPATH = "${TOPDIR}"
BBFILES ?= ""

BBLAYERS ?= " \
  /home/USERNAME/src/poky/meta \
  /home/USERNAME/src/poky/meta-yocto \
  /home/USERNAME/src/poky/meta-yocto-bsp \
  /home/USERNAME/src/poky/meta-raspberrypi \
  /home/USERNAME/src/poky/meta-openembedded/meta-oe \
  /home/USERNAME/src/poky/meta-openembedded/meta-networking \
  /home/USERNAME/src/poky/meta-openembedded/meta-gnome \
  /home/USERNAME/src/poky/meta-b2g \
  "
BBLAYERS_NON_REMOVABLE ?= " \
  /home/USERNAME/src/poky/meta \
  /home/USERNAME/src/poky/meta-yocto \
  "

local.conf

Now we'll edit the local.conf file. Again, open it in your preferred editor. First, edit the two variables BB_NUMBER_THREADS and PARALLEL_MAKE. Set BB_NUMBER_THREADS to the number of CPU cores you want to use and PARALLEL_MAKE to "-j NUMBER_OF_CORES" (replace NUMBER_OF_CORES again with the number of CPU cores you have available). For a quad-core machine, the following settings would result:

BB_NUMBER_THREADS = "4"
PARALLEL_MAKE = "-j 4"

Now go down to the "Machine Selection" section of the configuration file. There, add the following line above the MACHINE ??= "qemux86" line:

MACHINE ?= "raspberrypi"

Finally, add the following three lines at the end of the file:
BBMASK = "meta-raspberrypi/recipes-multimedia/libav|meta-raspberrypi/recipes-core/systemd"
DISABLE_OVERSCAN = "1"
GPU_MEM = "64"
The first line masks some unnecessary recipes. The second line disables overscan. You can enable it if you want to use your Raspberry Pi on a TV device. Finally, the third line specifies the amount of memory used by the GPU. Depending on your Raspberry Pi model, 256 or 512 MB RAM are available. 64 MB graphics memory was enough in initial tests, but further tests are required to determine a good value here. For reference, a complete local.conf file could look like this one (with all comments removed):
BB_NUMBER_THREADS = "4"
PARALLEL_MAKE = "-j 4"

MACHINE ?= "raspberrypi"
MACHINE ??= "qemux86"

DISTRO ?= "poky"

PACKAGE_CLASSES ?= "package_rpm"

EXTRA_IMAGE_FEATURES = "debug-tweaks debug-tools nfs-server"

USER_CLASSES ?= "buildstats image-mklibs image-prelink"

PATCHRESOLVE = "noop"

BB_DISKMON_DIRS = "\
    STOPTASKS,${TMPDIR},1G,100K \
    STOPTASKS,${DL_DIR},1G,100K \
    STOPTASKS,${SSTATE_DIR},1G,100K \
    ABORT,${TMPDIR},100M,1K \
    ABORT,${DL_DIR},100M,1K \
    ABORT,${SSTATE_DIR},100M,1K" 

CONF_VERSION = "1"

BBMASK = "meta-raspberrypi/recipes-multimedia/libav|meta-raspberrypi/recipes-core/systemd"
DISABLE_OVERSCAN = "1"
GPU_MEM = "64"

Compile everything

Now that you have checked out all sources and created all configuration files you're ready to build everything. Run
cd ~/src/poky
. ./oe-init-build-env rpi-build
bitbake -v rpi-b2g-image

Now OpenEmbedded takes over, fetches all required source packages from the Internet and builds everything. This process will take a couple hours, so go and get some fresh air until everything is ready for you to play with. (Just getting a coffee will definitely be not enough, even a six-course dinner might take not long enough.

Sometimes the git fetch from github will fail (e.g. to get the Raspberry Pi firmware). If this happens, simply re-run bitbake to try again, it usually works the second or third time.

Currently the meta-oe (meta-openembedded) layer contains a bug which prevents building the whole system since two dependencies are missing. If you get an error about missing Perl or Bash in the do_rootfs step of bitbake, try to apply this patch sent to the OpenEmbedded mailing list.

After bitbake finishes, a SD card image containing a complete Linux distribution together with Firefox OS is created. Assuming you used the recommended folder for your build environment, you can find the image at ~/src/poky/rpi-build/tmp/deploy/images/rpi-b2g-image-raspberrypi.rpi-sdimg.

Congratulations, you've successfully managed to build Firefox OS for your Raspberry Pi! Now fasten your seatbelts as we're getting ready to power up the device with it.

Flash It

In this step we'll prepare a SD card with the Firefox OS image. First, you need to have a SD card image ready. You can either

If were building the image yourself, you're ready to go. If you plan to use a pre-built image, you need to first decompress it:

bunzip rpi-b2g-image-raspberrypi-*.rootfs.rpi-sdimg.bz2

Now insert the SD card into your reader. Depending on your desktop environment, it will try to auto-mount the card or show you its contents. Close all those windows and umount the card again. To write the image to the card, you need the device name. The easiest way is to look at

dmesg | tail
after inserting the card. You'll see messages like this one:
sd 6:0:0:1: [sdd] 63404032 512-byte logical blocks: (32.4 GB/30.2 GiB)
sd 6:0:0:1: [sdd] No Caching mode page present
sd 6:0:0:1: [sdd] Assuming drive cache: write through
The interesting information is [sdd], which tells us that the device /dev/sdd was added. Write down this device name, as we'll need it below to write the image to.

Before we can write any data to the device, we need to ensure that it is not mounted. Run

mount
and ensure that no device with the device name you figured out earlier is listed.

If it is still mounted, run

sudo umount /dev/sdd*
(replace sdd with your device name) to umount it.

Ensure that you use the right device in the following steps. All contents on it will be overwritten!

Now you're ready to write the image to your SD card. Simply run

sudo dd if=your-image.rpi-sdimg of=/dev/YOURDEVICE
sync
(again, replacing YOURDEVICE with your SD card device, e.g. sdd).

After those two commands succeded, you can remove the SD card from your reader and you're ready to run Firefox OS on your Raspberry Pi for the first time!

Run It

Since you've mastered all the more difficult steps up to now, we're now ready for the first look at Firefox OS. Insert your prepared SD card into your Raspberry Pi, connect the keyboard, the monitor and the network cable (if available). Now also plug your power cable in and the Raspberry Pi will boot up. After a couple seconds you should see a small raspberry on the top-left corner of your screen, and after a couple more seconds a splashscreen will show a large raspberry and a progress bar. Note that the first boot will take longer than the subsequent boots, be patient!

As soon as the device is booted you'll be presented with a console login screen. The username is root and no password is set (simply press enter).

If you connected a network cable test if you have connectivity. If your network supports DHCP, the network should already be configured and you can test it by running "ping", like shown below.

root@raspberrypi:~# ping mozilla.org
PING mozilla.org (63.245.217.105): 56 data bytes
64 bytes from 63.245.217.105: seq=0 ttl=54 time=209.268 ms
64 bytes from 63.245.217.105: seq=1 ttl=54 time=203.915 ms

If you don't use DHCP use the standard Linux utilities (like ifconfig) to set your network configuration.

Displaying a Web Site

A first test is to use Firefox OS to display a single web site. Run

B2G_HOMESCREEN=http://www.mozilla.org b2g &
on your Raspberry Pi. After a couple of seconds, the Mozilla homepage should appear on your screen.

The same also works for local sites (use file:// URLs), so you can use your Raspberry Pi to show information or status pages (like a "News" page or the server status).

Displaying a WebApp

This section still requires some more work and will be added soon, please stay tuned.

Connect to your Raspberry Pi

By default a SSH server is installed and enabled. You can connect as user "root" with no password by default.

Develop Firefox OS

This section will be added in the future, please stay tuned.