Raspberry Pi 3 Model B/B+ Raspbian

Board description

The Raspberry Pi 3 Model B/B+ is a popular single board computer based on Broadcom SoCs. It is the most powerful board within the Raspberry Pi family and probably the most popular with “makers”.

770A5842-462x322

URL: https://www.raspberrypi.org/products/raspberry-pi-3-model-b-plus
URL: https://www.raspberrypi.org/products/raspberry-pi-3-model-b
Wiki: https://elinux.org/RPi_Hub

Test results

The Raspbian releases in the table below have been tested by the Mender community. Please update it if you have tested this integration on other Raspbian releases:

Rasbian Build Runtime
Raspbian Buster 2019-07-10 :test_works: :test_workaround: Note: HDMI issue
Raspbian Buster 2019-06-20 :test_works: :test_works:Note: Upgrading from Stretch
Raspbian Stretch 2019-04-08 :test_works: :test_works:
Raspbian Stretch 2018-11-13 :test_works: :test_works:

Build Means that the image generation completes without errors and outputs images.
Runtime Means that Mender has been verified to work on the board.

Getting started

Prerequisites

  • A Linux-based laptop/workstation (Ubuntu has been verified to work)
  • You need to install Docker Engine to use this tutorial
  • You need to install the following additional packages:
    sudo apt-get install qemu-user-static git

Build Docker image for mender-convert

Open a terminal and clone the mender-convert repository, e.g.

git clone --no-checkout https://github.com/mendersoftware/mender-convert.git

Enter your mender-convert environment:

cd mender-convert

Checkout latest release:

git checkout 1.2.x

There is a utility script which can be used to generate the appropriate docker image to run mender-convert:

./docker-build

This will create a container image you can use to run mender-convert.

Download the latest stable Raspberry Pi raw disk image

Go to the official download site for Raspberry Pi images and download the latest image.

In our example we will use the 2019-06-20-raspbian-buster-lite.zip raw disk image.

Move the binaries into your mender-convert environment

Download the raw Raspberry Pi disk image into a subdirectory input:

mkdir -p input
cd input
wget https://downloads.raspberrypi.org/raspbian_lite/images/raspbian_lite-2019-06-24/2019-06-20-raspbian-buster-lite.zip

Extract the raw Raspberry Pi disk image:

unzip 2019-06-20-raspbian-buster-lite.zip && cd ..

Convert the Raspberry Pi disk image to support Mender

With the raw disk image and the container configured above, we can convert the image.

You can get your Hosted Mender tenant token at the My organization page in Hosted Mender.
If you want to use a self-hosted Mender server, please do not use the --tenant-token option and adjust --server-url. Alternately, if you want to build the image for demo purposes, use the --demo flag together with --demo-host-ip option.

Setup the environment prior to running mender-convert:

DEVICE_TYPE="raspberrypi3"
RAW_DISK_IMAGE="input/2019-06-20-raspbian-buster-lite.img"

ARTIFACT_NAME="2019-06-20-raspbian-buster-lite"
MENDER_DISK_IMAGE="2019-06-20-raspbian-buster-lite.sdimg"
TENANT_TOKEN="<INSERT-TOKEN-FROM Hosted Mender>"

NOTE! Update the TENANT_TOKEN with the one you got from My organization page in Hosted Mender.

To avoid problems with disk images that have been booted and expanded to occupy all available space, we run raw-disk-image-shrink-rootfs (see this thread for additional information):

./docker-mender-convert raw-disk-image-shrink-rootfs \
            --raw-disk-image ${RAW_DISK_IMAGE}

Run mender-convert inside the container by running:

./docker-mender-convert from-raw-disk-image                       \
            --raw-disk-image $RAW_DISK_IMAGE                      \
            --mender-disk-image $MENDER_DISK_IMAGE                \
            --device-type $DEVICE_TYPE                            \
            --artifact-name $ARTIFACT_NAME                        \
            --bootloader-toolchain arm-buildroot-linux-gnueabihf  \
            --server-url "https://hosted.mender.io"               \
            --tenant-token $TENANT_TOKEN                          \
            --demo

NOTE! The --demo flag configures suitable polling intervals for testing and evaluation and this is to not be used in a production environment.

Conversion will take 10-15 minutes, depending on your storage and resources available.

NOTE!

You will need an SD card with an capacity of at least 8GB when using the default arguments. The SD card layout will be the following using the default arguments:

Part Type Purpose Size Configure size
mmcblk0p1 vfat Store the bootloader 44MB Extracted from input image
mmcblk0p2 ext4 Store the root file system and kernel (active) 3908MB --storage-total-size-mb 1
mmcblk0p3 ext4 Store the root file system and kernel (inactive) 3908MB --storage-total-size-mb 1
mmcblk0p4 ext4 Store persistent data, preserved during Mender updates. 128MB --data-part-size-mb 2

1. The rootfs partition size is calculated using the following formula:

 (storage-total-size-mb - data-part-size-mb - boot-part-size) / 2

