Introduction

Everything big starts small, and this is the first page of our documentation.

Getting Started

Please click on the link below your device to start initial setup.

</br>ROCK 3A

Getting Started with ROCK 3A

This guide is designed for ROCK 3A enthusiast. The purpose is to learn about ROCK 3A as well as how to prepare and set up for basic use. When you get a board, you need to know what model it is and which hardware version it is. The information is printed in the top side of the board. We will introduce the board information as much as possible.

What you need

Necessary

• ROCK 3A main board

• One of the Storage media below:

  • microSD, larger than 8GB
  • eMMC module, larger than 8GB

• Power supply

  • The ROCK 3 is powered by Type-C port and has a wide range of input voltage, from 9V to 21V. ROCK 3 supports USB Type-C PD 2.0 with 9V/2A, 12V/2A, 15V/2A and 20V/2A. Besides, the Pi supports QC 3.0/2.0 with 9V/2A and 12V/1.5A.
  • The Type-C cable you using needs to support data communication. We call it USB Type-C charging data cable.

• USB Keyboard and Mouse

  • With four USB-A connectors, ROCK 3 can be equipped with a full sized keyboard and mouse.

• Monitor and HDMI Cable

  • ROCK 3 is equipped with a full sized HDMI connector. HDMI capable monitor is recommended.
  • HDMI EDID display data is used to determine the best display resolution. On monitors and TVs that support 1080p (or 4K) this resolution will be selected. If 1080p is not supported the next available resolution reported by EDID will be used. This selected mode will work with MOST but not all monitors/TVs.

• USB to TTL serial cable

  • ROCK 3 exports a dedicated serial console for CPU, which can access the low level debug message.

• USB Male A to Male A cable

  • If you want write image on ROCK 3 from USB OTG port or use fastboot/adb commands you need an USB Male A to Male A cable to connect ROCK 3 and PC.

Optional

• microSD Card Reader

  • For flashing the image into microSD Card

• USB type A to type A cable

  • This is needed for fastboot/adb commands.

• USB to TTL serial cable

• This is needed for serial console.

• Ethernet cable

• ROCK 3 supports Internet access via WIFI or Ethernet.

• An Ethernet cable is used to connect your ROCK 3 to a local network and the Internet.

• Camera Module

  • ROCK 3 supports camera function.

• LCD Module

  • ROCK 3 supports LCD display function.

• Audio cable

  • Audio can be played through speaker or headphones using a standard 3.5mm jack.

• WiFi/BT Cards

Starting the board for the first time

ROCK 3A can be started with eMMC Module or μSD Card. Now, you are presented with three options when installing your new operating system onto your ROCK 3A.

Prepare

• When starting system with eMMC Module
  (Option a) Insert the eMMC Module into ROCK Pi eMMC USB Reader. Then plug the ROCK Pi eMMC USB Reader into host PC.
  (Option b) Insert eMMC Module into eMMC to μSD card converter board. Insert the converter board into μSD Card Reader. Then plug the Card Reader into host PC.

• When starting system with μSD Card (Option c) Insert the μSD Card into μSD Card Reader. Then plug the Card Reader into host PC.

Image flash tool

• Download the flash tool, etcher, from downloads. Choose the right version for your host operation system. Here we operate on host Ubuntu 16.04.

• Do update your etcher to latest edition according to etcher's instruction after you launch it. Otherwise, your pc might malfunction during flashing.

Network setup

Ethernet

ROCK 3A is equipped with one 1G Ethernet port. You can use a network cable (one end connected to the external network port or route) to connect your ROCK 3 to the network. The ROCK 3 will automatically configure the network for your surfing on the Internet.

To test the Ethernet, we need to follow the steps:

• Switch to super user mode by command $ sudo su

• Check whether the Ethernet is normal by command, ifconfig, which would show us a network card, eth0, and the Ethernet IP address. Also, use tool, ping, to connect to a normal domain.

 $ ifconfig
 $ ping www.baidu.com

• If failed to connect to a normal domain. , try $ sudo dhclient eth0

WIFI

ROCK 3 Model A doesn't come with on board WiFi/BT. Currently the following WiFi Cards are tested and supported by the ROCK 3 Model A.

• More Intel WiFi cards are supported in theory as long as the kernel versions requirements < 4.19 for vendor kernel. The WiFi firmware should be put under '''/lib/firmware''' manually. Check Intel website for the WiFi card model and download fw.
• Check whether your sbc support WIFI either through Hardware or command line. Rock 3A doesn't have wifi module.

