Building ROCK OS Images with Radxa's build system

Build the latest Linux operating system (OS) images and customise your kernel with Radxa’s new build system.

If you need to incorporate your own software or system overlays and tweaks into a custom image for your ROCK board the Radxa build tools can ease the way.

In this project we cover rbuild - the image building tool and bsp which helps you build the latest supported kernels.

It’s assumed you know some common Linux commands and the basics of using Git source code management but the rest will be explained in detail.

Difficulty: Medium

Time: 2 Hr

Steps: 8

Credit: None

Licence: None

Parts Needed:

Step 1: Linux Dev Host

Unless you have a lot of time on your hands, you will need a fairly powerful Linux host with plenty of RAM and a large SSD running Debian 12 (Bookworm) or Ubuntu 22.04 (Jammy).

It may be possible to use a VM on another platform but this is not officially supported.

The build system uses Docker so you will need a working version of Docker Engine installed to build the kernel and Operating System (OS) images.

The host system used to test this project is a Dell XPS laptop with 12 CPU cores / 32GB RAM / 2TB SSD running Ubuntu 22.04 (Jammy). It can build the Linux kernel in about 5 mins on a good day.

Install Docker Engine using the installation instructions for your host OS: https://docs.docker.com/engine/install/

Now test that you can run Docker as your unprivileged user:

$ docker run hello-world

We also need Minicom to connect with the target boards serial console, so install it now:

$ sudo apt install minicom

Step 2: Target Board

rbuild can build Linux OS images for any of the ROCK boards. In this project we are building an image for the ROCK 3A which is our target board.

Tip: Substitute the board of your choice here - the process is the same

To build a basic CLI image (which is recommended as a first build) you will need a USB-to-Serial adapter cable connected to the serial pins on the ROCK and the USB connector on your host. This will allow you to attach your host to the ROCK and observe the boot process in a serial terminal, helping you to debug any issues. You will also be able to login if the board boots successfully.

The baud rate for ROCK boards serial console is 1.5Mbps - not all adapters can handle that speed.

Tip: Some ROCK boards (ROCK 4C+) have a max tolerance of 3.14V on the TX/RX pins - the USB-to-Serial cable recommended above is safe to use with any of the ROCK boards.

Connect a good quality QC power supply to the USB-C port. Whilst there are many low cost power supplies available, they can lead to strange and difficult to diagnose boot issues due to voltage fluctuations. So save yourself some grief and get a good one with a suitable quality cable.

We also connect an optional Ethernet cable which will allow you to install extra packages directly to the target if required.

Step 3: Serial Terminal

Minicom works well with the ROCK boards for interacting with the serial console. Writing a configuration script saves time and makes sure your settings are correct.

Enter the following into a file named .minirc.rock in your home directory on your host, using your favourite editor. Change the port setting if your ROCK board enumerates on a different port when its connected:

pu port 	/dev/ttyUSB0
pu baudrate	1500000
pu bits	8
pu parity	N
pu stopbits	1
pu rtscts	No

Now you can start Minicom with the following command from a terminal on the host:

minicom rock

Use CTRL+A to open the menu and then X to exit.

Step 4: Rbuild

rbuild is the image builder tool provided by Radxa who are the manufacturer of ROCK boards. It can build the standard images or be used to integrate different kernel and u-boot versions.

I recommend setting up a separate build working directory for each board on your host. Here we are building for the ROCK 3A so create a working directory of that name and clone rbuild from: https://github.com/radxa-repo/rbuild

$ mkdir rock-3a && cd rock-3a
$ git clone https://github.com/radxa-repo/rbuild.git

Now change into the directory and run rbuild with no arguments. This will display all the options and supported boards available.

$ cd rbuild
$ ./rbuild

Rbuild has the following syntax:

rbuild <board> [distro] [flavour]

Where the name of the board, the distro and the flavour are copied from the rebuild output above. So to build a Debian Bullseye CLI image for the ROCK 3A use:

$ sudo chmod 0666 /dev/kvm
$ ./rbuild rock-3a bullseye cli

The first time you run a new build the docker image will download before the kernel build process starts up.

