ClusterCTRL: How to write an image to the eMMC?

To write an image to the eMMC on a Compute Module you need to boot it as a USB Device using the MSD (Mass Storage Device) files provided with the rpiboot tool.

In the following steps you will need to replace X with the Pi node number (X=1 for p1, X=5 for p5, etc).


When using ClusterCTRL with Compute Modules "clusterctrl status" will show the status for both Power "pX:S" (X=Node number, S=Status 0=on/1=off) and USBBOOT "uX:S" (X=Node number, S=Status on/off).

uX:0 Try to boot from the onboard eMMC and fallback to booting as a USB device.
uX:1 Boot as a USB device.

You will also see a "ctrl_bus:" line, this shows the details for all ClusterCTRL device found (space separate if you have multiple ClusterCTRL devices).

For each ClusterCTRL device you will see 3 numbers, for example.


The first number above "20" shows the ORDER, this is used if you have multiple ClusterCTRL devices on the same controller (lower numbers have a higher priority). A ClusterHAT always has highest priority so if present will be used for p1-p4. It will then assign the next pX.. numbers to the ClusterCTRL device with the lowest ORDER, then the next lowest etc (you may need this ORDER value to save the state below).

The second number "3" is the I2C bus (/dev/i2c-3 for example) used to communicate with the ClusterCTRL device.

The last number "3" is the maximum number of nodes this device supports.


First power off the node with "clusterctrl off pX" then check the USBBOOT setting with "clusterctrl status".

If you see "uX:1" you don't need to make any changes to write the image.
If you see "uX:0" run "clusterctrl usbboot on pX" to enable USBBOOT.

If you've moved the USB Cable since powering on the controller you will need to re-run "sudo clusterctrl init" to reconfigure the symlinks for USBBOOT.

Setup Mass Storage Device boot files

Make sure the boot directory for pX is empty (this will remove all files for the pX filesystem, ensure you have a backup of any data first).

sudo rm -rf /var/lib/clusterctrl/nfs/pX/{*,.*}

The error "unable to remove  directories . and .." error is expected and can be ignored.

Then create the boot directory and copy over the files required to boot as a MSD.

sudo mkdir /var/lib/clusterctrl/nfs/pX/boot/
sudo cp -r /usr/share/rpiboot/msd/ /var/lib/clusterctrl/nfs/pX/boot/

Power on the Compute Module

clusterctrl on pX

You can watch the Compute Module booting as a USB device by tailing the log (CTRL-c to exit).

tail -f /var/log/kern.log /var/log/daemon.log

In a few seconds you should see a new MSD /dev/sdY - please remember if you have other storage devices on your Pi this may not always be the same device (/dev/sda for example).

You can now use "dd" as normal to write an image to this device, in the example below I'm going to call the device /dev/sdY you will need to replace sdY with the device shown in the logs above. Remember getting this wrong may overwrite another storage device or just create a file on the root filesystem!

sudo dd if=ClusterCTRL-2019-07-10-lite-1-p4.img of=/dev/sdY bs=4M status=progress

Set username and password / reconfigure node number / enable SSH

Recent Raspberry Pi OS require a username and password to be set, they no longer have the default "pi" user. You may also need to change the pX number of the node (for example to change a p4 image to p5). Or enable SSH which is also disabled by default on current Raspberry Pi OS.

Reread the partition table (replace sdY with the real device).

sudo partprobe /dev/sdY

Mount the boot filesystem (replace sdY with the real device).

sudo mount /dev/sdY1 /mnt/

To set a username and password (required)

set +o history # Turn off bash history temporarily
# Replace myusername and mypassword with your details.
echo "myusername:"$(echo 'mypassword' | openssl passwd -6 -stdin) | sudo tee /mnt/userconf.txt
set -o history # Turn history back on again

To change the pX node number edit cmdline.txt changing the end of the "init=" part to the desired pX at the end of the line.

sudo nano /mnt/cmdline.txt

Ensure cmdline.txt is a single line.

To enable SSH

sudo touch /mnt/ssh

Unmount the boot filesystem.

sudo umount /mnt

Clean up

Force all blocks to be written.

sudo sync

Power off the node and disable USBBOOT

clusterctrl off pX
clusterctrl usbboot off pX

Save power on state (optional)

If you want the node to always boot from eMMC you will need to save the state (replacing ORDER with the order number shown in the "clusterctrl status" output above).

clusterctrl save ORDER

This command saves both power and USBBOOT states for use on next power up

You can now power on the node and it will boot from the eMMC.

clusterctrl on pX

Within a few seconds you should see it boot up (the first boot will be slower as it reconfigures and resizes the filesystem).

tail -f /var/log/kern.log /var/log/daemon.log

You can now accesses the node as normal "ping pX.local", "ssh pi@pX.local", if you haven't enabled SSH you can access it using the serial console "screen /dev/ttypiX" (CTRL-x then 'k' to exit).

You can comment on this FAQ