Updating your Flame

This article covers how to update the software on your Flame — including updating Firefox OS and pushing new apps to your phone — along with backing up your data, and other useful troubleshooting and testing information. Before starting to do any of this, you should make sure you have run through the Initial setup information.

Quick guide to updating your device

There is a lot of information in this article, so here we've included a quick start guide that takes you through the steps you need quickly to get your device updated. You can refer to the below sections for more detail if it is needed.

Full flash to the latest base image

This set of steps needs to be done before you do anything else to your phone (see Base image and Base image installation if you require more details.)

Prerequisites: Make sure you have adb and fastboot installed and available in your system's PATH (see Installing ADB and Fastboot.)

Download the latest base image —Base image v18D_nightly_v5 — to your computer.
On your Flame device, enable remote debugging by navigating to Settings > Developer and enabling the Debugging via USB option.
Connect your Flame to your computer via a USB cable.
Verify that the computer is connected to the device by typing this command:
```
adb devices  
```
You should see something like the following:
```
List of devices attached
94f7ce4c    device
```
If you don't see your device attached (no second line), then try unplugging and replugging the USB cable and trying again; also check that Debugging via USB is enabled on the phone as mentioned in step 2. If you get a message saying that adb could not be found, you probably haven't set your path correctly (see prerequisites.)
Extract the base image zip file and navigate to the new directory, using for example:
```
cd v18D_nightly_v5
```
Run the flashing script by running the correct below command for your system
```
# Windows
flash.bat
# Linux / OSX
./flash.sh
```

Note: if you don't see the right filename for your system, you can rename flash.bat or flash.sh back and forth as needed. The contents are the same.

Note: Verify the contents of the base image using the checksum below:

Checksum: SHA512(v18D_nightly_v5.zip)= f92123446f71289dd0ea23b0c602f8a192267fbfcf2f25682cbc072f8bbe3e8b795aea3305ba6ea6cc504d252f1d895b07704b5b65700fcf3760e1386b89c431
Build id: 20151221215202

At this point you should be on the latest 2.6 base image, and be able to receive FOTA updates.

Note: if you want to be on the very latest builds of flame (that have not been smoke tested), go to settings -> developer, scroll down to the bottom, and change the channel to nightly-latest. Reboot the device, then go back to settings -> device info and check for updates. You can update to the latest version without having to shallow flash. For shallow flashing see the next section.

Update channel reset bug

As mentioned in bug 1217490, some Firefox OS testers testing Firefox OS 2.5 or the latest FOTA updates (on Flame, but also on other dogfooding devices) may find that when they install a FOTA update, their update channel is reset to nightly, meaning that they won’t receive subsequent FOTA updates coming through other channels. To avoid this, it is recommended that you set your update channel to nightly-latest in the Firefox OS settings via WebIDE. To do this:

Plug your phone into your computer via USB (make sure Debugging via USB is set to ADB and DevTools in the Phone's Developer Settings.)
Go to Firefox Desktop and open WebIDE.
Connect WebIDE to your phone by selecting it under USB Devices. Accept the connection prompt that appears on your phone.
Under Other on the right hand side of the WebIDE UI, select Device Settings.
Find app.update.channel in the list, and change the setting value in the corresponding textbox to nightly-latest.
Find app.update.channel.backup and change the setting value to nightly-latest if you want it to persist after further updates.

Shallow Flash to the latest Firefox OS nightly (Gaia and Gecko)

This set of steps only needs to be done if you want to update to the VERY latest builds (see Updating your Flame to a nightly build if you require more details.)

Prerequisites: Windows users will need to install Cygwin, which provides a Linux-like environment on Windows. The instructions below include steps for how to automatically install the appropriate packages if you don't already have it installed.

Download the latest build from Mozilla Central. Download both the b2g-XX.XX.en-US.android-arm.tar.gz and gaia.zip files.
All platforms: Download the shallow flash script in the same directory as the build files.
Windows users: Also download the shallow_flash.bat Windows script in the same directory. If you don't already have Cygwin installed, also download the installation file (you don't have to run it, the shallow_flash.bat script will use the installer to automatically configure the necessary packages).

