[ Topic template - Yocto Project ]

Board Integrations Yocto Project
1

Board description

TODO: Short description of the board.

TODO: Upload a board picture here.

  • Vendor URL: TODO — vendor page with the board specs
  • Wiki: TODO — wiki URL (if available)
  • SoC / SoM: TODO — e.g. NXP i.MX8MP, Qualcomm QRB2210, TI AM625
  • Yocto MACHINE: TODO — e.g. raspberrypi4-64
  • Config in mender-community-images: TODO — e.g. yocto/wrynose/floating/<TARGET>.yml

Test results

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

TODO: Update the table below with the Yocto Project versions you tested and the result. Sample data:

Yocto Project Build Runtime
wrynose (6.0) :test_works: :test_works:
scarthgap (5.0) :test_works: :test_workaround: 1
kirkstone (4.0) :test_workaround: 2 :test_fails: 3

1. Runtime note … (describe any manual step required at runtime). 2. Build note … (describe the workaround, e.g. a required bbappend or a layer pin). 3. Board does not boot / freezes after the bootloader with the following message …

Build means the Yocto Project build using this Mender integration completes without errors and produces images.Runtime means Mender has been verified to work on the board. For boards that integrate through a bootloader, verify the relevant bootloader integration — see GRUB or U-Boot. Some platforms instead reuse a native A/B boot mechanism driven by a custom Update Module rather than Mender’s GRUB/U-Boot rootfs integration; note which model applies to your board.

Getting started

Prerequisites

  • A supported Linux distribution with the Yocto Project host dependencies installed, as described in the Yocto Project reference manual.

    • NOTE: the exact package list depends on the Yocto Project release you are building; use the reference manual matching your chosen release.

  • kas installed and on your PATH:

    pip install kas
    • Optionally, run the build inside a managed container with kas-container instead of natively.

  • git.

The build configurations are maintained in the mender-community-images repository, which consolidates the kas configurations (and mender-convert configurations) for the known Mender community board integrations.

Legacy note. Board integrations were historically set up with Google’s repo tool and manifests in mendersoftware/meta-mender-community, and later via in-tree kas/ configurations in that same repository. Those kas configurations have since been consolidated into mender-community-images. New repo-based setups are no longer accepted — use kas.

Configuring the build

Get the build configurations

git clone https://github.com/TheYoctoJester/mender-community-images
cd mender-community-images

Board configurations live under yocto/<release>/{tagged,floating}/<TARGET>.yml:

  • tagged/ — every layer is pinned to a specific commit, for reproducible builds.
  • floating/ — layers track their branch tips; versions change as upstream advances.

The authoritative list of supported boards for a release is the contents of yocto/<release>/tagged/ and yocto/<release>/floating/.

NOTE on releases: wrynose (6.0) and scarthgap (5.0) are the maintained LTS tiers; kirkstone (4.0) is kept on demand only. wrynose currently ships floating configurations only — a tagged/ tier will be added once upstream cuts wrynose branches for meta-mender and meta-raspberrypi.

Building the image

From the repository root, point kas at your board’s configuration. For the primary target (wrynose, floating):

kas build yocto/wrynose/floating/<TARGET>.yml

TODO: replace <TARGET> with your board’s configuration name (for example raspberrypi4-64). For a reproducible build on a release that has a tagged/ tier (e.g. scarthgap), use yocto/scarthgap/tagged/<TARGET>.yml instead.

kas resolves the layers, sets the MACHINE and image target defined in the configuration, and runs the build. The default image target for community configurations is core-image-minimal unless the board’s configuration specifies otherwise.

Configure the Mender server (optional)

This step is not required for a successful build, but images built by default are only suitable for standalone deployments, because they carry no server configuration.

To connect the device to a Mender server, provide MENDER_SERVER_URL and MENDER_TENANT_TOKEN. With kas, add them through a local override configuration layered on top of the board configuration. Create my-server-config.yml in the repository root:

header:
  version: 14
local_conf_header:
  mender-server: |
    MENDER_SERVER_URL = "https://hosted.mender.io"
    MENDER_TENANT_TOKEN = "<your tenant token>"
    # Give each build a distinct, meaningful Artifact name:
    MENDER_ARTIFACT_NAME = "release-1"

Then append it to the build, colon-separated:

kas build yocto/wrynose/floating/<TARGET>.yml:my-server-config.yml

Obtain your tenant token from your Mender server’s organization settings. If you use a regional Hosted Mender instance, set MENDER_SERVER_URL accordingly — see Regions.

Alternatively, open a shell in the build environment and edit conf/local.conf directly:

kas shell yocto/wrynose/floating/<TARGET>.yml
# edit conf/local.conf, then e.g.: bitbake core-image-minimal

Using the build output

After a successful build, the images and build artifacts are placed in build/tmp/deploy/images/<MACHINE>/. TODO: update <MACHINE> and give the full path to the disk image and the Mender Artifact.

The disk image (suffix depends on the board’s partitioning and bootloader — e.g. .wic, .sdimg, .uefiimg) is used to provision device storage for devices that do not have Mender running yet. See the official documentation on provisioning a new device.

If Mender is already running on the device and you want to deploy a rootfs update from this build, use the Mender Artifact file (.mender suffix). Deploy it in managed mode through the Mender server (upload it under Releases in the server UI) or with the Mender client in standalone mode.

References

TODO: Add any relevant references, such as repository README files.

Known issues

  • Known issue #1
  • Known issue #2
  • …
3 Likes