To test the WIFI performance, we need to follow the steps:

• Switch to super user mode $ sudo su

• Open the WIFI $ nmcli r wifi on

• Scan WIFI $ nmcli dev wifi

• Connect to WIFI network $ nmcli dev wifi connect "wifi_name" password "wifi_password"

• Test WIFI perpormance by tool iperf3.

Now you can check your Network state

*Look at network configure: $ sudo ifconfig

*Test network: $ping -c 5 www.google.com

Image download guide

• Download the official Ubuntu/Debian system image from downloads

Install System to microSD

• After unpacking the system image package, we run the tool by executing the command

./etcher-etcher-electron-1.4.5-x86_64.AppImage

If you get an error message: "No polkit authentication agent found" you can try and start it with sudo, but do know that this is running the tool as '''root'''.

• In the etcher window, click '''Select image'''.

• In the etcher window, click '''Select Drive'''.

• In the etcher window, click '''Flash'''.
  If you don't use the etcher's latest edition or you use corrupted image package, etcher may malfunction in this step.

• In the etcher window, once it shows us Flash Complete! It is done and can be put into the RockPi.

Connect to Serial Console

ROCK 3 exports a dedicated serial console, which can access the low level debug message.

Requirement

• ROCK 3
• USB Type-C power adapter and USB Type-C charging data cable
• Host PC with Windows or Linux
• USB to TTL serial cable
  • The definition of each pin of USB to TTL cable is showing like this:

Note

• The default baudrate of ROCK 3 is 1500000(1.5Mbps), please check if your USB to TTL cable support 1.5Mbps baudrate. Some model of CP210X and PL2303x have baudrate limitation,and the FT232RL have some power issue(20211112), please check the specified model. We also tested that some cable does not work well. Make sure choose a high quality one. The instructions below use a CH340_series based cable.

• It seems that the serial tool on macOS platform can not support custom baudrate such as 1.5Mbps due to driver restriction. If you know how to set custom baudrate on macOS, please add an item here to show your findings.

Connection

Connect the USB to TTL serial cable as below. '''Don't connect the red wire.'''

Serial setting on host PC

The default serial setting for ROCK 3 u-boot and kernel console is:

    data bit: 8
    stop bit: 1
    parity  : none
    flow control: none

Linux

Minicom is the serial tool that supports wide range baud rate.

Install minicom:

    sudo apt-get install minicom

Plug in the USB to TTL cable, kernel dmesg | tail should show the following device:

    [1036835.755730] usb 1-6.4.3: New USB device found, idVendor=0403, idProduct=6001
    [1036835.755732] usb 1-6.4.3: New USB device strings: Mfr=1, Product=2, SerialNumber=0
    [1036835.755733] usb 1-6.4.3: Product: USB <-> Serial

Enable SSH Access

SSH server is enabled on port 22 of ROCK 3A default image.

Please use angryip to find your board IP address.

To access ROCK 3A by SSH, try

ping rockpie.local
ssh rock@rockpie.local

or if your router/network doesn't support Local Domain, you need to check your network/router administrator page and look for the ROCK 3A ip address.

ping ip-of-device
ssh rock@ip-of-device

Note: You can also get the IP of ROCK 3A from option 1 if you can not access network administrator page.

Building System Image

This documentation serves as a quick guide for building images for supported products. Custom images should refer to each build tool's reference for available options.

Build with Radxa kernel and firmware

To get started, please first config your system according to Development Reference. This one will also include additional dependencies for building kernel and firmware in later steps.

You can then clone rbuild which is our image generator:

git clone --depth 1 https://github.com/radxa-repo/rbuild.git
cd rbuild
./rbuild

Running rbuild without any argument will display the help message, which lists the supported products, the supported distro, and flavors. You can then build the image with:

./rbuild <board> [distro] [flavor]

distro and flavor are optional arguments. If you omit them, a default value will be used.

Once the command returns, you can find the built image located in the same folder, along with the SHA-512 hash.

To speed up image generation to make your debugging experience easier, you can update common/rootfs.yaml to use a faster APT mirrors.

Build kernel from source

Once you are comfortable with rbuild, you can try with bsp to create custom kernel for your image. Run the following commands to clone bsp to your system:

git clone --depth 1 https://github.com/radxa-repo/bsp.git
cd bsp
./bsp

Similarly running bsp without any argument give you the help message. Supported forks are listed here as well. Running ./bsp linux [fork] to get the build going, and you can find the resulting deb packages in the same folder. There will be multiple linux-images-....deb packages. The one with the largest size is the real kernel package, others are virtual packages.

