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, so the Device Management Update Service can update it remotely.
This tutorial shows you how to:
Create the update image for a Raspberry Pi 3 device using Yocto.
Note: There is another tutorial that covers creating a delta update image.
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, though only one of them is active at any point. During the firmware update, the Update 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. The device uses the root file system that Yocto compressed, containing the updated firmware.
In Linux, the update process 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 can't access data in the previous file system (including the
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 (
bootflags) because the Device Management Client code uses them.
- 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:
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.cfile in the environment:
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 with the additional flag
EXTRA_CONF_FILE=1for quicker consecutive builds.
Build an update image using Yocto
To update the firmware on a device, 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 at
Copy the Yocto image to the micro SD card
Now you have an SD card image, you can write it to the device's micro SD 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 the Raspberry Pi 3 console UART is connected to your PC using a USB to serial converter.
Note: You only need to install the update image on the device if the device does not have your application and the Update client installed. If you previously installed your application and the Update client on the device and it is connected to the Device Management, 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, and then use the command lsblk to locate the SD card. In this example, the SD card is mounted as
/dev/sdcand 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
After 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, with which you can deliver updates to remote devices.