Firefox OS/TCP/Flashing your device/: Difference between revisions

Latest revision as of 14:11, 1 February 2015

These instructions are being tested. Please report successes or issues with them in the #TCP IRC channel.

Notes About Terminology

Firefox OS is frequently referred to by its code name (and original name) B2G.
The files we use to flash the device are referred to as images, ROMs or builds.
The proper abbreviation for Firefox OS is FxOS.
The process of flashing refers to writing the ROMs to the device to update the operating system to a different version.
Flatfish is the code name we use to refer to the 10" tablets being tested.

Flashing Your Device

If you have not flashed the updated bootloader, we recommend doing so before flashing a new build.

Before beginning, it is best if your device is not almost dead (if the battery's red, it's almost dead).

Download the build you would like to flash.
- Check the build status page to see if there are notes about major issues with the listed builds.
- If none of the listed builds are viable ("good"), choose the build in the stable folder.
- Download the build files from dropbox. Only builds from the last seven days (and the stable build) are available.
- Using the Download (as zip) option will save time and make for a much smaller download.

Windows

Extract this file into the same folder as your build files.
If you have not installed Android USB drivers previously, you likely need to follow these directions to do so. If you do not and receive the error device not found you'll need to install them.
Turn on your device and plug it in to your computer via the USB cord.
Run the flash file. It may also be called flash.bat. The icon may have gears in it.
You should then be asked if you want to flash user data. Saying yes will clear any user data such as apps you have installed and emails. Data stored on an SD Card will survive.
If you are moving between a major version of FxOS (e.g. 1.4 -> 2.0 or 2.0 -> 1.4) we recommend that you choose to flash the user data (thereby deleting it).
After making your userdata selection the tablet will reboot into "fastboot" mode and display the Firefox OS logo. In the command window, if you see < waiting for device > for longer than 30 seconds, try unplugging the USB cord from your computer and plugging it back in.
The flash will take a few minutes and the screen may display random colors. Do not unplug, disturb or mock the device during this time.
Once finished, press any key to reboot the tablet.

Linux