However, to integrate kernel into the image, you should first check if the kernel is compatiable with your targeting product. A single kernel can support multiple products, and the list is defined as SUPPORTED_BOARDS in linux/[fork]/fork.conf file.

Once you have the correct kernel package, you can copy it to rbuild folder, and use -k [linux-images.deb] to specify a local kernel package in rbuild.

Build firmware from source

In addition to custom kernel, you can also build custom firmware for your image. The most common choice is U-Boot but we are also looking to support EDK2 for EFI boot, hence we are calling this section "firmware" instead of the more commonly used "bootloader" in embedded development.

bsp supports building U-Boot package as well. Unlike the kernel, we have one firmware per product. This is to allow each firmware to have the correct hardware configuration coded in, as on ARM platform there is no standardized hardware discovery mechanism.

Simply running ./bsp u-boot [fork] to have the U-Boot package built. Copy it to rbuild folder and use -f [u-boot.deb] to specify a local firmware package in rbuild.

You can also run ./bsp u-boot [fork] [product] to build firmware for a single product. By default all products supported by the same code fork will be built and packaged together.

Flash image

You can use sudo ./rbuild --write-image xxx.img /dev/sdX to write an image to a block device. The command support raw image (.img) and gz/xz/zip compressed files.

In addition you can also specify -s option, which will shrink rootfs before writting the image. This only works for raw image file type.

Development

Dependency

Arch/Manjaro:

sudo pacman -Syu --noconfirm --needed base-devel aarch64-linux-gnu-gcc arm-none-eabi-gcc git uboot-tools cpio multipath-tools jq docker dpkg swig bc dtc inetutils rsync
# `fpm` from AUR is currently broken, otherwise you can install it with yay
sudo pacman -S rubygems
gem install fpm

Debian/Ubuntu:

We use docker provided from distro's own repository. If you installed docker from another source, please remove docker.io from apt install command.

sudo apt update
sudo apt install -y build-essential crossbuild-essential-arm64 gcc-arm-none-eabi git u-boot-tools cpio multipath-tools jq docker.io bison flex libssl-dev python2 ruby swig python2-dev
sudo gem install fpm

Additional system config

sudo usermod -a -G docker $USER
sudo systemctl enable docker
sudo reboot

lbuild

fork.conf

fork.conf is the kernel fork configuration file. This file is mandatory and is sourced early by lbuild. You can override many options but below are some most commonly used (and supported) settings for this file:

LINUX_GIT Specify upstream kernel repo.

LINUX_COMMIT or LINUX_BRANCH or LINUX_TAG Specify the exact kernel revision. The first defined option in the listed order will be used.

LINUX_DEFCONFIG Specify the defconfig used for building. Default to defconfig.

SUPPORTED_BOARDS Specify the supported boards list, which is a Bash array.

kconfig.conf

kconfig.conf is a kernel configuration file. This file mirrors defconfig format.

rbuild

Folder structure

.github/            GitHub workflow related files.
.rootfs/            Untracked folder containing rootfs generated by the last build.
                    Can be used to speed up image generation the next time.

common/             rbuild scripts
    .packages/      Untracked folder for soft linking local packages
    flavors/        Package lists for various supported flavors
    overlays/       Various overlays for directly applying onto rootfs
    add_repo.yaml   Adding custom apt repo in rootfs
    clean.yaml      Common clean up script
    hack_install_deb.yaml
                    HACK for installing local package.
                    Only for debug use. Repo should not contain prebuild deb packages.
    hw-info.conf    Stores SoC's vendor and each vendor's preferred partition table type.
    image.yaml      Core script for deploying a rootfs to disk image.
                    Also install device specific kernel and firmware.
    rootfs.sh       Prepare the system for first boot.
    rootfs.yaml     Core script for generating a device-agnostic rootfs.
    sdboot.sh       Additional script for setting systemd-boot.

.gitignore          gitignore file
configs/            Board specific configs.
docs/               Documentation.
action.yaml         GitHub custom action file. Allow this repo to be used in GitHub Workflow.
rbuild              Main script.
README.md           Project readme.

How to add new boards?

Enabling new board in rbuild is simple, as most jobs should have already been done before touching this repo.

You should first update lbuild and ubuild to have them generate linux-images-<board-name> and u-boot-<board-name> deb packages. Do not mismatch those packages with different boards as the script might call files under board specific folder. In case of Linux kernel the package's name should not be touched, and linux-images-<board-name> needs to be added to deb's Provides property using SUPPORTED_BOARDS variable in fork.conf.

