Welcome to Firefly
English
English
Firefly Docsss
Last Updated: 2026-10-12 11:17:51

Software Upgrade

AIBOX-K3 does not currently support full system software upgrades using apt upgrade. Regular software packages can be installed and updated using apt update and apt install. Executing the apt update and apt install commands works without issue. To upgrade critical packages such as esos, uboot, and kernel, you need to download the official Firefly SDK package and update it by compiling and flashing it.

Documentation

The following links contain the "Product Brief," "Datasheet," and "User Manual."

SDK

Buildroot's code is hosted on GitHub and includes several repositories managed using repo. Before downloading, you need to:

  1. Install repo

Requires repo version >= 2.41; otherwise, the download process will fail.

$ repo --version
repo version v2.48
       (from https://mirrors.tuna.tsinghua.edu.cn/git/git-repo)
       (tracking refs/heads/stable)
       (Mon, 7 Oct 2024 18:44:19 +0000)
repo launcher version 2.50
       (from /usr/bin/repo)
       (currently at 2.48)
repo User-Agent git-repo/2.48 (Linux) git/2.25.1 Python/3.8.10
git 2.25.1
git User-Agent git/2.25.1 (Linux) git-repo/2.48
Python 3.8.10 (default, Nov  7 2024, 13:10:47)
[GCC 9.4.0]
OS Linux 5.4.0-196-generic (#216-Ubuntu SMP Thu Aug 29 13:26:53 UTC 2024)
CPU x86_64 (x86_64)
Bug reports: https://issues.gerritcodereview.com/issues/new?component=1370071

Download from Github

mkdir ~/k3-buildroot-sdk
cd ~/k3-buildroot-sdk

repo init -u https://github.com/Firefly-spacemit-linux/manifests.git -b spacemit -m k3_linux6.18_release.xml

# Synchronize SDK code
repo sync -c --no-tags

Compiling Linux Firmware

Note:

  1. Builds in a container by default. To build on the host machine, configure the environment variable export DIRECT_BUILD=1. When switching between container and host machine builds, you need to clean the output directory.

  2. A new set of commands has been added. These are incompatible with older commands. To use the new commands, delete the env.mk file generated by the old commands in the project root directory. You can then use make help to view the list of new commands. For example, you can use make k3-build to directly compile a specified solution.

    $ cd ~/k3-buildroot-sdk-1.0
$ rm -rf env.mk
$ make help
Buildroot Build System - Help

Available solutions:
  firefly-k3 k3 k3_ci k3_fpga k3_plt

Development Commands:
  make vars                          # Show project information
  make <solution>-supported          # Check if solution is supported
  make <solution>-config             # Apply solution defconfig
  make <solution>-menuconfig         # Configure buildroot for solution
  make <solution>-linux-menuconfig   # Configure Linux kernel for solution
  make <solution>-uboot-menuconfig   # Configure U-Boot for solution
  make <solution>-busybox-menuconfig # Configure BusyBox for solution
  make <solution>-build              # Build specified solution
  make <solution>-pkg PKG=<package>  # Build specified package for solution
  make <solution>-shell              # Enter build container for solution
  make <solution>-source             # Download all source packages for solution
  make <solution>-clean              # Clean solution build artifacts
  make <solution>-cleanbuild         # Clean and rebuild solution
  make build-docker-image            # Build Docker image
  make update-docker-image           # Update Docker image

Quick Start: Run 'make <solution>-build' to get started, e.g.:
  make k3-build

Compiling Buildroot Firmware

Pre-compilation Configuration

$ cd ~/k3-buildroot-sdk-1.0
$ make envconfig
Available configs in /home2/lvsx/ext/project/k3/buildroot-ext/configs:
  1. spacemit_firefly-k3_defconfig
  2. spacemit_k3_ci_defconfig
  3. spacemit_k3_defconfig
  4. spacemit_k3_fpga_defconfig
  5. spacemit_k3_plt_defconfig

Your choice (1-5):

Enter 1 here and select spacemit_firefly-k3_defconfig.

The compilation process may require downloading some third-party packages; the exact time depends on your network environment. If you download the third-party packages that buildroot depends on beforehand, the recommended compilation time is approximately 1 hour based on your hardware configuration.

The compilation output is located in the /output/k3/images/ directory. A successful compilation and packaging log is shown below:

Generating sdcard image...................................
INFO: cmd: "mkdir -p "/firefly-k3/build/genimage.tmp"" (stderr):
INFO: cmd: "rm -rf "/firefly-k3/build/genimage.tmp"/*" (stderr):
INFO: cmd: "mkdir -p "/firefly-k3/images"" (stderr):
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition 'env' from 'env.bin' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition 'bootinfo' from 'factory/bootinfo_block.bin' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition 'fsbl' from 'factory/FSBL.bin' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition 'esos' from 'esos.itb' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition 'opensbi' from 'fw_dynamic.itb' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition 'uboot' from 'u-boot.itb' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition 'bootfs' (in MBR) from 'bootfs.img' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition 'rootfs' (in MBR) from 'rootfs.ext4' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition '[MBR]' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition '[GPT header]' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition '[GPT array]' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): adding primary partition '[GPT backup]' ...
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): writing GPT
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): writing protective MBR
INFO: hdimage(Buildroot-firefly-k3-20260508163419-sdcard.img): writing MBR
INFO: cmd: "rm -rf "/firefly-k3/build/genimage.tmp/"" (stderr):
Successfully generated at /firefly-k3/images/Buildroot-firefly-k3-20260508163419-sdcard.img