2. You rarely need to adjust the data part size using --data-part-size-mb as this will expanded on first boot to occupy the remaining free blocks of the SD card.

You can read more about the partition layout required for Mender here

Use the output images

After a successful conversion, the images and artifacts are:

  • output/2019-06-20-raspbian-buster-lite.sdimg
  • output/2019-06-20-raspbian-buster-lite.ext4
  • output/2019-06-20-raspbian-buster-lite.mender

The disk image (with .sdimg suffix) is used to provision the device storage for devices without Mender running already. Please proceed to the official documentation on provisioning a new device for steps to do this.

On the other hand, if you already have Mender running on your device and want to deploy a rootfs update from this conversion, you should use the Mender Artifact files, which have .mender suffix. You can either deploy this Artifact in managed mode with the Mender server as described in Deploy to physical devices or by using the Mender client only in Standalone deployments.

Boot from the SD card and connect to your Mender server

Ensure your device has Internet connectivity (e.g. through Ethernet cable with DHCP support).

After provisioning a SD card with the converted disk image (.sdimg) above, boot your device from it.

After about 10 minutes, you should see your device Pending authorization under the Devices tab in your Mender server.
Authorize your device to join your Mender server.

You can now deploy software updates to your Raspberry Pi using the Mender server!

Create your first update Artifact

In Mender the software updates are packaged as Mender Artifact files.
You already have one Mender Artifact from your initial conversion above.

For testing purposes, we will generate a new Mender Artifact using a emulated device environment.
Enter the device-image-shell subdirectory in mender-convert. If this directory does not exist, make sure you use a recent branch or tag of the mender-convert repository (e.g. master).

cd device-image-shell

Build Docker image for device-image-shell

For simplicity and portability, the emulated device environment is provided as a Docker container.
Build the Docker image:

./docker-build

Use the device-image-shell container image

You can now enter a shell in your device root file system image by running docker-device-image-shell with the desired arguments:

  1. path to your existing root file system image
  2. desired name for the generated Mender Artifact
  3. device type, which Mender uses to ensure compatibility between devices and software

Starting from your original root file system image created above, enter an emulated shell (you might need to adjust the path – the first argument):

./docker-device-image-shell ../output/2019-06-20-raspbian-buster-lite.ext4 2019-06-20-raspbian-buster-lite-modified raspberrypi3

You should now see a shell prompt. You are in an emulated environment, so any commands run here will behave as if you ran them on your device! In addition, any changes you make will be preserved in the output root file system image and Mender Artifact.

For example, to update to the latest packages run:

apt update
apt upgrade

When you are done, press Ctrl+D or run the exit command. Generating the Mender Artifact will take a few more minutes, depending on the size of the input image and resources available on your workstation.

After it finishes you can find your new .ext4 and .mender files in the output/ directory, e.g.

  • output/2019-06-20-raspbian-buster-lite-modified.ext4
  • output/2019-06-20-raspbian-buster-lite-modified.mender

You can use the Mender Artifact (.mender file) to deploy the changes you made in the shell to all your devices!

Upload and deploy your new Mender Artifact

Go to your Mender server and upload this new Artifact under the Artifacts tab.
This might take a while, as the Raspbian distribution is quite large.

After the Artifact is uploaded, go to the Deployments tab and create a deployment
using this Artifact and your Raspberry Pi device. You should shortly
see the deployment being in progress. This will usually take a bit longer than
uploading your Artifact if you are on the same network as the device.

Verify the update

After the deployment has succeeded, log in to your device and verify that all packages have been updated to the latest version.

Run the following command:

sudo apt update

It should tell you that all packages are up to date!

Now you can deploy the original system again by uploading the original Mender Artifact output
by mender-convert (e.g. 2019-06-20-raspbian-buster-lite.mender) to your Mender server.

You can also generate more Mender Artifact files using the docker-device-image-shell tool!

An improved workflow to generate Artifacts

The workflow of using an emulated device works for testing purposes, but it might
have some limitations as we are emulating and not logged in to a real device or user.

When working with real deployments the recommended workflow is to have
one golden device, that has not been converted to support Mender.
On this device you carry out all the modifications you need, and then
use the resulting SD card to create Mender Artifact files, in summary:

  • flash vanilla Rasbian to the SD card
  • boot the SD card, log in and make any modifications needed
  • copy the SD card into an image on your workstation (e.g. using dd)
  • run mender-convert with the from-raw-disk-image option to generate a Mender Artifact (like above)
  • upload the Artifact to your Mender server
  • deploy it to your devices

Note that your golden device or SD card is not running Mender and is
not modified during deployments. It is simply the “source” for
generating the Artifacts that you deploy to the devices in the field.

References

  • The documentation on Building a Mender Debian image contains more information about using Mender with the Debian family of distributions.

  • The official Mender documentation explains how Mender works. This is simply a board-specific complement to the official documentation.

