Build and customise Dataplicity OS

Build Dataplicity OS when you want to reproduce the CM5 quickstart image, change its package set, or use its Yocto integration as a worked example for your own product image. Bringing your own OS remains the normal product path; see Integrate your Linux image.

The build produces two different delivery artefacts:

• .wic.xz and .wic.bmap initialise a CM5 eMMC device;
• .raucb updates an already flashed A/B device.

The factory image creates the complete disk layout. The current .raucb is rootfs-only: it updates the inactive root filesystem but does not update the boot, kernel, or firmware partitions.

Ask Dataplicity support for access to the current reference build source. Signing keys are deliberately not included.

Build host requirements

A full kas/Yocto build normally needs:

• a Linux build host or kas container;
• approximately 100 GB of free disk;
• 16 GB or more RAM;
• git, python3, and pipx.

On a small workstation, use the repository's validation script instead of starting BitBake:

./scripts/validate.sh

It checks the reference layout, recipes, pinned components, and expected key files without downloading the Yocto layers.

Create development signing keys

RAUC cannot build a signed bundle until signing material exists. For a local development build:

KEEP_CA_KEY=1 ./scripts/gen-lab-keys.sh

This creates gitignored files under keys/lab/ and copies the public CA certificate into the image keyring location. These keys are for disposable development images. Before building a product image, read Build OS firmware and configure RAUC signing and replace them with your own trust material.

Run the build

Install kas and build both targets from kas.yml:

pipx install kas
kas build kas.yml

You can also use kas-container build kas.yml on a host where you do not want to install all Yocto build dependencies.

The reference configuration pins Poky Scarthgap, meta-openembedded, meta-raspberrypi, and meta-rauc revisions. Output appears under:

build/tmp-glibc/deploy/images/raspberrypi-cm5-io-board/
  dataplicity-os-image-raspberrypi-cm5-io-board.wic
  dataplicity-os-image-raspberrypi-cm5-io-board.wic.bmap
  *.raucb

dist/
  dataplicity-os-raspberrypi-cm5-io-board-VERSION.wic.xz
  dataplicity-os-raspberrypi-cm5-io-board-VERSION.wic.bmap

The raw .wic is an intermediate. Use the compressed .wic.xz for the first flash. Use the .raucb only after its signature and compatible value match the device and Device Class.

Changes required for a product

Do not ship the reference lab policy unchanged.

1. Set a product-specific RAUC compatible value in system.conf.
2. Generate and protect your own RAUC CA and signing key.
3. Bake only the public verification CA into every root filesystem slot.
4. Configure the matching public CA as the Dataplicity Device Class keyring.
5. Use the production profile: admin locked on boot, sshd disabled, and UFW denying inbound traffic with no port 22 rule.
6. Review every package and pinned source revision.
7. Record the exact board, bootloader, EEPROM, and partition-layout revision.
8. Pass the physical failed-boot rollback protocol before enabling managed updates.

The reference compatible is dataplicity-os-cm5. A fork should use an identifier owned by the product, such as acme-controller-cm5-v1. This prevents a valid bundle for one product from being accepted by another.

The two keyring locations serve different verifiers. The CA baked into the image lets RAUC verify a bundle on the device. The matching CA configured on the Device Class lets Dataplicity verify a bundle before offering it. Neither location contains a private signing key.

Lab, staging, and production builds

Three postures exist. Do not confuse a local lab build with a signed customer release.

Posture	How it is produced	DATAPLICITY_PRODUCTION_IMAGE	DATAPLICITY_STAGING_DEBUG_PROFILE	Access and tooling
Lab / local kas	kas build kas.yml or the public OS Build CM5 image workflow	0	0	May include debug-tweaks (empty root), socket-activated SSH for bring-up, and lab RAUC keys. Not a customer release.
Staging or prod release	Private Prelude release-dataplicity-os workflow	1	0	Drops debug-tweaks. Locks admin on boot, keeps sshd disabled, UFW denies inbound with no port 22 rule. Writes /etc/dataplicity/build-channel as production. Uses the staging or prod RAUC device CA and resigns bundles with the matching environment signer.
Staging debug profile	Same release workflow with the debug profile enabled	1	1	Staging only; blocked for prod. Enables password login (dataplicity for root and admin), SSH, UFW allow for TCP 22, diagnostic packages, and /etc/dataplicity/build-channel as debug. Faceplate labels the unit as a debug build.

Staging and prod releases differ mainly by target environment: API and M2M hosts come from device provisioning, and each environment has its own RAUC CA and signing secret. The secure access defaults are the same whenever the debug profile is off.

Optional kas overlays:

• kas/release.yml injects the immutable DATAPLICITY_OS_VERSION into release builds;
• kas/private.yml is for internal private overlays and must never carry production PEMs in the public tree.

Keep the staging debug profile out of manufacturing and customer fleets. Qualify Remote Shell and temporary local-console unlock as the production support path.

CSI camera boot overlays

Compute Modules do not auto-detect CSI cameras. Dataplicity OS sets explicit Raspberry Pi boot overlays through RPI_EXTRA_CONFIG in kas.yml (also editable under recipes-bsp/bootfiles). The lab default enables two HQ camera overlays:

camera_auto_detect=0
dtoverlay=imx477,cam0
dtoverlay=imx477,cam1

Camera	Overlay
HQ	imx477
Module 3 / NoIR	imx708
Module 2	imx219
Global Shutter	imx296
AI Camera	imx500

Change the overlays to match the fitted sensors and CSI ports before flashing a hardware SKU. Comment out unused dtoverlay lines rather than leaving mismatched sensors enabled. Camera overlays belong in the boot firmware configuration that the factory .wic writes; the current rootfs-only .raucb does not update boot partition contents.

Change the rest of the hardware configuration

For another machine:

1. start with the raspberrypi-cm5-io-board machine definition;
2. select the new kas machine;
3. update the RAUC slot devices and partition labels in system.conf;
4. update the Wic partition layout;
5. verify the bootloader's bounded-attempt and automatic-fallback behaviour;
6. qualify the exact physical board and image revision.

A different ARM board, x86 appliance, or custom SoC should normally use the bring-your-own Linux contract rather than forcing the CM5 boot design. See Integrate your Linux image.

Keep the image current

Yocto images are frozen at build time. To deliver a kernel, OpenSSL, systemd, Dataplicity agent, Lens, or application fix:

1. update and review the relevant pinned layer or recipe;
2. rebuild the image and signed .raucb;
3. test it on the exact hardware;
4. stage a Dataplicity OS Image rollout.

Dataplicity OS does not depend on an apt or opkg security-update feed. The maintainer of a product image owns its pin updates, validation, signing, and release cadence. Dataplicity can help with the integration and fleet rollout.