Documentation

Appearance

Build and customise Dataplicity OS #

Build Dataplicity OS when you want to reproduce the reference image, change its package set, or use its Yocto integration as the starting point for your own product.

The build produces two different delivery artefacts:

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

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:

sh
./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:

sh
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:

sh
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:

text
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

Use the .wic 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 keyring on the Dataplicity Device Class.
  5. Remove debug-tweaks and define production login, sudo, SSH, and firewall policy.
  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.

Change the hardware configuration #

Compute Modules do not auto-detect CSI cameras. The reference configuration sets explicit camera overlays. Change RPI_EXTRA_CONFIG to match the fitted hardware, for example imx477, imx708, imx219, imx296, or imx500.

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 can use the same Dataplicity contract without copying 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.