Revolution Pi (Connect 5, Connect 4, Flat S)

This article refers to Platform v3.3.0. The current Platform version is v3.3.0.

Beta

This platform is newly supported and the integration is currently in Beta. You can follow this guide from start to finish, but you may come across minor issues. If you do, contact our support team and we will resolve them as soon as possible.

Overview

This guide details the installation process for KUNBUS Revolution Pi devices. These are DIN-rail industrial controllers built around Raspberry Pi Compute Modules, with PiBridge connectors for KUNBUS I/O expansion modules.

Revolution Pi devices have no SD card slot: Barbara OS is written directly to the internal eMMC, which the device exposes as a USB mass-storage device through Raspberry Pi's rpiboot utility.

Supported models

Model	Compute Module	eMMC required	I/O expansion
RevPi Connect 5	CM5 (BCM2712)	32 GB	PiBridge, up to 10 modules
RevPi Connect 4	CM4 (BCM2711)	32 GB	PiBridge, up to 10 modules
RevPi Flat S	CM4S (BCM2711)	32 GB	none

A single Barbara OS image serves the whole family, though the boards identify themselves in two different ways. The Connect 5 and Connect 4 carry a HAT EEPROM on the carrier board: the firmware reads the model over I²C at boot and composes the matching device tree automatically. The Flat S has no HAT EEPROM, so the image selects its overlay through a model-conditional section of config.txt, keyed on the Compute Module the firmware detects. The firmware evaluates only the section matching the module it finds, so you do not need a different image per model or per variant.

32 GB eMMC is a hard requirement

The Barbara OS partition layout needs 16.3 GB of eMMC. Variants shipping 8 GB of eMMC — such as the 2 GB-RAM RevPi Connect 4 SKUs (article numbers 100376 and 100377) — cannot be used.

The original RevPi Flat (without the "S") is also not supported: it is based on the Compute Module 3+ and ships 8 GB of eMMC. Only the Flat S (CM4S, 32 GB) is.

What you need

• The Revolution Pi device and a 24 V DC power supply (10.8 … 28.8 V DC).
• A USB cable to the device's flashing port:
  • USB-C for the RevPi Connect 5,
  • micro-USB for the RevPi Connect 4 and Flat S.
• A Linux host to run rpiboot and write the image.
• The Barbara OS image for Revolution Pi, downloaded from the OS Images view in Barbara Panel (see OS Images view).

Barbara Supported Hardware

See the Supported Hardware section for the full list of compatible devices.

Connect the power supply (X4)

Power reaches the device through the X4 screw terminal. The poles are silk-screened on the housing next to the connector — read the labels rather than counting pin positions, because the pinout differs between Revolution Pi generations.

On a RevPi Connect 5, X4 is labeled as follows:

Pin	Label	Connect
1	24V	+24 V DC (positive)
2	0V	0 V (return)
3	NC	leave unconnected
4	NC	leave unconnected

Follow this order:

1. De-energize the power supply.
2. Wire 24V and 0V according to the labels on your unit.
3. Check the polarity before switching anything on.
4. Switch on the power supply.

Electrical requirements

Keep every connection referred to the same system ground and never exceed 28.8 V DC. Per the manufacturer's UL note, the device may only be supplied from circuits complying with Class 2 or SELV (UL 61010-1). Never feed voltage into a pole marked NC.

The USB port is data only — it does not power the device — so X4 must be wired before flashing.

Prepare the host

Barbara OS is written to the eMMC while the device runs Raspberry Pi's rpiboot mass-storage gadget. Build it once on your Linux host:

sudo apt install git libusb-1.0-0-dev pkg-config build-essential
git clone --depth=1 https://github.com/raspberrypi/usbboot
cd usbboot && make

Put the device into flashing mode

The order of these steps matters — rpiboot must already be waiting on the host when the device receives power.

1. If the hardware watchdog is armed, disable it so it cannot fire mid-write.

2. Shut the device down and disconnect it from the power supply.

3. Connect the USB cable between the host and the device's flashing port (USB-C on Connect 5, micro-USB on Connect 4 and Flat S).

4. On the host, start the mass-storage gadget:

   sudo ./rpiboot -d mass-storage-gadget

5. Reconnect the power supply. rpiboot detects the device, uploads the gadget, and the internal eMMC appears on the host as a removable block device.

The cable is the mode switch

There is no jumper and no button to press on a Revolution Pi. As long as the USB cable is connected, the device stays in bootloader mode and cannot boot normally — the carrier board asserts nRPIBOOT whenever that port is in use. Cable connected means flashing mode; cable removed means normal boot.

Identify the new device before writing anything:

lsblk

The eMMC appears as a ~32 GB disk (for example /dev/sdb). Confirm the size and make sure it is not one of your own disks.

Write the image

