Developing with Radxa ROCK CM3 + Radxa ROCK 3 Compute Module I/O Board

Taking the time to set up an effective development environment will make building operating systems and flashing Radxa ROCK CM3 modules a breeze. Using the Radxa ROCK 3 Compute Module I/O Board we go through the details of how to achieve it.

The project guides you through the basics of setting up and configuring a build environment for the ROCK CM3 System-on-Module (SoM) using the ROCK 3 Compute Module I/O Board and an Ubuntu Linux host.

We show how to set up and configure the host build environment with Radxa’s rbuild toolchain and build a CLI image based on Debian.

The OS is then flashed to the SD card and a test boot performed. Following that, we build the flashing tool for the on-board eMMC memory on the CM3 and use the OTG port on the carrier board to transfer the system.

Finally, we add Docker using the default installation.

ROCK CM3 SoM is based on the powerful Rockchip RK3566 System on Chip (SoC) with a Quad-core Arm® Cortex®-A55 64-bit, 2.0GHz CPU & Arm Mali™-G52-2EE GPU.

Modules are available with 2GB / 4GB RAM and in None / 16GB / 32GB eMMC flash storage variants.

Full details are in the Datasheet.

With simplified schematics: RM116Radxa-CM3_V1.31A_20221123.pdf

The ROCK 3 Compute Module I/O Board gives access to the full feature set of the CM3 SoM including USB, PCIe, SATA, audio, video, camera and display interfaces plus GPIO, RTC, wireless and high-speed Ethernet features.

Full details are here: Radxa-CM3-IO-Board-Product-Brief-v0.8.pdf

Along with simplified schematics: Radxa-CM3-IO-V1.3-SCH.pdf

• Difficulty: Medium
• Time: 4 Hr
• Steps: 11
• Credit: None

Parts Needed:

Step 1: Development Environment

The image below shows my development environment including the laptop host and monitor running Ubuntu 22.04.

The CM3 is press-fit mounted to the carrier board and powered with a 12V / 1A PSU. The power requirement depends on the types of peripherals attached to the board.

I also attached an OKdo 15” Portable Monitor and a USB keyboard to the I/O carrier board for TTY log in directly. There is also a USB-to-Serial cable attached to the GPIO header and a console Terminal running Minicom on the host to capture kernel boot messages.

This gives a comfortable environment for effective development.

Step 2: Linux Host

Various OS images are available from Radxa and 3rd Parties for the CM3, but not all of them boot successfully so we will build our own using the Radxa build tool, rbuild on a Linux host.

This is fairly easy to set up as it runs in a container. Currently only Ubuntu 22.04 is Officially supported but it is possible to configure a Virtual Machine on other OS’s. I recommend keeping it simple to reduce the system dependencies for a smooth experience.

Full details are available here: Radxa rbuild Tool

The build runs in a containerized environment with two options, Podman and Docker. I used Docker as this was already installed and running successfully on my host. I didn’t install docker.io as recommended as my default Docker installation worked successfully.

Here’s a snapshot of the Docker packages installed under Ubuntu 22.04 which you will need to install, if you don’t already have them:

Add your user to the docker group and reboot before moving on:

$ sudo adduser $USER docker
$ sudo reboot

Now test that docker runs successfully from your user without sudo:

$ docker run hello-world

Step 3: rbuild

To setup rbuild you just clone it from the Radxa repo to a suitable working directory on your host system:

$ mkdir cm3 && cd cm3
$ git clone --depth 1 https://github.com/radxa-repo/rbuild.git
$ cd rbuild
$ sudo chmod 0666 /dev/kvm

Now run rbuild with no arguments to test and see the help and command line options:

$ ./rbuild

If everything is successful you should see output like this displaying all the options:

Once you are at this stage you can build your first image.

This will take a few minutes depending on the speed of your host and internet download speed. Once the first build has completed, subsequent runs are much faster. Mine takes about 10 mins on a 16 core thread ripper.

Parameters for rbuild follow this pattern:

./rbuild [--options] <product> [suite] [flavour]

To build the Bullseye CLI image for the CM3 running in on the CM3 I/O Board as a compressed image, issue the following command:

$ ./rbuild --compress radxa-cm3-io bullseye cli

Tip: If you get the following message make sure to run the chmod command above and re-run rbuild

KVM detected but the permission is not optimal.
You might need to run `sudo chmod 0666 /dev/kvm` to have rbuild working.

, you will have the compressed OS image in your working directory along with the checksum file ready for flashing to either SD card or eMMC storage:

radxa-cm3-io_debian_bullseye_cli.img.xz

Step 4: SD Flash

Test the image by flashing it to a good quality 32GB SD card. I use SanDisk Ultra cards which are fast and reliable. balenaEtcher flashing software runs on Linux and does a reliable job with a validation check:

https://etcher.balena.io/

Once flashed, with the power supply removed, insert the SD card into the slot beneath the audio jack on the ROCK 3 I/O board, and you are nearly ready to boot.

Step 5: Minicom

minicom is a serial console application that allows you to see the kernel boot messages and gives access to console login. Install the package on Ubuntu with:

$ sudo apt install minicom

Create a config file in your home directory with the following filename .minicom.rock and contents:

$ vi .minirc.rock
pu port /dev/ttyUSB0
pu baudrate	1500000
pu bits 8
pu parity N
pu stopbits	1
pu rtscts No

Connect the USB-to-TTL cable to the GPIO header and the host's USB-A socket.

Tip: You must use a cable with a chip that’s capable of 1.5Mb rate. Not all cables can support this speed.

Open a Terminal and start minicom:

$ minicom rock

Step 6: Boot

