BBB software update process

From Crashcourse Wiki

Jump to: navigation, search



This is a detailed description of the format of the eMMC "flasher" images you can use to update your BBB, and how that process works. From this, you can probably figure out how to create your own flasher images.

WARNING: All the evidence suggests that you can't reflash your BBB solely on USB power -- get a 5VDC power supply.

Also note that the official Circuitco software update page is here if you need even more information.

Which flasher image should you use?

You can find the regularly updated flasher images here -- I'll use the current image of BBB-eMMC-flasher-2013.06.20.img.xz for the rest of this discussion.

Note well that while the flashing process writes a new OS into 2G of eMMC, you need at least a 4G uSD card to hold the uncompressed flasher image.

How to examine a flasher image

If you're not familiar with how to examine the contents of a flasher image after downloading one, read up on the kpartx utility here. We'll use that to examine the current flasher image and walk through the update process.

Copying the flasher image to a uSD card

I've never gone wrong with dd, so uncompress the downloaded image and:

$ sudo dd if=BBB-eMMC-flasher-2013.06.20.img of=/dev/sdX bs=1M

for whatever device file value of "sdX" is appropriate for you.

How to update

Once you copy the (uncompressed) flasher image to a compatible uSD card, just treat the update process as if you wanted to boot from the uSD card -- power off the board, insert the uSD card, hold down the Boot button, apply power and continue to hold down the Boot button until the first LED comes on. That's actually longer than necessary, but it should be a guarantee that you've started the update process properly.

NOTE: The "Boot" button is the button next to the micro SD card slot -- it's the one labelled "S2" on the board itself but it's typically referred to in the documentation as the "Boot" button.

At that point, just sit back for about 45 minutes and watch the flashing LEDs until they all come on solid. Mission accomplished.

How flashing works -- examining the contents of the flasher image

Mount the image partitions to examine them

Now let's look at the internals of the flasher image, and how the flashing procedure actually works.

Assuming we've downloaded the image BBB-eMMC-flasher-2013.05.20.img.xz, uncompress it and use kpartx to create the corresponding mapper device files,

$ sudo kpartx -a BBB-eMMC-flasher-2013.05.20.img

verify the creation,

$ sudo kpartx -l BBB-eMMC-flasher-2013.05.20.img
loop0p1 : 0 144522 /dev/loop0 63
loop0p2 : 0 6988275 /dev/loop0 144585

and create a couple directories and mount the partitions:

$ mkdir fat linux
$ sudo mount /dev/mapper/loop0p1 fat
$ sudo mount /dev/mapper/loop0p2 linux

And now, let's examine those image partitions.

The boot (FAT) partition

There's nothing flasher-related in the boot partition, just normal boot content:

$ cd fat
$ ls -l
total 474
-rwxr-xr-x 1 root root     41 May 20 19:33 ID.txt
-rwxr-xr-x 1 root root  99904 May  3 17:13 MLO
-rwxr-xr-x 1 root root 378948 May  3 17:13 u-boot.img
-rwxr-xr-x 1 root root     14 Mar 18 11:01 uEnv.txt

Here are the two text files:

$ cat ID.txt
BeagleBone Black eMMC flasher 2013.05.20
$ cat uEnv.txt 

The above shows that if you want to change some of the boot parameters, you can edit uEnv.txt which will be read by U-Boot before flashing.

The root (Linux) partition

The root partition of a flasher image looks like any other Linux root filesystem, containing enough to boot a Linux system:

