Skip to content

How to Compile firmware

Jump to bottom
Guoping Liu edited this page Sep 30, 2026 · 12 revisions

How to Compile the Firmware

This page describes how to build the ThirdReality LinuxBox / HubV3 firmware from source.

The project is a fork of the Armbian build framework with ThirdReality board support, patches and packages added on top. Two build lines are maintained in parallel:

Current line Legacy line
Git branch hubv3-6.6.y hubv3
Kernel 6.6.120 (mainline stable) 5.10.x (mainline stable)
Armbian framework 24.11 22.11
Userspace Debian 12 bookworm Debian 12 bookworm
Build entry point make-armbian-build-release.sh make_armbian_for_hubv3.sh
Latest release v2.14.01.50 v1.14.01.21
Status actively developed, use this for new work maintenance only

Each line has a single build script that does everything — dependency setup, kernel and U-Boot compilation, rootfs creation and the final conversion to a flashable Amlogic burn image. Use the script; the individual framework steps are not supported as a standalone procedure.

Board naming: the current line uses the public name hubv3, the legacy line uses the internal Armbian name trhubv3. They refer to the same hardware.

1. Build host requirements

Both lines build on the same class of host:

  • x86_64 machine, bare metal or a full VM (aarch64 also works)
  • Debian 12 or Ubuntu 22.04 (jammy) — other distributions are not tested
  • 4 GB RAM minimum, 8 GB recommended
  • At least 40 GB of free disk space (kernel worktree + rootfs cache + images)
  • Root access (sudo or a root shell)
  • Working internet access to github.com, git.kernel.org and the Debian mirrors

Install the minimum tooling; the framework installs the rest of its dependencies on first run:

sudo apt-get update
sudo apt-get install -y git zip device-tree-compiler build-essential \
    qemu-user-static binfmt-support rsync python3 python3-venv

WSL is not supported. The build runs natively on the host and needs loop devices and binfmt_misc for arm64 emulation; use bare metal or a full virtual machine instead.

2. Get the source code

git clone git@github.com:thirdreality/LinuxBox.git
cd LinuxBox

Typical clone output:

Cloning into 'LinuxBox'...
remote: Enumerating objects: 84723, done.
remote: Total 84723 (delta 0), reused 0 (delta 0), pack-reused 84723 (from 1)
Receiving objects: 100% (84723/84723), 497.58 MiB | 1.13 MiB/s, done.
Resolving deltas: 100% (56121/56121), done.
Updating files: 100% (11012/11012), done.

Then check out the branch you want to build:

# current line (kernel 6.6)
git checkout hubv3-6.6.y

# or the legacy line (kernel 5.10)
git checkout hubv3

To build a released version exactly as it was shipped, check out its tag instead:

git checkout v2.14.01.50

If git refuses to use your SSH key, point it at the key explicitly:

git config --global core.sshCommand "ssh -i /home/<user>/.ssh/id_rsa"

Large clones over a slow link may also need:

git config --global http.version HTTP/1.1
git config --global http.postBuffer 524288000

3. Build the current line (hubv3-6.6.y, kernel 6.6.120)

make-armbian-build-release.sh is the release build script. It prepares userpatches/ from vendor.repo/, runs the Armbian build, then converts the resulting .img into an Amlogic burn image ready for flashing.

sudo ./make-armbian-build-release.sh -b hubv3 -d us -r v2.14.01.50

Options:

Option Values Meaning
-b hubv3 target board (default, and the only board you normally need)
-d us, kr, cn destination; cn selects the China download mirror
-r e.g. v2.14.01.50 ThirdReality release version stamped into the image
-h – print usage

The version passed to -r is also converted into a numeric VERSION_ID (major*1000000 + minor*10000 + patch*100 + build) which ends up in /etc/os-release on the device, so keep the four-field vX.Y.ZZ.NN format.

Startup output looks like this:

[HUBV3] INFO: Working directory is '/root/LinuxBox'
[HUBV3] INFO: Board selected: [ hubv3 ]
[HUBV3] INFO: Destination selected: [  ]
[HUBV3] INFO: Release Version selected: [ v2.14.01.50 ]
[HUBV3] INFO: VERSION_ID calculated: [ 2140150 ]
[HUBV3] INFO: Start building ...

