Secondary Customization Firmware

Introduction

firmware-kits is a secondary customization firmware assistant tool developed by our company. The tool provides the following features:

Re-extract firmware upgrade packages
Modify or replace the file system
Replace partitions
Assistant tool for repacking upgrade packages

Development Vision

In factory mass-production delivery scenarios, users often want to embed development and production tools into the firmware upgrade package to ensure consistency of production versions. This tool aims to provide a convenient implementation solution and lower the cost of standardizing versions.
Build a firmware customization and pre-debugging environment that is independent of real hardware. Based on X86‑ARM64 QEMU virtualization technology, the target file system can be run directly; developers can complete application pre-installation, custom configuration, and debugging in the virtual environment without relying on real hardware, reducing hardware resource usage and effectively lowering development and hardware investment costs.

firmware-kits is used to preprocess BM1684 and RK3588 firmware packages before the official firmware upgrade. It can unpack the original firmware following a specified flow, adjust the sizes of partitions such as ROOTFS/DATA/CUSTOM, mount the rootfs for manual modification of system contents, and repack the firmware into a package that can be delivered or used for upgrading after the modifications are complete.

The tool is suitable for scenarios where firmware contents need to be customized before upgrading, such as expanding partitions, preloading files, adjusting rootfs configuration, and generating TFTP or SD card upgrade packages. For ordinary firmware upgrades, the upgrade management features described earlier on this page should still be preferred; use firmware-kits only when the firmware needs to be modified or repacked first.

If your workflow includes exporting the rootfs on the device and repackaging the firmware on a PC, also refer to Device rootfs Export and Firmware Repackaging.

The following describes how to use firmware-kits to unpack, modify, and repack BM1684 and RK3588 firmware. Follow the steps strictly.

All commands are executed in the firmware-kits directory.

Environment Preparation

4.1 Operating System Requirements

An Ubuntu 20.04/22.04 x86_64 host is recommended.

4.2 Install Dependencies

sudo apt update
sudo apt install -y u-boot-tools qemu-user-static p7zip-full unzip e2fsprogs

4.3 Download the Tool Package

4.4 Check the Tool Package Directory

Enter the tool package directory:

cd firmware-kits

Confirm that the directory contains at least the following contents:

firmware-kits
flow/
scripts/
tools/
bin/

Confirm that the main program can be executed:

./firmware-kits --help

Firmware processing involves mounting, chroot, file system adjustment, and repacking, so sudo is required for official operations.

Basic Commands

Process the firmware from scratch:

sudo ./firmware-kits run -l <flow-file> -f <firmware-file>

Resume after the flow is paused:

sudo ./firmware-kits resume

Parameter description:

Parameter	Description
`run`	Execute a firmware processing flow from scratch
`resume`	Continue execution from the position where it was last paused
`-l`	Specify the flow file, for example `flow/bm1684_tftp_data.yaml`
`-f`	Specify the original firmware file
`-o`	Advanced parameter, passed to the processing script; do not use it unless specifically instructed

When the tool reaches a position that requires manual handling, it pauses automatically and prompts which command to execute next. After the manual operation is complete, run sudo ./firmware-kits resume to continue.

Important Notes

Do not delete out/, .firmware-kits_state.json, or tools/.env while the flow is paused.
Do not shut down the host after the rootfs has been mounted unless you have confirmed that the unmount is complete.
Process only one firmware flow at a time; do not run multiple firmware-kits run/resume commands in multiple terminals simultaneously.
The output directory is out/. If the artifacts are no longer needed, run sudo rm -rf out/ to free up space.
If the flow reports that an interrupted record exists, run sudo ./firmware-kits resume first; do not directly re-run run.

Firmware Creation Operations

6.1 Obtain the Upgrade Firmware

6.2 Unpack the Upgrade Package

6.3 Expand the ROOTFS

Tip

Before modifying the ROOTFS contents and deploying new files, expand the ROOTFS partition and file system size in advance to reserve sufficient storage space, avoiding insufficient space when adding programs, configuration files, and resource data later, which could cause packaging failures or abnormal firmware operation.

6.4 Replace the File System

6.5 Regenerate the Upgrade Firmware Package

FAQ

Insufficient Permissions Reported

Firmware processing involves mounting, chroot, and root-owned files. Confirm that the command was run with sudo.

If deleting the output directory fails, run:

sudo rm -rf out/

Unsure What to Execute Next

If the flow is paused, the terminal usually prompts the next command. Generally, you only need to:

View or modify the partition size as prompted, or modify the rootfs contents.
Run sudo ./firmware-kits resume when done.

What to Do If the Partition Size Does Not Need to Be Modified

At the partition size pause point, if no modification is needed, run directly:

sudo ./firmware-kits resume

What to Do If the rootfs Contents Do Not Need to Be Modified

At the rootfs content modification pause point, if no modification is needed, run directly:

sudo ./firmware-kits resume

apt Commands Show locale or /dev/pts Warnings

Some rootfs environments may display warnings related to locale or /dev/pts. As long as the command eventually succeeds, it generally does not affect firmware creation.

How to Confirm There Are No Leftover Mounts

After a normal flow completes, there are usually no leftover mounts. To check, run:

mount | grep firmware-kits/out

No output means there are no leftover mounts.

If there is output, contact the delivery personnel for handling; do not arbitrarily delete directories that are currently mounted.

Execution Records

Two actual execution records are provided with the package and can be downloaded to review the complete operation process:

The logs keep only the firmware processing commands that customers care about, terminal output, pause point operations, demonstrations of commands executed inside the rootfs, demonstrations of file copying, the final artifact paths, and the mount check results.

Recovery from an Abnormal Interruption

If you see a message similar to the following when running run:

Interrupted record found, please use `sudo ./firmware-kits resume` to continue

It means the previous flow did not complete. Run:

sudo ./firmware-kits resume

If you confirm that the previous flow is no longer needed, clean up the state and output:

sudo rm -f .firmware-kits_state.json tools/.env
sudo rm -rf out/

After the cleanup, run can be executed again.