B2G installer add-on

The B2G installer add-on helps to solve the long-standing issue of not being able to redistribute full system builds because of blobs (proprietary components.) This article details how the add-on works, and how to install it.

Building a blobfree distribution

One solution to the named issue above is to produce a so-called "blobfree" distribution (see bug 1175934) that bundles everything needed for a device build:

• Full system built out of sources.
• Device compatibility information.
• Partition mapping.
• List of required Blobs, along with mappings to their required destinations in the final build.

Such a blobfree distribution can be built by specifying the |blobfree| make target when building B2G:

$ ./build.sh blobfree

The B2G installer add-on facilitates installing such distributons.

Adding new device support

To make a new device available from within the add-on when the user plugs in a compatible device, a few steps are required:

1. Make sure that your device has support for generating a blobfree distribution. Check the blobfree section of the B2G building page.
2. Once your device does have support for this, you can proceed to make it available from the add-on. First, fork the builds repository.
3. File a bug in Bugzilla in the Firefox OS :: B2GInstaller component.
4. Augment builds.json with the information for your new device.
5. Send a PR on Github, attach it to the bug you created and ask for review :gerard-majax.

The builds.json file contains an array of objects, each one describing a compatible device. Those objects have the following properties:

• id: The name of the device as displayed to the user.
• builds: An array of the builds available for this device. Each build object inside the array must have these properties:
  • name: The string displayed when selecting the build.
  • description: A user-friendly description of what this build is.
  • url: URL of the blobfree distribution file.
• adb: A set of Android properties that the device MUST match to be detected as compatible.
• fastboot: A set of Fastboot variables that the device MUST match to be detected as compatible.
• requiresRoot: Optional value that defines whether the device must be rootable for installation to go ahead. This defaults to true.

Installation

To install the B2G installer add-on, follow these steps:

• Make sure you are running Firefox Desktop Nightly and have the ADB Helper installed (v0.8.6 at least) — see the bottom of the fxos-simulator page for the install link.
• Create a separate profile

  ./firefox -P

• Install the B2G installer add-on XPI, using either of those methods:
  • Install it from AMO (recommended).
  • Build it yourself — see the Hacking section.
• Make sure ADB helper 0.8.6 or higher is installed (WebIDE -> Project -> Manage Extra Components)
• Make sure you have at least 2GB of available space in /tmp/.
• Load the about:b2g-installer page (write this in the search bar). You might have to restart the browser before this works the first time.
• If you want to help us improve the addon, you can tick the checkbox to collect information directly from your usage sessions. What information we collect is explained below, in the Data section.

Ready to use VM

You can also make use of a pre-built virtual machine as an OVA package. Please check with VirtualBox or your favorite tool on how to import this appliance. It provides a ready-to-use B2G Installer installation that supports some devices out of the box (udev, etc. already configured.) See bug 1204482 for more details, and the link below to download. Please verify the SHA1 to make sure the VM is good to use (~1.5GB download).

https://drive.google.com/file/d/0B8Ju6ek0Knd6WnE0N2F6ZHF0VTQ/view?usp=sharing
SHA1: 01574220718e90d7de498952270cbbaee8e85acd

It is recommended to use the VM if you are running on an OS where B2G Installer does not work (e.g., Windows), or if you are running into issues with the steps above. The default configuration of this VM should handle those devices:

• Mozilla Flame
• Sony Xperia Z3 and Sony Xperia Z3 Compact
• LG Nexus 4 and LG Nexus 5
• Fairphone 2
• Wileyfox Swift

If you are willing to flash another device, you will have to configure USB passthrough with the proper USB VID/PID (do not forget the fastboot ones, that might differ) and also configure udev rules.

Usage

1. When the add-on starts up, it will download builds.json from Github to get the list of available builds. A local zip file can always be used.
2. Attach your device via USB, and wait for the add-on to detect it.
3. Once it has been detected as a supported device, a list of builds will be made available.
4. Pick the build you want, click Flash and wait. 

Screenshots

When the device is not plugged in:

When selecting a build:

When flashing a device:

Data

As part of improving the addon, we are collecting some data as it is used. The main goal is to ensure the add-on works properly for everyone. We are also collecting data to discover which devices people are interested in, so that supported builds can be adjusted accordingly. No tracking is being done.

We are sending two external telemetry pings to collect this data:

• One upon the device being detected by the add-on after it is plugged into the computer (this will happen every time the add-on is running *and* a device with ADB enabled is plugged in.) For this ping, we record:
  • Device identification variables (model, build id, manufacturer, bootloader.)
  • Whether this device has a CyanogenMod build installed.
  • Whether a supported build was detected on the device.

  Sample payload of plugging a supported device:

  {
    "payload": {
      "buildid": "KOT49H",
      "isSupported": true,
      "model": "Xperia Z3 Compact (B2G)",
      "bootloader": "s1",
      "manufacturer": "Sony"
    }, [...]
  }

  Sample payload of plugging an unsupported device:

  {
    "payload": {
      "buildid": "LVY48I",
      "isSupported": false,
      "model": "Xperia Z1 Compact (B2G)",
      "bootloader": "s1",
      "manufacturer": "Sony"
    }, [...]
  }
  

• One each time a device flashing procedure is running. That will happen either at the end of a successful flashing procedure, or upon failure. For this ping, we record:
  • The same variables as above.
  • Whether the device is already running a B2G build.
  • The URL of the build flashed (full path for a public build, filename without the whole path for a local build.)
  • Whether the user kept their data.
  • Whether the flashing was successful.

  Sample payload with flash success:

  {
    "payload": {
      "isSupported": true,
      "installResult": true,
      "runsB2G": true,
      "buildid": "KOT49H",
      "keepData": false,
      "buildURL": "https://index.taskcluster.net/v1/task/gecko.v1.mozilla-central.latest.linux.nexus-4-kk-user.opt/artifacts/public/build/mako.blobfree-dist.zip",
      "model": "AOSP on Mako",
      "bootloader": "MAKOZ30d",
      "manufacturer": "LGE"
    }, [...]
  }

  Sample payload with flash failure:

  {
    "payload": {
      "isSupported": true,
      "installResult": false,
      "runsB2G": true,
      "buildid": "KOT49H",
      "keepData": false,
      "buildURL": "https://index.taskcluster.net/v1/task/gecko.v1.mozilla-central.latest.linux.nexus-4-kk-eng.opt/artifacts/public/build/mako.blobfree-dist.zip",
      "model": "AOSP on Mako",
      "bootloader": "MAKOZ30d",
      "manufacturer": "LGE"
    }, [...]
  }

Hacking

• The code lives in the b2g-installer repo. You need to apply the patch to a mozilla-central clone, and then symlink browser/extensions/b2g-installer to your clone of the b2g-installer repo.
• To build it you need to run |./mach build && ./mach build package|.
• The resulting XPI will be produced in your MOZ_OBJDIR/dist/xpi-stage/b2g-installer/ directory.
• It contains a copy of the source code of external tools from AOSP/CAF, needed when building partitions.
• Tests are written as mochitest/xpcshell tests.
• Check also the meta bug and its dependencies: Bug 1166276

TODO

1. Move back out of mozilla-central tree for building. This probably implies rewriting tests with something else than mochitests.
2. Convert building of tools from moz.build to Makefile.
3. Support external source of blobs (needed to handle upgrade case).