Building an update image for the Raspberry Pi 3 device

This tutorial describes the firmware image for the Raspberry Pi 3 and explains how you can build an update image (including the firmware update and the bootloader) for the Raspberry Pi 3 device that enables it to be remotely updated by the Device Management Update Service.

This tutorial shows you how to:

1. Create the update image for a Raspberry Pi 3 device using Yocto.

   Note: There is another tutorial that covers creating a delta update image.

2. Install the update image on the SD card of the Raspberry Pi 3 device.

The Raspberry Pi3 Update image

An update image for Raspberry Pi 3 is built with the Yocto build environment and contains a complete Linux root file system, compressed in a .tar.bz2 archive. This image includes two root file system partitions, although only one of them is active at any point. During the firmware update, the Upload client downloads the update image to the inactive file system partition and uncompresses the archive file. The Update client reboots the device, at which point the bootloader sets the active root file system partition to one which has just been updated, and the device uses the root file system that Yocto compressed, containing the updated firmware.

Note that in Linux, the update process currently updates the complete root file system (ROOTFS). It is not possible to update from one Yocto distribution to another, for example from Morty to Rocko.

Storing data persistently on a Raspberry Pi 3

When the Update client installs firmware on a Raspberry Pi 3 device, it formats the inactive root file system partition, deleting any data on it. You will be unable to access data in the previous file system (including the /home and /etc directories).

If you want to persistently store data in the device's file system, you can use additional partitions to mount directories for this data (such as the /home directory). You'll need to add these partitions to the SD card by:

• Modifying the Yocto recipe that generates the update image.
• Editing the SD card partition table, after you have transferred the image to the SD.

Note: If you modify the partition layout, do not delete the default partitions (rootfs1, rootfs2, config, cache and bootflags) because the Device Management Client code uses them.

Prerequisites

You will need:

• A Raspberry Pi 3 board.
• The serial console on your Raspberry Pi 3 connected to your PC using a USB to serial adapter.

You should have:

• Prepared your development environment.

• Integrated the Device Management Update client into your user application.

• Installed the Yocto build environment:

  • If you have not already done so, import the top level Yocto repository and install its dependencies:

    git clone https://github.com/ARMmbed/mbed-cloud-client-yocto-setup
    cd mbed-cloud-client-yocto-setup
    mbed deploy --protocol git
    

  • Also make sure that you have exported the absolute path to your mbed_cloud_dev_credentials.c file in the environment:

      ```
      export MBED_CLOUD_IDENTITY_CERT_FILE_IMPORT=/absolute/path/to/credentials/file
      ```
    

  Note: The Yocto build process can take a lot of time and resources (disk space and RAM). Depending on the configuration of your PC, the first build might take a few hours to complete. Subsequent builds will be much faster. You can use bitbake caches to reduce the time it takes to build the image.

  • (Optional) To create cache directories for quicker builds, execute the following commands:

    sudo mkdir /var/cache/bitbake
    sudo chown <build-username>:<build-username> /var/cache/bitbake
    Then compile the SW with additional flag 'EXTRA_CONF_FILE=1' to enable consecutive builds to be quicker.
    

Build an update image using Yocto

To update the firmware on a device:

1. Build a Yocto image using the following command:

   make -f Makefile.example build-raspberry-example
   

   Or if you have enabled bitbake caches enabled, use this command:

   make -f Makefile.example EXTRA_CONF_FILE=1 build-raspberry-example
   

   The output of this step is an SD card image for a Raspberry Pi 3 device. You'll find this the .rpi-sdimg file in the following location: rpi-build/tmp/deploy/images/raspberrypi3/mbed-cloud-client-example-image-raspberrypi3.rpi-sdimg.

Copy the Yocto image to the micro SD card

Now you have an SD card image, you can write it to the device's microSD card, and boot your Raspberry Pi 3 device from this card. This example uses dd to copy the SD card image directly to the SD card, using dd. Refer to the Raspberry Pi documentation for more information.

Make sure that the Raspberry Pi 3 console UART is connected to your PC using an USB to serial converter.

Note: You only need to install the update image on the device if it currently does not have your application and the Update client installed. If you have previously installed your application and the Update client on the device and it is connected to the Device Management, then you can update the firmware using a manifest file and an update campaign.

To copy the image to the SD card:

• Check where the SD-card is mounted to your PC. Connect an SD-card to your PC, then use the command lsblk to locate the SD card. In this example, the SD-card is mounted as /dev/sdc and has a size of 7.5GB:

~$ lsblk
NAME                 MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sda                    8:0    0 238.5G  0 disk
├─sda1                 8:1    0   476M  0 part
└─sda2                 8:2    0   238G  0 part
  ├─vg00-swap (dm-0) 252:0    0   7.5G  0 lvm  [SWAP]
  └─vg00-root (dm-1) 252:1    0 230.6G  0 lvm  /
sdb                    8:16   0   1.8T  0 disk
├─sdb1                 8:17   0   128M  0 part
└─sdb2                 8:18   0   1.8T  0 part
sdc                    8:32   1   7.5G  0 disk
├─sdc1                 8:33   1    16M  0 part
└─sdc2                 8:34   1 492.3M  0 part

• Use the dd utility to write the image to the SD card:

  dd if=rpi-basic-image-raspberrypi3.rpi-sdimg of=/dev/sdc
  

• Once the device boots and confirms on the serial console that it was able to register to Device Management, it is ready to receive updates.

Next step: Create a firmware manifest

Now that you have a device that can be remotely updated, you can create a manifest file which will enable you to deliver updates to remote devices.