What the script does, step by step:

  1. Removes userpatches/, output/ and .tmp/, then re-creates userpatches/ by rsync-ing vendor.repo/userpatches/ into it and writes 24.11 to userpatches/VERSION.
  2. Cleans stale kernel build state in cache/sources/linux-kernel-worktree/6.6__meson64__arm64 (make clean) and exports KERNEL_REUSE_LOCAL=yes so the local worktree is reused instead of being re-fetched.
  3. Runs the Armbian build for BOARD=trhubv3 BRANCH=current RELEASE=bookworm (kernel 6.6.120, U-Boot v2023.10, board family trhub).
  4. Unpacks the generated linux-u-boot-*.deb to get u-boot.nosd.bin.
  5. Calls amlogic-tools.repo/convert.sh to repack the rootfs image into the eMMC burn image and moves the result into output/images/.

The script deletes userpatches/ and output/ on every run. Keep local customisations in vendor.repo/userpatches/ (which is tracked in git) and in userpatches/config-linuxbox-images.conf, not in the generated userpatches/ copy.

The first build takes a long time because the kernel source, toolchain and Debian packages all have to be downloaded. Subsequent builds reuse cache/ and are much faster.

4. Build the legacy line (hubv3, kernel 5.10)

git checkout hubv3
sudo ./make_armbian_for_hubv3.sh -b trhubv3 -d us -r v1.14.01.21

Options are the same as above, except that this branch expects the internal board name trhubv3 for -b.

Example log:

** Board selected: [ trhubv3 ]
** Destination selected: [  ]
** R3 Version selected: [ v1.14.01.21 ]
** VERSION_ID calculated: [ 1140121 ]
[ o.k. ] This script will try to update
[ o.k. ] Using config file [ /root/LinuxBox/userpatches/config-hubv3-images.conf ]

On this branch the per-image configuration lives in custom/ and is copied into userpatches/ by the script (config-hubv3-images.conf, customize-image.sh, bl706_cache). The script also handles the burn-image conversion using the in-tree converter under tools/Armbian_Convert, and renames the result from *.burn.img to *.<version>.img.

5. Build output

Current line (hubv3-6.6.y)

output/images/thirdreality_hubv3_armbian_24.11_bookworm_6.6.120_v2.14.01.50.burn.img.zip
output/images/<board>/archive/*.img          # raw Armbian rootfs image
output/debs/                                 # kernel, headers, u-boot, bsp packages
output/logs/                                 # build logs

Legacy line (hubv3)

output/images/*.burn.image      # or *.<version>.img after renaming
output/debs/
output/logs/

The *.burn.img* file is the one you flash to the device.

6. Flashing the image

The burn image is flashed with the Amlogic USB Burning Tool, which is a Windows-only utility provided by Amlogic. There is no Linux or macOS equivalent, so even if you build on Linux you need a Windows machine (or a Windows VM with USB passthrough) to flash the result.

Step-by-step instructions: How to burn the image to LinuxBox

7. Troubleshooting

"<path>" contains whitespace. Not supported. Aborting. Move the checkout to a path without spaces.

Build fails with "no space left on device" The build needs ~40 GB. Clean intermediate state and retry:

rm -rf .tmp output/logs output/info output/packages-hashed
sudo rm -rf cache/rootfs/*        # rootfs tarballs, safe to regenerate

Kernel rebuild picks up stale objects

cd cache/sources/linux-kernel-worktree/6.6__meson64__arm64 && make clean

arm64 chroot commands fail / Exec format error QEMU user emulation is not registered:

sudo apt-get install --reinstall -y qemu-user-static binfmt-support
sudo systemctl restart systemd-binfmt.service
cat /proc/sys/fs/binfmt_misc/qemu-aarch64   # should exist

apt / DNS failures inside the chroot Force IPv4 and add retries on the host, then rebuild:

sudo tee /etc/apt/apt.conf.d/99force-ipv4 <<'EOF'
Acquire::ForceIPv4 "true";
Acquire::Retries "5";
EOF

On the legacy line you can also pass MANAGE_ACNG=no to bypass apt-cacher-ng.

Cannot locate built .img under output/images/* The branding (VENDOR) changes the image filename, so it no longer contains "Armbian". Look under output/images/<board>/archive/ for the real artifact.

Slow or failing downloads in mainland China Pass -d cn to the build script to select the China download mirror.

8. Pre-built images

If you do not want to build yourself:

All releases: https://github.com/thirdreality/LinuxBox/releases

9. Further reading

Clone this wiki locally