Hacking b2g on Raspberry Pi

This page is intended for folks who are interested in building and running b2g on Raspberry Pi devices.

NBB: parameters like RAM allocation for video memory are currently tuned for Raspberry Pis with 512MB RAM (Model B rev2 and Model B+). A 256MB Pi should work but performance may not be optimal.

Status

b2g on the Raspberry Pi is still very much a work in progress. Eventually a nice compability matrix will be posted. Also see bug 1001404 for overall tracking. For now, the worst bugs to watch out for are

• OpenGL rendering is not supported yet. This means graphics performance is worse than it will be eventually. Also, WebGL won't work correctly either. bug 1084624
• the output resolution of the RPi is artificially limited to 480p for the time being. bug 1072148
• audio output doesn't seem to be fully working bug 1072499
• system capabilities like camera and GPIO access are not yet supported by the b2g runtime.

Flash an existing build

First download the build. Next extract it as follows

tar jxvf ffos-rpi-*.img.tar.bz2

That will produce a file called ffos-rpi-*.img. Now insert your SD card into a card reader/writer. Your OS should add your SD card as a device called something like /dev/mmcblk0, /dev/sdc, or /dev/disk2. Let's call that device $disk below.

WARNING WARNING WARNING: the remaining steps with COMPLETELY AND PERMANENTLY ERASE YOUR SD CARD. Be extra-triple-careful that you found the right device for your SD card.

Finally, run

sudo dd bs=4M if=ffos-rpi-*.img of=$device

Note: this disk image is pre-partitioned for a 4GB disk. If you have a larger SD card and want to allocate the remaining space for your SDCARD partition, then resize that partition in a tool like gparted.

Enable touchscreen output

b2g on the Raspberry Pi supports a class of extension touchscreens. So far, only the PiTFT has been tested, so that model is strongly recommended. The default prebuilt b2g image, and images you build yourself, include support for touchscreen output by default. However, it's disabled by default.

Once you've attached a touchscreen (by which we mean the PiTFT) to your Raspberry Pi (when it's powered off, of course), you can enable it by running the following command through adb (see below)

adb shell setprop persist.fbtft adafruitts

This restarts b2g and has it output to the PiTFT device. At any time you can revert to HDMI output by running

adb shell setprop persist.fbtft none

This setting persists across reboots, as you would expect.

Note: if you're configured your RPi to output through the touchscreen, and you disconnect the touchscreen (when the RPi is powered off, of course), then after rebooting the RPi may still try to output through the nonexistent screen. This bug is not yet understood and seems to be a kernel issue. But you can still follow the directions above to revert to HDMI output.

Building b2g for RPi

Install the b2g build prerequisites. For the time being, only linux is officially supported as a build environment; you can use OS X but you'll have to manually partition your RPi's SD card for the first flash. Note that Ubuntu 12.04 is the best-supported development OS. If you're not running Ubuntu 12.04 on your development machine, you can install it as virtual machine and build in there.

A b2g build environment consumes a fair amount of disk space, between 15-20 GB. Please make sure you have enough free space on your development machine (or VM).

To build b2g for your RPi, first download the b2g helper scripts

git clone https://github.com/mozilla-b2g/B2G.git

Next configure b2g for your Raspberry Pi

cd B2G
./config.sh rpi

The config.sh step can take quite a while, because it downloads a large amount of data. Once that finishes, you need to apply a patch to the gecko checkout (for now; the patches are making their way through reviews etc.). Download the patch from here and then apply to your B2G/gecko subdirectory by running the command

(cd gecko && git apply [the patch you downloaded])

Note: if git apply fails, you may need to use patch -p1. Also, the contents of this patch should shrink over time as changes are landed upstream. So after you repo sync your checkout, you may need to return to this page and apply a new version of the patch. Hopefully, soon no extra patches will be needed.

Note: because of bug 1085599, gecko is frozen to this version, and gaia is frozen to this version (just because the gecko version is frozen). If a feature you were expecting to use is unavailable, this might be why. But normally you don't need to worry about this.

Next, either copy the files device/rpi/rpi/custom-settings.json and device/rpi/rpi/custom-prefs.js in your gaia/build/config/ directory, or --- if you already have custom settings or prefs --- append the contents of those files to your existing custom-* files.

Finally, build b2g

./build.sh

This step also takes some time, because it's building an entire operating system. When your build finishes, it's time to flash it onto an SD card for your RPi.

A prebuilt linux kernel image is included in the b2b source checkout. However, if you want to build your own kernel, follow the instructions in $B2G/device/rpi/rpi/README.

Preparing to flash b2g onto your SD card

Note: you may find it more convenient to simply flash an existing image, following the instructions above.

Flashing an image requires the following

• an SD card with a capacity of at least 4GB
• a machine with an SD card reader/writer
• a linux host OS on which you have superuser privileges

An Ubuntu 12.04 OS is recommended for building, but any linux distribution is OK for flashing an image. If you're running Ubuntu 12.04 in a VM, that's perfectly fine: you can mirror your build into your host OS and then flash from your host.

On Ubuntu 12.04, you may need to disable automounting of USB drives.

If you built b2g in your host OS, you can skip the following instructions.

To mirror your b2g build into your host OS, first find out your guest VM's IP address by running the following command within your guest VM

ifconfig

You'll see a line printed that says something like inet addr:AAA.BBB.CCC.DDD. That AAA.BBB.CCC.DDD is your guest VM's IP address.

Next install sshd on your guest OS. On ubuntu, use the command