Once you have both of them available, you can start building system image to test your kernel and U-Boot. Copy both files to rbuild folder (this folder will be mounted in docker so if those files are outside of rbuild folder the script won't be able to access them). Create board-name.conf under configs, with one line SOC=system_on_chip_model (model number in lower case). If you are adding Rockchip based device, their SoC name usually starts with rk and can be recognized by common/hw-info.conf. For non-standard name (Rockchip PX30, Amlogic based SoC), update hw-info.conf's get_soc_family function. For entirely new vendor, you will also need to update get_partition_type function and review any mention of soc_family within the script.

Once you create the board config file (yes, it's that simple), run the following command:

./rbuild -r -d -k linux-image-board-name.deb -f u-boot-board-name.deb board-name

-r means reusing rootfs generated in previous run. This saves a lot of time when testing multiple devices or different kernels. -d means dropping into a debug shell if any step fails. -k and -f specify the custom kernel and firmware (currently U-Boot) you are going to use. This will build a CLI image by default.

You can then test your image. Once you are sure your kernel and firmware are up to sniff, create new repos in radxa-pkg organization to automatically generate packages for them (or update the existing one), create new releases, and update radxa-repo/apt to include them in the apt repo. You can then build image without -k and -f options.

Now you can update radxa-build organization to have the image auto generated over there.

pkgbase

pkgbase contains a set of helper scripts to help you create radxa-repo packages. The focus here is to simplify common package generation tasks, while enforcing some policies on all our packages.

A very basic package file can be seen here (pkg.conf.shell), which actually creates nothing:

PB_PKGS=( "shell" )

shell_package() {
    echo "Shell package can build in ways you like."
}

pkg.conf supports building multiple packages. Simply add the build prefix to PB_PKGS array, and write the mandatory prefix_package function for each package.

pkgbase also provides multiple hooks for advanced builds.

Create new package

To create new package, simply base your main branch off root branch from this repo:

PKG_NAME="my-new-package"
mkdir $PKG_NAME
cd $PKG_NAME
git init
git remote add upstream https://github.com/radxa-repo/pkgbase.git
git fetch upstream
git checkout -b main upstream/root
git remote add origin https://github.com/radxa-pkg/$PKG_NAME.git
git push -u origin main

You can then add pkg.conf file to the repo. pkgbase provides some sample pkg.conf file for you to use as a starting point. Currently the following types of package are supported:

• fpm that packages an existing root folder structure (usually ./root folder) into a deb file. Requires PB_MODULES=( "fpm" ) for loading fpm module.
• shell that allows abritary build scripts.

Build package

Run the following command:

PKG_NAME="my-new-package"
git clone --depth 1 https://github.com/radxa-repo/pkgbase.git
git clone --depth 1 https://github.com/radxa-pkg/$PKG_NAME.git
cd $PKG_NAME
../pkgbase/build.sh pkg.conf

You can check .mod files to see some additional dependencies each module requires. This is currently designed for GitHub Actions so that is not a complete list.

apt

Our apt repo automatically source the release binaries from radxa-pkg organization. We have the following convention to ensure the package info can be parsed by our tools.

1. Release's name has to be a version number only.

   apt-repo-action will record the release name as version number and store it in pkgs.json. If the release name contains additional info, that might break future package gathering operation.

2. Split unrealated packages into their own repo.

   apt-repo-action only compare the latest release with pkgs.json. As such if two packages are upgraded independently, they should be split into 2 different repo, so their content can be updated only when needed.

   However, if the same source code will generate multiple packages, they can be put in the same repo and the same release, so everything can be updated together.

3. Use pkg.conf to customize package upload.

   By default, every package will be uploaded to bullseye and jammy release. If you want to adjust the release destination, you can add a pkg.conf file in your release assets.

   It will have the following format with comment added. Note this has to be a legal json document and comment is actually not supported in the spec:

   {
       // Full file name
       "sample_1.0-1_all.deb": {
           // List targeting releases
           "Releases": [
               "bullseye",
               "jammy"
               // The last item in the array cannot have trailing comma!
           ]
       },
       "rockchip_1.0-1_all.deb": {
           // Upload to vendor specific release
           "Releases": [
               "bullseye-rockchip"
           ]
       },
       "private_1.0-1_all.deb": {
           // Do not upload this package
           "Releases": []
       }
   }
   

   Currently every releases share the same binary pool, so package with exact same file name will be overwritten by one another.

ROCK 3A hardware Features

Contributors