The Buildroot-K3-xxx.zip file is suitable for Titan Flasher, or can be unzipped and flashed using fastboot; Buildroot-K3-xxx-sdcard.img is the SD card firmware, which can be written to the SD card using the dd command or balenaEtcher after unzipping.

The default username for the firmware is root, and the password is firefly.

Compiling Bianbu Firmware

Preparation

Download the firmware archive and extract it to obtain the rootfs.ext4 root filesystem.

Check SDK Version

$ realpath .repo/manifests/k3_linux6.18_release.xml

Example output for SDK v1.0.0:

$ realpath .repo/manifests/k3_linux6.18_release.xml
K3_SDK/.repo/manifests/k3/k3_linux6.18_release_20260611_v1.0.0a.xml

Example output for SDK v1.0.9:

$ realpath .repo/manifests/k3_linux6.18_release.xml
K3_SDK/.repo/manifests/k3/k3_linux6.18_release_20261010_v1.0.9a.xml

Note: The firmware packaging method differs between SDK v1.0.0 and SDK v1.0.9 (or later). It is recommended to update the SDK to the latest version before proceeding with the tutorial.

  • Firmware packaging tutorial for SDK v1.0.0 only

After downloading the firmware archive, extract it and copy the rootfs.ext4 file from the extracted contents to SDK/buildroot-ext/board/spacemit/k3/:

# Example: If the firmware filename is Firefly-K3_Bianbu-LXQt_v1.0.9a_261010.zip, adjust the unzip command accordingly.
unzip Firefly-K3_Bianbu-LXQt_v1.0.9a_261010.zip -d Firefly-K3_Bianbu-LXQt_v1.0.9a_261010

# Copy the extracted rootfs.ext4 to the specified SDK directory. The file must be named `rootfs.ext4`.
cp Firefly-K3_Bianbu-LXQt_v1.0.9a_261010/rootfs.ext4 /SDK/buildroot-ext/board/spacemit/k3/rootfs.ext4
  • Firmware packaging tutorial for SDK V1.0.9 and later versions
# Example: If the firmware file is named Firefly-K3_Bianbu-LXQt_v1.0.9a_261010.zip and has been copied to the SDK root directory. Adjust the decompression command according to the actual firmware filename.
unzip Firefly-K3_Bianbu-LXQt_v1.0.9a_261010.zip -d Firefly-K3_Bianbu-LXQt_v1.0.9a_261010

# Copy the extracted rootfs.ext4 to the directory specified by the SDK
cd /path/to/sdk
mkdir -p prebuilt_rootfs
cp Firefly-K3_Bianbu-LXQt_v1.0.9a_261010/rootfs.ext4 /SDK/prebuilt_rootfs/Bianbu-Lxqt_rootfs.ext4
cd prebuilt_rootfs/
ln -sf Bianbu-Lxqt_rootfs.ext4 rootfs.ext4

Note: rootfs.ext4 must be a symbolic link pointing to the actual filesystem file. The build script uses this rootfs.ext4 link to determine the target filename and generate the corresponding firmware image.

Pre-compilation configuration

$ cd ~/k3-buildroot-sdk-1.0
$ make envconfig
Available configs in /home2/lvsx/ext/project/k3/buildroot-ext/configs:
  1. spacemit_firefly-k3_defconfig
  2. spacemit_k3_ci_defconfig
  3. spacemit_k3_defconfig
  4. spacemit_k3_fpga_defconfig
  5. spacemit_k3_plt_defconfig

Your choice (1-5):

Enter 1 here and select spacemit_firefly-k3_defconfig.

The compilation process will replace the buildroot file system with the /SDK/buildroot-ext/board/spacemit/k3/rootfs.ext4 file system.

Configuration

Configuration requires entering the Docker build environment.

make firefly-k3-shell

buildroot

Configuration:

make menuconfig

The configuration is saved to buildroot-ext/configs/spacemit_firefly-k3_defconfig by default.

make savedefconfig

Linux

Configuration:

make linux-menuconfig

Save the configuration, which by default is saved to bsp-src/linux-6.18/arch/riscv/configs/k3_bianbu_defconfig:

make linux-update-defconfig

u-boot

Configuration:

make uboot-menuconfig

Save the configuration, which by default is saved to bsp-src/uboot-2022.10/configs/k3_defconfig:

make uboot-update-defconfig

Recompile Completely

If you have already compiled completely using make envconfig, you can directly use make to compile completely again.

Compile a Specific Package

Buildroot supports compiling a specific package. You can use make help to view the guide.

Common Commands:

  • Delete the compilation directory of <pkg>: make <pkg>-dirclean

  • Compile <pkg>: make <pkg>

  • Recompile <pkg>: make <pkg>-rebuild

u-boot

#Compilation
make uboot

#Cleanup
make uboot-dirclean

#Recompile
make uboot-rebuild

Linux

The kernel's default configuration is k3_bianbu_defconfig

#Compilation
make linux

#Cleanup
make linux-dirclean

#Recompile
make linux-rebuild

opensbi

#Compilation
make opensbi

#Cleanup
make opensbi-dirclean

#Recompile
make opensbi-rebuild

After compiling the specified package, it can be downloaded separately to the device for verification, or compiled into the firmware:

make

On this page

Software Upgrade
Documentation
SDK
Download from Github
Compiling Linux Firmware
Compiling Buildroot Firmware
Pre-compilation Configuration
Compiling Bianbu Firmware
Preparation
Check SDK Version
Pre-compilation configuration
Configuration
buildroot
Linux
u-boot
Recompile Completely
Compile a Specific Package
u-boot
Linux
opensbi