In your terminal, cd into the directory you saved the files in and flash the builds to your phone using the following:

# Linux
./shallow_flash.sh --gaia=gaia.zip --gecko=b2g-XX.XX.en-US.android-arm.tar.gz
# Mac
./shallow_flash.sh --gaia gaia.zip --gecko b2g-XX.XX.en-US.android-arm.tar.gz
# Windows
# You could also double click the shallow_flash.bat icon (with the cogs) from Windows Explorer.
shallow_flash.bat

This process will flash gaia.zip and a single b2g-XX.XX.en-US.android-arm.tar.gz file onto your phone. The files will be sent to the device and it will reboot after the process completes.

Note : On Linux, if the script fails during flashing Gaia, you can try replacing full options by their shortened version to see if that helps. Replace --gaia=gaia.zip by -g gaia.zip and --gecko=b2g-XX.XX.en-US.android-arm.tar.gz by -G b2g-XX.XX.en-US.android-arm.tar.gz.

Updating & upgrading the Flame's software

We have two main "channels" of Firefox OS software version releases for the Flame phone:

The first channel is our release channel. Flames ship with this channel and will receive over-the-air updates for future major versions, that is, Flames will update from 1.3 to 2.0 to 2.1, etc.
The second channel is our nightly channel. Flames can be flashed to this channel, and after the initial flashing will get over the air updates on a daily or nearly daily basis.

Base Image

You can get recovery files and tools at the following storage locations:

Up-to-date (use these unless you have a good reason not to)

Production:
- Stable: Base image v18D.zip: The very latest stable archive, containing a Flame base production image of Firefox OS 2.0.
- Nightly: Base image v18D_nightly_v5: The very latest version of the Flame base production image of Firefox OS 2.6.
```
Checksum: SHA512(v18D_nightly_v5.zip)= f92123446f71289dd0ea23b0c602f8a192267fbfcf2f25682cbc072f8bbe3e8b795aea3305ba6ea6cc504d252f1d895b07704b5b65700fcf3760e1386b89c431
Build id: 20151221215202
```
- Sideload: image v18D_nightly_v5 update.zip: The sideload file for updating your phone manually. See the sideload section for instructions on how to update your phone to this build without losing data.
```
Checksum: SHA512(update.zip)= 4c174f901a242a96729aa45d8551200ef4566913473f88f935c264689031a483e46d21856f0919c4dff467277d2f9c90cf0879107a6671d7b84c5d05405f4b6d
Build id: 20151221215202
```
- Nightly: Base image v18D_nightly_v4: contains a Flame base production image of Firefox OS 2.5. This is the same as the previous one but with the updated system partition size (see bug 1184980.) Before updating your phone to a Nightly build you should flash the latest base image to make sure the underlying systems are up to date.
```
Checksum: SHA512(v18D_nightly_v4.zip)= 9105e29fd39da1ae487b01da4431a803d619d31482147b4383002b8a10268905fd444b108a438395a78d289cfe4e8fba10c3fb6b0d187f3535f027bf90c2391a
Build id: 20150527010201
```
- Nightly: Base image v18D_nightly_v3: Contains a Flame base production image of Firefox OS 2.5 that includes security, font, NFC, camera, and other fixes (see bug 1154072 for more details.)
```
Checksum: SHA512(v18D_nightly_v3.zip)= 98ec1d24604eaed4a22e7d1439501544622788b30f8f2993409bfc2244a4886863d33238aa78ccb7cd5f9f71464058b81920cc0ba85806a1dbf0220d08a8444b
```
Engineering: There is no engineering Base image. Use a production base image and flash it to an engineering nightly build.

Note: You can find out what base image your device is running using the command adb shell getprop ro.bootloader. The version is the last four characters, with the last one then removed, prefixed by 'v' (e.g. L1TC000118D0 > v18D).

