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”.


Wiki: https://elinux.org/RPi_Hub

Test results

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

Rasbian Build Runtime
Raspberry Pi OS Bullseye 2022-01-28 :test_works: :test_works:
Raspberry Pi OS Bullseye 2021-10-30 :test_works: :test_works:
Raspberry Pi OS Buster 2020-05-27 :test_works: :test_works:
Raspbian Buster 2020-02-05 :test_works: :test_works:
Raspbian Buster 2019-09-26 :test_works: :test_works:
Raspbian Buster 2019-09-16 :test_works: :test_works:
Raspbian Buster 2019-07-10 :test_works: :test_works:
Raspbian Buster 2019-06-20 :test_works: :test_workaround: 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.

Image downloads

The Raspberry Pi OS images in the table below come with Mender integrated.

Release Size (uncompressed) Size (compressed) SHA-256
Raspberry Pi OS Bullseye Lite 2022-01-28 7.4 GB 578 MB
Raspberry Pi OS Bullseye Lite 2021-10-30 7.4 GB 552 MB 672b69c6d570253be9bda15935f971aa5f7122c870aae7f12b7794ea99205192
Raspberry Pi OS Buster Lite 2021-01-11 7.4 GB 552 MB 672b69c6d570253be9bda15935f971aa5f7122c870aae7f12b7794ea99205192
Raspberry Pi OS Buster Lite 2020-05-27 7.4 GB 546 MB 68c30d665c3ee567a8cd225ddca147ca8f91dc4efdeca90a796048ac5124500c
Raspbian Buster Lite 2020-02-05 7.4 GB 549 MB 52d3113156715c3b4de3a12a729d17a96fe5af7eba886f862af8ba55543e743a

Get started

If you are starting with Mender, use a prebuilt image from above and follow the Mender Get Started.

Convert your own image (advanced)

To save time, use a prebuilt image and follow the Mender Get Started. The rest of this post explains how to build your own customized Raspberry Pi OS image with Mender integrated.


  • A Linux-based laptop/workstation (Ubuntu has been verified to work)
  • You need to install Docker Engine to use this tutorial

Build Docker image for mender-convert

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

git clone -b 3.0.0 https://github.com/mendersoftware/mender-convert.git

Enter your mender-convert environment:

cd mender-convert

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


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

Download the latest stable Raspberry Pi raw disk image

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

mkdir -p input
cd input
wget https://downloads.raspberrypi.org/raspios_lite_armhf/images/raspios_lite_armhf-2022-01-28/2022-01-28-raspios-bullseye-armhf-lite.zip

Extract the raw Raspberry Pi disk image:

unzip 2022-01-28-raspios-bullseye-armhf-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 Mender Professional tenant token at the My organization page in Mender Professional.

Configure the Mender client for hosted Mender server:

./scripts/bootstrap-rootfs-overlay-hosted-server.sh \
    --output-dir ${PWD}/input/rootfs_overlay_demo \
    --tenant-token "Paste token from Mender Professional"

There are additional scripts in the scripts/ directory to configure with a local demo server, or production server.

Run mender-convert inside the container by running:

MENDER_ARTIFACT_NAME=release-1 ./docker-mender-convert \
    --disk-image input/2022-01-28-raspios-bullseye-armhf-lite.img \
    --config configs/raspberrypi3_config \
    --overlay ./input/rootfs_overlay_demo

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


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 256MB MENDER_BOOT_PART_SIZE_MB
mmcblk0p2 ext4 Store the root file system and kernel (active) 3892MB MENDER_STORAGE_TOTAL_SIZE_MB 1
mmcblk0p3 ext4 Store the root file system and kernel (inactive) 3892MB MENDER_STORAGE_TOTAL_SIZE_MB 1
mmcblk0p4 ext4 Store persistent data, preserved during Mender updates. 128MB MENDER_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 MENDER_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:

  • deploy/2021-10-30-raspios-bullseye-armhf-lite-raspberrypi3-mender.cfg
  • deploy/2021-10-30-raspios-bullseye-armhf-lite-raspberrypi3-mender.ext4
  • deploy/2021-10-30-raspios-bullseye-armhf-lite-raspberrypi3-mender.img
  • deploy/2021-10-30-raspios-bullseye-armhf-lite-raspberrypi3-mender.mender

The disk image (with .img suffix) is used to provision the device storage for devices without Mender running already. You can write write the img image to an SD card using the following command:

cat deploy/2021-10-30-raspios-bullseye-armhf-lite-raspberrypi3-mender.img | sudo dd of=<path to device> bs=4M && sudo sync

Be careful! If you point to the wrong <path to device> when executing the above command, you risk overwriting your workstation’s local or connected storage devices.

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 (upload it under Releases in the server UI) 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!

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 --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.


  • 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

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

The raspi-config tool is a small utility that is commonly used on Raspberry Pi OS 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.

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

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!


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

6 posts were split to a new topic: Device not visible in “Pending”

3 posts were split to a new topic: Can I create a new artifact from an mender based sdimg?

Are there any standard set of test cases, that one should conduct to test the integrity of the system.
Apart from the normal ones

See this link: https://docs.mender.io/hosted/devices/yocto-project/bootloader-support/u-boot/integration-checklist

Of course that just tests Mender. You probably will need to review Raspberry Pi docs and general Yocto docs to understand other parts of the system and the needs for testing there.


Yes, Sorry I did not phrase my question properly. I did perform those steps. What I wanted to know. How do I test the retry and rollback feature from the https://hosted.mender.io

How do I create a failed scenario? How do I create a retry scenario?

I think I don’t know care about the fail scenario because the board integration checklist takes care of that. but How Do I create a retry scenario?

The steps in the integration checklist do verify that rollback is performed but if you want to test it in a full deployment then just power cycle the board while it is rebooting the first time.

Testing a retry will require implementing state scripts. You can see our examples here. If you create a ArtifactCommit_Enter script that returns “21” then it will retry. You will need to make sure to eventually return OK to avoid the server timing out the deployment.

Im still having the Problem with my Image not booting after converting it due to ‘dtoverlay=pi3-disable-bt’.

Can someone explain how exactly to aply the workaround reported in here

Im not very experienced with patching uboot.


I was able to fix the problem with disable-bt overlay:

  • I forked the mender-uboot and applied the patch mentioned here
  • I patched integration-scripts to create the binaries
  • I run mender-convert using the patched binaries
    Everything is now running nice and smoothly and i can use ttyAMA0.

I think it would make sense to offer that patched version of mender-uboot binaries for a “new” device type (raspberrypi3serial) and by assigning RASPBERRYPI_CONFIG=“raspberrypi3serial” those binaries would then be used when running mender convert. the raspberrypi_config.)


Sounds interesting!

How about a PR, and we’ll take it from there?


I just encountered an issue when upgrading from buster to bullseye. This update does also need updates to the boot partition. I’m writing this here in the hope it helps others spend less time debugging…

1 Like

5 posts were split to a new topic: Mender-convert for Raspberry Pi 3 - storage/card too small

A post was split to a new topic: Mender-convert for Raspberry Pi - 64bit?