Known issues

HDMI issue on Raspbian 2019-07-10 image

There is currently a known issue with HDMI output when converting a 2019-07-10 image. Additional background information can be found in this ticket.

The workaround if you intended to use graphics on the Raspberry Pi together with a 2019-07-10 Buster image, is to enable Full KMS Graphics Driver in your golden image, prior to running it trough mender-convert.

You can do this using raspi-config and you can find the option under, “Advanced Options” -> “GL Driver” -> “GL (Full KMS)”

raspi-config does not work as expected on a converted image

The raspi-config tool is a small utility that is commonly used on Raspbian to configure various aspects of the Raspberry Pi hardware and trying to use this tool on a converted image will not work (by design).

Specifically it relates to fact that we change the mount point of the boot partition, which on a stock image is mounted at /boot, but on a converted image it is mounted at /uboot. The raspi-config tool will try to perform lookups of files in /boot, and this is typically what will fail when trying to run this tool on a converted image.

The recommend approach is to use the raspi-config utility on the “Golden Image” as described in the “An improved workflow to generate Artifacts” section above, and not try to modify the converted image as this should be viewed as a static configuration that you can share across your device fleet.

U-boot build fails

If building U-boot fails with:

     D	scripts/Kconfig
     input in flex scanner failed
     ....
     include/linux/kconfig.h:4:32: fatal error: generated/autoconf.h: No such file or directory
     #include <generated/autoconf.h>

you might be using a case-sensitive filesystem which is not supported. This is a limitation of U-boot build system. Case-sensitive filesystems are typically used on OSX (Mac) and Windows but you can also run in to this on Linux if running on a NTFS formatted partition.

For details see this discussion

Boot firmware files

Raspberry Pi boards have a set of boot firmware files that are located on the vfat boot part, and a selection of these files are:

bootcode.bin  fixup.dat     fixup_cd.dat  fixup_db.dat
fixup_x.dat   start.elf     start_cd.elf  start_db.elf
start_x.elf

Occasionally there will be changes to the Raspberry Pi software stack that requires that these files are updated. One example would be a change in the Linux kernel that relies on functional changes in the boot firmware and in this case you need to update the boot firmware together with the Linux kernel to get a functional device.

See this thread where the limitations of the boot firmware files on Raspberry Pi are discussed.

Because of this limitation certain upgrade paths using Mender might not work out-of-the box, e.g one known that will not work is:

  • Raspbian Stretch 2019-04-08 -> Raspbian Buster 2019-06-20

To support this update path you must update the boot firmware files at the same time you are updating to Raspbian Buster 2019-06-20. You can utilize state-scripts for this.

Note that it is unsafe to do update the boot firmware files because there is no way you can update these files atomically and it is not possible to roll-back in case you install something that does not boot, which might render your device unusable without physical intervention.

Devicetree is not updated

To be able to support update of Linux kernel and devicetree, Mender requires these to be installed in the /boot directory for each rootfs (normally /dev/mmcblk0p2 and /dev/mmcblk0p3 ). On the other hand, the Raspberry Pi boot firmware requires that the DTB file is in the same partition as the boot firmware ( /dev/mmcbl0p1 ) and the config.txt file. For now Mender will not use the DTB that is delivered with new artifacts and will continue to boot with the original DTB that was populated using the sdimg file.

Problem using ‘dtoverlay=pi3-disable-bt’

pi3-disable-bt disables the Bluetooth device and restores UART0/ttyAMA0 to GPIOs 14 and 15. It is also necessary to disable the system service that initialises the modem so it doesn’t use the UART

There is currently a known issue with above functionality, that is to enable UART0 on PIN 14 and 15.

It is actually not something that is caused by Mender specifically, but Mender requires U-boot to be present to support robust features such as roll-back. U-boot is typically not enabled if you do a stock Raspberry Pi and some people are often surprised that the Bluetooth UART stopped working when they integrate Mender .

The problem is in U-boot which does conflicting configuration, and there is a workaround reported here and it has been reported to U-boot but unclear when/if it will be fixed.


If this post was useful to you, please press like, or leave a thank you note to the contributor who put valuable time into this and made it available to you. It will be much appreciated!

3 Likes

Tested newest Raspbian (2019-04-08) with Hosted Mender just now. No issues.

Also upgrading from 2018-11-13 to 2019-04-08 using a Mender Artifact works as expected! :slight_smile:

I built my mender image using 1.1x in Feb, then Mender Server 2.0 was released. Will my image work if I upgrade my server to Mender 2.0?

There was one change in your readme where you removed this line:

./docker-mender-convert from-raw-disk-image
–mender-client /mender

Currently, the image I created works great with Mender 1.7

Yes, that should be no problem!

3 posts were split to a new topic: Issues adding Mender to 2018-04 raspbian lite

11 posts were split to a new topic: Problems with Raspbian Buster

5 posts were split to a new topic: Issue with GL driver on Raspbian Stretch