Customization stick

Please copy/paste "{{Translationlist | xx | origlang=en | translated={{{translated}}}}}" (where xx is ISO 639 language code for your translation) to Customization stick/translations

HowTo [ID# 282667]  +/-

  This page is monitored by the OLPC team.

  For Developers

A customization stick is a USB flash drive with special boot files that upon reboot will install activities and content bundles, and optionally a new OS image, from the USB flash drive onto an XO.

This lets you install your own set of activities and library content on top of a signed OLPC build. You may want to include a named activity pack in your customization stick.

Deprecation warning

Please note that the customization stick is deprecated and is unlikely to work on recent OLPC OS releases.

OLPC focuses on large-scale deployments, and processes such as this one which require a technician touching every laptop tend to be unrealistic. While the customization stick is of obvious use to smaller projects, unfortunately it had a few technical problems and the challenges of maintaining a separate USB-bootable customization environment compatible with a range of ever-changing OLPC OS releases make this hard to maintain.

Instead, deployments (even small ones) are encouraged to use OS Builder to create custom images with the activities already included. Once you have got to grips with OS Builder, you will hopefully appreciate the added simplicity here, in that a two-step installation process (install OS, install activities) is now just one.

For situations where OS Builder is inappropriate, the reccomendation is to write a script to be executed at the terminal on target laptops, or to write and maintain your own customization stick equivalent. See Customization stick development for technical information on how the customization stick was built.

Download files

Due to hardware differences, a different customization stick is needed for each hardware model.

• If you are working with XO-1 hardware, download customization-2.zip
• If you are working with XO-1.5 hardware, download customization-xo1.5-1.zip

This customization zip file will be used in the instructions below.

Preparing the customization stick:

• Get a USB flash drive
  • NOTE: this does not currently work when booting from an SDIO card. You must use a USB drive.
  • The USB flash drive must be formatted with a VFAT partition, this is the default for larger USB flash drives.
• Unpack the customization zip file (downloaded above) into the root directory of the USB flash drive.
  • This will create an empty subdirectory bundles and a subdirectory boot containing some zip files. These files have the special boot instructions that install the other files that you put on the USB flash drive.
• Optional: If you want to install an OS image, add fs.zip and osNNN.img to the USB flash drive from the base build you want to install.
  • This is optional. If no signed base build is present, the activities will still be installed.
  • For example, the files for build 711 (release 8.1.2) are at http://download.laptop.org/xo-1/os/official/711/jffs2/ , where you'll find the files fs.zip and os711.img.
  • Only official releases are signed, and have an associated fs.zip file.
• Create your activity bundle (.xo file).
• Create your content bundle (.xol file).
• Drag the .xo files (activity bundles) and .xol files (library bundles) you want to install into the bundles directory on the USB flash drive.
  • For example, look at the list of activities in the G1G1 activity pack, then visit http://wiki.laptop.org/go/Activities to download the latest version of activities that you wish to add to the bundles directory.
  • Or, use the create-customization-key Python script to populate the bundles directory.
• If you create a zip file containing files named frame00.565 through frame26.565 and place it in bundles with a name ending in .pb, you can customize the boot animation. You might also replace the shutdown graphic (but our UL certification depends on displaying the standard graphic).

Warning: Activities may not upgrade correctly

The customization key installs activities by unzipping them into place. If an older version of the same activity is installed, some of the files from the old version may remain after upgrade. This happens when some files in the old version do not appear in the file list in the new version. This is not always harmless. If an activity loads all files in a directory then it can incorrectly load both old and new files.

A safe work-around is to completely remove the activity you wish to upgrade from the XO laptop before you use the customization key.

Using the customization stick:

Once you've created your USB flash drive(s) containing this special set of files:

• Insert the USB flash drive into a powered-off XO
• Turn the machine on while holding down all four game pad keys to update to newer build and customize.

The machine will erase all contents of the flash including any existing activation lease or developer key on the XO, install the base build, and then install your custom activity and content set. It will then power-off, and you can remove the USB flash drive and move on to the next XO.

• If you only want to customize:
  • On secure/restricted machines you can turn the machine on; you don't have to hold down any game pad keys.
  • On developer/unrestricted machines, you will need to hold down the x game key to simulate security.

NOTE: If your machine is unactivated, this stick does not perform the activation step for you. You will need to Activate your XO in order to get the machine to boot after this process. Note that you can not put your activation lease on the customization stick and expect it to work; the XO will boot the customization routine instead of booting into the activation routine. Your activation lease file (lease.sig) must be on a different stick (or else you must temporarily rename the 'boot' directory on the customization stick).

Scaling up

For large-scale country deployments, we provide a tool to convert a customization stick into a filesystem image suitable for Quanta to flash onto machines at the factory. See the Image builder page for more information.

See also

• Firmware security explains how the XO firmware handles files like runos.zip and actos.zip at boot time.
• Customization stick development

Previous Versions:

• customization-1.zip deprecated: this version hangs when unpacking bundles with many files because of a resource starvation bug