The file you downloaded from Panel is a compressed disk image named revpi-<environment>-<version>-<build>.wic.bz2, for example revpi-pro-4.7.2-1785428437.wic.bz2.

Write it with Etcher. The eMMC behaves like a removable disk here, so the procedure is the usual one: select the compressed image, choose the ~32 GB target disk, and flash. Etcher reads the compressed file directly, so you do not need to decompress it first, and it verifies the write when it finishes.

warning

Check which disk you selected before you start. Etcher lists every removable disk, and the eMMC appears alongside your own drives.

On Linux you can write it from the command line instead:

bunzip2 -c revpi-<environment>-<version>-<build>.wic.bz2 | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync

First boot

1. Wait for the write to complete and flush.
2. Disconnect the USB cable. While it is connected the device will not boot.
3. Power-cycle the device.

On the first boot Barbara OS prepares its storage and claims the rest of the eMMC, so this boot takes a little longer than the ones after it.

The node requests an address over DHCP on eth0 and connects to the platform on its own.

Retrieve the Barbara ID

To register the node in Barbara Panel you need its Barbara ID, the unique hexadecimal string that identifies it, of the form revpi-<hex>. A Revolution Pi is a headless DIN-rail controller with no monitor attached, so there are two practical ways to read it: over the network from the agent's API, or from a USB drive.

From the agent API

Until the node is registered, the agent exposes a small HTTP API on TCP port 18100 that returns the Barbara ID as JSON. The node takes its address over DHCP, so look that address up in your DHCP server or router first:

curl -s http://<node-ip>:18100/device/barbaraId
# {"barbaraId":"revpi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

# just the value:
curl -s http://<node-ip>:18100/device/barbaraId | jq -r .barbaraId

GET /healthz reports whether the API is up ({"status":"ok","apiRunning":true,...}), and the agent serves GET /device/getConfig and GET /network/connectivityCheck on the same port.

Availability and access

• This API is available only until the node is registered in Panel. Once you register it, the API shuts down and the port closes, so query it during onboarding.
• It is unauthenticated. Query it from a trusted network and do not expose port 18100 beyond your operator workstation.

From a USB drive

If you cannot reach the node over the network, the Barbara USB Assistant Tool writes the node's information onto a USB flash drive:

1. Prepare a USB flash drive formatted as FAT32.
2. Plug it into one of the node's USB-A ports. Keep the flashing cable disconnected, or the device stays in bootloader mode instead of booting.
3. Wait a few seconds while the agent detects the drive and writes the data.
4. Move the drive to your computer and open the barbara folder at its root.
5. Open barbaraInfo.txt. The Barbara ID is on lines 4 and 5:

barbaraInfo.txt

Timestamp:
    334673

Barbara ID:
    revpi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The same file also reports the Barbara OS version, the node's network interfaces with their addresses, and its connectivity status, which is useful if the node does not appear in Panel later.

Want to learn more?

The drive can carry commands as well as collect data. The full reference is in USB Assistant Tool.

Register and verify the node

Register the node with the Barbara ID you just read, following Add a node to Panel. Once it is registered, the node reports itself as online in Barbara Panel and shows the version of Barbara OS it is running. That is the confirmation you need: it means the image booted, prepared its storage, and reached the platform.

If the node never comes online, see Troubleshooting.

I/O expansion modules

The piControl driver and the extension-module firmware are installed and loaded automatically, so the base device's own process image is available as soon as the node boots.

Nested PiBridge modules

piControl reads the layout of nested I/O modules from /etc/revpi/config.rsc. On Barbara OS that path is managed configuration and persists across updates. Until a configuration is supplied, only the base device's process image is exposed.

Applications running in containers reach the I/O through the /dev/piControl0 device node. See Access host devices from a container.

Troubleshooting

The eMMC never appears on the host. rpiboot must be started before the device is powered. Repeat the sequence: power off, cable in, start rpiboot, then power on. Check you used -d mass-storage-gadget — the legacy msd gadget does not drive CM4/CM5.

The device does not boot after flashing. Check that the USB cable is disconnected; while it is present the device stays in bootloader mode by design.

Wi-Fi or Bluetooth do not come up. Confirm the variant actually includes the radio module — the Revolution Pi catalog offers otherwise identical article numbers with and without WLAN/BT.

A serial port is missing. RS485 and CAN are variant-dependent options. Check your unit's article number against the manufacturer's variant table before assuming a port should exist.

Summary

You wired the X4 terminal, put the device into rpiboot flashing mode, wrote Barbara OS to the internal eMMC, read the Barbara ID from a USB drive, and registered the node in Barbara Panel, where it now reports itself as online.

A single image covers the whole Revolution Pi family, and the piControl driver exposes the industrial I/O to your containers, so the DIN-rail hardware you deploy in the field is managed from Barbara Panel alongside every other node.

The node is ready to run workloads. To deploy your first one, see Install your first application.