ChromiumOS > Guides > Device >

Flashing chromiumOS

If you need to update your platform version (i.e. to update to the latest release, or to flash a specific version for debugging), you will need to be able to flash ChromiumOS to your device. This guide will walk you through the process of checking out the ChromiumOS code and setting up your environment to flash a device over SSH. For more context, please refer to the full ChromiumOS developer guide.

Prerequisites

This guide assumes you are working from home and have a gLinux workstation or Cloudtop, a corp laptop, and a DUT (Device Under Test). It also assumes you are familiar with the process of deploying ChromeOS to your DUT over SSH. If you haven't yet, please follow the instructions in Building, deploying, and testing.

You will need to prepare the DUT by flashing a test image using a USB stick at least once before you can flash ChromiumOS over SSH.

Setup

Follow these steps to set up your environment and check out the ChromiumOS code.

Add the following line to your .bashrc to ensure new files are global-read by default:

~$ echo "umask 022" >> ~/.bashrc

Apply the change:

~$ source ~/.bashrc

Create the folder for the ChromiumOS code:

~$ mkdir ~/chromiumos

Navigate to the chromiumos directory and initialize the repo:

~$ cd ~/chromiumos

~/chromiumos$ repo init \
    https://chrome-internal.googlesource.com/chromeos/manifest-internal.git

~/chromiumos$ repo sync -j4

Note: This init + sync process will take quite a while, possibly a few hours.

Enter the `chroot`

The ChromiumOS workflow uses a chroot, a self-contained execution environment. To set up the chroot (and in the future, to re-enter it):

~chromiumos$ cd src/scripts

~/chromiumos/src/scripts$ cros_sdk

Once you're inside the chroot, you will see (cr) prepended to your prompt.

Flash a pre-built chromiumOS image

You can now flash ChromiumOS to your DUT over SSH using a tool called xBuddy. You can reference the examples below to get started. Be sure to customize the address of your DUT in the ssh URL, as well as the board name and version in the xBuddy URL.

Example 1: Flash the latest version from the dev channel to an eve device.

(cr) ~/chromiumos$ cros flash ssh://127.0.0.1:7777 \
    xbuddy://remote/eve/latest-dev \
    --no-ping --log-level=info

Example 2: Flash a specific version or board.

Port:
Board:
Milestone:
Platform version:

(cr) ~/chromiumos$ cros flash ssh://127.0.0.1:$PORT  \
    xbuddy://remote/$BOARD/R$MILESTONE-$PLATFORM_VERSION \
    --no-ping --log-level=info --board=$BOARD

You can find version numbers, and the corresponding release number, by searching on go/goldeneye. See Understanding chromeOS releases for more detail on version numbers.

Each image is downloaded to your workstation, and each image is several GB in size. You should periodically remove these downloaded images to prevent filling up storage space on your workstation. You can find previously downloaded images under ~/chromiumos/devserver/static/.

Flash a custom-built of chromiumOS image

Sometimes it may be required to work on a local build of ChromiumOS and to test changes on your DUT. The following instructions are from the ChromiumOS developer guide but summarized here.

NOTE: If this your first time running these commands, it could take a long time.

Some of the steps require you to enter the chroot and some are run outside in the ~/chromiumos repository. Commands entered in the chroot will be represented using (cr) and commands outside the chroot will be represented using (outside). To enter the chroot:

cd ~/chromiumos
cros_sdk

You will then need to set an environment variable BOARD depending on which DUT you would like to deploy to.

(cr) ~/chromiumos/src/scripts$ export BOARD=<your pick of board>

Initialize build for a board

(cr) ~/chromiumos/src/scripts$ setup_board --board=${BOARD}

Build packages for your board

If this is the first time running cros build-packages, then run this command:

(outside) ~/chromiumos/src/scripts$ cros build-packages --board=${BOARD} --autosetgov --autosetgov_sticky

If you would like to disable DCHECKS:

(outside) ~/chromiumos/src/scripts$ cros build-packages --board=${BOARD} --no-withdebug

Else you may use this default command and add the flags you need.

(outside) ~/chromiumos/src/scripts$ cros build-packages --board=${BOARD}

Build a disk image for your board

(outside) ~/chromiumos/src/scripts$ cros build-image --board=${BOARD} --noenable_rootfs_verification test

Installing ChromiumOS on your device

There are two options, either by USB or by SSH.
- SSH:
  
  DUT:
  
  Port:
```
(cr) ~/chromiumos/src/scripts$ cros flash ssh://$DUT:$PORT ../build/images/${BOARD}/latest/chromiumos_test_image.bin
```
- USB stick:
  
  NOTE: This option doesn't seem to work when port forwarding through a cloudtop machine.
  
  Plug in your USB stick and give it about 10 seconds to register.
```
(cr) ~/chromiumos/src/scripts$ cros flash usb:// ${BOARD}/latest
```