$ cd linux
$ ls -l
total 84
drwxr-xr-x.  2 root root  4096 Mar 18 06:45 bin
drwxr-xr-x.  2 root root  4096 Mar 18 06:45 boot
drwxr-xr-x.  2 root root  4096 May 20 13:34 build
drwxr-xr-x.  3 root root  4096 Mar  5 04:06 dev
-rw-r--r--.  1 root root    12 Mar 13 08:17 eeprom.dump
drwxr-xr-x. 35 root root  4096 Mar 27 08:03 etc
drwxr-sr-x.  4 root root  4096 Mar 12 06:12 home
drwxr-xr-x.  9 root root  4096 Mar 16 04:37 lib
drwx------   2 root root 16384 Mar 12 07:39 lost+found
drwxr-xr-x. 10 root root  4096 Mar 12 06:12 media
drwxr-xr-x.  2 root root  4096 Mar 12 06:12 mnt
drwxr-xr-x.  2 root root  4096 Mar  5 04:06 proc
drwxr-xr-x.  2 root root  4096 Mar  5 04:06 run
drwxr-xr-x.  2 root root  4096 Mar 27 08:03 sbin
drwxr-xr-x.  2 root root  4096 Mar  5 04:06 sys
drwxrwxrwt.  2 root root  4096 Mar  5 04:06 tmp
drwxr-xr-x.  9 root root  4096 Mar 20 06:40 usr
drwxr-xr-x. 12 root root  4096 Oct 19  2012 var

In addition, it contains a top-level build/ directory, containing everything needed to format the eMMC and copy into it a full Linux installation:

$ cd build
$ ls -l
total 349592
-rw-r--r--. 1 root root 357429378 May 20 13:34 Angstrom-Cloud9-IDE-GNOME-eglibc-ipk-v2012.12-beaglebone.rootfs.tar.gz
-rw-r--r--. 1 root root     51221 Apr 12 04:55 beaglebg.jpg
-rw-r--r--. 1 root root        68 Apr  4 06:14 connman.settings
-rwxr-xr-x. 1 root root      2143 Apr  5 04:44
-rwxr-xr-x. 1 root root      1657 Mar 27 08:04
-rw-r--r--. 1 root root     99976 May 20 13:34 MLO
-rw-r--r--. 1 root root    379412 May 20 13:34 u-boot.img


The above is what makes this a "flasher" image.

How the update process is initiated

The script /usr/bin/ is what does all the updating, and it's kicked off by being defined as a systemd service in the flasher image, thusly:

$ cat lib/systemd/system/emmc.service
Description=Flashing eMMC
After=dev-mmcblk1.device dev-tty11.device



The systemd service emmc.service, plus the content in the build/ directory, is what makes this a "flasher" image as opposed to just another Linux install booting from uSD card.

NOTE: While the top-level build/ directory has its own script, it appears that's not actually used, so I'm not sure what it's doing there. In any event, it doesn't appear to be doing any harm so no big deal.

The mechanics of the script

Step by step, walk through the flasher image's /usr/bin/ script, which is what does all the flashing.

First, create a couple mount points that will represent the eMMC partitions we're about to create and format, and cd into the build/ directory for everything from this point on:


HOSTARCH="$(uname -m)"

cd /build

Check for existing valid EEPROM -- if not, write it:

HEADER=$(hexdump -e '8/1 "%c"' /sys/bus/i2c/devices/0-0050/eeprom -s 5 -n 3)

if [ ${HEADER} -eq 335 ] ; then
        echo "Valid EEPROM header found"
        echo "Invalid EEPROM header detected"
        if [ -e /eeprom.dump ] ; then
                echo "Adding header to EEPROM"
                dd if=/eeprom.dump of=/sys/devices/ocp.2/44e0b000.i2c/i2c-0/0-0050/eeprom

Use the supplied script to partition eMMC and format those partitions, then mount those new, empty partitions to be populated with new content:

echo "Paritioning eMMC"
./ /dev/mmcblk1

echo "Mounting partitions"
mkdir -p ${PART1MOUNT}
mkdir -p ${PART2MOUNT}
mount /dev/mmcblk1p1 ${PART1MOUNT} -o relatime
mount /dev/mmcblk1p2 ${PART2MOUNT} -o async,noatime

