Documentation

Appearance

Use Dataplicity OS on Compute Module 5 #

This guide starts with an unprovisioned Raspberry Pi Compute Module 5 and ends with the device online in your Dataplicity organisation.

Dataplicity OS is a CM5 quickstart, not the required OS for Dataplicity products. It is currently built for a CM5 with onboard eMMC on the official CM5 IO board. Select that platform from the official Dataplicity OS factory image catalog. If you need a different board or want to own the image build, use Integrate your Linux image or Choose a Dataplicity OS image.

Match CSI camera boot overlays to the fitted sensors before manufacturing; see Build and customise Dataplicity OS. Flash a production-profile image for customer units, not the staging debug channel.

What you need #

  • a CM5 with eMMC and the official CM5 IO board;
  • Ethernet with DHCP, DNS, outbound HTTPS, and working time synchronisation;
  • a host with Raspberry Pi usbboot/rpiboot;
  • bmaptool (preferred) or dd;
  • the Dataplicity OS .wic.xz image and, when supplied, its .wic.bmap;
  • a Dataplicity account with permission to add a device.

Optional NVMe storage is for application data such as camera footage. The reference image boots from eMMC and keeps its RAUC slots and /var/lib/dataplicity there.

1. Flash the eMMC #

  1. Fit the CM5 to the IO board.
  2. Set the board to eMMC-disable or rpiboot mode using the IO-board jumper.
  3. Connect the IO board's USB device port to the host and run rpiboot.
  4. Identify the new block device carefully. The next command overwrites it.
  5. Write the compressed image directly:
sh
sudo bmaptool copy \
  dataplicity-os-rpi-cm5-VERSION.wic.xz \
  /dev/diskN

Raspberry Pi Imager can also write the .wic.xz directly. Do not pass the compressed file to dd.

Replace /dev/diskN with the CM5 eMMC device. Remove the boot jumper before powering the board again.

2. Complete first boot #

Connect HDMI or serial console and Ethernet, then power on the board. The first boot:

  1. expands the dpdata partition where possible;
  2. mounts it at /var/lib/dataplicity;
  3. prepares persistent agent and admin state;
  4. creates the agent virtual environment from the wheelhouse already in the image;
  5. starts the Dataplicity services.

The image includes the agent software, but it does not contain credentials for your Dataplicity organisation. Provisioning is a separate step.

Check the local image:

sh
rauc status
dataplicity rauc-ready
systemctl status dataplicity-rescue dataplicity-supervisor

An OTA-related gap is expected before the device belongs to a Device Class with an OS image configured.

3. Provision the Dataplicity agent #

An official factory image download is prepared for the selected organisation and Device Class. On first boot, the device provisions a new identity and then removes the temporary boot provisioning material.

In the Dataplicity app:

  1. select Add device;
  2. choose the Device Class and its CM5 factory image;
  3. prepare and download the image;
  4. flash and boot each physical device independently.

The first-boot provisioner recognises the on-image agent layout, records a unique identity under /var/lib/dataplicity, and starts the configured agent services. Do not put downloaded provisioning material in a public image, repository, or support ticket.

Wait for the device to appear online in the inventory. Open its Remote Shell to prove the normal production support path.

For a custom or unpersonalised image, run the organisation-scoped installer during a controlled first-boot or commissioning stage. Run it independently on each physical device; do not clone an already provisioned data partition. See Installing for mass production.

4. Verify the access policy #

Use Dataplicity Remote Shell for normal production support. Production images lock admin on every boot, keep sshd disabled, and enable UFW with no inbound port 22 rule.

When physical access is required, an authorised operator can temporarily unlock admin for the attached console. The unlock ends at reboot and does not enable SSH or change the firewall. See Dataplicity OS local console and remote access.

5. Verify the finished device #

You are done when:

  • the device appears online in the correct Dataplicity organisation and Device Class;
  • Remote Shell opens and has the intended Linux permissions;
  • dataplicity rauc-ready reports the expected A/B layout;
  • the identity remains unchanged after a reboot;
  • the production console, SSH, and firewall policy matches the product.

Next, build and sign your own RAUC firmware or prepare a managed image rollout.