The Raspberry Pi Zero W comes with added wireless LAN and Bluetooth connectivity compared to Raspberry Pi Zero.
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:
|Raspbian Stretch 2018-11-13|
Build Means that the image generation completes without errors and outputs images.
Runtime Means that Mender has been verified to work on the board.
- 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
Open a terminal and clone the mender-convert repository , e.g.
git clone --no-checkout https://github.com/mendersoftware/mender-convert.git
Checkout a latest revision:
git checkout origin/1.1.x
There is a utility script which can be used to generate the appropriate docker image to run
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
2018-11-13-raspbian-stretch-lite.zip raw disk image.
Move the binaries into your
Download the raw Raspberry Pi disk image into a subdirectory
mkdir -p input cd input wget https://downloads.raspberrypi.org/raspbian_lite/images/raspbian_lite-2018-11-15/2018-11-13-raspbian-stretch-lite.zip
Extract the raw Raspberry Pi disk image:
unzip 2018-11-13-raspbian-stretch-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
Setup the environment prior to running mender-convert:
DEVICE_TYPE="raspberrypi0w" RAW_DISK_IMAGE="input/2018-11-13-raspbian-stretch-lite.img" ARTIFACT_NAME="2018-11-13-raspbian-stretch-lite" MENDER_DISK_IMAGE="2018-11-13-raspbian-stretch-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 .
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 \ --mender-client /mender \ --artifact-name $ARTIFACT_NAME \ --bootloader-toolchain arm-buildroot-linux-gnueabihf \ --server-url "https://hosted.mender.io" \ --tenant-token $TENANT_TOKEN
Conversion will take 10-15 minutes, depending on your storage and resources available.
NOTE!: above command will not work currently on OSx because of casesensitivity issue with filesystem when building u-boot.
Use the output images
After a successful conversion, the images and artifacts are:
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.
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.
Build Docker image for
For simplicity and portability, the emulated device environment is provided as a Docker container.
Build the Docker image:
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:
- path to your existing root file system image
- desired name for the generated Mender Artifact
- 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/2018-11-13-raspbian-stretch-lite.ext4 2018-11-13-raspbian-stretch-lite-modified raspberrypi0w
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
.mender files in the
output/ directory, e.g.
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
mender-convert (e.g. 2018-11-13-raspbian-stretch-lite.mender) to your Mender server.
You can also generate more Mender Artifact files using the
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
from-raw-disk-imageoption 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.
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