If you have not added the udev rules for the tablet, you need to add them for the device (use idVendor 18d1 and 0bb4 - that's two separate rules).
Ensure ADB and Fastboot is installed on the system.
- Ubuntu: There is an unoffical PPA for both tools.
- Arch: Install the android-tools package.
Turn on your device and plug it in to your computer via the USB cord.
Run the flash-flatfish.sh file.
- If you get permission denied, make sure the file has the executable permission by running chmod +x flash-flatfish.sh.
- You must pass the location (path) of the image files as an argument (./flash-flatfish.sh .
  should work if the files are in the same directory)
You should then be asked if you want to flash user data. Saying yes will clear any user data such as apps you have installed and emails. Data stored on an SD Card will survive.
If you are moving between a major version of FxOS (e.g. 1.4 -> 2.0 or 2.0 -> 1.4) we recommend that you choose to flash the user data (thereby deleting it).
After making your userdata selection the tablet will reboot into "fastboot" mode and display the Firefox OS logo. In the command window, if you see < waiting for device > for longer than 30 seconds, try unplugging the USB cord from your computer and plugging it back in.
The flash will take a few minutes and the screen may display random colors. Do not unplug, disturb or mock the device during this time.
Once finished, press any key to reboot the tablet.

Mac OS X

Currently, it is not possible to flash new builds natively in Mac OS X. It is recommended to run Linux in a VM and flash new builds using the above instructions.

Solving problems

If you run into problems you should ensure your device and host are fully prepared for developing as described above.

Linux

If the script fails try running 'adb devices'. If it gives a permissions error you may need to manually restart the adb server

adb kill-server
sudo adb start-server
adb devices

Also make sure you have set up the udev rules as described above and 'lsusb' shows the tablet with something like 'ID 18d1:0003'.

@@ Line 8: / Line 8: @@
 * ''Flatfish'' is the code name we use to refer to the 10" tablets being tested.
 ==Flashing Your Device==
-<div class="note error">If you have not flashed the [https://wiki.mozilla.org/FirefoxOS/TCP/Flashing_the_Flatfish_bootloader updated bootloader], please do so before flashing a new build.</div>
+<div class="note error">If you have not flashed the [https://wiki.mozilla.org/FirefoxOS/TCP/Flashing_the_Flatfish_bootloader updated bootloader], we recommend doing so before flashing a new build.</div>
 Before beginning, it is best if your device is not almost dead (if the battery's red, it's almost dead).
 * Download the build you would like to flash.
-** Check the [https://etherpad.mozilla.org/CmJbD8V0QX build status page] to see if there are notes about major issues with the listed builds.
+** Check the [http://mzl.la/1z5DZ4w build status page] to see if there are notes about major issues with the listed builds.
 ** If none of the listed builds are viable ("good"), choose the build in the ''stable'' folder.
 ** Download the build files [https://www.dropbox.com/sh/b2py1btcwstqldl/AABblbq_csa1IHQwdvLdfptTa from dropbox]. Only builds from the last seven days (and the stable build) are available.
 ** Using the ''Download'' (as zip) option will save time and make for a much smaller download. [[File:dropbox_download_button.png]]
+===Windows===
 * Extract [http://test1.manichord.com/moz-tcp/ADB-Fastboot-and-Scripts.zip this file] into the '''same''' folder as your build files.
-* ''Windows users'': If you have not installed Android USB drivers previously, you likely need to follow [https://wiki.mozilla.org/FirefoxOS/TCP/Installing_USB_Drivers_on_Windows these directions] to do so.  If you do not and receive the error <code>device not found</code> you'll need to install them.
+* If you have not installed Android USB drivers previously, you likely need to follow [https://wiki.mozilla.org/FirefoxOS/TCP/Installing_USB_Drivers_on_Windows these directions] to do so.  If you do not and receive the error <code>device not found</code> you'll need to install them.
-* ''Linux users'': If you have not, you need to [https://developer.mozilla.org/en-US/Firefox_OS/Firefox_OS_build_prerequisites#For_Linux.3A_configure_the_udev_rule_for_your_phone add udev rules] for the device (use idVendor '''18d1''' and '''0bb4''' - that's ''two'' separate rules).
 * Turn on your device and plug it in to your computer via the USB cord.
-* Run the ''flash'' file.
+* Run the ''flash'' file. It may also be called '''flash.bat'''. The icon may have gears in it.
-** On Windows the file will be called '''flash''' or '''flash.bat''' (if you have file extensions unhidden). The icon may have gears in it.
-** On Linux the file will be called '''flash-flatfish.sh'''
-*** Ensure you have proper permissions to run it
-*** On Linux you must pass the location (path) of the image files as an argument (''<div style="display:inline; color:blue">./flash-flatfish.sh .</div>'' should work if the files are in the same directory)
 * You should then be asked if you want to flash user data.  Saying yes will clear any user data such as apps you have installed and emails.  Data stored on an SD Card will survive. <br>If you are moving between a major version of FxOS (e.g. 1.4 -> 2.0 or 2.0 -> 1.4) we recommend that you choose to flash the user data (thereby deleting it).
 * After making your userdata selection the tablet will reboot into "fastboot" mode and display the Firefox OS logo.  In the command window, if you see <code>< waiting for device ></code> for longer than 30 seconds, try unplugging the USB cord from your computer and plugging it back in.
 * The flash will take a few minutes and the screen may display random colors. Do not unplug, disturb or mock the device during this time.
 * Once finished, press any key to reboot the tablet.
+===Linux===
+* If you have not added the udev rules for the tablet, you need to [https://developer.mozilla.org/en-US/Firefox_OS/Firefox_OS_build_prerequisites#For_Linux.3A_configure_the_udev_rule_for_your_phone add them] for the device (use idVendor '''18d1''' and '''0bb4''' - that's ''two'' separate rules).
+* Ensure ADB and Fastboot is installed on the system.
+** Ubuntu: There is an unoffical [http://www.webupd8.org/2012/08/install-adb-and-fastboot-android-tools.html PPA] for both tools.
+** Arch: Install the ''android-tools'' package.
+* Turn on your device and plug it in to your computer via the USB cord.
+* Run the ''flash-flatfish.sh'' file.
+** If you get permission denied, make sure the file has the executable permission by running ''chmod +x flash-flatfish.sh''.
+** You must pass the location (path) of the image files as an argument (''<div style="display:inline; color:blue">./flash-flatfish.sh .</div>'' should work if the files are in the same directory)
+* You should then be asked if you want to flash user data.  Saying yes will clear any user data such as apps you have installed and emails.  Data stored on an SD Card will survive. <br>If you are moving between a major version of FxOS (e.g. 1.4 -> 2.0 or 2.0 -> 1.4) we recommend that you choose to flash the user data (thereby deleting it).
+* After making your userdata selection the tablet will reboot into "fastboot" mode and display the Firefox OS logo.  In the command window, if you see <code>< waiting for device ></code> for longer than 30 seconds, try unplugging the USB cord from your computer and plugging it back in.
+* The flash will take a few minutes and the screen may display random colors. Do not unplug, disturb or mock the device during this time.
+* Once finished, press any key to reboot the tablet.
+===Mac OS X===
+Currently, it is not possible to flash new builds natively in Mac OS X. It is recommended to run Linux in a VM and flash new builds using the above instructions.
+== Solving problems ==
+If you run into problems you should ensure your device and host are fully prepared for developing as described above.
+=== Linux ===
+If the script fails try running 'adb devices'. If it gives a permissions error you may need to manually restart the adb server
+<pre>
+adb kill-server
+sudo adb start-server
+adb devices
+</pre>
+Also make sure you have set up the udev rules as described above and 'lsusb' shows the tablet with something like 'ID 18d1:0003'.