Building for demo

This document outlines the steps needed to build a Yocto Project image for a device. The build output will most notably include:

• a disk image for flashing the device storage during initial provisioning
• an Artifact containing rootfs filesystem image file that Mender can deploy to your provisioned device, it has suffix .mender

What is meta-mender?

meta-mender is a set of layers that enable the creation of a Yocto Project image where the Mender client is part of the image. With Mender installed and configured on the image, you can deploy image updates and benefit from features like automatic roll-back, remote management, logging and reporting.

Inside meta-mender there are several layers. The most important one is meta-mender-core, which is required by all builds that use Mender. meta-mender-core takes care of:

• Compiling Mender for devices
• Partitioning the image correctly
• Setting up the bootloader to support Mender

Refer to the linked sections for details on configuring each of these steps.

The other layers in meta-mender provide support for specific boards used in Mender testing suite.

What is meta-mender-community?

meta-mender-community is a set of layers containing board-specific settings for Mender integration.

Prerequisites

Board integrated with Mender

Mender needs to integrate with your board, most notably with the boot process. Although the integration is automated for most boards, please see Board integration for general requirements and adjustment you might need to make before building.

Check out the board integrations at Mender Hub to see if your board is already integrated. If you encounter any issues and want to save time, you can use the Mender Consulting services to integrate your board.

Correct clock on device

Make sure that the clock is set correctly on your devices. Otherwise certificate verification will become unreliable and the Mender Client can likely not connect to the Mender Server. See certificate troubleshooting for more information.

Yocto Project

Starting from scratch

Full details for building the Yocto project for your board are available at Mender Hub. The tested reference platforms for Mender are available at the following:

• Raspberry Pi 3 Model B/B+
• Raspberry Pi 4 Model B
• BeagleBone Black
• QEMU

If you encounter any issues, please see Board integration for general requirements and adjustments you might need to enable your board to support Mender.

Configuring the build

The following settings will be present in the default conf/local.conf after running the steps from Mender Hub. These are likely to need customization for your setup.

# The name of the disk image and Artifact that will be built.
# This is what the device will report that it is running, and different updates must have different names
# because Mender will skip installation of an Artifact if it is already installed.
MENDER_ARTIFACT_NAME = "release-1"

# The version of Mender to build. This needs to match an existing recipe in the meta-mender repository.
#
# Given your Yocto Project version, see which versions of Mender you can currently build here:
# https://docs.mender.io/overview/compatibility#mender-client-and-yocto-project-version
#
# Given a Mender Client version, see the corresponding version of the mender-artifact utility:
# https://docs.mender.io/overview/compatibility#mender-clientserver-and-artifact-format
#
# By default this will select the latest version of the tools that is backwards compatible with the
# given Yocto branch.
# If you need an earlier version, or a later version even though it may not be backwards compatible,
# please uncomment the following and set to the required version. If you want to use the bleeding
# edge version, specify "master-git%", but keep in mind that these versions may not be stable:
#
# PREFERRED_VERSION_mender = "5.0.0"
# PREFERRED_VERSION_mender-client = "5.0.0"
# PREFERRED_VERSION_mender-artifact = "4.0.0"
# PREFERRED_VERSION_mender-artifact-native = "4.0.0"
# PREFERRED_VERSION_mender-connect = "2.3.0"

ARTIFACTIMG_FSTYPE = "ext4"

# Build for hosted Mender
#
# To get your tenant token:
#    - log in to https://hosted.mender.io
#    - click your email at the top right and then "My organization"
#    - press the "COPY TO CLIPBOARD"
#    - assign content of clipboard to MENDER_TENANT_TOKEN
#
#MENDER_SERVER_URL = "https://hosted.mender.io"
#MENDER_TENANT_TOKEN = ""

# Build for Mender demo server
#
# https://docs.mender.io/administration/demo-installation
#
# Uncomment below and update IP address to match the machine running the
# Mender demo server
#MENDER_DEMO_HOST_IP_ADDRESS = "192.168.0.100"

# Build for Mender production setup (on-prem)
#
# https://docs.mender.io/administration/production-installation
#
# Uncomment below and update the URL to match your configured domain
# name and provide the path to the generated server.crt file.
#
# Note that a custom server.crt file is only necessary if you are using
# self-signed certificates.
#
# NOTE! It is recommend that you provide below information in your custom
# Yocto layer and this is only for demo purposes. See linked documentation
# for additional information.
#MENDER_SERVER_URL = "https://docker.mender.io"
#FILESEXTRAPATHS:prepend:pn-mender-server-certificate := "<DIRECTORY-CONTAINING-server.crt>:"
#SRC_URI:append:pn-mender-server-certificate = " file://server.crt"
#IMAGE_INSTALL:append = " mender-server-certificate"

Adding meta-mender to existing Yocto Project environment

If you have an existing Yocto Project environment and want to add Mender to that, you will need to add the required meta layers to your build environment. The instructions here are the basic steps needed to do this however your actual setup may require different mechanisms such as the Google repo tool.