sudo apt-get install openssh-server

Other distributions require similar commands.

Next, on your linux host, install sshfs. On ubuntu, use the command

sudo apt-get install sshfs

Other distributions require similar commands. You also need to enable "other users" to access your sshfs mounts. (The other user will be superuser, when you flash your image following the instructions below.) First run the command

sudo gedit /etc/fuse.conf

Then find the line that reads

# user_allow_other

And edit it to

user_allow_other

Save the file by pressing Ctrl-s and then close the editor.

Finally, mount your guest VM's build image by running the following commands

mkdir B2G
sshfs $user@$AAA.BBB.CCC.DDD:/home/$user/$B2G B2G -o allow_root

Be sure to replace $user with your username in your guest VM, $AAA.BBB.CCC.DDD with your guest VM's IP address that you found following the instructions above, and $B2G with the path to the B2G checkout you made above within your home directory.

To ensure that your build has been mirrored correctly, run the following command in your host OS

ls B2G

You should see listed all the files and directories from your B2G/ directory in your guest VM.

You'll usually want to unmount the remote B2G directory when you've finished flashing your SD card. To unmount it, run the command

fusermount -u B2G

Flashing b2g onto an SD card

You only need to follow these steps once. After your SD card is prepared for the first time, you can update it with new build files without removing it from your RPi. Those partial-update steps are described below.

Note: you may find it more convenient to simply flash an existing image, following the instructions above.

To flash an SD card with a B2G build for the first time, run the commands below. (If you built in a guest VM, be sure to follow the steps above to mirror your build into your host machine.)

cd $B2G
sudo ./flash.sh -f

You have to run the flash.sh command as superuser because it directly writes to your SD card block device. Follow the instructions and prompts presented by flash.sh to complete the setup process.

The script attempts to auto-detect your SD card. If it fails, then simply pass your SD card device to the script manually as follows

sudo DISK="/dev/your-sd-card" ./flash.sh -f

When the flashing script finishes, your SD card is ready. Congratulations! Remove it from your host machine, insert it into your Raspberry Pi and start up b2g! :)

Preparing a development environment

To hack b2g on the RPi, you'll need to create an adb connection. adb is the "android debug bridge" over which diagnostic output is received and development commands are sent. Usually an adb connection is made over USB, but the RPi's USB ports can't be configured for slave mode. (On Models B and newer.)

You can connect adb over TCP/IP, though. You have the option of connecting over wifi or ethernet. To connect over wifi, first join the wireless LAN that your host machine is on.

WARNING WARNING WARNING: FFOS builds for the RPi are intended for DEVELOPERS. They are WILDLY INSECURE. Don't connect your RPi to a network on which you don't mind it getting completely pwned.

Next, find your wifi card's IP address through the gaia settings app. Call this address $IP. Finally, on your host machine, run

adb connect $IP:5555

(5555 is the port that the adb server on your RPi listens on.)

Alternatively, to connect over ethernet, first connect your RPi's ethernet cable to your LAN. The SAME CAVEATS ABOUT SECURITY apply. Next, boot up your RPi and find out its IP address on your LAN. You can do this by either looking at your network router's client table (easy), or running the following command on your RPi's serial console (a little harder; see instructions below on how to set up a serial console)

netcfg

Let's call your RPi's address $IP. Connect adb by running the following command on your host machine

adb connect $IP:5555

To test your adb connect, run the following command on your host

adb logcat

You should see a long list of diagnostic messages. Pressing Ctrl-c stops the logcat output.

In addition to adb, a serial console is strongly recommended. A serial console is basically required for anyone doing networking or kernel development. You can purchase a serial-to-USB or serial-port connector for your RPi, for example this one from adafruit. Some RPi kits also include one of these. The adapter shown above requires you to connect the black lead to pin 6 (ground), the white lead to pin 8 (GPIO14, UART0_TXD), and the green lead to pin 10 (GPIO15, UART0_RXD). You don't need to connect the red lead if your RPi already has a power source.

WARNING: be very careful that you connect the leads to the correct pins! At least one developer has burned out a USB-to-serial adapter by connecting the wrong pins.

The b2g kernel is pre-configured to open a serial console for the RPi, so all you need to do is plug the USB cable into your host machine and start up a terminal emulator. The minicom program works well. On ubuntu, install minicom with the command

sudo apt-get install minicom

Then connect to your RPi using the command

minicom -b 115200 -o -D /dev/ttyUSB0

(Replacing /dev/ttyUSB0 with the device assigned to your USB-to-serial adapter, if it's not assigned that name.) You should then see terminal output and get a shell prompt.

Note: you must run minicom in a "smart terminal". minicom doesn't work when run inside an emacs shell, and it errors out with a somewhat cryptic message ("No cursor motion capability (cm)").

Rebuilding b2g and updating your RPi

To update your B2G build directory to the latest sources, run the following commands

cd $B2G
./repo sync
./build.sh

You can sync these files to your RPi using the regular b2g update commands, while your RPi device is running b2g. You don't need to power off your RPi or remove its SD card to update it. The commands are

• ./flash.sh : update the system and data files
• ./flash.sh system : update the system files
• ./flash.sh data : update the data files
• ./flash.sh gecko : update the b2g runtime
• ./flash.sh gaia : update the gaia apps and data

In addition, you can run the following non-standard update commands

• ./flash.sh boot : update the RPi firmware, bootloader files, and kernel
• ./flash.sh kernel : update the kernel only

You can also flash your SD card anew at any time by following the instructions above. But this should usually not be necessary.