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 currently built for a CM5 with onboard eMMC on the official CM5 IO board. Ask Dataplicity support for the current image and checksum. If you need a different board or want to own the image build, use Build and customise Dataplicity OS.

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 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 image:
sh
sudo bmaptool copy \
  dataplicity-os-image-raspberrypi-cm5-io-board.wic \
  /dev/diskN

If bmaptool is unavailable:

sh
sudo dd \
  if=dataplicity-os-image-raspberrypi-cm5-io-board.wic \
  of=/dev/diskN \
  bs=4M status=progress conv=fsync

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, admin, and SSH 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 #

In the Dataplicity app:

  1. select Add device;
  2. choose the Device Class when prompted;
  3. copy the complete account-specific install command;
  4. run that command unchanged from the local console.

The installer recognises the on-image agent layout, records a unique identity under /var/lib/dataplicity, and starts the configured agent services. Do not put the generated command or its provisioning key 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 manufacturing line, run the same 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. Connect with SSH #

The current reference build is intended for integration and lab use. It enables socket-activated SSH and allows TCP port 22 through UFW, but does not ship your public key.

From the local console, install your key:

sh
install -d -m 700 -o admin -g users /var/lib/dataplicity/ssh
install -m 600 /dev/stdin /var/lib/dataplicity/ssh/authorized_keys <<'EOF'
ssh-ed25519 AAAA... your-name@workstation
EOF
chown admin:users /var/lib/dataplicity/ssh/authorized_keys

Confirm the listener and firewall:

sh
systemctl enable --now sshd.socket
ufw status verbose

Then connect from your workstation:

sh
ssh admin@DEVICE_IP

The authorised-keys file and /home/admin live on dpdata, so they survive RAUC A/B slot changes. Dataplicity Remote Shell remains the preferred support path because it needs no inbound port or customer-network firewall rule.

Before shipping a production product, remove debug-tweaks, choose your own login and sudo policy, and decide deliberately whether inbound SSH belongs in the product threat model.

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;
  • optional SSH works with your key and no password login is required.

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