Plug in the 12V power supply, and the CM3 module will start the boot sequence, which will be visible in the Serial Terminal. The Green LED on the CM3 module comes on. Once the boot is complete, the CM3 LED and the I/O board Green LED start flashing, and the Red power LED on the board will be on.

You can then login to the console:

username: rock
password: rock
hostname: radxa-cm3-io

Or via TTY if you have a monitor and keyboard attached. You can also login remotely via SSH if you have Ethernet:

$ ssh rock@radxa-cm3-io

Step 7: Poweroff

When you have finished working with the system, always power it down properly with the poweroff command before removing the power supply. This will prevent any corruption of the storage media:

$ sudo poweroff

Step 8: rkdeveloptool

CM3 modules with on-board flash storage need to be mounted as a Mass Storage Device (MSD) on the host so you can flash them. The CM3 I/O board has a dedicated On-the-Go (OTG) microUSB connector specially for this purpose.

Radxa provides rkdeveloptool for flashing eMMC media over USB from a host PC. Although there are instructions for doing this from a Mac or Windows PC, I always recommend flashing Linux from a Linux host. You are far less likely to have any issues if you do this.

On the Linux host, you have to build and install the software on your system. Documentation is found here: https://docs.radxa.com/en/compute-module/cm3/lowlevel-development/rkdeveloptool?host-os=debian

I used the following sequence to build rkdeveloptool successfully, including adding the patches:

$ sudo apt-get update
$ sudo apt-get install -y libudev-dev libusb-1.0-0-dev dh-autoreconf pkg-config libusb-1.0 build-essential git wget
$ git clone https://github.com/rockchip-linux/rkdeveloptool
$ cd rkdeveloptool
$ wget https://patch-diff.githubusercontent.com/raw/rockchip-linux/rkdeveloptool/pull/73.patch
$ wget https://patch-diff.githubusercontent.com/raw/rockchip-linux/rkdeveloptool/pull/85.patch
$ git am *.patch
$ autoreconf -i
$ ./configure
$ make -j $(nproc)
$ sudo cp rkdeveloptool /usr/local/sbin/

Check version is at least 1.32:

$ rkdeveloptool -v
rkdeveloptool ver 1.32

Step 9: Flash SPL

With rkdeveloptool installed successfully on the host, the next step is to flash the eMMC, where two stages are required. The first is to flash the Secondary Program Loader (SPL), which must be followed by flashing the OS image in the same Terminal session.

Download the SPL for the CM3 to the same location as your OS image: https://dl.radxa.com/rock3/images/loader/radxa-cm3-io/rk356x_spl_loader_ddr1056_v1.10.111.bin

Make sure the I/O board is powered off. Remove all connections, including the USB-to-TTL cable and SD card.

Connect the host PC with a USB-A to microUSB cable to the socket between the Audio jack and the USB hub.

Press and hold the tiny Maskrom button on the CM3 module whilst applying 12V power to the I/O board. None of the LEDs will be on at this stage, so there is no indication of feedback.

Open a Terminal on your host and change to your image directory, then check that the CM3 module has started in Maskrom mode and is visible as an MSD:

$ cd rbuild
$ rkdeveloptool ld
 DevNo=1	Vid=0x2207,Pid=0x350a,LocationID=303 Maskrom

Flash the SPL; these commands need to be executed as superuser!

$ sudo rkdeveloptool db rk356x_spl_loader_ddr1056_v1.10.111.bin

Step 10: Flash OS

Now flash the OS image. The image must be uncompressed and run from the same session as the SPL flash command. It takes a few minutes to complete (7 mins on my 32GB module). This command writes to offset 0, not device zero! The flash status is printed on the standard output, and when it completes, reset the device. The Green LED on the CM3 will turn on, and after a few seconds, the Green LED on the IO board will start to flash, indicating the system has started successfully.

$ unxz -k radxa-cm3-io_debian_bullseye_cli.img.xz
$ sudo rkdeveloptool wl 0 radxa-cm3-io_debian_bullseye_cli.img
$ sudo rkdeveloptool rd

Step 11: Docker

It’s very straightforward to install Docker on the system.

Disconnect the USB cable you used to flash the eMMC and connect up the USB-to-TTL cable again, and attach an Ethernet cable. This way, you can cut and paste the commands into the console session for a smooth installation. 

Open a Terminal and run minicom.

I followed the standard build instructions: https://docs.docker.com/engine/install/debian/

Setup Docker's apt repository.

$ sudo apt-get update
$ sudo apt-get install ca-certificates curl
$ sudo install -m 0755 -d /etc/apt/keyrings
$ sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
$ sudo chmod a+r /etc/apt/keyrings/docker.asc
$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
$ sudo apt-get update

Install the Docker packages.

$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Update system user: https://docs.docker.com/engine/install/linux-postinstall/

Add your user to the docker group and verify that you can run docker commands without sudo.

$ sudo usermod -aG docker $USER
$ newgrp docker
$ docker run hello-world

You will now have Docker available on your CM3 for further customization.

Summary

Due to the nature of ROCK CM3 SoM devices, it’s a complicated process to build and flash system images to onboard eMMC and boot these boards successfully.

Radxa has made the process relatively straightforward with their OS build tool, rbuild, which runs in a containerized environment so all the required toolchain components are self-contained and version-controlled.

They also provide an effective tool for flashing the onboard eMMC storage on the CM3 using the dedicated rkdeveloptool, which mounts the device as an MSD on the host system.

If you take the time to set up an Ubuntu host with all the required tools, it makes easy work of building Operating Systems for the CM3 module and flashing the onboard memory using the ROCK 3 Compute Module I/O Board.

The CM3 I/O Board gives you access to all the CM3’s peripherals to help you develop your own carrier boards, and the board is also laid out so you can build it into your own specialized system and customize it with thousands of Open Source software packages like Docker.