Important: When running a shallow or full flash, your phone data will be overwritten: you should therefore back up your data before updating! See the Backing up and restoring your Flame data section for more details.

Outdated

These base images are stable & production only.

Base image v188.zip: An updated archive containing a Flame base image of Firefox OS 2.0 with bug fixes from the previous image.
Base image v180.zip: An older archive containing a Flame base image of Firefox OS 2.0.
Base image v123.zip: A discontinued image of Firefox OS 1.3 based on Android Jellybean; you shouldn't use this anymore.

Note: Using a locale with base image v188 produces a mixed UI with locale and English languages.

Note: Firefox OS images v180 and above are based on Android KK (Kitkat, 4.4); JB (Jellybean, 4.1–4.3) builds have now been discontinued and are no longer supported, so don't use anything older than v180.

Base Image installation

To install the base image on your device:

Make sure remote debugging is enabled on your Flame, using the Remote debugging/Debugging via USB option in the device's Developer settings (the option is different, depending on whether you have Firefox 1.3 and under, or Firefox 1.4+ installed).
Connect your Flame to your computer via a USB cable if it isn't already. Verify that the computer is connected to the device by running the adb devices command in a terminal.
Download the base image .zip file referenced above. Unzip it onto your Desktop.
Go into the directory you extracted the software into and run it:
- On Windows, enter the directory in your command prompt, then run the flash.bat script using flash.bat (or double click the file in explorer).
  Note: If flash.bat is missing, simply rename the flash.sh file to flash.bat, then run that. Make sure you have adb and fastboot installed and available on PATH.