Once the kernel has been built, the distro packages need to be pulled in and the system image built. The process will utilise most of the resources available on the machine. This is time to take a coffee break or go and do something completely different for a while, depending on how fast your build system is.

The next time you run the build it will be much quicker. My system takes about 5 mins which is acceptable.

Step 5: Booting

Currently the ROCK 3A build is set to kernel 5.10. If all went well you will have an image file suitable for flashing to SD or eMMC media and a SHA sum of the image, dumped in the build directory.

Flash the image rock-3a_debian_bullsey_cli.img to your media using balenaEtcher.

Before removing the media, open /dev/sda1 which is mounted as the config directory. In there you will see two files, before.txt and config.txt.

Open before.txt and comment out the line that disables ssh (so you will be able to login over ssh) and set the locale line to your preferred locale. For me it’s en_GB:

#   disable_service <systemd unit name>
#disable_service ssh
disable_service smbd
disable_service nmbd
…
#   update_locale <locale>
update_locale en_GB.UTF-8

Tip: make a copy of before.txt and save it on your host as it is deleted on first boot.

config.txt can be used to run commands on every boot, for this example we are leaving it blank.

Now unmount the media and put it into the ROCK board then open a terminal on your host and start minicom:

$ minicom rock

Connect the power supply to the ROCK and the boot sequence will start, which you can observe in the console.

The green power LED should turn on and after a few seconds the blue heartbeat LED will flash to show the OS is running. If all goes well you will be presented with the login prompt.

Login with the default user radxa and password radxa.

The kernel version is displayed and you are given a command line prompt as the radxa user. Have a look round and then power down safely with:

$ sudo poweroff

Congratulations you have just successfully built your first ROCK Linux operating system!

Step 6: Other Builds

If you want to try out the desktop versions just run rbuild again with the relevant parameters.

Try this to get a Debian image with a lovely Plasma KDE desktop:

$ ./rbuild rock-3a bullseye kde

This might take a bit longer to build as there are a lot more packages and configuration steps in the build pipeline, but it’s well worth the wait. Obviously, you will need to attach a keyboard, mouse and HDMI monitor to appreciate your handiwork.

Step 7: BSP

As well as building the standard images, Radxa also provides a Board Support Package tool bsp to build newer Linux kernel versions, depending on the board model.

Clone the bsp repo from https://github.com/radxa-repo/bsp into the same parent directory as rbuild above and update the submodules:

$ cd rock-3a
$ git clone https://github.com/radxa-repo/bsp.git
$ cd bsp
$ git submodule init
$ git submodule update

Now run bsp without any parameters to test and see the options:

$ ./bsp

This will output all the various options and parameters that can be used with bsp and also the supported linux editions. These can be investigated by opening the relevant fork.conf file in the bsp/linux/<edition> directory.

So for the latest kernel version we can see that the ROCK 3A is supported:

$ cat linux/latest/fork.conf

Let’s build the latest kernel:

$ ./bsp linux latest

Once the build completes you will end up with a whole load of .deb package files in the build directory. You will need these kernel packages and the matching header packages for the next step.

Step 8: Custom OS

Now that we have built a new kernel it can be integrated into an OS image using rbuild with the -c switch. This tells rbuild to use the supplied kernel / header packages when it builds the image. It has the following syntax:

rbuild -c <your-kernel> <board> [distro] [flavour]

So to build a Debian CLI image with the latest kernel we use the following commands. The bsp directory must be at the same level as the rbuild directory in the file system for the -c option to work:

$ cd ../rbuild
$ sudo chmod 0666 /dev/kvm
$ ./rbuild -c latest rock-3a bullseye cli

This will output the image file rock-3a_debian_bullseye_cli.img which you can flash to your media then boot the board:

Summary

If you want to produce custom images for your ROCK board containing your own packaged software or overlays and tweaks, you need to be able to build your own system images and sometimes configure the kernel.

Radxa supports both of these cases with the rbuild tool for building OS images and the bsp tool for building kernels.

This project shows how to use both of these open source projects to build the latest OS image for the ROCK 3A but the same process can be used to build images for any of the ROCK boards.

References:

Docker docs: https://docs.docker.com

Radxa docs: https://radxa-doc.github.io/software/build.html