Please make sure you are standing in the directory where poky resides, i.e. the top level of the Yocto Project build tree, and run these commands:

git clone -b scarthgap https://github.com/mendersoftware/meta-mender

Note that this command checks out the HEAD of the scarthgap branch and is not a specific tagged release. The Yocto project release schedule differs from the Mender release schedule so even though you may be using a specific release of Mender, you will still need to take further steps if you want to use a tagged release of the Yocto project.

Next, initialize the build environment:

source oe-init-build-env

This creates a build directory with the default name, build, and makes it the current working directory.

Then, add the Mender layers into your project:

bitbake-layers add-layer ../meta-mender/meta-mender-core

bitbake-layers add-layer ../meta-mender/meta-mender-demo

Configuring the build

Add these lines to the start of your conf/local.conf:

# The name of the disk image and Artifact that will be built.
# This is what the device will report that it is running, and different updates must have different names
# because Mender will skip installation of an Artifact if it is already installed.
MENDER_ARTIFACT_NAME = "release-1"

INHERIT += "mender-full"

# A MACHINE integrated with Mender.
# raspberrypi3, raspberrypi4, beaglebone-yocto, vexpress-qemu and qemux86-64 are reference boards
MACHINE = "<YOUR-MACHINE>"

# The version of Mender to build. This needs to match an existing recipe in the meta-mender repository.
#
# Given your Yocto Project version, see which versions of Mender you can currently build here:
# https://docs.mender.io/overview/compatibility#mender-client-and-yocto-project-version
#
# Given a Mender Client version, see the corresponding version of the mender-artifact utility:
# https://docs.mender.io/overview/compatibility#mender-clientserver-and-artifact-format
#
# By default this will select the latest version of the tools that is backwards compatible with the
# given Yocto branch.
# If you need an earlier version, or a later version even though it may not be backwards compatible,
# please uncomment the following and set to the required version. If you want to use the bleeding
# edge version, specify "master-git%", but keep in mind that these versions may not be stable:
#
# PREFERRED_VERSION_mender = "5.0.0"
# PREFERRED_VERSION_mender-client = "5.0.0"
# PREFERRED_VERSION_mender-artifact = "4.0.0"
# PREFERRED_VERSION_mender-artifact-native = "4.0.0"
# PREFERRED_VERSION_mender-connect = "2.3.0"

# The following settings to enable systemd are needed for all Yocto
# releases sumo and older.  Newer releases have these settings conditionally
# based on the MENDER_FEATURES settings and the inherit of mender-full above.
DISTRO_FEATURES:append = " systemd"
VIRTUAL-RUNTIME_init_manager = "systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
VIRTUAL-RUNTIME_initscripts = ""

ARTIFACTIMG_FSTYPE = "ext4"

# Build for hosted Mender
#
# To get your tenant token:
#    - log in to https://hosted.mender.io
#    - click your email at the top right and then "My organization"
#    - press the "COPY TO CLIPBOARD"
#    - assign content of clipboard to MENDER_TENANT_TOKEN
#
#MENDER_SERVER_URL = "https://hosted.mender.io"
#MENDER_TENANT_TOKEN = ""

# Build for Mender demo server
#
# https://docs.mender.io/administration/demo-installation
#
# Uncomment below and update IP address to match the machine running the
# Mender demo server
#MENDER_DEMO_HOST_IP_ADDRESS = "192.168.0.100"

# Build for Mender production setup (on-prem)
#
# https://docs.mender.io/administration/production-installation
#
# Uncomment below and update the URL to match your configured domain
# name and provide the path to the generated server.crt file.
#
# Note that a custom server.crt file is only necessary if you are using
# self-signed certificates.
#
# NOTE! It is recommend that you provide below information in your custom
# Yocto layer and this is only for demo purposes. See linked documentation
# for additional information.
#MENDER_SERVER_URL = "https://docker.mender.io"
#FILESEXTRAPATHS:prepend:pn-mender-server-certificate := "<DIRECTORY-CONTAINING-server.crt>:"
#SRC_URI:append:pn-mender-server-certificate = " file://server.crt"
#IMAGE_INSTALL:append = " mender-server-certificate"

Building the image

Once you are done with all the configuration steps, build an image with bitbake:

bitbake <YOUR-TARGET>

Replace <YOUR-TARGET> with the desired target or image name, e.g. core-image-full-cmdline.

Using the build output

After a successful build, the images and build artifacts are placed in tmp/deploy/images/<YOUR-MACHINE>/.

There is one Mender disk image, which will have one of the following suffixes:

• .uefiimg if the system boots using the UEFI standard (x86 with UEFI or ARM with U-Boot and UEFI emulation) and GRUB bootloader
• .sdimg if the system is an ARM system and boots using U-Boot (without UEFI emulation)
• .biosimg if the system is an x86 system and boots using the traditional BIOS and GRUB bootloader

This disk image is used to provision the device storage for devices without Mender running already. Please proceed to 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 using this build, you should use the Mender Artifact files, which have .mender suffix.