Populate the new boot partition on eMMC with the U-Boot-related files, and generate a simple uEnv.txt there:

echo "Copying bootloader files"
cp MLO u-boot.img ${PART1MOUNT}
echo "optargs=quiet drm.debug=7" >> ${PART1MOUNT}/uEnv.txt


Now unload the entire Angstrom root filesystem tarball in the other partition:

echo "Extracting rootfs"
tar zxf Angstrom-Cloud9-IDE-GNOME-eglibc-ipk-v2012.12-beaglebone.rootfs.tar.gz -C ${PART2MOUNT}

If there was any BeagleBone "Getting Started" content in the root filesystem tarball, copy it into the FAT partition so it's available after boot:

echo "Populating VFAT partition"
if [ -d ${PART2MOUNT}/usr/share/beaglebone-getting-started ] ; then
        cp -r ${PART2MOUNT}/usr/share/beaglebone-getting-started/* ${PART1MOUNT}

Save some version information for debugging purposes, and we're done with the FAT partition so unmount it:

echo "Cloud9 GNOME Image 2013.05.12" > ${PART1MOUNT}/ID.txt
echo "Cloud9 GNOME Image 2013.05.12" > ${PART2MOUNT}/etc/dogtag

umount ${PART1MOUNT}

I'll explain this part at some point:

if [ "${HOSTARCH}" = "armv7l" ] ; then

        echo "Generating machine ID"
        systemd-nspawn -D ${PART2MOUNT} /bin/systemd-machine-id-setup

        echo "Running Postinsts"
        cpufreq-set -g performance
        systemd-nspawn -D ${PART2MOUNT} /usr/bin/opkg-cl configure
        cpufreq-set -g ondemand

        # Hack to get some space back
        systemd-nspawn -D ${PART2MOUNT} /usr/bin/opkg-cl remove db-doc --force-depends

        #echo "Setting timezone to Europe/Paris"
        #systemd-nspawn -D ${PART2MOUNT} /usr/bin/timedatectl set-timezone Europe/Paris


rm -f ${PART2MOUNT}/etc/pam.d/gdm-autologin

rm -f ${PART2MOUNT}/etc/systemd/system/
rm -f ${PART2MOUNT}/etc/systemd/system/*
ln -s /dev/null ${PART2MOUNT}/etc/systemd/system/xinetd.service

touch ${PART2MOUNT}/etc/default/locale

Most of the rest is fairly self-explanatory, ending with unmounting the eMMC Linux partition, at which point the flashing is complete:

# enable wifi
mkdir -p ${PART2MOUNT}/var/lib/connman/
cp connman.settings ${PART2MOUNT}/var/lib/connman/settings

# Replace wallpaper
if [ -e ${PART2MOUNT}/usr/share/pixmaps/backgrounds/gnome/angstrom-default.jpg ] ; then
        cp beaglebg.jpg ${PART2MOUNT}/usr/share/pixmaps/backgrounds/gnome/angstrom-default.jpg

umount ${PART2MOUNT}


At this point, the flashing of eMMC is complete, so finish things off by turning on all four LEDs to signify end of flashing:

if [ -e /sys/class/leds/beaglebone\:green\:usr0/trigger ] ; then
        echo default-on > /sys/class/leds/beaglebone\:green\:usr0/trigger
        echo default-on > /sys/class/leds/beaglebone\:green\:usr1/trigger
        echo default-on > /sys/class/leds/beaglebone\:green\:usr2/trigger
        echo default-on > /sys/class/leds/beaglebone\:green\:usr3/trigger

At this point, power down, remove the uSD card, and power up again.

Cleaning up after yourself

If you used kpartx to examine the contents of the flasher image, you should deactivate it by unmounting the flasher image partitions, then unregistering the device files that were created for it:

$ sudo kpartx -d BBB-eMMC-flasher-2013.05.20.img
loop deleted: /dev/loop0

(Back to BeagleBone Black page.)

Personal tools