Overview

The Chromium OS reference factory software provides a sample factory install and test flow for manufacturing Chrome devices. It is available as part of the public Chromium OS repository on chromium.org. This code is meant as a starting point, to modify and adapt to different projects. The basic steps are:

1. An initial/bootable version of the EC and firmware is pre-flashed onto the Chromium EC chip and SPI-ROM before system assembly.
2. After system assembly, insert the Factory Install Shim USB stick. After the device boots and the DEV mode screen displays, press Ctrl-U to boot from USB. The shim contacts a mini-Omaha server to request an install image. The firmware also supports booting and installing from a network location using tftp, without a USB stick.
3. A factory test image, signed release image, and EC/firmware is installed or updated. Included on disk are two full Chrome OS images: the test image and the shipping image.
4. The system automatically reboots using the factory test image and begins manufacturing tests. This test suite is based on pytest. The software supports sequencing tests, configuration, firmware and configuration updates, reboots, and other events in a configurable sequence.
5. Functional, Run-In, and manual tests run as configured. Upon completion, results are displayed on the screen. Results are also available as an electronic pass/fail record with detailed logs for uploading to the shopfloor server.
6. The factory test image is automatically erased, leaving the release image as bootable.
7. On failure, the system continues running subsequent tests and reports failures on completion. Alternatively you can configure it to halt on failure at specific break points. For details, see the Options class in src/platform/factory/py/test/factory.py and generic test lists under src/platform/factory/py/test/test_lists/* .
8. The factory image and test image can be combined into an SSD image and imaged onto the internal drive before assembly. The first time the device boots, the sequence starts at step 4 above, using the factory test image.

Building the factory install shim

To build a factory install shim, you need a Chromium OS development environment. After finishing the setup_board sequence and selecting the target board:

1. From inside the cros-chroot:

(cros-chroot) ~/trunk/src/scripts $ ./setup_board --board x86-generic --default

2. Build all the packages, including the factory install shim package

./build_packages

3. Build a special factory install shim image (with special kernel and rootfs):

./build_image factory_install

4. The target URL to connect to the mini-Omaha server is stored in the factory install shim image, in the first partition of the image file (/dev/sd?1:dev_image/etc/lsb-factory). You can modify this file using the following command:

edit_lsb_factory.sh

5. Follow the prompts to specify the host name or IP address of the mini_Omaha server and save your changes. An image named factory_install_shim.bin is created in your build directory (../builds/$BOARD/latest). The following table describes the options:

Option	Description
(1) Modify mini-Omaha server host.	Type the host name (myserver.mydomain.com) or IP address of your mini-Omaha server. The format of the new URL is http://<server>:8080/update.
(2) Enable/disable board prompt on download.	By default, a user must type i to start the installation after the image is downloaded. Disable this prompt if you want the installation to start automatically after download, without user input.
(3) Enable/disable RELEASE-ONLY recovery download mode.	By default, a factory test image is installed along with a release image. Enable this option to install only a release image.

6. Copy the image to your SD card or USB memory stick with the command:

On boot, the factory install shim displays a download status and downloads the image from the server. On completion, the shim reboots. If you are using legacy firmware (not Chrome OS firmware), you might need to remove the SD card to allow booting the newly-installed image.
After the image starts downloading and the status message turns green, you can remove the SD card—it is not needed after that point.

Building a factory test image

To build a factory test image, you need a Chromium OS development environment. Also required are any files in private repos that are specific to the system being manufactured. You can access upcoming board repositories in a .repo/local_manifest.xml file, which Google provides after the board repositories and authentication are set up.

1. From inside the cros-chroot:

(cros-chroot)~/trunk/src/scripts $

2. Build all the packages, including the autotest package:

./build_packages

3. Build a test image. This step creates an image named chromiumos_test_image.bin in your build directory.

./build_image test

4. Build the factory toolkit. This step creates a file called install_factory_toolkit.run.

./make_factory_toolkit.sh

5. Run the factory toolkit, patching chromiumos_test_image.bin.

~/trunk/src/build/images/YOUR_BOARD_NAME/latest/install_factory_toolkit.run \

/path/to/chromiumos_test_image.bin

Now when you image a device with chromiumos_test_image.bin, the factory tests are enabled.

Booting your factory test image via USB

For development and local testing, it is possible to boot the factory test image from a USB memory stick rather than using a network install. The following steps are optional:

1. Copy the image binary to USB storage (for example, /dev/sd1).

cros flash usb:// chromiumos_factory_image.bin

2. On your device, switch to developer mode,and enter VT2 by pressing Ctrl-Alt-F2.
3. Log in as root with password test0000 if required.
4. Run the following command:

sudo chromeos-firmwareupdate --mode=todev

5. Insert the USB memory stick and press Ctrl-U at the blue boot warning screen. You can also enter VT2 and install the image to SSD using the chromeos-install command.

Note: This does not apply to CR48—on that system firmware write protection must be disabled.

Preparing a factory package set

By default, a factory installation places the factory test image in the first slot of Chrome OS image partitions (#2 and #3), and the release image in the second slot (#4 and #5).

For branches R16 and later

You can build a generic factory package from a release image and a factory image as follows:

This command generates a miniomaha.conf file and a partition update .gz set. Any existing configuration and partition update sets are erased.

Starting with R16, for running the same configuration multiple times, or releasing a preconfigured setup for partners, make_factory_package also supports a --config mode:

(cros-chroot) ~/trunk/src/make_factory_package.sh \

--config=path/to/config_file.conf

The configuration file is a text file with all parameters you want to assign. The configuration file also supports variables for specifying a relative path for the image file source. For example, $MFP_CONFIG_DIR refers to the directory location of the configuration file. See make_factory_package.sh --help for more information.

Example with variables

x86-generic

To configure multiple boards in the same file, use the syntax [board-name] to separate the entries. Specify the --board option for the first board and then --subfolder for all remaining boards, as follows:

[BOARD1]
 --board BOARD1 --factory FACTORY1 ....
[BOARD2]
 --subfolder BOARD2
--board BOARD2 ....
[BOARD3]
 --subfolder BOARD3 --board BOARD3 ....

Example with multiple configurations

x86-generic and _3g

Notes

• After R16, the firmware is automatically extracted from the release image (--release), unless you specify either a different updater (--firmware path/to/updater) or none to skip overwriting the firmware. Before R16, the default value of the --firmware parameter is none. A value of none should be used only for development and testing, not for actual mass production in the factory.
• The file hwid_bundle.sh is located in the hwid subfolder of your factory test image (internal source tree), or in the factory bundle archive (zip or tbz). If the goal is to run a few factory tests without the finalize step, use --hwid none to skip the HWID steps.
• The factory test image, factory install shim, and release image must be compatible. Since boot, update, and partition formats are not yet final, all images must currently be built from the same branch.

Setting up a mini-Omaha server installation

To set up a mini-Omaha server installation, you need a Chromium OS development environment. The factory test image and release image update package set are required, as described above. Python 2.6 is required, with module cherrypy 3.0. You can install this by running sudo apt-get install python-cherrypy3 on Ubuntu.

To prepare packages and start the mini-Omaha server:

or

~/trunk/src/make_factory_package.sh --config path/to/config --run

The --run_omaha parameter tells make_factory_setup.sh to invoke miniomaha.py (the mini-Omaha server) after packages have been prepared successfully.

• To manually start the server, change the working directory to ~/trunk/src/platform/factory-utils/factory_setup.
• To check if the server is configured correctly:
• python ./miniomaha.py --factory_config miniomaha.conf --validate_factory_config
• To start the server with prepared factory packages:
• python ./miniomaha.py --factory_config miniomaha.conf

Output is logged to stdout, the server displays incoming requests, and files are served.

Note: Before R17, the path and file name of the mini-omaha server is different, and the --run option is unsupported. You need to run the following:

Building an SSD image

To pre-image the machines rather than image them over the network, you can generate the disk image from a factory test image and a release image.

A generic factory package can be built from a release image and a factory image:

You can image directly to a device, or to a .bin file. Available options are:

• --diskimg=XX specifies the destination device or file
• --sectors=XX specifies the number of sectors in the bin file
• --preserve prevents wiping of the unused space for faster imaging

Modifying the factory test image or adding test cases

The factory test image runs the series of pytests located at src/platform/factory/py/test/pytests/* (installed in /usr/local/factory/py/test/pytests/* on the DUT). The sequence of pytest cases are determined by test_lists files under /usr/local/factory/py/test/test_lists/*.py. Status is logged to /var/log/factory.log and more details can be found under /var/factory/*.

After modifying the source code, you can run the following commands to push files to the DUT. The host machine and DUT must be on the same subnet.

1. From inside the cros-chroot:

(cros-chroot)~/trunk/src/platform/factory $

2. Update factory source code on DUT:

./bin/goofy_remote DUT_IP_ADDRESS

For more information on adding test cases, build the Chromium OS Factory SDK documentation:

1. From inside the cros-chroot:

(cros-chroot)~/trunk/src/platform/factory $

2. Build the SDK documentation

make doc

3. Open the following file in a browser window:

~/trunk/src/platform/factory/build/doc/html/index.html