- On Linux / OSX, enter the directory in your terminal, then run the flash.sh script using ./flash.sh (previous instructions encouraged you to use sudo. Don't. It is really dangerous to use sudo with things you download from the Internet. If the flash script fails to see your device, please double-check that your udev rules are correct). If you do not see a flash.sh file, simply rename flash.bat to flash.sh first and then use the above command.

Note: If you get a "permission denied" error when running the above commands, your shell script probably doesn't have the right permissions. Running chmod +x flash.sh on it should solve this problem.

Note: If the flash script gets stuck at "< waiting for device >" while the display shows "ThunderSoft(R)", the script doesn't have permission to access the device while in fastboot mode. You need to setup the udev rules to give it access. Also USB 3 ports may not work well with fastboot and can be the cause of this problem.

Note: You are also welcome to build your own builds to install on the Flame: see Building and installing Firefox OS.

Font fix

Important: This step is only needed for base image v180.

After updating Gecko and Gaia to nightly with the v180 base image, there will be a mismatch between the fonts that Gecko and Gaia expects and what the base image provides (this has been fixed as of v188). To fix this, you have two choices:

download our font update package, extract it, navigate into the directory created by extracting, and run the supplied flash.sh script.
use the update_system_fonts.sh script, which will download and flash the system fonts automatically.

Updating your Flame to a nightly build

Note: For the current build, Nightly development builds of Firefox OS do not support A-GPS, which may lead to slow performance of GPS functionality. We plan to resolve this in an updated future Nightly channel.

Before updating your phone to a Nightly build you should flash the latest base image to make sure the underlying systems are up to date. Download a base image with the same or a higher version of Firefox OS than the version you intend to use in step 3 below and use it to update your device's software, as explained above.
Because the above step installs a fresh operating system on your device, you'll need to enable remote debugging on your Flame again, using the Remote debugging option in the device's Developer settings.
Next, choose a build to install (found on https://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/). You'll want one of the following:
- Production builds (including locales)
  - Latest master builds (currently 2.6)
  - Latest v2.5 builds
  - 2.2 build
  - 2.1 build
  - 2.0 build
- Engineering builds (with test apps and only pseudo-locales)
  - Latest master builds (currently 2.6)
  - Latest v2.5 builds
  - 2.2 build
  - 2.1 build
  - 2.0 build
Pick a version and download both the b2g-XX.XX.en-US.android-arm.tar.gz and gaia.zip files. Save them inside a directory on your Desktop called something like fxos.
Download the shallow flash script and save it in the same directory as the above two files.
For Windows users: Also download the shallow_flash.bat windows script and install Cygwin, which provides a Linux-like command environment on Windows. You will need to install the default Cygwin base category plus the unzip package but shallow_flash.bat will do this for you if you download and copy the Cygwin setup*.exe to the same folder as the script.
In your Terminal, cd into the directory you saved the files in and Flash the builds to your phone using the following:

Linux:
```
./shallow_flash.sh --gaia=gaia.zip --gecko=b2g-XX.XX.en-US.android-arm.tar.gz
```
Mac:
```
./shallow_flash.sh --gaia gaia.zip --gecko b2g-XX.XX.en-US.android-arm.tar.gz
```
Windows:

Double click shallow_flash.bat (with the cogs icon) or run it from a command shell. It will flash gaia.zip and a single b2g-XX.XX.en-US.android-arm.tar.gz file.

Note: If your update fails with an error "Flashing out/target/product/flame/system.img failed because the image was too large.", you will need to update to the newest base image, then try applying the nightly build again. This is because the system partition size has been updated (see bug 1184980.)

Note: If you get a "permission denied" error when running the above commands, your shell script probably doesn't have the right permissions. Running chmod +x shallow_flash.sh on it should solve this problem.

Note: A "shallow flash" updates Gecko and Gaia plus data directories, as opposed to a full flash, which updates Gecko/Gaia, but also the underlying Gonk layer and associated binaries particular to that device type. This is why it is a good idea to update to the official base image first, as suggested above, then shallow flash over the top of that, once you've got the Gonk/binary layer right.

Note: You can check the update status of each build on the Flame OTA status page.

Once the install procedure finishes the phone should reboot into the updated build and display the first time user workflow.

Switch to nightly update channel

In v2.2 you can change the Update channel from default to nightly under Developer settings.

Below is the older method, if you don't find that setting in your device.

Make sure remote debugging is enabled on your Flame, using the Remote debugging/Debugging via USB option in the device's Developer settings.
Download the change channel script: follow the link, press the Raw button, then use your browser's save functionality to save the page directly as change_channel.sh.
In your Terminal, cd into the directory you saved the script in and change the update channel on your phone using the following command:
```
./change_channel.sh -v nightly
```
Once the phone reboots, check for updates by going into Settings > Device information > Check now.

Note: This step isn't needed in newer versions of the Firefox OS software — you should just get OTA updates automatically.

Note: You can choose between several different update channels. Run "./change_channel.sh -h" to see the other channel options.

Fastboot mode

If flashing a new build to your phone fails to work, your phone may become unresponsive, leading to the phone rebooting in recovery mode. The recovery mode provides few options (Reboot, Update from adb, Wipe data, Wipe cache, and Update from sdcard). Unfortunately, selecting Update from adb triggers a sideload mode in which you cannot use the other adb commands. The adb sideload command would work but the various flash scripts rely on other adb commands.

You can force fastboot mode as follows:

Power off the phone (which may involve removing the battery in extreme cases...).
Power the phone up again by pressing the Volume Down and Power buttons together.

The phone should now display the text "FASTBOOT": it is in fastboot mode and is waiting for a USB connection. At this point, a USB-connected, computer with adb installed should see the phone listed when the fastboot devices command is run. Note that regular adb would not see the device — only fastboot sees it. In this mode, you can use the flash script to install the last base image as explained above. As the script does use both adb and fastboot commands, you may see some initial error and warnings from adb, but the device should be flashed properly at the end of the procedure.

Emergency download mode

If flashing a new build to your phone fails to work, your phone becomes unresponsive, and the phone cannot enter fastboot mode, you can use emergency mode for recovery. You'll need the provided emergency USB cable with the “Recovery Cable” red label on it and the Emergency Download Tool to enter this mode. For full instructions, see the Flame emergency rescue tool tutorial included in the download tool's files. Contact the device maker (flameservice [at] thundersoft.com) if you need any more technical support.

Emergency download tool dialog box as it is when it start.

Note: The tool provided is Windows-only.

Recovery mode

You can enter recovery mode to clear your phone data or manually update the firmware. There are two ways to enter this mode:

If ADB tools are available, make sure Remote debugging is turned on in the phone's Developer settings, connect your phone to your computer via USB and enter adb reboot recovery on the command line.
If your phone is powered off, press the Volume Up + Power buttons together.

When in recovery mode, press the Volume up/down keys to move the selection highlight, and the Power key to select. Make sure you have your phone data (Contacts, SMS, etc.) backed up before clearing data, and your upgrade packages downloaded before updating.

Updating your phone via an adb sideload

If you have adb installed on your computer, you can perform an adb sideload to update your phone, given the current sideload update.zip build. To do this:

Connect the device to the computer via USB.
Type the following :
```
adb reboot recovery
```
Press volume down once on the device to get to the option "apply update from ADB". If you went too far you can press volume up to move up the menu selection.
Press the power button to select the option.
On the computer, in the directory that you have stored the update.zip, type:
```
adb sideload update.zip 
```
Wait until the sideload finishes; on the device it should issue the message "Install from ADB complete".
navigate to the "reboot system now" option on the phone by pressing the volume up button on the device, then hit the power button to select that option.

Backing up and restoring your Flame data

When using a Flame, you won't want to lose your phone's contacts and other data while upgrading to a new build (as explained earlier in this article). To backup and restore data you can use our Backup and restore profile tool, which is contained in the B2G-flash-tool Git repo.

To use this, first open up your terminal/command line.

Clone the above repo (you'll need Git installed) using

git clone https://github.com/Mozilla-TWQA/B2G-flash-tool

The tool is a Python file: backup_restore_profile.py. Make sure you have Python installed (2.7.x is probably best.) Linux and Mac systems should have this out of the box.
Enter the directory you just cloned using cd B2G-flash-tool.

Note: When using this tool, you'll also need to make sure that your phone is connected via USB to your computer, and that ADB (see Important steps to follow first above) and Debugging via USB (in your device's Developer settings) are enabled.

Note: If you get a message complaining about lack of permissions to execute this file, cd into the directory where you saved the file, and run the following command:

chmod +x backup_restore_profile.py

Backing up data from your phone

Before backing up you should make sure your device is updated with the most recent OTA update. To do this, on your phone go to Settings app > Device Information > Check for updates > click Check Now. If there is an update available, you should shortly get a notification of an available update. Choose to install the update.

Now, in the directory where you saved the backup_restore_profile.py file, run the following:

python backup_restore_profile.py -b

This should save your device profile to a directory called mozilla-profile, in the same directory as the script is located.

Warning: by default, it does not save the internal sd card content. So files like photos or videos from the gallery app will not be saved. If you want to backup the sd card content, add the --sdcard option

python backup_restore_profile.py -b --sdcard

Restoring data to your phone

Before restoring you should again make sure your device is updated with the most recent OTA update. Go to Settings app > Device Information > Check for updates > click Check Now. If there is an update available, you should shortly get a notification of an available update. Choose to install the update.

In the directory where your mozilla-profile directory is located (see above section), run the following:

python backup_restore_profile.py -r

Note: You can get a list of all the options the tool supports by running python backup_restore_profile.py -h.

Pushing apps to your Flame

The App Manager and WebIDE tools make it easy to push apps to your phone, for testing, etc.

RAM adjustment

You can adjust the available RAM capacity to see how apps perform on Firefox OS phones with lower memory footprints.

This is accomplished by entering fastboot mode (install fastboot first, which is available on the same SDK page as ADB) and typing:

adb reboot bootloader
fastboot oem mem [0|256-1024]

“0” is the memory automatically detected and “256-1024” is the number of megabytes. For example, if you want to adjust device RAM capacity to 512M, enter fastboot oem mem 512.

You'll need to then reboot your device for the settings to take effect. This can be done using:

fastboot reboot

The current memory size can be returned by entering fastboot mode and typing:

fastboot getvar mem