Raspberry PI 0 WiFi Raspbian

The Raspberry Pi Zero W comes with added wireless LAN and Bluetooth connectivity
compared to Raspberry Pi Zero.

URL: https://www.raspberrypi.org/products/raspberry-pi-zero-w
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 Stretch 2018-11-13 :test_works: :test_works:
Raspi OS Buster 2020-05-27 :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

Build Docker image for mender-convert

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

git clone -b 2.2.1 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:

./docker-build

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/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 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}/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/2019-06-20-raspbian-buster-lite.img \
    --config configs/raspberrypi0w_config \
    --overlay ${PWD}/rootfs_overlay_demo

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 MENDER_BOOT_PART_SIZE_MB
mmcblk0p2 ext4 Store the root file system and kernel (active) 3908MB MENDER_STORAGE_TOTAL_SIZE_MB 1
mmcblk0p3 ext4 Store the root file system and kernel (inactive) 3908MB 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/raspberrypi-release-1.sdimg.gz
  • deploy/raspberrypi-release-1.ext4
  • deploy/raspberrypi-release-1.mender

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

zcat deploy/raspberrypi-release-1.sdimg.gz | 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 or by using the Mender client only in Standalone
deployments. See Mender introduction for an overview.

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.

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

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.

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!

1 Like

Note that after the previous git clone --no-checkout https://github.com/nandra/mender-conversion-tools command, the name of the directory is mender-conversion-tools.

Thanks for reporting, I have edited the wiki to make sure that the checkout is done to mender-convert directory.

We renamed the repo at some point and that is probably why there was a difference, the current mainstream name is mender-convert.

1 Like

Thank you @mirzak!

Next step:

./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                  \
            --server-url "https://hosted.mender.io"         \
            --tenant-token $TENANT_TOKEN

Running mender-convert from-raw-disk-image --raw-disk-image input/2018-11-13-raspbian-stretch-lite.img --mender-disk-image 2018-11-13-raspbian-stretch-lite.sdimg --device-type raspberrypi0w --artifact-name 2018-11-13-raspbian-stretch-lite --server-url https://hosted.mender.io --tenant-token [elided]
*** Data partition size set to default value: 128MB ***
*** Total storage size set to default value: 8GB ***

Mender conversion tool

A tool that takes an existing embedded image (Debian, Ubuntu, Raspbian, etc)
and converts it to a Mender image by restructuring partition table and adding
necessary files.

Usage: ./mender-convert COMMAND [options]

General commands:

        from-raw-disk-image                     - composes fully functional Mender
                                                  image compliant with Mender
                                                  partition layout, having all
                                                  necessary files installed
        mender-disk-image-to-artifact           - creates Mender artifact file
                                                  from Mender image

Expert commands:
[... rest of help message]
1 Like

Updated wiki again, was missing some mandatory commands.

1 Like

A post was split to a new topic: How to set new sizes with mender-convert

@andrew_wilcox thanks for reporting @mirzak thanks for fixing

@MarekBelisko once the resize bug is sorted out, can this be moved back to the official mender-convert repo? I think the ARMv6 support will be part of mender-convert 1.1, right?

Also, do you know if a converted image (for ARMv6) runs both on RPI0 and RPI3 (since the original does)?

@eystein yes I think it make sense. Iā€™ll update when resize bug will be sorted out. Thanks for reminder.

@MarekBelisko awesome!

Also, just curious if it would make sense to call the device type ā€œraspberrypi0-wifiā€ as this is what the MACHINE is called in Yocto?

Yes I think it make sense to update device type also. Thanks.

Hey,
Iā€™ve successfully deployed the latest raspbian buster using this board integration. Iā€™m using an 8GB SD card (not my choice but our clientsā€™). When I deploy the system and boot the device it boots fine but the rootfs is left with unallocated space:
Screenshot from 2020-01-22 15-06-17

Any idea what is causing this free space and how to get rid of it? I used a systemd to extend the rootfs on first boot. Works find but unfortunately I get an error when I use this configuration to create and deploy a new mender artifact:
error: transient error: Reboot to new update failed. Expected "upgrade_available" flag to be true but it was false
Which is a shame cause until here this solution worked. Any hints on how to expand the rootfs?

BTW: this is the systemd I came up with:

[Unit]
Description=QuakeSaver - Resize root filesystem on first boot
DefaultDependencies=no
After=data.mount

[Service]
Type=oneshot
ExecStart=/bin/bash -c "ROOT_DEV=$(/bin/findmnt / -o source -n) && /sbin/resize2fs $ROOT_DEV && /bin/systemctl disable qs-resize2fs.service && /sbin/reboot"
[Install]
WantedBy=sysinit.target

Note: I donā€™t know if that details matters but I had to limit the total size setting: MENDER_STORAGE_TOTAL_SIZE_MB=7400
Thus, the remark in the documentation is actually misleading stating that you need at least an 8GB for the default settings to work. An 8GB is not enough for the default parameters

You can do something similar that is done in this configuration file,

This makes sure that rootfs is filled up with free space, the default is by design not to fill up the rootfs (leaving it unallocated). Reasoning is that rootfs should be considered stateless and you do not really need the extra free space (as anything written to the rootfs will be lost on an update) and adding ā€œfree spaceā€ will increase the update time as it will need to write zeroes for the allocated ā€œfree spaceā€

I see. Thanks!
But since this is a debian running that also writes some logs to the SD card doesnā€™t it make sense to expose all available sectors so that the wear leveling has more space to do itā€™s work?
If there is only 100 MB of free allocated space and log files only write to those 100 MB doesnā€™t the card decline earler then when it has another 400 MB to write logs to? Iā€™m not so much into the details of wear leveling but thought that space has to be allocated for that?!

My understanding is that wearleveling is handled at a lower level by the SD card controller, so I do not think that this should have any impact on this.

:man_facepalming: You are absolutely right. Should have done better research before prematurely optimizing things that need no optimizationā€¦

25 posts were split to a new topic: Issues with Raspberry Pi 0 WiFi Raspbian

Hi,
2020-05-27-raspios-buster working fine so far
2021-05-07-raspios-buster threw kernel panic during system update: RPI0w Kernel Panic Related to ipv6_rcv Ā· Issue #4466 Ā· raspberrypi/linux Ā· GitHub

@bao-eng
Thank you for the update, Iā€™m adding `2020-05-27 to the supported versions now :slight_smile: