amlogic-s9xxx-armbian Documentation

File: README.md Copy Chapter

Armbian

English Instructions | 中文说明 | 日本語説明

Armbian is a lightweight Linux distribution built specifically for ARM chips, based on Debian/Ubuntu. The Armbian system is lean, clean, and 100% compatible with Debian/Ubuntu, inheriting its functionality and rich software ecosystem. It runs securely and stably on TF/SD/USB storage and the device's eMMC. This project preserves the integrity of the official Armbian system while extending support for unofficially supported devices such as TV boxes, and adds a set of convenient management commands. You can now replace the Android TV system on your TV box with Armbian, transforming it into a powerful server.

This project relies on many contributors to build the Armbian system for Amlogic, Rockchip, and Allwinner devices. It supports writing to eMMC, kernel updates, and other features. For detailed usage, see the Armbian User Documentation. The latest Armbian system can be downloaded from Releases. Welcome to Fork and customize. If this project is helpful, please click the Star button in the upper right corner to show your support.

Default Information for Armbian System Copy Chapter

Supported Devices Copy Chapter

⬆️ Models from each platform (Amlogic/Rockchip/Allwinner) are ranked by SoC performance from high to low.

[!TIP]
At present, the s905 box can only be used with TF/SD/USB; other box models support writing to EMMC. For more information, refer to the ✅ Supported Device List. To add new device support, see Section 12.15 of the documentation: Adding New Supported Devices. Please read the Armbian User Documentation before use, as it provides solutions to common issues.

Installation and Upgrade Instructions for Armbian Copy Chapter

Choose the Armbian system that matches your device model. Refer to the corresponding documentation for device-specific usage instructions.

• Install Armbian to EMMC Copy Section

1. For Rockchip platform devices, refer to Chapter 8 of the documentation.

2. For Amlogic and Allwinner platform devices, use tools such as Rufus or balenaEtcher to write the system to a USB stick, then insert the USB stick into the device. Log in to the Armbian system (default user: root, default password: 1234) and enter the command:

armbian-install

Example: armbian-install -m yes -a no

• Update Armbian Kernel Copy Section

Log in to the Armbian system and enter the command:

# Run as root user (sudo -i)
# If no parameter is specified, it will be updated to the latest version.
armbian-update

Example: armbian-update -k 5.15 -u stable -d deb

When specifying the kernel version via the -k parameter, you can provide an exact version number (e.g., armbian-update -k 5.15.50) or specify only the kernel series (e.g., armbian-update -k 5.15). When a series is specified, the latest version within that series will be used automatically.

During kernel updates, the currently running kernel is automatically backed up to the /ddbr/backup directory, retaining the 3 most recent versions. If the newly installed kernel proves unstable, you can restore a backup kernel at any time. If a kernel update renders the system unbootable, use armbian-update -s to restore the system kernel. For more details, see the Help Document.

• Replace Armbian Sources Copy Section

Log in to the Armbian system and enter the command:

armbian-apt

Choosing the appropriate software source for your country or region can significantly improve download speeds. For more details, see the Help Document.

• Install Common Software Copy Section

Log in to the Armbian system and enter the command:

armbian-software

The command armbian-software -u updates the local software center list. Based on user feedback in Issues, commonly used software has been gradually integrated with one-click install/update/uninstall support. This includes Docker images, desktop software, application services, and more. See the detailed instructions.

• Modify Armbian Configuration Copy Section

Log in to the Armbian system and enter the command:

armbian-config

• Create Swap for Armbian Copy Section

If you find the device's memory insufficient when running memory-intensive applications such as Docker, you can create a swap virtual memory partition to use a portion of disk space as additional memory. The parameter unit is GB, with a default value of 1.

Log in to the Armbian system and enter the command:

armbian-swap 1

• Control LED Display Copy Section

Log in to the Armbian system and enter the command:

armbian-openvfd

Debug according to the LED Screen Display Control Instructions.

• Backup/Restore EMMC Original System Copy Section

Supports backing up and restoring the device's EMMC partition via TF/SD/USB. Before installing Armbian on a new device, it is recommended to back up the original Android TV system for future restoration if needed.

Boot the Armbian system from TF/SD/USB and enter the command:

armbian-ddbr

Enter b at the prompt to back up the system, or r to restore.

[!IMPORTANT]
Alternatively, the Android system can be flashed directly into eMMC via USB cable. Android system images are available in Tools.

• Compile the Kernel in Armbian Copy Section

For kernel compilation instructions, see the Compile Kernel documentation. Log in to the Armbian system and enter the command:

armbian-kernel -u
armbian-kernel -k 6.6.12

• More Usage Instructions Copy Section

To update all service scripts in the system to the latest version, log in to the Armbian system and enter the command:

armbian-sync

For common issues and their solutions when using Armbian, see documents.

Local Packaging Copy Chapter

1. Clone the repository to local git clone --depth 1 https://github.com/ophub/amlogic-s9xxx-armbian.git

2. Install the necessary software packages (using Ubuntu 24.04 as an example)

Enter the ~/amlogic-s9xxx-armbian root directory, then run the installation command:

sudo apt-get update -y
sudo apt-get full-upgrade -y
# For Ubuntu-24.04
sudo apt-get install -y $(cat compile-kernel/tools/script/ubuntu2404-build-armbian-depends)

3. Enter the ~/amlogic-s9xxx-armbian root directory, create the build/output/images folder, and upload the Armbian image file (e.g., Armbian_21.11.0-trunk_Odroidn2_current_5.15.50.img) to the ~/amlogic-s9xxx-armbian/build/output/images directory. Retain the release version number (e.g., 21.11.0) and kernel version number (e.g., 5.15.50) in the original filename, as they will be used for naming the rebuilt Armbian system.

4. Enter the ~/amlogic-s9xxx-armbian root directory and run sudo ./rebuild -b s905x3 -k 6.6.12 to generate the Armbian image for the specified board. Output files are saved in the build/output/images directory.

• Local Packaging Parameter Description Copy Section

• sudo ./rebuild: Use default configuration to package all device models.
• sudo ./rebuild -b s905x3 -k 6.6.12: Recommended. Build with default configuration for the specified kernel.
• sudo ./rebuild -b s905x3 -k 6.1.y: Build with default configuration, using the latest kernel in the 6.1.y series.
• sudo ./rebuild -b s905x3_s905d -k 6.6.12_5.15.50: Build with default configuration for multiple kernels simultaneously. Use _ to join multiple kernels.
• sudo ./rebuild -b s905x3 -k 6.6.12 -s 2560: Build a single kernel and model with default configuration; ROOTFS partition size set to 2560 MiB.
• sudo ./rebuild -b s905x3_s905d: Build all kernels for multiple models with default configuration. Use _ to join multiple models.
• sudo ./rebuild -k 6.6.12_5.15.50: Build all models with default configuration and multiple specified kernels. Use _ to join kernels.
• sudo ./rebuild -k 6.6.12_5.15.50 -a true: Same as above, with automatic upgrade to the latest kernel within each series.
• sudo ./rebuild -t btrfs -s 2560 -k 6.6.12: Build all models with btrfs filesystem, 2560 MiB ROOTFS, and kernel 6.6.12.

Use GitHub Actions for Compilation Copy Chapter

1. Workflow configuration files are located in the .github/workflows/ directory.

2. Fresh Build: On the Actions page, select Build Armbian server image to use the build-armbian-arm64-server-image.yml workflow. You can choose from Ubuntu series (e.g., resolute) or Debian series (e.g., trixie). Click Run workflow to start the build.

3. Rebuild: If Releases already contains compiled Armbian_.*-trunk_.*.img.gz files and you only need to repackage for other boards, skip the source compilation step and use build-armbian-using-releases-files.yml for secondary builds.

4. To use other Armbian systems (e.g., the odroidn2 image from the official armbian.tnahosting.net download site), simply reference this repository's script in the workflow file build-armbian-using-official-image.yml for Armbian restructuring to support other devices. Example:

- name: Build Armbian
  uses: ophub/amlogic-s9xxx-armbian@main
  with:
    build_target: armbian
    armbian_path: build/output/images/*.img
    armbian_board: s905d_s905x3_s922x_s905x
    armbian_kernel: 6.12.y_6.18.y

• GitHub Actions Input Parameter Description Copy Section

These parameters correspond to the local packaging command options described above.

• GitHub Actions Output Variable Description Copy Section

Uploading to Releases requires Workflow read and write permissions for the repository. See the usage instructions for details.

Build Armbian Docker Image Copy Chapter

For creating Docker images of the Armbian system, refer to the armbian_docker build script.

Compiling Kernel Using GitHub Actions Copy Chapter

For kernel compilation instructions, see compile-kernel.

- name: Compile the kernel
  uses: ophub/amlogic-s9xxx-armbian@main
  with:
    build_target: kernel
    kernel_version: 6.12.y_6.18.y
    kernel_auto: true
    kernel_sign: -yourname

Armbian Contributors Copy Chapter

First and foremost, thanks to 150balbes for the outstanding contributions and the solid foundation laid for running Armbian on Amlogic TV boxes. The Armbian system compiled here uses the latest official source code for real-time builds. The development approach is inspired by tutorials from authors such as ebkso. Thanks to everyone's dedication and sharing, enabling Armbian to run on an ever-growing range of devices.

The u-boot, kernel, and other resources used in this system are primarily sourced from the unifreq/openwrt_packit project. Some files have been contributed by users through Pull Requests and Issues in projects such as amlogic-s9xxx-openwrt, amlogic-s9xxx-armbian, luci-app-amlogic, u-boot, and kernel. To acknowledge these pioneers and contributors, all contributions since the repository's creation (2021-09-19) are recorded in CONTRIBUTORS.md. Thanks again to everyone for breathing new life and purpose into these devices.

Other Distributions Copy Chapter

• The amlogic-s9xxx-openwrt project provides the OpenWrt system for TV boxes, also applicable to Armbian-supported devices.
• The fnnas project provides the FnNAS system for TV boxes, also applicable to Armbian-supported devices.
• unifreq has created OpenWrt systems for a wide range of Amlogic, Rockchip, and Allwinner devices, serving as a benchmark project in the community. Highly recommended.
• Scirese has tested the build, installation, and usage of Arch Linux ARM / Manjaro systems on Android TV boxes. See his repository for details.
• 7Ji has published articles on reverse engineering and development for the Amlogic platform, covering topics such as installing ArchLinux ARM and analyzing the Amlogic boot mechanism. His ampart project provides a partition tool for reading and editing Amlogic eMMC partition tables and DTB partitions, enabling 100% utilization of eMMC space. The amlogic-s9xxx-archlinuxarm project provides build and usage instructions for Arch Linux ARM. The YAopenvfD project offers an alternative openvfd daemon implementation.
• 13584452567 is the pioneer for Rockchip device support in this repository. Through his contributions, support was expanded for numerous Rockchip devices including EAIDK-610, King3399, TN3399, Kylin3399, ZCube1-Max, tvi3315a, xiaobao, and more. He also maintains specialized kernels for Allwinner devices such as TQC-A01, and has provided extensive technical support and solutions in Discussions and Issues, making significant contributions to the community.
• cooip-jm shares many guides on Armbian, LXC, Docker, AdGuard, and other applications in his wiki. Recommended reading.

Links Copy Chapter

• armbian
• unifreq
• kernel.org

License Copy Chapter

The amlogic-s9xxx-armbian © OPHUB is licensed under GPL-2.0

File: build-armbian/README.cn.md Copy Chapter

构建文件说明

English Instructions | 中文说明 | 日本語説明

编译 Armbian 系统所需的文件按功能分类存放在各个子目录中。

armbian-files Copy Chapter

此目录存放 Armbian 构建过程中所需的全部文件。其中，common-files 目录存放与平台无关的通用文件，platform-files 目录存放各平台专用文件，different-files 目录存放针对不同设备的差异化配置文件。更多说明详见 documents 中的 12.15 章节。

所需固件将从 ophub/firmware 仓库自动下载至 common-files/usr/lib/firmware 目录。

kernel Copy Chapter

在 kernel 目录下创建与版本号对应的文件夹，如 stable/5.10.125。若需编译多个内核，依次创建各版本目录并放入对应的内核文件即可。内核文件可从 kernel 仓库下载，也可自行编译。若本地未预先存放内核文件，构建脚本将自动从 kernel 仓库下载。

u-boot Copy Chapter

系统引导文件。根据所用内核版本的不同，相应的 u-boot 文件将由安装或更新脚本自动获取和配置。所需的 u-boot 将从 ophub/u-boot 仓库自动下载至 u-boot 目录。

File: build-armbian/README.md Copy Chapter

Build Files Reference

English Instructions | 中文说明 | 日本語説明

The files required for compiling the Armbian system are organized in their respective directories.

armbian-files Copy Chapter

This directory contains all the files used during the Armbian build process. The common-files subdirectory holds platform-independent shared files, the platform-files subdirectory holds platform-specific files, and the different-files subdirectory holds device-specific configuration files. For further details, refer to Section 12.15 of the documentation.

Required firmware files are automatically downloaded from the ophub/firmware repository into the common-files/usr/lib/firmware directory.

kernel Copy Chapter

Create a version-specific folder under the kernel directory, e.g., stable/5.10.125. For multiple kernels, create separate directories sequentially and place the corresponding kernel files in each. Kernel files can be downloaded from the kernel repository, or you can compile them yourself. If no kernel files are present locally, the build script will automatically download them from the kernel repository.

u-boot Copy Chapter

System bootloader files. Depending on the kernel version, the appropriate u-boot files are automatically managed by the installation and update scripts as needed. Required u-boot files are automatically downloaded from the ophub/u-boot repository into the u-boot directory.

File: compile-kernel/README.cn.md Copy Chapter

内核编译与使用指南

English Instructions | 中文说明 | 日本語説明

本项目编译的内核兼容 Armbian 和 OpenWrt 系统，可用于 amlogic-s9xxx-armbian、amlogic-s9xxx-openwrt、flippy-openwrt-actions 和 unifreq/openwrt_packit 等项目。既可在编译固件时集成，也可安装到已有系统中使用。

你可以根据需要调整内核配置，例如添加驱动和补丁。也可以编译带有个性化签名的内核，如 5.10.95-happy-new-year、5.10.96-beijing-winter-olympics、5.10.99-valentines-day 等。

内核仓库 Copy Chapter

在 ophub/kernel 的 Releases 中提供了预编译的内核文件。

本地编译 Copy Chapter

• 在 Ubuntu 系统下运行 Copy Section

1. 克隆仓库到本地：git clone --depth 1 https://github.com/ophub/amlogic-s9xxx-armbian.git

2. 安装必要的软件包（以 Ubuntu 24.04 为例）：

进入 ~/amlogic-s9xxx-armbian 根目录，然后执行安装命令：

sudo apt-get update -y
sudo apt-get full-upgrade -y
# For Ubuntu-24.04
sudo apt-get install -y $(cat compile-kernel/tools/script/ubuntu2404-build-armbian-depends)

3. 进入 ~/amlogic-s9xxx-armbian 根目录，执行 sudo ./recompile -k 5.15.100 等指定参数命令即可编译内核。脚本将自动下载并安装编译环境和内核源代码，并完成全部配置。编译完成的内核文件保存在当前源码树的 compile-kernel/output 目录中，或通过 -h 参数指定的目录中。

• 在 Armbian 系统下运行 Copy Section

可以直接在 Armbian 系统中编译内核，也可以在 Ubuntu/Debian 等系统上通过 Docker 容器运行 Armbian 系统来编译内核。Armbian 系统 Docker 镜像的制作方法可参考 armbian_docker 构建脚本。

1. 更新本地编译环境和配置文件：armbian-kernel -u

2. 编译内核：执行 armbian-kernel -k 5.15.100 等指定参数命令即可编译内核。脚本将自动下载并安装编译环境和内核源代码，并完成全部配置。编译完成的内核文件保存在 /opt/kernel/compile-kernel/output 目录中。

• 本地编译参数说明 Copy Section

• sudo ./recompile : 使用默认配置编译内核。
• sudo ./recompile -k 5.15.100 : 使用默认配置，并通过 -k 进行指定需要编译的内核版本，多个版本同时编译时使用 _ 进行连接。
• sudo ./recompile -k 5.15.100 -f stable : 使用默认配置，并通过 -k 5.15.100 参数指定需要编译的内核版本，通过 -f stable 参数指定从内核仓库下载 stable 目录下的配置文件。
• sudo ./recompile -k 5.15.100 -a true : 使用默认配置，并通过 -a 参数设置编译内核时，是否自动升级到同系列最新内核。
• sudo ./recompile -k 5.15.100 -n -ophub : 使用默认配置，并通过 -n 参数设置内核自定义签名。
• sudo ./recompile -k 5.15.100 -m dtbs : 使用默认配置，并通过 -m 参数指定仅制作 dtbs 文件。
• sudo ./recompile -k 5.15.100_6.1.10 -a true -n -ophub : 使用默认配置，并通过多个参数进行设置。

’ 提示：推荐使用 unifreq 的 linux-6.1.y、linux-5.15.y、linux-5.10.y 等仓库的内核源代码进行编译，其中已针对相关设备添加了驱动和补丁。配置文件推荐使用 ophub/kernel 中的模板，已针对支持的设备进行了预配置，可在此基础上进行个性化定制。

使用 GitHub Actions 编译内核 Copy Chapter

1. 在 Action 页面选择 Compile the kernel，点击 Run workflow 按钮即可开始编译。

2. 详见模板 compile-kernel-via-docker.yml。代码如下：

- name: Compile the kernel
  uses: ophub/amlogic-s9xxx-armbian@main
  with:
    build_target: kernel
    kernel_version: 6.12.y_6.18.y
    kernel_auto: true
    kernel_sign: -yourname

’ 注意：若你 fork 仓库并进行了修改，使用时须将 Actions 的用户名改为你自己的仓库，例如：

uses: YOUR-REPO/amlogic-s9xxx-armbian@main

• GitHub Action 输入参数说明 Copy Section

相关参数与本地编译命令相对应，请参考上述说明。

• GitHub Action 输出变量说明 Copy Section

上传到 Releases 需要给仓库设置 Workflow 读写权限，详见使用说明。

内核使用指南 Copy Chapter

本项目编译的内核兼容 Armbian 和 OpenWrt 系统。以下以 ophub 的项目为例进行说明。

在 Armbian 系统中使用 Copy Section

以下分别介绍如何在编译 Armbian 固件时集成内核，以及如何将内核安装到已有系统中。

• 使用内核编译 Armbian 固件

Armbian 固件编译支持本地操作，也支持通过 github.com 的 Actions 在线编译。本地编译方法详见：本地化打包，使用 Actions 在线编译的方法详见：使用 GitHub Actions 进行编译

• 将内核安装到已有的 Armbian 系统

使用 armbian-update 命令可将编译好的内核安装到已有的 Armbian 系统中，具体操作方法详见：更新 Armbian 内核

• 自定义编译驱动模块

在 Linux 主线内核中，部分驱动尚未被支持，可自行编译所需的驱动模块。具体操作方法详见：编译驱动模块

在 OpenWrt 系统中使用 Copy Section

以下分别介绍如何在 OpenWrt 系统编译固件时集成内核，以及如何将内核安装到已有系统中。

• 使用内核编译 OpenWrt 固件

OpenWrt 固件编译支持本地操作，也支持通过 github.com 的 Actions 在线编译。本地编译方法详见：本地化打包，使用 Actions 在线编译的方法详见：使用 Github Actions 进行编译

• 将内核安装到已有的 OpenWrt 系统

使用 luci-app-amlogic 插件可将编译好的内核安装到已有的 OpenWrt 系统中，具体操作方法详见：升级 OpenWrt

File: compile-kernel/README.md Copy Chapter

Kernel Compilation and Usage Guide

English Instructions | 中文说明 | 日本語説明

The compiled kernel is compatible with both Armbian and OpenWrt systems. It can be used in projects such as amlogic-s9xxx-armbian, amlogic-s9xxx-openwrt, flippy-openwrt-actions, and unifreq/openwrt_packit. The kernel can be integrated during firmware compilation or installed into an existing system.

You can adjust the kernel configuration as needed—for example, adding drivers and patches. You can also compile personalized kernels with custom signatures, such as 5.10.95-happy-new-year, 5.10.96-beijing-winter-olympics, 5.10.99-valentines-day, and so on.

Kernel Repository Copy Chapter

Pre-compiled kernels are available in the Releases of ophub/kernel.

Local Compilation Copy Chapter

• Running on Ubuntu System Copy Section

1. Clone the repository to local: git clone --depth 1 https://github.com/ophub/amlogic-s9xxx-armbian.git

2. Install the required packages (for Ubuntu 24.04):

Navigate to the ~/amlogic-s9xxx-armbian root directory, then run the installation command:

sudo apt-get update -y
sudo apt-get full-upgrade -y
# For Ubuntu-24.04
sudo apt-get install -y $(cat compile-kernel/tools/script/ubuntu2404-build-armbian-depends)

3. Navigate to the ~/amlogic-s9xxx-armbian root directory, then run sudo ./recompile -k 5.15.100 or other specified parameters to compile the kernel. The script automatically downloads and installs the build environment and kernel source code, and completes all necessary configuration. The compiled kernel files are saved in the compile-kernel/output directory within the source tree, or in the directory specified by the -h option.

• Running on Armbian System Copy Section

You can compile the kernel directly in an Armbian system, or run the Armbian system within a Docker container on Ubuntu/Debian to compile the kernel. For instructions on creating the Armbian Docker image, refer to the armbian_docker build script.

1. Update the local build environment and configuration files: armbian-kernel -u

2. Compile the kernel: Run armbian-kernel -k 5.15.100 or other specified parameters to compile the kernel. The script automatically downloads and installs the build environment and kernel source code, and completes all necessary configuration. The compiled kernel files are saved in the /opt/kernel/compile-kernel/output directory.

• Local Compilation Parameter Reference Copy Section

• sudo ./recompile: Compile the kernel using the default configuration.
• sudo ./recompile -k 5.15.100: Use the default configuration and specify the kernel version to be compiled through -k. Multiple versions are connected using _ for simultaneous compilation.
• sudo ./recompile -k 5.15.100 -f stable : Use the default configuration and specify the kernel version to be compiled through -k 5.15.100, and specify the configuration files to be downloaded from the stable directory of the kernel repository through -f stable.
• sudo ./recompile -k 5.15.100 -a true: Use the default configuration and set whether to automatically upgrade to the latest kernel of the same series during kernel compilation through the -a parameter.
• sudo ./recompile -k 5.15.100 -n -ophub: Use the default configuration and set the kernel custom signature through the -n parameter.
• sudo ./recompile -k 5.15.100 -m dtbs: Use the default configuration and specify only the creation of dtbs files through the -m parameter.
• sudo ./recompile -k 5.15.100_6.1.10 -a true -n -ophub: Use the default configuration and set multiple parameters.

💡 Tip: We recommend using the kernel source code from repositories such as linux-6.1.y, linux-5.15.y, linux-5.10.y of unifreq for compilation, who added drivers and patches for related boxes. It is recommended to use the template in ophub/kernel, which has been pre-configured according to the related boxes and can be customized based on this.

Compile Kernel Using GitHub Actions Copy Chapter

1. In the Action page, select Compile the kernel and click the Run workflow button to compile.

2. See the use of the template compile-kernel-via-docker.yml. The code is as follows:

- name: Compile the kernel
  uses: ophub/amlogic-s9xxx-armbian@main
  with:
    build_target: kernel
    kernel_version: 6.12.y_6.18.y
    kernel_auto: true
    kernel_sign: -yourname

’ Note: If you fork the repository and make modifications, you must change the Actions username to your own repository when using it, for example:

uses: YOUR-REPO/amlogic-s9xxx-armbian@main

• GitHub Action Input Parameters Copy Section

These parameters correspond to the local compilation commands. Refer to the descriptions above.

• GitHub Action Output Variables Copy Section

To upload to Releases, you need to set Workflow read/write permissions for the repository. For details, see Usage Instructions.

Kernel Usage Guide Copy Chapter

The compiled kernel supports both Armbian and OpenWrt systems. The following examples use ophub's projects.

Using in Armbian Copy Section

The following sections describe how to integrate the kernel during Armbian firmware compilation and how to install it in an existing system.

• Compiling Armbian Firmware with the Kernel

Armbian firmware compilation supports both local and online workflows via GitHub Actions. For local compilation, see Local Packaging. For online compilation via Actions, see Using GitHub Actions for Compilation.

• Installing the Kernel in an Existing Armbian System

Use the armbian-update command to install the compiled kernel into an existing Armbian system. For detailed instructions, see Update Armbian Kernel.

• Compiling Custom Driver Modules

Some drivers are not yet included in the Linux mainline kernel. You can compile custom driver modules as needed. For instructions, see Compile Driver Module.

Using in OpenWrt Copy Section

The following sections describe how to integrate the kernel during OpenWrt firmware compilation and how to install it in an existing system.

• Compiling OpenWrt Firmware with the Kernel

OpenWrt firmware compilation supports both local and online workflows via GitHub Actions. For local compilation, see Local Packaging. For online compilation via Actions, see Use GitHub Actions for Compilation.

• Installing the Kernel in an Existing OpenWrt System

Use the luci-app-amlogic plugin to install the compiled kernel into an existing OpenWrt system. For detailed instructions, see Update OpenWrt.

File: documents/README.cn.md Copy Chapter

Armbian 构建及使用方法

English Instructions | 中文说明 | 日本語説明

GitHub Actions 是 Microsoft 推出的一项服务，提供高性能的虚拟服务器环境，可用于构建、测试、打包和部署项目。公开仓库可免费无时间限制地使用，单次编译时间长达 6 小时，足以满足 Armbian 的编译需求（通常 3 小时左右即可完成编译）。本项目仅供技术交流，不足之处敬请谅解。请勿发起网络攻击或恶意使用 GitHub Actions。

目录

• Armbian 构建及使用方法
• 目录
  • 1. 注册自己的 Github 的账户
  • 2. 设置隐私变量 GITHUB_TOKEN 等
  • 3. Fork 仓库并设置工作流权限
  • 4. 个性化 Armbian 系统定制文件说明
  • 5. 编译系统
    • 5.1 手动编译
    • 5.2 定时编译
    • 5.3 自定义默认系统配置
    • 5.4 使用逻辑卷扩大 Github Actions 编译空间
    • 5.5 制作 Armbian Docker 镜像
  • 6. 保存系统
  • 7. 下载系统
  • 8. 安装 Armbian 到 EMMC
    • 8.1 Amlogic 系列安装方法
    • 8.2 Rockchip 系列安装方法
      • 8.2.1 Radxa-Rock5B 的安装方法
        • 8.2.1.1 安装系统至 microSD
        • 8.2.1.2 安装系统至 eMMC
        • 8.2.1.3 安装系统至 NVMe
      • 8.2.2 电犀牛 R66S 的安装方法
      • 8.2.3 电犀牛 R68S 的安装方法
      • 8.2.4 贝壳云的安装方法
      • 8.2.5 我家云的安装方法
      • 8.2.6 泰山派的安装方法
    • 8.3 Allwinner 系列安装方法
    • 8.4 Docker 版本的 Armbian 安装方法
      • 8.4.1 安装 Docker 运行环境
      • 8.4.2 设置 macvlan 网络
      • 8.4.3 运行 Armbian Docker 容器
  • 9. 编译 Armbian 内核
    • 9.1 如何添加自定义内核补丁
    • 9.2 如何制作内核补丁
    • 9.3 如何自定义编译驱动模块
  • 10. 更新 Armbian 内核
  • 11. 安装常用软件
  • 12. 常见问题
    • 12.1 每个盒子的 dtb 和 u-boot 对应关系表
    • 12.2 LED 屏显示控制说明
    • 12.3 如何恢复原安卓 TV 系统
      • 12.3.1 使用 armbian-ddbr 备份恢复
      • 12.3.2 使用 Amlogic 刷机工具恢复
    • 12.4 设置盒子从 USB/TF/SD 中启动
      • 12.4.1 初次安装 Armbian 系统
      • 12.4.2 重新安装 Armbian 系统
    • 12.5 禁用红外接收器
    • 12.6 启动引导文件的选择
    • 12.7 网络设置
      • 12.7.1 使用 interfaces 设置网络
        • 12.7.1.1 由 DHCP 动态分配 IP 地址
        • 12.7.1.2 手动设置静态 IP 地址
        • 12.7.1.3 在 docker 中使用 OpenWrt 建立互通网络
      • 12.7.2 使用 NetworkManager 管理网络
        • 12.7.2.1 新建网络连接
          • 12.7.2.1.1 获取网络接口名称
          • 12.7.2.1.2 获取现有网络连接名称
          • 12.7.2.1.3 新建有线网络连接
          • 12.7.2.1.4 新建无线网络连接
        • 12.7.2.2 修改无线网络连接中的 WiFi SSID or PASSWD
        • 12.7.2.3 修改网络地址分配方式
          • 12.7.2.3.1 静态 IP 地址 - IPv4
          • 12.7.2.3.2 DHCP 获取动态 IP 地址 - IPv4 / IPv6
        • 12.7.2.4 修改网络连接 MAC 地址
          • 12.7.2.4.1 方法一：使用 nmcli 命令修改 MAC 地址
          • 12.7.2.4.2 方法二：通过配置文件修改 MAC 地址
        • 12.7.2.5 如何禁用 IPv6
      • 12.7.3 如何启用无线
      • 12.7.4 如何启用蓝牙
    • 12.8 如何添加开机启动任务
    • 12.9 如何更新系统中的服务脚本
    • 12.10 如何获取 eMMC 上的安卓系统分区信息
      • 12.10.1 获取分区信息
      • 12.10.2 分区信息分享
      • 12.10.3 分区信息解读
      • 12.10.4 用于 eMMC 安装
    • 12.11 如何制作 u-boot 文件
      • 12.11.1 如何制作 Amlogic 设备的 u-boot 文件
        • 12.11.1.1 如何提取 bootloader 和 dtb 文件
        • 12.11.1.2 如何制作 acs.bin 文件
        • 12.11.1.3 如何编译 u-boot 文件
      • 12.11.2 如何制作 Rockchip 设备的 u-boot 文件
        • 12.11.2.1 如何使用 Radxa 的 u-boot 制作脚本
        • 12.11.2.2 如何使用 cm9vdA 的 u-boot 制作脚本
    • 12.12 内存大小识别错误
    • 12.13 如何反编译 dtb 文件
      • 12.13.1 直接反编译 dtb 文件
      • 12.13.2 从运行中的设备导出完全态 DTS（推荐）
    • 12.14 如何修改 cmdline 设置
    • 12.15 如何添加新的支持设备
      • 12.15.1 添加设备配置文件
      • 12.15.2 添加系统文件
      • 12.15.3 添加 u-boot 文件
        • 12.15.3.1 查看分区信息布局情况
        • 12.15.3.2 备份关键分区
        • 12.15.3.3 添加特殊分区写入文件
      • 12.15.4 添加流程控制文件
    • 12.16 如何解决写入 eMMC 时 I/O 错误的问题
    • 12.17 如何解决 Bullseye 版本没有声音的问题
    • 12.18 如何编译 boot.scr 文件
    • 12.19 如何开启远程桌面和修改默认端口
    • 12.20 TCP 拥塞控制优化方案
    • 12.21 关于 HDMI EDID 识别异常问题的解决方法

1. 注册自己的 Github 的账户 Copy Chapter

注册账户以进行后续的系统定制操作。点击 github.com 网站右上角的 Sign up 按钮，根据提示完成注册。

2. 设置隐私变量 GITHUB_TOKEN 等 Copy Chapter

根据 GitHub 文档，在每个工作流作业开始时，GitHub 会自动创建唯一的 GITHUB_TOKEN 机密以在工作流中使用。可以使用 ${{ secrets.GITHUB_TOKEN }} 在工作流作业中进行身份验证。

在 Actions 中制作 Armbian Docker 镜像并推送到 Docker Hub 时，需要设置 DOCKERHUB_USERNAME 和 DOCKERHUB_PASSWORD 两个隐私变量。在自己的仓库页面，点击右上角的 Settings > Secrets and variables > Actions > Repository secrets > New repository secret 按钮，添加如下两个隐私变量：

• 变量名 DOCKERHUB_USERNAME：值是登录 Docker Hub 的用户名
• 变量名 DOCKERHUB_PASSWORD：值是登录 Docker Hub 的密码

3. Fork 仓库并设置工作流权限 Copy Chapter

打开仓库 https://github.com/ophub/amlogic-s9xxx-armbian ，点击右上角的 Fork 按钮，将仓库代码复制到自己的账户下。Fork 完成后，访问自己账户中的 amlogic-s9xxx-armbian 仓库，在右上角的 Settings > Actions > General > Workflow permissions 下选择 Read and write permissions 并保存。操作示意如下：

4. 个性化 Armbian 系统定制文件说明 Copy Chapter

系统编译流程由 .github/workflows/build-armbian-arm64-server-image.yml 文件控制，workflows 目录下的其他 .yml 文件用于实现不同功能。编译时采用 Armbian 官方的最新代码进行实时编译，相关参数请参阅官方文档。

- name: Compile Armbian [ ${{ inputs.set_release }} ]
  id: compile
  if: ${{ steps.down.outputs.status }} == 'success' && !cancelled()
  run: |
    # Compile method and parameter description: https://docs.armbian.com/Developer-Guide_Build-Options
    cd build/
        ./compile.sh RELEASE=${{ inputs.set_release }} BOARD=odroidn2 BRANCH=current BUILD_MINIMAL=no \
                      BUILD_ONLY=default HOST=armbian BUILD_DESKTOP=no EXPERT=yes KERNEL_CONFIGURE=no \
                      COMPRESS_OUTPUTIMAGE="sha" SHARE_LOG=yes
    echo "status=success" >> ${GITHUB_OUTPUT}

使用 ophub 打包 Armbian 时，可通过 armbian_files 参数将自定义文件添加或覆盖至 ophub 的 common-files 目录。目录结构必须与 Armbian 根目录保持一致，以确保文件被正确覆盖到固件中（例如：默认配置文件应存放于 etc/default/ 子目录下）。示例如下：

- name: Rebuild Armbian
  uses: ophub/amlogic-s9xxx-armbian@main
  with:
    build_target: armbian
    armbian_path: build/output/images/*.img.gz
    armbian_files: files
    ...

5. 编译系统 Copy Chapter

系统编译支持多种方式，包括手动编译、定时编译以及特定事件触发编译。

5.1 手动编译 Copy Section

在仓库导航栏中点击 Actions，依次点击 Build armbian > Run workflow > Run workflow 即可开始编译。全部流程约需 3 小时。操作示意如下：

5.2 定时编译 Copy Section

在 .github/workflows/build-armbian-arm64-server-image.yml 文件里，使用 Cron 设置定时编译，5 个不同位置分别代表的意思为 分钟 (0 - 59) / 小时 (0 - 23) / 日期 (1 - 31) / 月份 (1 - 12) / 星期几 (0 - 6)(星期日 - 星期六)。通过修改不同位置的数值来设定时间。系统默认使用 UTC 标准时间，请根据你所在国家时区的不同进行换算。

schedule:
  - cron: '0 17 * * *'

5.3 自定义默认系统配置 Copy Section

默认系统配置信息记录在 model_database.conf 文件中，BOARD 名称必须唯一。

其中 BUILD 值为 yes 的是默认构建的设备，这些设备可直接使用对应系统。默认值为 no 的设备未包含在默认构建中，使用时需下载相同 FAMILY 的已构建系统。写入 USB 后，在电脑上打开 USB 中的 boot 分区，修改 /boot/uEnv.txt 文件中的 FDT dtb 名称，即可适配列表中的其他设备。

本地编译时通过 -b 参数指定，GitHub Actions 编译时通过 armbian_board 参数指定。-b all 表示构建所有 BUILD 为 yes 的设备。指定 BOARD 参数时，无论 BUILD 值为 yes 或 no 均可构建，例如：-b r68s_s905x3-tx3_s905l3a-cm311

5.4 使用逻辑卷扩大 Github Actions 编译空间 Copy Section

GitHub Actions 默认编译空间为 84G，去除系统和必要软件包后可用空间约 50G。编译全部固件时可能遇到空间不足的问题，可通过逻辑卷将编译空间扩大至约 110G。参照 .github/workflows/build-armbian-arm64-server-image.yml 文件中的方法，使用以下命令创建逻辑卷，并在编译时使用逻辑卷路径。

- name: Create simulated physical disk
  run: |
    mnt_size=$(expr $(df -h /mnt | tail -1 | awk '{print $4}' | sed 's/[[:alpha:]]//g' | sed 's/\..*//') - 1)
    root_size=$(expr $(df -h / | tail -1 | awk '{print $4}' | sed 's/[[:alpha:]]//g' | sed 's/\..*//') - 4)
    sudo truncate -s "${mnt_size}"G /mnt/mnt.img
    sudo truncate -s "${root_size}"G /root.img
    sudo losetup /dev/loop6 /mnt/mnt.img
    sudo losetup /dev/loop7 /root.img
    sudo pvcreate /dev/loop6
    sudo pvcreate /dev/loop7
    sudo vgcreate github /dev/loop6 /dev/loop7
    sudo lvcreate -n runner -l 100%FREE github
    sudo mkfs.xfs /dev/github/runner
    sudo mkdir -p /builder
    sudo mount /dev/github/runner /builder
    sudo chown -R runner:runner /builder
    df -Th

5.5 制作 Armbian Docker 镜像 Copy Section

Armbian 系统 Docker 镜像的制作方法请参考 armbian_docker 制作脚本。

6. 保存系统 Copy Chapter

系统保存设置同样在 .github/workflows/build-armbian-arm64-server-image.yml 文件中控制。编译完成的系统将通过脚本自动上传至 GitHub 官方的 Releases。

- name: Upload Armbian image to Release
  uses: ophub/upload-to-release@main
  if: ${{ env.PACKAGED_STATUS }} == 'success' && !cancelled()
  with:
    tag: Armbian_${{ env.ARMBIAN_RELEASE }}_${{ env.PACKAGED_OUTPUTDATE }}
    artifacts: ${{ env.PACKAGED_OUTPUTPATH }}/*
    allow_updates: true
    gh_token: ${{ secrets.GITHUB_TOKEN }}
    body: |
      These are the Armbian OS image
      * OS information
      Default username: root
      Default password: 1234
      Install command: armbian-install
      Update command: armbian-update

7. 下载系统 Copy Chapter

从仓库首页右下角的 Release 版块进入，选择与自身设备型号对应的系统。操作示意如下：

8. 安装 Armbian 到 EMMC Copy Chapter

Amlogic、Rockchip 和 Allwinner 的安装方法各不相同。不同设备支持不同的存储介质，包括外置 microSD 卡、eMMC 和 NVMe 等，以下按设备类型分别介绍安装方法。首先从 Releases 下载对应设备的 Armbian 系统，解压为 .img 格式备用，然后根据设备类型参照以下相应章节进行安装。

安装完成后，将设备接入路由器，开机约 2 分钟后，在路由器中查找设备名称为 Armbian 的 IP 地址，使用 SSH 工具连接即可进行管理配置。默认用户名为 root，默认密码为 1234，默认端口为 22

8.1 Amlogic 系列安装方法 Copy Section

登录 Armbian 系统 (默认用户: root, 默认密码: 1234) → 输入命令：

armbian-install

举例: armbian-install -m yes -a no

8.2 Rockchip 系列安装方法 Copy Section

各设备的安装方法如下。

8.2.1 Radxa-Rock5B 的安装方法

Radxa-Rock5B 支持 microSD/eMMC/NVMe 等多种存储介质，安装方法因介质而异。下载 rk3588_spl_loader_v1.08.111.bin 和 spi_image.img 文件备用。下载 RKDevTool 工具及驱动备用。下载 Rufus 或者 balenaEtcher 写盘工具备用。

8.2.1.1 安装系统至 microSD

使用 Rufus 或 balenaEtcher 等工具将 Armbian 系统镜像写入 microSD，然后将 microSD 插入设备即可使用。

8.2.1.2 安装系统至 eMMC

使用 microSD 卡安装：将 Armbian 系统镜像写入 microSD 卡，将 microSD 卡插入设备并启动，上传 armbian.img 镜像文件到 microSD 卡，使用 dd 命令将 Armbian 镜像写入 NVMe，命令如下：

dd if=armbian.img  of=/dev/mmcblk1  bs=1M status=progress

• 使用 USB 转 eMMC 读卡器安装：将 eMMC 模块与电脑连接，使用 Rufus 或 balenaEtcher 等工具将 Armbian 系统镜像写入 eMMC，然后将 eMMC 插入设备即可使用。
• 使用 Maskrom 模式安装：关闭开发板电源。按住金色按钮。将 USB-A 转 C 型电缆插入 ROCK 5B C 型端口，另一端插入 PC。松开金色按钮。检查 USB 设备提示找到一个 MASKROM 设备。右键单击列表的空白区域，然后选择加载 rock-5b-emmc.cfg 配置文件（配置文件和 RKDevTool 在同一个目录下）。将 rk3588_spl_loader_v1.08.111.bin 和 Armbian.img 按下图所示设置，选择写入即可。

8.2.1.3 安装系统至 NVMe

ROCK-5B 主板配备 SPI 闪存，将引导加载程序写入 SPI 闪存后，可支持 SoC maskrom 模式不直接支持的启动介质（如 SATA、USB3 或 NVMe）。使用 NVMe 启动前需先写入 SPI 文件，方法如下：

关闭开发板电源，移除 MicroSD 卡、eMMC 模块等可启动设备。按住金色（或部分修订版上的银色）按钮，将 USB-A 转 Type-C 线缆插入 ROCK-5B 的 Type-C 端口，另一端插入 PC。松开按钮，检查 USB 设备是否发现 MASKROM 设备。在列表框中右键选择加载配置，在资源管理器中选择配置文件（配置文件和 RKDevTool 在同一目录下），根据下图选择 rk3588_spl_loader_v1.08.111.bin 和 spi_image.img 文件，点击写入即可，如下图所示：

• 使用读卡器安装：将 M.2 NVMe SSD 插入 M.2 NVMe SSD 转 USB3.0 读卡器以连接到主机。使用 Rufus 或 balenaEtcher 等工具将 Armbian 系统镜像写入 NVMe，然后将 NVMe 插入设备即可使用。
• 使用 microSD 卡安装：将 Armbian 系统镜像写入 microSD 卡，将 microSD 卡插入设备并启动，上传 armbian.img 镜像文件到 microSD 卡，使用 dd 命令将 Armbian 镜像写入 NVMe 中，命令如下：

dd if=armbian.img  of=/dev/nvme0n1  bs=1M status=progress

8.2.2 电犀牛 R66S 的安装方法

使用 Rufus 或 balenaEtcher 等工具将 Armbian 系统镜像写入 microSD，然后将 microSD 插入设备即可使用。

8.2.3 电犀牛 R68S 的安装方法

• 下载 RKDevTool 工具及驱动，解压并安装 DriverAssitant 驱动程序，打开 RKDevTool 工具备用。
• R68s 在关机状态下，先插入 USB 双公头线，然后按住 Recovery 键并插上 12V 电源，两秒之后松开 Recovery 键，刷机工具会发现一个 LOADER 设备。
• 在 RKDevTool 工具操作界面的空白处点右键，添加项。
• 地址是 0x00000000，名字是 armbian，路径点击右侧选择 armbian.img 系统文件。
• 选择添加的 armbian 一行外，取消其他行的选择，点击执行写入即可。
• 补充说明：如果 eMMC 中写入了其他系统，请先在高级功能里擦除，再写入 Armbian 系统。如果无法擦除，先重新写入一次 MiniLoaderAll.bin 引导文件，然后再次进入 MASKROM 写入 Armbian 系统。MiniLoaderAll.bin 引导文件设置：地址 0xCCCCCCCC, 名字 Loader, 路径选择 RKDevTool 刷机工具 Image 目录下的 MiniLoaderAll.bin 文件。

8.2.4 贝壳云的安装方法

方法转载自 milton 的教程。刷机需要进入 Maskrom 模式。先断开所有连接，通过短接 CLK 和 GND（使用 TTL 的 GND, 或者旁边小按钮的 GND 均可）这两个触点，然后将 USB 连接到 PC 就会检测到 MASKROM 设备了。短接点位置如下：

打开 RKDevTool 刷机工具，右键添加项。

• 地址 0xCCCCCCCC, 名字 Boot, 路径选择 rk3328_loader_v1.14.249.bin。
• 地址 0x00000000, 名字 system, 路径选择要刷的 Armbian.img 系统。
• 勾选强制按地址写入，点执行，等右侧下载面板显示进度完成即可。

8.2.5 我家云的安装方法

方法转载自 cc747 的教程。刷机需要进入 Maskrom 模式。确保设备处于断电状态，拔掉所有线缆。用 USB 双公头线，一头插入我家云的 USB2.0 接口，一头插入电脑。用回形针插入 Reset 孔并按住不松开。插入电源线，等待数秒，直到 RKDevTool 下方出现发现一个LOADER设备后松开回形针。将 RKDevTool 切换到高级功能点击进入Maskrom按钮，提示发现一个MASKROM设备。右键添加项。

• 地址 0xCCCCCCCC, 名字 Boot, 路径选择 rk3328_loader_v1.14.249.bin。
• 地址 0x00000000, 名字 system, 路径选择要刷的 Armbian.img 系统。
• 勾选强制按地址写入，点执行，等右侧下载面板显示进度完成即可。

8.2.6 泰山派的安装方法

• 下载 RKDevTool 工具及驱动，解压并安装 DriverAssitant 驱动程序，打开 RKDevTool 工具。(注意，请使用2.86版本工具而不是2.92，2.92版本刷入时会闪退)
• 泰山派关机状态下按住 Recovery 键后插入type-c数据线，待 RKDevTool 提示发现一个 LOADER 设备后松开 Recovery 键。右键添加项。
• 地址 0x00000000, 名字 system, 路径选择要刷的 Armbian.img 系统。
• 点击执行，等待进度条完成即可

8.3 Allwinner 系列安装方法 Copy Section

登录 Armbian 系统 (默认用户: root, 默认密码: 1234) → 输入命令：

armbian-install

8.4 Docker 版本的 Armbian 安装方法 Copy Section

可以在 Ubuntu/Debian/Armbian 系统中使用 Docker 版本的 Armbian 镜像。这些镜像托管在 Docker Hub 上，可以直接下载使用。

提供了四个不同内核版本的 Armbian Docker 镜像：armbian-trixie，armbian-bookworm，armbian-noble，armbian-resolute。每个版本均提供 arm64 和 amd64 架构，可根据需要选择。

其中 armbian-trixie 基于 debian13，armbian-bookworm 基于 debian12，armbian-noble 基于 ubuntu24.04，armbian-resolute 基于 ubuntu26.04。

arm64 版本适用于 Amlogic/Rockchip/Allwinner 等平台架构的设备，amd64 版本适用于 x86_64 架构的电脑和服务器。

8.4.1 安装 Docker 运行环境

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
sudo newgrp docker

8.4.2 设置 macvlan 网络

# 查看已有的 docker 网络是否包含 macvlan 网络
docker network ls

# 如果没有 macvlan 网络，则创建 macvlan 网络
# 其中的网段、网关和网卡名称根据自己的实际网络修改
docker network create -d macvlan \
    --subnet=10.1.1.0/24 \
    --gateway=10.1.1.1 \
    -o parent=eth0 \
    macvlan

8.4.3 运行 Armbian Docker 容器

以 armbian-trixie:arm64 镜像为例，说明如何运行 Armbian 容器。

# 以后台方式运行 Armbian 容器
# 其中的容器名称，IP 地址，镜像版本等根据自己的实际情况修改
docker run -itd --name=armbian-trixie \
    --privileged \
    --network macvlan \
    --ip 10.1.1.15 \
    --hostname=armbian-trixie \
    -e TZ=Asia/Shanghai \
    --restart unless-stopped \
    ophub/armbian-trixie:arm64

# 查看 Armbian 容器日志
docker logs -f armbian-trixie

# 进入 Armbian 容器
docker exec -it armbian-trixie bash

# 退出 Armbian 容器
exit

# 停止并删除 Armbian 容器
docker rm -f armbian-trixie

9. 编译 Armbian 内核 Copy Chapter

支持在 Ubuntu、Debian 或 Armbian 系统中编译内核，同时支持本地编译和 GitHub Actions 云编译，具体方法详见 内核编译说明。

9.1 如何添加自定义内核补丁 Copy Section

当内核补丁目录 tools/patch 中有通用内核补丁目录（common-kernel-patches），或者有 与内核源码库同名 的目录时（例如 linux-5.15.y），可以使用 -p true 自动应用内核补丁。补丁目录的命名规范如下：

~/amlogic-s9xxx-armbian
    └── compile-kernel
        └── tools
            └── patch
                ├── common-kernel-patches  # 固定目录名：存放各版本都通用的内核补丁
                ├── linux-5.15.y           # 与内核源码库同名：存放专用补丁
                ├── linux-6.1.y
                ├── linux-5.10.y-rk35xx
                └── more kernel directory...

• 在本地编译内核时，可以手动创建相应目录，添加对应的自定义内核补丁。
• 在 GitHub Actions 云编译时，可通过 kernel_patch 参数指定内核补丁在仓库中的目录，例如 kernel 仓库中 compile-beta-kernel.yml 的使用方法：

- name: Compile the kernel
  uses: ophub/amlogic-s9xxx-armbian@main
  with:
    build_target: kernel
    kernel_version: 5.15.1_6.1.1
    kernel_auto: true
    kernel_patch: kernel-patch/beta
    auto_patch: true

当使用 kernel_patch 参数指定自定义内核补丁时，补丁目录请参照上述规范进行命名。

9.2 如何制作内核补丁 Copy Section

• 从 Armbian 和 OpenWrt 等仓库获取：例如 armbian/patch/kernel 和 openwrt/rockchip/patches-6.1，lede/rockchip/patches-5.15 等，这些基于主线内核的仓库中的补丁通常可直接使用。
• 从 github.com 仓库的 commits 中获取：在对应的 commit 地址后添加 .patch 后缀即可生成补丁。

添加自定义内核补丁前，需先与上游内核源码仓库 unifreq/linux-k.x.y 进行比对，确认该补丁尚未被合入，以避免冲突。通过测试的内核补丁，建议向 unifreq 维护的系列内核仓库提交。社区的每一份贡献，都将使 Armbian 和 OpenWrt 系统更加稳定可靠。

9.3 如何自定义编译驱动模块 Copy Section

Linux 主线内核中部分驱动尚未内置，可自行编译驱动模块。请选择支持主线内核的驱动，安卓驱动通常不兼容主线内核，无法编译。参考帖子 如何编译 rtl8189fs 驱动模块

示例如下：

# 第一步，更新最新内核
# 由于早期的 header 文件不全，所以需要更新到最新的内核。
# 各内核版本要求不低于 5.10.222, 5.15.163, 6.1.100, 6.6.41, 6.12, 6.18
armbian-sync
armbian-update -k 6.1


# 第二步，安装编译工具
mkdir -p /usr/local/toolchain
cd /usr/local/toolchain
# 下载编译工具
wget https://github.com/ophub/kernel/releases/download/dev/arm-gnu-toolchain-15.3.rel1-aarch64-aarch64-none-linux-gnu.tar.xz
# 解压
tar -Jxf arm-gnu-toolchain-15.3.rel1-aarch64-aarch64-none-linux-gnu.tar.xz
# 安装其他编译依赖包（可选项，可根据错误提示手动安装缺少项）
armbian-kernel -u


# 第三步，下载驱动，编译
# 下载驱动源码
cd ~/
git clone https://github.com/jwrdegoede/rtl8189ES_linux
cd rtl8189ES_linux
# 设置编译环境
gun_file="arm-gnu-toolchain-15.3.rel1-aarch64-aarch64-none-linux-gnu.tar.xz"
toolchain_path="/usr/local/toolchain"
toolchain_name="gcc"
export CROSS_COMPILE="${toolchain_path}/${gun_file//.tar.xz/}/bin/aarch64-none-linux-gnu-"
export CC="${CROSS_COMPILE}gcc"
export LD="${CROSS_COMPILE}ld.bfd"
export ARCH="arm64"
export KSRC=/usr/lib/modules/$(uname -r)/build
# 根据源码的实际路径设置 M 变量
export M="/root/rtl8189ES_linux"
# 编译驱动
make


# 第四步，安装驱动
sudo cp -f 8189es.ko /lib/modules/$(uname -r)/kernel/drivers/net/wireless/
# 更新模块依赖关系
sudo depmod -a
# 加载驱动模块
sudo modprobe 8189es
# 检查驱动是否加载成功
lsmod | grep 8189es
# 可以看到成功加载驱动
8189es               1843200  0
cfg80211              917504  2 8189es,brcmfmac

图示如下：

10. 更新 Armbian 内核 Copy Chapter

登录 Armbian 系统 → 输入命令：

# 使用 root 用户运行 (sudo -i)
# 如果不指定参数，将更新为最新版本。
armbian-update

举例: armbian-update -k 5.15 -u stable -d deb

通过 -k 参数指定内核版本号时，既可精确指定版本号（如 armbian-update -k 5.15.50），也可指定内核系列（如 armbian-update -k 5.15），指定系列时将自动使用该系列的最新版本。

更新内核时将自动备份当前使用的内核至 /ddbr/backup 目录，保留最近 3 个版本。若新内核不稳定，可随时恢复至备份版本：

# 进入备份的内核目录，如 6.6.12
cd /ddbr/backup/6.6.12
# 执行更新内核命令，会自动安装当前目录下的内核
armbian-update

[SOS]：当因异常情况导致更新不完整、系统无法从 eMMC/NVMe/sdX 启动时，可从 USB 等其他磁盘启动任意版本的 Armbian 系统，然后运行 armbian-update -s 命令将 USB 中的系统内核恢复至 eMMC/NVMe/sdX，实现系统救援。不指定磁盘参数时，默认从 USB 设备恢复 eMMC/NVMe/sdX 中的内核。若设备有多个磁盘，可精确指定目标磁盘名称，示例如下：

# 恢复 eMMC 中的内核
armbian-update -s mmcblk1
# 恢复 NVMe 中的内核
armbian-update -s nvme0n1
# 恢复移动存储设备中的内核
armbian-update -s sda
# 磁盘名称可以简写为 mmcblk0/mmcblk1/nvme0n1/nvme1n1/sda/sdb/sdc 等，也可以使用完整的名称，如 /dev/sda
armbian-update -s /dev/sda
# 当设备只有 eMMC/NVMe/sdX 中的一个内置存储时，可以省略磁盘名称参数
armbian-update -s

如果您因网络问题无法访问 github.com 进行在线更新，可以手动下载内核文件并上传至 Armbian 系统的任意目录。随后进入该目录，运行 armbian-update 命令即可执行本地安装。若当前目录下存在完整的内核文件集，系统将优先使用本地文件进行更新。内核支持 tar 和 deb 两种格式，各自所需的 4 个核心文件如下：

• tar 格式更新所需的 4 个文件为：header-xxx.tar.gz，boot-xxx.tar.gz，dtb-xxx.tar.gz，modules-xxx.tar.gz。
• deb 格式更新所需的 4 个文件为：linux-image-xxx.deb，linux-dtb-xxx.deb，linux-headers-xxx.deb，linux-libc-dev-xxx.deb。
• 无需移除其他无关的内核文件，即使它们同时存在也不会影响更新，系统能够精准识别所需文件。在设备支持的内核范围内，您可以自由切换版本，例如从 6.6.12 内核变更为 5.15.50 内核。

通过 -r/-u/-b/-d 等参数设置的自定义选项，可固化至配置文件 /etc/ophub-release 的相关参数中，无需每次手动输入。对应设置为：

# 自定义修改参数的赋值
-r  :  KERNEL_REPO='ophub/kernel'
-u  :  KERNEL_TAGS='stable'
-b  :  KERNEL_BACKUP='yes'
-d  :  DOWNLOAD_TYPE='deb'

11. 安装常用软件 Copy Chapter

登录 Armbian 系统 → 输入命令：

armbian-software

使用 armbian-software -u 命令可更新本地软件中心列表。根据用户在 Issue 中的反馈，逐步整合常用软件，支持一键安装、更新和卸载。包括 docker 镜像、桌面软件、应用服务 等。详见更多说明。

根据所在国家或地区，使用 armbian-apt 命令选择合适的软件源以提高下载速度。例如，选择中国的清华大学源：

/* Detailed source-code truncated for AI context efficiency. */

12. 常见问题 Copy Chapter

以下汇总了使用 Armbian 过程中可能遇到的常见问题。

12.1 每个盒子的 dtb 和 u-boot 对应关系表 Copy Section

支持的设备列表位于 Armbian 系统的配置文件 /etc/model_database.conf。

12.2 LED 屏显示控制说明 Copy Section

请查阅说明

12.3 如何恢复原安卓 TV 系统 Copy Section

通常使用 armbian-ddbr 对设备的安卓 TV 系统进行备份和恢复。

此外，也可通过线刷方式将安卓系统写入 eMMC。安卓系统镜像可在 Tools 中查找。

12.3.1 使用 armbian-ddbr 备份恢复

建议在安装 Armbian 系统前，先备份设备原有的安卓 TV 系统，以便后续需要时恢复。从 TF/SD/USB 启动 Armbian 系统后，输入 armbian-ddbr 命令，根据提示输入 b 执行备份，备份文件存放路径为 /ddbr/BACKUP-arm-64-emmc.img.gz，请妥善保存。需要恢复时，将备份文件上传至 TF/SD/USB 设备的相同路径，输入 armbian-ddbr 命令，根据提示输入 r 执行恢复。

12.3.2 使用 Amlogic 刷机工具恢复

• 通常情况下，重新接入电源后若能从 USB 启动，重新安装即可，可多次尝试。

• 若接入显示器后屏幕黑屏且无法从 USB 启动，则需对设备进行短接初始化。先将设备恢复至原安卓系统，再重新刷入 Armbian。首先下载并安装 amlogic_usb_burning_tool 系统恢复工具。准备一条 USB 双公头数据线，准备一个 曲别针。

• 以 x96max+ 为例，确认主板上短接点的位置，下载设备的 Android TV 系统包。其他常见设备的安卓 TV 系统及对应短接点示意图也可在此下载查看。

操作方法：

1. 打开刷机软件 USB Burning Tool:
   [ 文件 → 导入系统包 ]: X96Max_Plus2_20191213-1457_ATV9_davietPDA_v1.5.img
   [ 选择 ]：擦除 flash
   [ 选择 ]：擦除 bootloader
   点击 [ 开始 ] 按钮
2. 使用 [ 曲别针 ] 将盒子主板上的 [ 两个短接点进行短接连接 ]，
   并同时使用 [ USB 双公头数据线 ] 将 [ 盒子 ] 与 [ 电脑 ] 进行连接。
3. 当看到 [ 进度条开始走动 ] 后，拿走曲别针，不再短接。
4. 当看到 [ 进度条 100% ], 则刷机完成，盒子已经恢复成 Android TV 系统。
   点击 [ 停止 ] 按钮, 拔掉 [ 盒子 ] 和 [ 电脑 ] 之间的 [ USB 双公头数据线] 。
5. 如果以上某个步骤失败，就再来一次，直至成功。
   如果进度条没有走动，可以尝试插入电源。通常情况下不用电源支持供电，只 USB 双公头的供电即可满足刷机要求。

恢复出厂设置完成后，设备已还原为 Android TV 系统。后续安装 Armbian 的操作与首次安装相同，按原流程操作即可。

12.4 设置盒子从 USB/TF/SD 中启动 Copy Section

根据实际情况，选择初次安装或重新安装 Armbian 系统的对应方法。

12.4.1 初次安装 Armbian 系统

• 将写好系统的 USB/TF/SD 插入设备。
• 开启开发者模式: 设置 → 关于本机 → 版本号 (如: X96max plus...), 快速点击版本号 5 次，直到系统显示 开启开发者模式 提示。
• 开启 USB 调试模式: 系统 → 高级选项 → 开发者选项 (设置 开启USB调试 为启用)。启用 ADB 调试。
• 安装 ADB 工具：下载 adb 并解压，将 adb.exe，AdbWinApi.dll，AdbWinUsbApi.dll 三个文件复制到 c://windows/ 目录下的 system32 和 syswow64 文件夹中。打开 cmd 命令面板，执行 adb --version 命令，若有输出则表示安装成功。
• 进入 cmd 命令模式，输入 adb connect 192.168.1.137 命令（其中 IP 根据设备实际情况修改，可在路由器管理界面查看），连接成功后将显示 connected to 192.168.1.137:5555
• 输入 adb shell reboot update 命令，设备将重启并从 USB/TF/SD 启动。通过浏览器访问系统 IP 地址或使用 SSH 连接即可进入系统。

12.4.2 重新安装 Armbian 系统

• 正常情况下，将写好 Armbian 的 U 盘插入 USB 即可直接启动，USB 启动优先于 eMMC。
• 若个别设备无法从 U 盘启动，可将 eMMC 中 Armbian 系统 /boot 目录下的 boot.scr 文件重命名（如 boot.scr.bak），再插入 U 盘即可正常启动。

12.5 禁用红外接收器 Copy Section

系统默认启用红外接收器支持。若将设备用作服务器，建议禁用 IR 内核模块以防止误触关机。完全禁用 IR 的方法：添加以下内容

blacklist meson_ir

至 /etc/modprobe.d/blacklist.conf 并重启。

12.6 启动引导文件的选择 Copy Section

• 目前已知设备中，仅 T95(s905x) / T95Z-Plus(s912) / BesTV-R3300L(s905l-b) 等少数设备需要使用 /bootfs/extlinux/extlinux.conf 文件，系统已默认添加。其他设备如有需要，将系统写入 USB 后打开 boot 分区，将系统自带的 /boot/extlinux/extlinux.conf.bak 文件名称中的 .bak 删除即可使用。写入 eMMC 时，armbian-install 会自动检查并在 extlinux.conf 文件存在时自动创建。

• 其他设备仅需 /boot/uEnv.txt 即可启动，请勿修改 extlinux.conf.bak 文件。

12.7 网络设置 Copy Section

12.7.1 使用 interfaces 设置网络

网络配置文件 /etc/network/interfaces 的默认内容如下：

source /etc/network/interfaces.d/*
# Network is managed by Network manager
auto lo
iface lo inet loopback

12.7.1.1 由 DHCP 动态分配 IP 地址

source /etc/network/interfaces.d/*

auto eth0
iface eth0 inet dhcp

12.7.1.2 手动设置静态 IP 地址

其中的 IP 和网关和 DNS 根据自己的网络情况修改。

source /etc/network/interfaces.d/*

auto eth0
allow-hotplug eth0
iface eth0 inet static
hwaddress ether 12:34:56:78:9A:DA
address 192.168.1.100
netmask 255.255.255.0
gateway 192.168.1.1
dns-nameservers 192.168.1.1

12.7.1.3 在 docker 中使用 OpenWrt 建立互通网络

其中的 MAC 地址根据自己的需要修改。

source /etc/network/interfaces.d/*

allow-hotplug eth0
no-auto-down eth0
auto eth0
iface eth0 inet manual

auto macvlan
iface macvlan inet dhcp
        pre-up ip link add macvlan link eth0 type macvlan mode bridge
        post-down ip link del macvlan link eth0 type macvlan mode bridge

auto lo
iface lo inet loopback

12.7.2 使用 NetworkManager 管理网络

12.7.2.1 新建网络连接

新建或修改网络连接前的准备工作

12.7.2.1.1 获取网络接口名称

查看设备中可用的网络接口。

nmcli device | grep -E "^[e].*|^[w].*|^[D].*|^[T].*" | awk '{printf "%-19s%-19s\n",$1,$2}'

执行命令后返回内容, DEVICE 列显示网络接口名称, TYPE 列显示网络接口类型。

其中 eth0 = 第1块有线网卡的名称, eth1 = 第2块有线网卡的名称, 以此类推, 无线网卡同理。

DEVICE             TYPE
eth0               ethernet
eth1               ethernet
eth2               ethernet
eth3               ethernet
wlan0              wifi
wlan1              wifi

12.7.2.1.2 获取现有网络连接名称

查看设备现有的网络连接（包含已启用和未启用的连接）。新建连接时，建议使用不同于现有连接的名称。

nmcli connection show | grep -E ".*|^[N].*" | awk '{printf "%-19s%-19s\n", $1,$3}'

执行命令后返回内容, NAME 列显示现有网络连接名称, TYPE 列显示网络接口类型。

其中 ethernet = 有线网卡, wifi = 无线网卡, bridge = 网桥

NAME               TYPE
cnc                ethernet
lan                ethernet
lte                ethernet
tel                ethernet
docker0            bridge
titanium           wifi
cpe                wifi

12.7.2.1.3 新建有线网络连接

在网络接口 eth0 上新建网络连接并立即生效 (动态 IP 地址 - IPv4 / IPv6)。

# Set ENV
MYCON=ether1                  # 新建网络连接名称
MYETH=eth0                    # 网络接口名称 = eth0 / eth1 / eht2 / eth3
IPV6AGM=stable-privacy        # IPv6 地址状态模式 = stable-privacy / eui64

# Add ETH
nmcli connection add \
con-name $MYCON \
type ethernet \
ifname $MYETH \
autoconnect yes \
ipv6.addr-gen-mode $IPV6AGM
nmcli connection up $MYCON
ip -c -br address

在网络接口 eth0 上新建网络连接并立即生效 (静态 IP 地址 - IPv4)。

# Set ENV
MYCON=ether1                  # 网络连接名称
MYETH=eth0                    # 网络接口名称 = eth0 / eth1 / eht2 / eth3
IP=192.168.67.167/24          # HOST IP 地址, 其中 24 是子网掩码 对应 255.255.255.0
GW=192.168.67.1               # 网关
DNS=119.29.29.29,223.5.5.5    # DNS 服务器地址

# Chg CON
nmcli connection add \
con-name $MYCON \
type ethernet \
ifname $MYETH \
autoconnect yes \
ipv4.method manual \
ipv4.addresses $IP \
ipv4.gateway $GW \
ipv4.dns $DNS
nmcli connection up $MYCON
ip -c -br address

12.7.2.1.4 新建无线网络连接

在网络接口 wlan0 上新建网络连接并立即生效 (动态 IP 地址 - IPv4 / IPv6)。

# Set ENV
MYCON=ssid                    # 新建网络连接名称, 建议使用 WiFi SSID 来指定连接名称
MYSSID=ssid                   # WiFi SSID 区分大小写
MYPSWD=passwd                 # WiFi 密码
MYWSKM=wpa-psk                # 安全性选择 WPA-WPA2 = wpa-psk or WPA3 = sae （无线路由器或 AP 中查看是哪一种加密方式）
MYWLAN=wlan0                  # 网络接口名称 = wlan0 / wlan1
IPV6AGM=stable-privacy        # IPv6 地址状态模式 = stable-privacy / eui64

# Add WLAN
nmcli connection add \
con-name $MYCON \
type wifi \
ifname $MYWLAN \
autoconnect yes \
ipv6.addr-gen-mode $IPV6AGM \
wifi.ssid $MYSSID \
wifi-sec.key-mgmt $MYWSKM \
wifi-sec.psk $MYPSWD
nmcli connection up $MYCON
ip -c -br address

12.7.2.2 修改无线网络连接中的 WiFi SSID or PASSWD

修改无线网络连接 ssid 中的 WiFi SSID or PASSWD 并立即生效。

# Set ENV
MYCON=ssid                    # 无线网络连接名称
MYSSID=ssid                   # WiFi SSID 区分大小写
MYPSWD=passwd                 # WiFi 密码
MYWSKM=wpa-psk                # 安全性选择 WPA-WPA2 = wpa-psk or WPA3 = sae

# Add WLAN
nmcli connection modify $MYCON \
wifi.ssid $MYSSID \
wifi-sec.key-mgmt $MYWSKM \
wifi-sec.psk $MYPSWD
nmcli connection up $MYCON
ip -c -br address

12.7.2.3 修改网络地址分配方式

12.7.2.3.1 静态 IP 地址 - IPv4

在网络连接 ether1 上修改 IP 地址分配方式为 静态 IP 地址 并立即生效。

*适用 有线连接 / 无线连接

# Set ENV
MYCON=ether1                  # 网络连接名称
IP=192.168.67.167/24          # HOST IP 地址, 其中 24 是子网掩码 对应 255.255.255.0
GW=192.168.67.1               # 网关
DNS=119.29.29.29,223.5.5.5    # DNS 服务器地址

# Chg CON
nmcli connection modify $MYCON \
ipv4.method manual \
ipv4.addresses $IP \
ipv4.gateway $GW \
ipv4.dns $DNS
nmcli connection up $MYCON
ip -c -br address

12.7.2.3.2 DHCP 获取动态 IP 地址 - IPv4 / IPv6

在网络连接 ether1 上修改 IP 地址分配方式为 DHCP 获取动态 IP 地址 并立即生效。

*适用 有线连接 / 无线连接

# Set ENV
MYCON=ether1                  # 网络连接名称

# Chg CON
nmcli connection modify $MYCON \
ipv4.method auto \
ipv6.method auto
nmcli connection up $MYCON
ip -c -br address

12.7.2.4 修改网络连接 MAC 地址

在网络连接上修改 MAC 地址 以解决局域网 MAC 地址冲突问题。

12.7.2.4.1 方法一：使用 `nmcli` 命令修改 MAC 地址

# 使用 nmcli connection show 命令查看网络连接名称
nmcli connection show
# 返回的结果中包含网口名字，例如'Wired connection 1'
NAME                UUID                                  TYPE      DEVICE
Wired connection 1  24d63dc7-c46f-3bf1-912f-1c33eb94338b  ethernet  eth0
lo                  35ca24e5-bdc0-4658-8ac8-435ee22e07f3  loopback  lo
Wired connection 2  59660b21-b460-30e0-8cb3-89b886556955  ethernet  --

# 设置变量
MYCON='Wired connection 1'    # 网络连接名称, 注意匹配网络接口类型
MYTYPE='802-3-ethernet'       # 网络接口类型 = 有线网卡        / 无线网卡
                              #            = 802-3-ethernet / 802-11-wireless
MYMAC='12:34:56:78:9A:BC'     # 设置新的 MAC 地址

# 执行修改
nmcli connection modify "${MYCON}" ${MYTYPE}.cloned-mac-address ${MYMAC}
nmcli connection up "${MYCON}"
ip -c a show "${MYCON}"

• 新建或修改部分网络参数, 网络连接可能会被断开, 并重新连接网络。
• 由于软硬件环境不同（盒子, 系统, 网络设备等）, 生效所需时间 1-15 秒左右, 更长时间未生效的建议检查软硬件环境。

12.7.2.4.2 方法二：通过配置文件修改 MAC 地址

添加 Mac 地址覆盖配置文件。

sudo mkdir -p /etc/systemd/network/
sudo nano /etc/systemd/network/10-mac-override.link

添加以下内容：

[Match]
# 设置需要修改 MAC 地址的网络接口名称
OriginalName=eth0

[Link]
# 设置符合规范的 MAC 地址
MACAddress=02:55:66:77:88:99

重启后生效。

12.7.2.5 如何禁用 IPv6

您可以使用 nmcli 实用程序在命令行中禁用 IPv6 协议，参考来源 disable-ipv6。

第一步，先使用 nmcli connection show 命令查看网络连接列表，返回结果如下：

NAME                 UUID                                   TYPE       DEVICE
Wired connection 1   8a7e0151-9c66-4e6f-89ee-65bb2d64d366   ethernet   eth0
...

第二步，将连接的 ipv6.method 参数设为 disabled ：

nmcli connection modify "Wired connection 1" ipv6.method "disabled"

第三步，重新连接网络：

nmcli connection up "Wired connection 1"

第四步，查看网络连接状态，如果没有显示 inet6 条目，则 IPv6 在该设备上被禁用：

ip address show eth0

第五步，验证 /proc/sys/net/ipv6/conf/eth0/disable_ipv6 文件现在是否包含值 1

# cat /proc/sys/net/ipv6/conf/eth0/disable_ipv6
1

也可以通过修改 /etc/sysctl.conf 文件来禁用 IPv6：

# Disable IPv6 by default
net.ipv6.conf.all.disable_ipv6 = 1
net.ipv6.conf.default.disable_ipv6 = 1
net.ipv6.conf.lo.disable_ipv6 = 1

12.7.3 如何启用无线

部分设备支持无线网络。关于无线 AP 模式的使用方法，请参考说明；配合开启 DHCP 服务的配置方法，请参考说明。关于无线客户端（Client）模式的使用方法，请参见以下说明：

# 安装管理工具
sudo apt-get install network-manager

# 查看网络设备
sudo nmcli dev

# 启用无线
sudo nmcli r wifi on

# 扫描无线
sudo nmcli dev wifi

# 连接无线
sudo nmcli dev wifi connect "wifi名称" password "wifi密码"

# 显示已保存的网络连接列表
sudo nmcli connection show

# 断开连接
sudo nmcli connection down "wifi名称"

# 忘记连接并取消自动连接
sudo nmcli connection delete "wifi名称"

12.7.4 如何启用蓝牙

部分设备支持蓝牙，启用方法如下：

# 安装蓝牙支持
armbian-config >> Network >> BT: Install Bluetooth support

# 重启系统
reboot

系统重启后，检查蓝牙驱动是否正常加载。桌面系统可通过菜单连接蓝牙设备，也可通过终端命令操作。

dmesg | grep Bluetooth

# 连接蓝牙设备
armbian-config >> Network >> BT: Discover and connect Bluetooth devices

也可以在终端中使用命令安装：

# 查看蓝牙服务运行状态
sudo systemctl status bluetooth

# 如果未启动，先开启蓝牙服务
sudo systemctl enable bluetooth
sudo systemctl start bluetooth

# 扫描附近的蓝牙设备
bluetoothctl scan on

# 启用蓝牙发现
bluetoothctl discoverable on

# 进行蓝牙 MAC 地址配对
bluetoothctl pair 12:34:56:78:90:AB

# 查看配对好的蓝牙设备
bluetoothctl paired-devices

# 连接蓝牙设备
bluetoothctl connect 12:34:56:78:90:AB

# 信任设备，方便以后直接连接
bluetoothctl trust 12:34:56:78:90:AB

# 断开蓝牙设备
bluetoothctl disconnect 12:34:56:78:90:AB

# 解除蓝牙配对
bluetoothctl remove 12:34:56:78:90:AB

# 阻止连接设备
bluetoothctl block 12:34:56:78:90:AB

12.8 如何添加开机启动任务 Copy Section

系统已内置自定义开机启动任务脚本，路径为 /etc/custom_service/start_service.sh，可根据个人需求在该脚本中添加自定义任务。

12.9 如何更新系统中的服务脚本 Copy Section

使用 armbian-sync 命令可一键将本地系统中的全部服务脚本更新至最新版本。

若 armbian-sync 更新失败，可能因命令版本过旧，可通过以下方法手动更新：

wget https://raw.githubusercontent.com/ophub/amlogic-s9xxx-armbian/main/build-armbian/armbian-files/common-files/usr/sbin/armbian-sync -O /usr/sbin/armbian-sync

chmod +x /usr/sbin/armbian-sync

armbian-sync

12.10 如何获取 eMMC 上的安卓系统分区信息 Copy Section

将 Armbian 系统写入 eMMC 时，需先确认设备的安卓系统分区表，确保数据写入安全区域，避免破坏原分区表导致系统无法启动。若写入了不安全的区域，可能无法启动或出现如下错误：

12.10.1 获取分区信息

若使用 2022.11 之后本仓库发布的 Armbian，可复制粘贴以下命令获取包含完整分区信息的网址（设备本身无需联网）

ampart /dev/mmcblk2 --mode webreport 2>/dev/null

ampart 的 webreport 模式为 2023.02.03 发布的 v1.2 版本引入的，如果你使用上面的命令无输出，则可能为不支持直接输出网址的旧版，你可以转而使用下面这条命令：

echo "https://7ji.github.io/ampart-web-reporter/?dsnapshot=$(ampart /dev/mmcblk2 --mode dsnapshot 2>/dev/null | head -n 1)&esnapshot=$(ampart /dev/mmcblk2 --mode esnapshot 2>/dev/null | head -n 1)"

生成的网址格式类似如下：

https://7ji.github.io/ampart-web-reporter/?esnapshot=bootloader:0:4194304:0%20reserved:37748736:67108864:0%20cache:113246208:754974720:2%20env:876609536:8388608:0%20logo:893386752:33554432:1%20recovery:935329792:33554432:1%20rsv:977272832:8388608:1%20tee:994050048:8388608:1%20crypt:1010827264:33554432:1%20misc:1052770304:33554432:1%20instaboot:1094713344:536870912:1%20boot:1639972864:33554432:1%20system:1681915904:1073741824:1%20params:2764046336:67108864:2%20bootfiles:2839543808:754974720:2%20data:3602907136:4131389440:4&dsnapshot=logo::33554432:1%20recovery::33554432:1%20rsv::8388608:1%20tee::8388608:1%20crypt::33554432:1%20misc::33554432:1%20instaboot::536870912:1%20boot::33554432:1%20system::1073741824:1%20cache::536870912:2%20params::67108864:2%20data::-1:4

将此网址复制到浏览器打开，即可查看格式清晰的 DTB 分区信息和 eMMC 分区信息：

12.10.2 分区信息分享

需要向他人分享分区信息时（如向本仓库汇报新设备情况或寻求帮助），请优先分享网址而非截图。若网址过长，可使用免费的短链接服务。

• 一方面，网页上的分区信息每次访问时均会动态生成，分区可写入的标注及表格格式等可能随时更新。
• 另一方面，截图中的分区参数无法被方便地复制用于计算。

此外，无需额外将参数整理为表格文件，网页表格布局已专门设计为可直接复制粘贴导入 Excel 或 LibreOffice Calc。

12.10.3 分区信息解读

DTB 表记录了安卓 DTB 中每台设备系统期望的分区布局，通常以一个大小为自动填充的 data 分区结尾。因此，相同系统（必然包括同型号）的设备，DTB 分区布局一定相同。设备上实际的分区布局因 eMMC 容量不同而有所差异，但始终由 DTB 分区布局决定（即已知 DTB 分区布局 +eMMC 准确大小，必然可推知 eMMC 分区情况。 上面的 DTB 分区信息和 eMMC 分区信息并非来自同一个盒子，你看出来了吗？）。

eMMC 表是设备上实际的 eMMC 分区布局。其中每一行表示一块存储区域，该区域可能是一个分区，也可能是分区间的间隙（由于晶晨的设计决策，每个分区之间至少有 8M 的间隙，原计划留作他用，但直至 S905X4 仍未使用，造成空间浪费）。对应分区的行中，字体为黑色，且偏移和掩码栏均有数值；对应空隙的行中，字体为灰色，偏移和掩码栏没有数值，且分区名为 gap 。

eMMC 表中，每一块存储区域的最后一栏为可写入的情况，绿色且 yes 表示这一区域可以写入，红色且 no 表示这一区域绝对不可以写入，黄色且有标注则表示某前提的下可以写入，或者只有部分可以写入。

以上表为例，bootloader 分区对应的 0+4M (0M~4M)绝对不可写入，其后的 32M 空隙（4M~36M）可以写入，reserved 分区对应的 36M+64M (36M~100M)绝对不可写入，其后的空隙一直到 env 前的空隙（100M~836M）都可以写入，env 的1M往后（837M一直到结尾）在不需要安卓启动 logo 的情况下都可以写入，则 eMMC 上所有可写入的范围为：

• 4M~36M
• 100M~836M
• 837M~结尾

在需要安卓启动 logo 的情况下，额外的，logo分区对应的 852M + 32M (852M~884M)不能写入，则 eMMC 上所有的可写入范围为：

• 4M~36M
• 100M~836M
• 837M~852M
• 884M~结尾

12.10.4 用于 eMMC 安装

若设备在使用 armbian-install 且 -a 参数（使用 ampart 调整 eMMC 分区布局）为 yes（默认值）时失败，则该设备无法使用最优分区布局（即把 DTB 分区信息调整为只有 data ，再由此生成 eMMC 分区信息，然后将所有还存在的分区均向前挪动，如此一来，117M 向后的空间便均可使用），你需要在 armbian-install 中修改对应的分区信息。

此文件中，声明分区布局的关键参数有三个：BLANK1, BOOT, BLANK2。其中 BLANK1 表示从 eMMC 开头算起的不可使用的大小；BOOT 表示 BLANK1 之后用于存放内核、DTB 等文件的分区大小，建议不小于 256M；BLANK2 表示 BOOT 之后不可使用的大小；在此之后的空间会全部用来创建 ROOT 分区，储存整个系统中 /boot 挂载点以外的数据。三者均应为整数，且单位为MiB (1 MiB = 1024 KiB = 1024^2 Byte)

以上述不需要 logo 分区的情况为例，为充分利用所有可用空间，由于 4M~36M 区域过小无法用作 BOOT，只能将其计入 BLANK1。100M~836M 区域足以用作 BOOT，可将其 736M 全部分配给 BOOT。其后 836M~837M 的不可用区域计入 BLANK2，相应参数配置如下（以 s905x3 为例，其他 SoC 需修改对应代码块）：

# Set partition size (Unit: MiB)
elif [[ "${AMLOGIC_SOC}" == "s905x3" ]]; then
    BLANK1="100"
    BOOT="736"
    BLANK2="1"

12.11 如何制作 u-boot 文件 Copy Section

u-boot 是引导系统启动的关键文件。Amlogic、Allwinner 和 Rockchip 设备在源码获取和编译流程上略有差异。

12.11.1 如何制作 Amlogic 设备的 u-boot 文件

由于 Amlogic 系列设备厂商大多不开源，需先从设备上提取 u-boot 相关文件，再进行编译。以下方法来自 unifreq 分享的制作教程。

12.11.1.1 如何提取 bootloader 和 dtb 文件

提取过程需使用 HxD 软件，可从 官网下载链接 或 备份下载链接 获取并安装。

在 cmd 面板中依次执行以下命令提取相关文件并下载至本地。

# 使用 adb 工具进入盒子
adb connect 192.168.1.111
adb shell

# 导出 bootloader 命令
dd if=/dev/block/bootloader of=/data/local/bootloader.bin

# 导出 dtb 命令
cat /dev/dtb >/data/local/mybox.dtb

# 导出 gpio 命令
cat /sys/kernel/debug/gpio >/data/local/mybox_gpio.txt

# 依次把 bootloader、dtb 和 gpio 文件都下载到本地电脑C盘根目录下的 mybox 文件夹
adb pull /data/local/bootloader.bin C:\mybox
adb pull /data/local/mybox.dtb C:\mybox
adb pull /data/local/mybox_gpio.txt C:\mybox

12.11.1.2 如何制作 acs.bin 文件

主线 u-boot 中最关键的是 acs.bin 文件，用于内存初始化，原厂 u-boot 位于系统起始 4MB 区域。使用前面获取的 bootloader.bin 提取 acs.bin 文件。

打开 HxD 软件，打开上面导出的 bootloader.bin 文件，右键 - 选择范围，起始位置 F200，长度 1000，选十六进制。

复制选择的结果，然后新建文件，插入式粘贴，警告忽略，另存为 acs.bin 文件。

若 bootloader 已锁定，则该区域的代码将显示为乱码，无法使用。正常情况下，该区域应包含大量 0，cfg 会连续出现数次，并夹杂 ddr 相关字样，此类代码为有效可用数据。

12.11.1.3 如何编译 u-boot 文件

制作 u-boot 需要 https://github.com/unifreq/amlogic-boot-fip 和 https://github.com/unifreq/u-boot 两个源码仓库，用于编译设备所需的 u-boot 文件。

在 amlogic-boot-fip 源码中，各机型仅 acs.bin 文件不同，其余文件通用。

制作方法详见 https://github.com/unifreq/u-boot/tree/master/doc/board/amlogic 中的说明，选择对应设备型号进行编译测试。

根据 unifreq 的方法制作 u-boot，需要使用设备的 acs.bin、dts 和 config 文件。其中安卓系统导出的 dts 无法直接转换为 Armbian 格式，需自行编写对应的 dts 文件。根据设备的具体硬件差异（如开关、LED、电源控制、TF 卡、SDIO WiFi 模块等），参照内核源码库中相似的 dts 文件进行修改。

以制作 X96Max Plus 的 u-boot 为例：

~/make-uboot
    ├── amlogic-boot-fip
    │   ├── x96max-plus                                     # 自己创建目录
    │   │   ├── asc.bin                                     # 自己制作源文件
    │   │   └── other-copy-files...                         # 复制其他目录的文件
    │   │
    │   ├── other-source-directories...
    │   └── other-source-files...
    │
    └── u-boot
        ├── configs
        │   └── x96max-plus_defconfig                       # 自己制作源文件
        ├── arch
        │   └── arm
        │       └── dts
        │           ├── meson-sm1-x96-max-plus-u-boot.dtsi  # 自己制作源文件
        │           ├── meson-sm1-x96-max-plus.dts          # 自己制作源文件
        │           └── Makefile                            # 编辑
        ├── fip
        │   ├── u-boot.bin                                  # 生成文件
        │   └── u-boot.bin.sd.bin                           # 生成文件
        ├── u-boot.bin                                      # 生成文件
        │
        ├── other-source-directories...
        └── other-source-files...

• 下载 amlogic-boot-fip 源码。在根目录创建 x96max-plus 目录，其中除自行制作的 asc.bin 文件外，其余文件可从其他目录复制。
• 下载 u-boot 源码。制作对应的 x96max-plus_defconfig 文件放入 configs 目录。制作对应的 meson-sm1-x96-max-plus-u-boot.dtsi 和 meson-sm1-x96-max-plus.dts 文件放入 arch/arm/dts 目录，并编辑此目录中的 Makefile 文件，添加 meson-sm1-x96-max-plus.dtb 文件的索引。
• 进入 u-boot 源码根目录，按照文档 https://github.com/unifreq/u-boot/blob/master/doc/board/amlogic/x96max-plus.rst 中的步骤操作。

最终生成两类文件：u-boot 根目录下的 u-boot.bin 为 /boot 目录使用的精简版 u-boot（对应仓库中的 overload 目录）；在 fip 目录下的 u-boot.bin 和 u-boot.bin.sd.bin 是 /usr/lib/u-boot/ 目录下使用的完整版 u-boot 文件（对应仓库中的 bootloader 目录），完整版两个文件相差 512 字节，较大的文件在头部填充了 512 字节的 0。

💡提示：写入 eMMC 测试前，请先阅读 12.3 节的救砖方法。务必确认已掌握短接点位置、备有原厂 .img 格式的安卓系统文件，并已成功测试短接刷机流程后，方可进行写入测试。

12.11.2 如何制作 Rockchip 设备的 u-boot 文件

Rockchip 设备的大部分厂商已开源 u-boot 源码，可在厂商源码仓库中获取并编译。同时，一些开源贡献者也分享了便捷的 u-boot 编译脚本，以下通过实例介绍几种编译方法。

12.11.2.1 如何使用 Radxa 的 u-boot 制作脚本

以编译 Rock5b(rk3588) 为例。

# 01.安装依赖
sudo apt-get update
sudo apt-get install -y git device-tree-compiler libncurses5 libncurses5-dev build-essential libssl-dev mtools bc python dosfstools flex bison

# 02.克隆源码
mkdir ~/rk3588-sdk && cd ~/rk3588-sdk
git clone -b stable-5.10-rock5 https://github.com/radxa/u-boot.git
git clone -b master https://github.com/radxa/rkbin.git
git clone -b debian https://github.com/radxa/build.git

# 源码说明：
# ~/rk3588-sdk/build/：Radxa 辅助脚本文件和用于构建 U-Boot、Linux 内核和根文件系统的配置文件。
# ~/rk3588-sdk/rkbin/：预构建的 Rockchip 二进制文件，包括第一阶段加载程序和 ATF（Arm Trustzone固件）。
# ~/rk3588-sdk/u-boot/：用于启动操作系统（如 Linux 或 Android）的第二阶段引导加载程序。

# 03.编译 u-boot （For ROCK 5B）
cd ~/rk3588-sdk
./build/mk-uboot.sh rk3588-rock-5b

# 04.构建成功后，将放置在 ~/rk3588-sdk/out/u-boot 目录
~/rk3588-sdk/out/u-boot
├── idbloader.img
├── rk3588_spl_loader_v1.08.111.bin
├── spi
│   └── spi_image.img
└── u-boot.itb

通过在 radxa/build 源码的 board_configs.sh 和 mk-uboot.sh 中添加更多选项，可编译其他设备的 u-boot 文件。例如编译 Beelink-IPC-R(rk3588) 设备的方法。

12.11.2.2 如何使用 cm9vdA 的 u-boot 制作脚本

cm9vdA 的开源项目 cm9vdA/build-linux 提供了编译 u-boot 和 kernel 的脚本及使用方法。以下为部分 Rockchip 设备 u-boot 编译的过程记录，摘录供参考。

• 编译 Lenovo-Leez-P710(rk3399) 设备的 u-boot：Link
• 编译 DLFR100(rk3399) 设备的 u-boot：Link
• 编译 ZYSJ(rk3399) 设备的 u-boot：Link

12.12 内存大小识别错误 Copy Section

若内存大小识别不正确（4G 内存识别为 1-2G 属异常，识别为 3.7G 属正常），可尝试手动复制 /boot/UBOOT_OVERLOAD 文件（注意是复制而非改名，改名后安装或更新操作将导致无法启动）：USB 中使用时保存为 /boot/u-boot.ext，eMMC 中使用时保存为 /boot/u-boot.emmc。

除排查内存识别问题外，请勿手动复制 u-boot 文件，错误操作可能导致无法启动或其他问题。

12.13 如何反编译 dtb 文件 Copy Section

12.13.1 直接反编译 dtb 文件

可以直接对已有的 dtb 文件进行反编译，通过调整相关参数进行适配。

# 安装依赖
sudo apt-get update
sudo apt-get install -y device-tree-compiler

# 1. 反编译命令（使用 dtb 文件生成 dts 源码）
dtc -I dtb -O dts -o xxx.dts xxx.dtb

# 2. 编译命令（使用 dts 编译生成 dtb 文件）
dtc -I dts -O dtb -o xxx.dtb xxx.dts

# 3.保存并重启
sync && reboot

12.13.2 从运行中的设备导出完全态 DTS（推荐）

在某些设备的适配与维护过程中，我们可能只能获取到编译后的二进制设备树文件（.dtb），而缺失对应的内核源码（.dts）。此时，建议在正常运行的 Armbian 系统中执行以下命令，直接从内核运行时环境中反编译并导出当前生效的设备树：

dtc -I fs -O dts /sys/firmware/devicetree/base > my_runtime.dts

该命令直接从内核内存中提取设备树数据，其导出的文本比单纯反编译磁盘上的静态 .dtb 文件更为准确和完整。因为引导加载程序（如 U-Boot）或系统固件在启动阶段，会根据实际的硬件检测结果对设备树进行动态修正或注入（例如：实时更新 bootargs 启动参数、动态开关特定外设的 status 状态、或调整 reg 寄存器地址等）。如果直接反编译磁盘上的静态文件，将无法捕获这些运行时改动。

采用此方法获取的是内核最终应用形态的运行态（Runtime）设备树，能真实反映硬件在系统底层的实际拓扑与工作状态。在参考、修复或重新适配该设备的 .dts 源码时，此文件具有极高的参考价值，能让排查冲突和补全外设配置变得更加准确和高效。

12.14 如何修改 cmdline 设置 Copy Section

Amlogic 设备在 /boot/uEnv.txt 文件中配置。Rockchip 和 Allwinner 设备在 /boot/armbianEnv.txt 文件中配置（添加至 extraargs 或 extraboardargs 参数）。使用 /boot/extlinux/extlinux.conf 的设备在该文件中配置。每次修改后需重启生效。

• 例如 Home Assistant Supervisor 仅支持 docker cgroup v1，而当前 docker 默认安装 v2 版本。如需切换至 v1，可在 cmdline 中添加 systemd.unified_cgroup_hierarchy=0 参数，重启后即可切换至 docker cgroup v1。

• 通过在 cmdline 中添加 mmc_core.max_freq=50000000 设置，可以限制 eMMC 最大频率为 50MHz。某些 S905L2 盒子 eMMC 在高频（HS200/HS400, 100MHz+）下不稳定，降频可解决启动失败/随机崩溃，读写错误和不稳定等问题。

• 通过在 cmdline 中添加 max_loop=128 设置，可以调整允许的 loop 挂载数量。

• 通过在 cmdline 中添加 usbcore.usbfs_memory_mb=1024 设置，可以永久将 USBFS 内存缓冲区从默认的 16 mb 改为更大（cat /sys/module/usbcore/parameters/usbfs_memory_mb），提升 USB 传输大文件的能力。

• 通过在 cmdline 中添加 usbcore.usb3_disable=1 设置，可以禁用 USB 3.0 的所有设备。

• 通过在 cmdline 中添加 usbcore.autosuspend=-1 设置，可以禁用 USB 自动挂起（防止 USB 设备省电断电）；添加 rootdelay=120 设置，可以在系统启动时等待 120 秒再挂载根分区（给 USB 设备时间就绪）；添加 mitigations=off 设置，可以关闭 CPU 漏洞缓解（Spectre/Meltdown），提升性能。

• 通过在 cmdline 中添加 extraargs=video=HDMI-A-1:1920x1080@60 设置，可以将视频显示模式强制为 1080p。

12.15 如何添加新的支持设备 Copy Section

为设备构建 Armbian 系统需要 设备配置文件、系统文件、u-boot 文件和流程控制文件 四部分，具体添加方法如下：

12.15.1 添加设备配置文件

在配置文件 /etc/model_database.conf 中，根据设备的测试结果添加对应配置信息。其中 BUILD 值为 yes 的是默认构建的设备，对应的 BOARD 值必须唯一，这些设备可直接使用默认构建的 Armbian 系统。

默认值为 no 的设备未包含在默认构建中，使用时需下载相同 FAMILY 的 Armbian 系统。写入 USB 后，在电脑上打开 USB 中的 boot 分区，修改 /boot/uEnv.txt 文件中的 FDT dtb 名称，即可适配列表中的其他设备。

12.15.2 添加系统文件

通用文件放在：build-armbian/armbian-files/common-files 目录下，各平台通用。

平台文件分别放在 build-armbian/armbian-files/platform-files/ 目录下，Amlogic、Rockchip 和 Allwinner 各自共享平台文件。其中 bootfs 目录存放 /boot 分区文件，rootfs 目录存放 Armbian 系统文件。

若个别设备有特殊配置需求，在 build-armbian/armbian-files/different-files 目录下创建以 BOARD 命名的独立目录，按需建立 bootfs 目录添加 /boot 分区文件，或建立 rootfs 目录添加系统文件。目录结构以 Armbian 系统中的实际路径为准，可用于添加新文件或覆盖通用文件和平台文件中的同名文件。

12.15.3 添加 u-boot 文件

Amlogic 系列的设备，共用 bootloader 文件和 u-boot 文件，新增文件分别放入对应目录。bootloader 文件在系统构建时将自动添加至 Armbian 系统的 /usr/lib/u-boot 目录，u-boot 文件自动添加至 /boot 目录。

Rockchip 和 Allwinner 系列的设备，为每个设备添加以 BOARD 命名的独立 u-boot 文件目录，对应的系列文件放在此目录中。

构建 Armbian 镜像时，这些 u-boot 文件将根据 /etc/model_database.conf 中的配置，由 rebuild 脚本写入对应的 Armbian 镜像文件中。

能使用标准 U-Boot 文件的设备，建议优先直接使用。部分设备可能无法编译或获取适用的 U-Boot，若这类设备已能正常运行 Ubuntu 等 Linux 系统，可尝试保留引导相关的关键分区来安装 Armbian 或 OpenWrt。通常需要保留的关键分区包括 bootloader、reserved 和 env。

这些分区可备份后，在制作新的 Armbian 或 OpenWrt 镜像时写回相应位置。制作完成的包含原系统引导分区的镜像，可直接使用 dd 命令写入 eMMC，也可使用相应系统的内置工具安装，例如 Armbian 的 armbian-install 命令，或 OpenWrt 的 晶晨宝盒 插件。

目前采用此方法的设备有 oes(a311d)，oes-plus(s922x)，oec-turbo(rk3566)，以下以 oes(a311d) 设备为例说明具体操作流程。

12.15.3.1 查看分区信息布局情况

ampart /dev/mmcblk2

# 得到的分区信息如下：
# ===================================================================================
# IO seek EPT: Seeking to 37748736
# EPT report: 20 partitions in the table:
# ===================================================================================
# ID| name            |          offset|(   human)|            size|(   human)| masks
# -----------------------------------------------------------------------------------
#  0: bootloader                      0 (   0.00B)           400000 (   4.00M)      0
#     (GAP)                                                 2000000 (  32.00M)
#  1: reserved                  2400000 (  36.00M)          4000000 (  64.00M)      0
#     (GAP)                                                  800000 (   8.00M)
#  2: cache                     6c00000 ( 108.00M)         20000000 ( 512.00M)      2
#     (GAP)                                                  800000 (   8.00M)
#  3: env                      27400000 ( 628.00M)           800000 (   8.00M)      0
#     (GAP)                                                  800000 (   8.00M)
#  ... other partitions ...
# ===================================================================================

12.15.3.2 备份关键分区

dd if=/dev/mmcblk2 of=bootloader.bin bs=1M count=4 skip=0
dd if=/dev/mmcblk2 of=reserved.bin bs=1M count=8 skip=36
dd if=/dev/mmcblk2 of=env.bin bs=1M count=1 skip=628

备份的文件放在 u-boot 仓库对应的目录 u-boot/amlogic/bootloader/a311d-oes 里面。

注意到 reserved 分区为 64MB，但仅备份了 8MB。原因在于 oes(a311d) 设备上 reserved 分区的前 8MB 为关键数据，后续 56MB 为空白，无需备份。具体查看方法：

# 首先，备份 reserved 分区完整的 64MB 大小的文件：
dd if=/dev/mmcblk2 of=reserved_64M.bin bs=1M count=64 skip=36

# 然后，把我们备份出来的 reserved_64M.bin 文件的前 8MB 提取出来：
dd if=reserved_64M.bin of=reserved_first_8M.bin bs=1M count=8

# 接下来，查看十六进制内容：
hexdump -C reserved_first_8M.bin | less

# 现在，我们查看返回结果最后几行的内容：
0071ffd0  4c 5e a8 1f fc 5b 5b 98  ae ef b0 97 0c 3b e8 c2  |L^...[[......;..|
0071ffe0  c8 e0 b2 74 3d 67 d5 3d  24 7b 63 b7 c7 73 f5 d8  |...t=g.=${c..s..|
0071fff0  a1 b8 38 a7 57 d6 b4 b5  e8 1c ba c0 07 0f f5 79  |..8.W..........y|
00720000  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
*
00800000

分析输出结果，最后一个包含非零数据的行的地址是 0071fff0。从地址 00720000 开始，所有内容都变成了 00（零）。hexdump 工具使用 （*） 来表示重复的行，这意味着从 00720000 一直到 00800000 (即8MB的末尾) 都是零。把效数据地址 0x00720000 换算成十进制是 7,471,104 字节，也就是 7471104 / 1024 / 1024 = 7.125 MB 大小，因此取整备份 8MB 即可。env 分区同理，仅前 80KB 为有效数据，其余为空白，因此仅备份 1MB。

12.15.3.3 添加特殊分区写入文件

具体实现细节请参考文件 /etc/armbian-board-release.conf 中定义的 write_board_bootloader 函数。该函数在镜像重构（rebuild）过程中被调用。此外，该配置文件也是功能强大的设备定制中心。您不仅可以通过 skip_mb="700" 等参数来精确控制镜像分区的布局与大小，还可以添加自定义脚本，以实现对内核或其他系统文件的特殊处理。所有针对特定设备的高级定制操作均集中在此文件中统一管理，确保配置清晰高效。

12.15.4 添加流程控制文件

在 yml 工作流控制文件 的 armbian_board 中添加对应的 BOARD 选项，使其支持在 GitHub Actions 中使用。

12.16 如何解决写入 eMMC 时 I/O 错误的问题 Copy Section

部分设备可从 USB/SD/TF 正常启动 Armbian，但写入 eMMC 时会出现 I/O 写入错误，例如 Issues 中的案例，报错内容如下：

[  284.338449] I/O error, dev mmcblk2, sector 0 op 0x1:(WRITE) flags 0x800 phys_seg 1 prio class 2
[  284.341544] Buffer I/O error on dev mmcblk2, logical block 0, lost async page write
[  284.446972] I/O error, dev mmcblk2, sector 0 op 0x1:(WRITE) flags 0x800 phys_seg 1 prio class 2
[  284.450074] Buffer I/O error on dev mmcblk2, logical block 0, lost async page write
[  284.497746] I/O error, dev mmcblk2, sector 0 op 0x1:(WRITE) flags 0x800 phys_seg 1 prio class 2
[  284.500871] Buffer I/O error on dev mmcblk2, logical block 0, lost async page write

此时可调整 dtb 中的工作模式速度和频率以稳定存储读写。SDR 模式下频率为速度的 2 倍，DDR 模式下频率等于速度。可用模式如下：

sd-uhs-sdr12
sd-uhs-sdr25
sd-uhs-sdr50
sd-uhs-ddr50
sd-uhs-sdr104

max-frequency = <208000000>;

以内核源码的 dts 文件中的代码片段举例：

/* SD card */
&sd_emmc_b {
	status = "okay";

	bus-width = <4>;
	cap-sd-highspeed;
	sd-uhs-sdr12;
	sd-uhs-sdr25;
	sd-uhs-sdr50;
	max-frequency = <100000000>;
};

/* eMMC */
&sd_emmc_c {
	status = "okay";

	bus-width = <8>;
	cap-mmc-highspeed;
	max-frequency = <100000000>;
};

通常将 &sd_emmc_c 的频率从 max-frequency = <200000000>; 下调至 max-frequency = <100000000>; 即可解决。若无效可继续下调至 50000000 进行测试，同时可通过调整 &sd_emmc_b 配置 USB/SD/TF，或使用 sd-uhs-sdr 限速。可通过修改 dts 文件并编译生成测试文件，也可参照 12.13 节 的方法对现有 dtb 文件进行反编译修改。反编译 dtb 文件时使用十六进制值，其中十进制的 200000000 对应的十六进制为 0xbebc200，十进制的 100000000 对应的十六进制为 0x5f5e100，十进制的 50000000 对应的十六进制为 0x2faf080，十进制的 25000000 对应的十六进制为 0x17d7840。也可以参照 12.14 节 的 cmdline 设置方法，在 cmdline 中添加 mmc_core.max_freq=50000000 参数来限制 eMMC 的最大频率来解决读写错误和不稳定等问题。

除软件层面的优化外，还可通过硬件升级和动手改造解决。

12.17 如何解决 Bullseye 版本没有声音的问题 Copy Section

声音问题的错误日志信息：

Mar 29 15:47:18 armbian-ct2000 kernel:  fe.dai-link-0: ASoC: dpcm_fe_dai_prepare() failed (-22)
Mar 29 15:47:18 armbian-ct2000 kernel:  fe.dai-link-0: ASoC: no backend DAIs enabled for fe.dai-link-0

请参考 Bullseye NO Sound 中的方法进行设置。

curl -fsSOL https://github.com/ophub/kernel/releases/download/tools/bullseye_g12_sound-khadas-utils-4-2-any.tar.gz
tar -xzf bullseye_g12_sound-khadas-utils-4-2-any.tar.gz -C /

systemctl enable sound.service
systemctl restart sound.service

重启 Armbian 进行测试。若声音仍无输出，可能是设备使用了旧版 conf 对应的音频输出路径，需在 /usr/bin/g12_sound.sh 中注释掉 L137-L142 的新配置（该配置主要适用于 G12B/S922X，旧版 G12A/S905X2 及基于 G12A 的 SM1/S905X3 大多不兼容），并取消 L130-L134 旧配置的注释。

12.18 如何编译 boot.scr 文件 Copy Section

Armbian 系统 /boot 目录下，boot.scr 是系统引导文件，由 boot.cmd 源码文件编译生成。修改 boot.cmd 后，通过 mkimage 命令重新编译即可生成新的 boot.scr。

通常无需修改这两个文件，如有调整需求可参考以下方法。

# 安装依赖
sudo apt-get update
sudo apt-get install -y u-boot-tools

# 编辑 boot.cmd 文件
cd /boot
copy /boot/boot.cmd /boot/boot.cmd.bak
copy /boot/boot.scr /boot/boot.scr.bak
nano boot.cmd

# 编译命令
mkimage -C none -A arm -T script -d boot.cmd boot.scr

# 重启测试
sync
reboot

# 补充说明
# 在 Amlogic 设备中，在 USB 中使用的是 /boot/boot.scr 文件，写入 eMMC 时使用的是 /boot/boot-emmc.scr 文件。

12.19 如何开启远程桌面和修改默认端口 Copy Section

在软件中心 armbian-software 中选择 201 安装桌面。安装过程中会询问是否开启远程桌面，输入 y 即可启用。远程桌面默认端口为 3389，可根据需要自定义端口：

sudo nano /etc/xrdp/xrdp.ini
# 修改为自定义端口，例如 5000
port=5000

12.20 TCP 拥塞控制优化方案 Copy Section

针对不同性能的设备，建议采用差异化的网络栈配置以获得最佳体验。请根据您的设备实际情况，编辑配置文件 /etc/sysctl.conf 并修改以下两行：

• 千兆设备（高性能/现代架构）：建议使用 fq + bbr 组合，以最大化吞吐量并提升抗丢包能力。
• 百兆设备（低性能/老旧架构）：建议使用 fq_codel + cubic 组合，以降低 CPU 负载并确保低延迟稳定性。

# 方案 A：千兆设备/高性能推荐 (Gigabit/High Performance)
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

# 方案 B：百兆设备/低性能推荐 (100M/Low Performance)
# net.core.default_qdisc = fq_codel
# net.ipv4.tcp_congestion_control = cubic

12.21 关于 HDMI EDID 识别异常问题的解决方法 Copy Section

应用场景：部分设备的 HDMI 接口无法从显示器读取 EDID（显示器的 EDID 芯片在 DDC 总线上不应答，属于板级硬件共性），内核拿不到显示器的能力列表，表现为无显示输出或只能以 1024x768 兜底分辨率输出（典型如 bdy-g98，详见 ophub/fnnas#606）。类似地，使用 KVM 切换器、HDMI 转接/采集设备时 EDID 也可能丢失或异常；或者在无显示器（headless）场景下，希望系统始终以固定分辨率输出。这些情况都可以通过内核参数强制注入一份 EDID 固件，绕开对显示器的读取。

工作原理：系统镜像已内置 initramfs 钩子，每次生成/重建 initramfs 时都会自动把 /lib/firmware/edid/ 目录下的全部 EDID 固件文件（预置约 30 个常用分辨率）打包进去。该机制默认处于待命状态——只要不加内核参数，打包进去的文件不产生任何影响。

添加方法：编辑 /boot/armbianEnv.txt，在 extraargs= 一行的末尾追加（以 6.x 内核为例）：

extraargs=video=HDMI-A-1:e drm.edid_firmware=HDMI-A-1:edid/1920x1080.bin

其中 video=HDMI-A-1:e 用于强制使能该接口（可选），drm.edid_firmware= 指定强制使用的 EDID 文件（路径相对于 /lib/firmware/）。两个容易踩的坑：

• 配置文件可能是 /boot/armbianEnv.txt、/boot/uEnv.txt 或 /boot/extlinux/extlinux.conf 等，请根据实际情况修改。
• 参数前缀与内核版本有关：6.x 内核用 drm.edid_firmware，早期内核用 drm_kms_helper.edid_firmware。不确定时在设备上确认：存在 /sys/module/drm/parameters/edid_firmware 就用 drm. 前缀，否则查看 /sys/module/drm_kms_helper/parameters/ 下的同名文件。前缀写错内核会静默忽略，不报错也不生效。
• 接口名不一定是 HDMI-A-1，可用 ls /sys/class/drm/ | grep HDMI 查看设备上的实际名称。

保存后重建 initramfs 并重启：

# 若提示 "update-initramfs: Not updating initramfs."，先执行：
sed -i 's/^update_initramfs=.*/update_initramfs=yes/' /etc/initramfs-tools/update-initramfs.conf

update-initramfs -u -k $(uname -r)
reboot

验证：

lsinitramfs /boot/initrd.img-$(uname -r) | grep edid   # initramfs 中应能看到 edid 文件
dmesg | grep -i edid                                   # 确认固件被内核加载
cat /sys/class/drm/card0-HDMI-A-1/modes                # 出现目标分辨率即生效

更换分辨率：从 ls /lib/firmware/edid/ 列出的预置文件中另选一个（如 1920x1080_50hz.bin），把内核参数指向新文件名，重新执行上面的 update-initramfs 命令并重启即可。也可以放入自制的 EDID 文件（128 字节的基块，或带扩展块的多块文件），方法相同。

注意事项：

• 预置的 EDID 不含 CTA 扩展块，因此 HDMI 音频不可用；需要音频时请换用带扩展块的 EDID 文件。
• 需要内核开启 CONFIG_DRM_LOAD_EDID_FIRMWARE=y（本仓库编译的内核已开启）。
• 想恢复显示器自动识别：从 extraargs 中删掉这两个参数，重启即可，无需其他操作。

File: documents/README.md Copy Chapter

Armbian Build and Usage Guide

English Instructions | 中文说明 | 日本語説明

GitHub Actions is a CI/CD service from Microsoft that provides high-performance virtual server environments for building, testing, packaging, and deploying projects. Public repositories can use it free of charge with no time limit, and each build can run for up to 6 hours — more than sufficient for compiling Armbian (typically completed within about 3 hours). This project is shared for educational and experience-exchange purposes. Please do not initiate any harmful network attacks or misuse GitHub Actions.

Table of Contents

• Armbian Build and Usage Guide
• Table of Contents
  • 1. Register your own Github account
  • 2. Set up private variable GITHUB_TOKEN etc
  • 3. Fork the repository and set Workflow permissions
  • 4. Customization instructions for personalized Armbian system files
  • 5. Compile the system
    • 5.1 Manual Compilation
    • 5.2 Scheduled Compilation
    • 5.3 Customizing Default System Configuration
    • 5.4 Expanding Github Actions Compilation Space Using Logical Volumes
    • 5.5 Build Armbian Docker image
  • 6. Saving the System
  • 7. Downloading the System
  • 8. Installing Armbian to EMMC
    • 8.1 Installation Method for Amlogic Series
    • 8.2 Installation Method for Rockchip Series
      • 8.2.1 Installation Method for Radxa-Rock5B
        • 8.2.1.1 Install the System to MicroSD
        • 8.2.1.2 Install the System to eMMC
        • 8.2.1.3 Installation of the system on NVMe
      • 8.2.2 Installation method for FastRhino R66S
      • 8.2.3 Installation method for FastRhino R68S
      • 8.2.4 Installation method for Beikeyun
      • 8.2.5 Installation method for Chainedbox-L1-Pro
      • 8.2.6 Installation method for lckfb-tspi
    • 8.3 Allwinner Series Installation Method
    • 8.4 Installation Method for the Docker Version of Armbian
      • 8.4.1 Install Docker Runtime Environment
      • 8.4.2 Configure macvlan Network
      • 8.4.3 Run Armbian Docker Container
  • 9. Compiling Armbian Kernel
    • 9.1 How to Add Custom Kernel Patches
    • 9.2 How to Make Kernel Patches
    • 9.3 How to Customize Compilation of Driver Modules
  • 10. Updating Armbian Kernel
  • 11. Installing Common Software
  • 12. Frequently Asked Questions
    • 12.1 dtb and u-boot Correspondence Table for Each Box
    • 12.2 Instructions for LED Screen Display Control
    • 12.3 How to Restore the Original Android TV System
      • 12.3.1 Backup and Restore Using Armbian-ddbr
      • 12.3.2 Recovering using Amlogic Flashing Tool
    • 12.4 Setting the box to boot from USB/TF/SD
      • 12.4.1 Initial Installation of Armbian System
      • 12.4.2 Reinstallation of Armbian System
    • 12.5 Disable Infrared Receiver
    • 12.6 Boot file selection
    • 12.7 Network Configuration
      • 12.7.1 Network Configuration Using Interfaces
        • 12.7.1.1 IP Address Assignment via DHCP
        • 12.7.1.2 Manual Setup of Static IP Address
        • 12.7.1.3 Establish Interconnected Network Using OpenWrt in Docker
      • 12.7.2 Network Management Using NetworkManager
        • 12.7.2.1 Create a New Network Connection
          • 12.7.2.1.1 Get Network Interface Name
          • 12.7.2.1.2 Get Existing Network Connection Name
          • 12.7.2.1.3 Create a Wired Network Connection
          • 12.7.2.1.4 Creating a Wireless Network Connection
        • 12.7.2.2 Modify WiFi SSID or PASSWD in Wireless Network Connection
        • 12.7.2.3 Modify Network Address Allocation Method
          • 12.7.2.3.1 Static IP address - IPv4
          • 12.7.2.3.2 DHCP Obtains Dynamic IP Address - IPv4 / IPv6
        • 12.7.2.4 Modify Network Connection MAC Address
          • 12.7.2.4.1 Method 1: Use the nmcli command to change the MAC address
          • 12.7.2.4.2 Method 2: Modify the MAC address via a configuration file
        • 12.7.2.5 How to Disable IPv6
      • 12.7.3 How to Enable Wireless
      • 12.7.4 How to Enable Bluetooth
    • 12.8 How to Add Startup Tasks
    • 12.9 How to Update Service Scripts in the System
    • 12.10 How to Get Android System Partition Information on eMMC
      • 12.10.1 Obtaining Partition Information
      • 12.10.2 Sharing Partition Information
      • 12.10.3 Interpreting Partition Information
      • 12.10.4 For eMMC Installation
    • 12.11 How to build the u-boot file
      • 12.11.1 How to build the u-boot file for Amlogic devices
        • 12.11.1.1 How to extract the bootloader and dtb files
        • 12.11.1.2 How to create the acs.bin file
        • 12.11.1.3 How to build the u-boot file
      • 12.11.2 How to build the u-boot file for Rockchip devices
        • 12.11.2.1 How to use Radxa's u-boot building script
        • 12.11.2.2 How to use cm9vdA's u-boot building script
    • 12.12 Error in Memory Size Recognition
    • 12.13 How to Decompile dtb Files
      • 12.13.1 Directly Decompile dtb Files
      • 12.13.2 Export Full-State DTS from a Running Device (Recommended)
    • 12.14 How to Modify cmdline Settings
    • 12.15 How to Add New Supported Devices
      • 12.15.1 Add Device Configuration File
      • 12.15.2 Add System Files
      • 12.15.3 Add u-boot Files
        • 12.15.3.1 Check the Partition Layout
        • 12.15.3.2 Back Up Key Partitions
        • 12.15.3.3 Add a Special Partition Writing File
      • 12.15.4 Add Process Control Files
    • 12.16 How to Resolve the Issue of I/O Errors While Writing to eMMC
    • 12.17 How to Solve the Issue of No Sound in the Bullseye Version
    • 12.18 How to build the boot.scr file
    • 12.19 How to Enable Remote Desktop and Modify the Default Port
    • 12.20 TCP Congestion Control Optimization Guide

1. Register your own Github account Copy Chapter

Register an account to proceed with system customization. Click the Sign up button in the upper right corner of github.com and follow the prompts to complete registration.

2. Set up private variable GITHUB_TOKEN etc Copy Chapter

According to the GitHub Docs, GitHub automatically creates a unique GITHUB_TOKEN secret at the start of every workflow job for use within the workflow. The {{ secrets.GITHUB_TOKEN }} can be used for authentication within the workflow job.

When building an Armbian Docker image in Actions and pushing it to Docker Hub, you need to set two secrets: DOCKERHUB_USERNAME and DOCKERHUB_PASSWORD. On your repository's page, click Settings in the top right corner, then navigate to Settings > Secrets and variables > Actions > Repository secrets > New repository secret, add the following two secrets:

• Secret name DOCKERHUB_USERNAME: The value is your username for logging into Docker Hub.
• Secret name DOCKERHUB_PASSWORD: The value is your password for logging into Docker Hub.

3. Fork the repository and set Workflow permissions Copy Chapter

Fork the repository by opening https://github.com/ophub/amlogic-s9xxx-armbian and clicking the Fork button in the upper right to copy the repository to your account. Once the fork is complete, navigate to your copy. Then go to Settings > Actions > General > Workflow permissions in the left navigation bar and save. The illustration is as follows:

4. Customization instructions for personalized Armbian system files Copy Chapter

The system compilation process is controlled in the .github/workflows/build-armbian-arm64-server-image.yml file. Additional .yml files in the workflows directory handle other functions. The system is compiled using Armbian's current official source code. Refer to the official documentation for parameter details.

- name: Compile Armbian [ ${{ inputs.set_release }} ]
  id: compile
  if: ${{ steps.down.outputs.status }} == 'success' && !cancelled()
  run: |
    # Compile method and parameter description: https://docs.armbian.com/Developer-Guide_Build-Options
    cd build/
        ./compile.sh RELEASE=${{ inputs.set_release }} BOARD=odroidn2 BRANCH=current BUILD_MINIMAL=no \
                      BUILD_ONLY=default HOST=armbian BUILD_DESKTOP=no EXPERT=yes KERNEL_CONFIGURE=no \
                      COMPRESS_OUTPUTIMAGE="sha" SHARE_LOG=yes
    echo "status=success" >> ${GITHUB_OUTPUT}

When building Armbian with ophub, the armbian_files parameter allows you to add or overwrite custom files in the common-files directory. The directory structure must strictly mirror the Armbian root filesystem to ensure files are correctly overlaid into the firmware (e.g., default configuration files should be placed under the etc/default/ subdirectory). Example configuration:

- name: Rebuild Armbian
  uses: ophub/amlogic-s9xxx-armbian@main
  with:
    build_target: armbian
    armbian_path: build/output/images/*.img.gz
    armbian_files: files
    ...

5. Compile the system Copy Chapter

The system can be compiled manually, on a schedule, or triggered by specific events. The following sections cover each method.

5.1 Manual Compilation Copy Section

In your repository's navigation bar, click the Actions button, then select Build armbian > Run workflow > Run workflow to start compilation. The process takes approximately 3 hours and is complete once all steps finish. The illustration is as follows:

5.2 Scheduled Compilation Copy Section

In the .github/workflows/build-armbian-arm64-server-image.yml file, use Cron to configure scheduled compilation. The five fields represent minutes (0–59) / hours (0–23) / day of month (1–31) / month (1–12) / day of week (0–6, Sunday–Saturday). Modify values as needed. The system uses UTC by default; convert to your local time zone accordingly.

schedule:
  - cron: '0 17 * * *'

5.3 Customizing Default System Configuration Copy Section

The default system configuration information is recorded in the model_database.conf file, in which the BOARD name must be unique.

Devices with BUILD set to yes are included in the default build and can be used directly. Devices set to no are not packaged by default. To use an unpackaged device, download the Armbian system with the same FAMILY, write it to USB, then open the USB boot partition on your computer and modify the FDT dtb name in /boot/uEnv.txt to match your device.

For local compilation, use the -b parameter; for GitHub Actions, use the armbian_board parameter. -b all packages all devices with BUILD set to yes. Specifying a BOARD explicitly will package it regardless of its BUILD value. For example: -b r68s_s905x3-tx3_s905l3a-cm311.

5.4 Expanding Github Actions Compilation Space Using Logical Volumes Copy Section

GitHub Actions provides 84GB of compile space by default, with approximately 50GB available after accounting for the system and required packages. When compiling all firmware, this may be insufficient. Use logical volumes to expand the compile space to approximately 110GB. Refer to the .github/workflows/build-armbian-arm64-server-image.yml file and use the commands below to create a logical volume. Then use the logical volume path during compilation.

- name: Create simulated physical disk
  run: |
    mnt_size=$(expr $(df -h /mnt | tail -1 | awk '{print $4}' | sed 's/[[:alpha:]]//g' | sed 's/\..*//') - 1)
    root_size=$(expr $(df -h / | tail -1 | awk '{print $4}' | sed 's/[[:alpha:]]//g' | sed 's/\..*//') - 4)
    sudo truncate -s "${mnt_size}"G /mnt/mnt.img
    sudo truncate -s "${root_size}"G /root.img
    sudo losetup /dev/loop6 /mnt/mnt.img
    sudo losetup /dev/loop7 /root.img
    sudo pvcreate /dev/loop6
    sudo pvcreate /dev/loop7
    sudo vgcreate github /dev/loop6 /dev/loop7
    sudo lvcreate -n runner -l 100%FREE github
    sudo mkfs.xfs /dev/github/runner
    sudo mkdir -p /builder
    sudo mount /dev/github/runner /builder
    sudo chown -R runner:runner /builder
    df -Th

5.5 Build Armbian Docker image Copy Section

To create a Docker image of the Armbian system, refer to the armbian_docker build script.

6. Saving the System Copy Chapter

System storage is also configured in the .github/workflows/build-armbian-arm64-server-image.yml file. The compiled system is automatically uploaded to GitHub Releases via script.

- name: Upload Armbian image to Release
  uses: ophub/upload-to-release@main
  if: ${{ env.PACKAGED_STATUS }} == 'success' && !cancelled()
  with:
    tag: Armbian_${{ env.ARMBIAN_RELEASE }}_${{ env.PACKAGED_OUTPUTDATE }}
    artifacts: ${{ env.PACKAGED_OUTPUTPATH }}/*
    allow_updates: true
    gh_token: ${{ secrets.GITHUB_TOKEN }}
    body: |
      These are the Armbian OS image
      * OS information
      Default username: root
      Default password: 1234
      Install command: armbian-install
      Update command: armbian-update

7. Downloading the System Copy Chapter

Navigate to the Releases section on the repository homepage and select the system image matching your device model. The illustration is as follows:

8. Installing Armbian to EMMC Copy Chapter

Installation methods vary across Amlogic, Rockchip, and Allwinner platforms. Devices differ in storage options — some use external microSD cards, some have eMMC, and some support NVMe or other media. Each platform's installation method is described separately below. First, download the appropriate Armbian system image for your device from Releases and decompress it to .img format. Depending on your device, follow the corresponding installation method.

After installation, connect the device to your router and allow 2 minutes for it to boot. Then find the device's IP address (listed as Armbian) in your router's admin panel and connect via SSH. The default username is root, the default password is 1234, and the default port is 22.

8.1 Installation Method for Amlogic Series Copy Section

Log in to the Armbian system (default user: root, default password: 1234) → Enter the command:

armbian-install

Example: armbian-install -m yes -a no

8.2 Installation Method for Rockchip Series Copy Section

Installation methods differ by device and are described individually below.

8.2.1 Installation Method for Radxa-Rock5B

Radxa-Rock5B supports multiple storage media (microSD/eMMC/NVMe), each with a different installation method. Download the rk3588_spl_loader_v1.08.111.bin and spi_image.img files. Download the RKDevTool tool and driver. Download Rufus or balenaEtcher for writing disk images.

8.2.1.1 Install the System to MicroSD

Use Rufus, balenaEtcher, or a similar tool to write the Armbian system image to a microSD card, then insert it into the device.

8.2.1.2 Install the System to eMMC

• Install via microSD card: Write the Armbian system image to a microSD card and boot the device from it. Upload the armbian.img file to the microSD card, then use dd to write it to eMMC:

dd if=armbian.img  of=/dev/mmcblk1  bs=1M status=progress

• Install via USB-to-eMMC card reader: Connect the eMMC module to your computer, use Rufus or balenaEtcher to write the Armbian system image to eMMC, then insert the eMMC module into the device.
• Install via Maskrom mode: Power off the development board. Hold the gold button, then connect a USB-A to Type-C cable between the ROCK 5B Type-C port and your PC. Release the gold button. Verify that a MASKROM device is detected. Right-click in the blank area of the list and load the rock-5b-emmc.cfg configuration file (the configuration file and RKDevTool are in the same directory). Set rk3588_spl_loader_v1.08.111.bin and Armbian.img as shown below and begin writing.

8.2.1.3 Installation of the system on NVMe

The ROCK-5B has an SPI flash memory on its motherboard. Installing the bootloader on this SPI flash memory can support other boot media (such as SATA, USB3, or NVMe) that are not directly supported by the SoC maskrom mode. To use NVMe, you must first write the SPI file. The method is as follows:

Power off the development board and remove all bootable devices (MicroSD cards, eMMC modules, etc.). Press and hold the golden button, then connect a USB-A to Type-C cable between the ROCK-5B and your PC. Release the golden button. Verify that a MASKROM device is detected. Right-click in the list to load the configuration file from the resource folder (the configuration file and RKDevTool are in the same directory), select rk3588_spl_loader_v1.08.111.bin and spi_image.img files according to the figure below, and click write:

• Install via card reader: Insert the M.2 NVMe SSD into an M.2 NVMe-to-USB 3.0 card reader and connect it to your computer. Use Rufus or balenaEtcher to write the Armbian system image to the NVMe drive, then install it in the device.
• Install via microSD card: Write the Armbian system image to a microSD card and boot the device from it. Upload the armbian.img file to the microSD card, then use dd to write it to NVMe:

dd if=armbian.img  of=/dev/nvme0n1  bs=1M status=progress

8.2.2 Installation method for FastRhino R66S

Use Rufus or balenaEtcher to write the Armbian system image to a microSD card, then insert it into the device.

8.2.3 Installation method for FastRhino R68S

• Download the RKDevTool tool and driver. Unzip, install the DriverAssistant driver, and open RKDevTool.
• With R68s powered off, connect the USB male-to-male cable, press and hold the Recovery key, then plug in the 12V power supply. Release the Recovery key after two seconds — the flashing tool should discover a LOADER device.
• Right-click in the blank area of the RKDevTool interface to add an item.
• Set address to 0x00000000, name to armbian, and path to the armbian.img system file.
• Select the armbian entry, deselect all other entries, and click execute to write.
• Note: If another system exists on eMMC, erase it first via Advanced Features before writing Armbian. If erasure fails, reflash the MiniLoaderAll.bin bootloader first, then enter MASKROM mode to write Armbian. MiniLoaderAll.bin settings: address 0xCCCCCCCC, name Loader, path to the MiniLoaderAll.bin file in the Image directory of RKDevTool.

8.2.4 Installation method for Beikeyun

This method is based on milton's tutorial. Flashing requires entering Maskrom mode. Disconnect all connections, short the CLK and GND contacts (using the TTL GND or the GND near the small button), then connect via USB to your PC. A MASKROM device should be detected. The short-circuit point location is shown below:

Open RKDevTool and right-click to add an item.

• Address 0xCCCCCCCC, name Boot, path select rk3328_loader_v1.14.249.bin.
• Address 0x00000000, name system, path select the Armbian.img system to be flashed.
• Check the "Force Write by Address" option, click "Execute," and wait for the progress to complete on the right-hand download panel.

8.2.5 Installation method for Chainedbox-L1-Pro

This method is based on cc747's tutorial. Power off the Chainedbox-L1-Pro and unplug all cables. Connect a USB male-to-male cable between the USB 2.0 port on the Chainedbox-L1-Pro and your computer. Insert a paperclip into the Reset hole and hold it down, then plug in the power cord. Wait until discovered a LOADER device appears at the bottom of RKDevTool, then release the paperclip. Switch to Advanced Features and click Enter Maskrom until Found a MASKROM device appears. Right-click to add an item.

• Address 0xCCCCCCCC, name Boot, path select rk3328_loader_v1.14.249.bin.
• Address 0x00000000, name system, path select the Armbian.img system to be flashed.
• Check the "Force Write by Address" option, click "Execute," and wait for the progress to complete on the right-hand download panel.

8.2.6 Installation method for lckfb-tspi

• Download the RKDevTool tool and driver. Unzip, install the DriverAssistant driver, and open RKDevTool. (Note: use version 2.86 instead of 2.92, as version 2.92 crashes during flashing.)
• With the tspi powered off, press and hold the Recovery key, then insert the Type-C data cable. Release the Recovery key after RKDevTool displays A LOADER device was found. Right-click to add an item.
• Address 0x00000000, name system, path select the Armbian.img system to be flashed.
• Click Execute and wait for the progress to complete.

8.3 Allwinner Series Installation Method Copy Section

Log in to the Armbian system (default user: root, default password: 1234) → Enter the command:

armbian-install

8.4 Installation Method for the Docker Version of Armbian Copy Section

You can use Docker versions of Armbian images on Ubuntu/Debian/Armbian systems. These images are hosted on Docker Hub and can be downloaded directly for use.

Four Armbian Docker images with different base versions are provided: armbian-trixie, armbian-bookworm, armbian-noble, and armbian-resolute. Each version has both arm64 and amd64 builds, allowing you to choose the appropriate version based on your needs.

Among them, armbian-trixie is based on Debian 13, armbian-bookworm is based on Debian 12, armbian-noble is based on Ubuntu 24.04, and armbian-resolute is based on Ubuntu 26.04.

The arm64 version is suitable for devices with platform architectures such as Amlogic/Rockchip/Allwinner, while the amd64 version is suitable for computers and servers with x86_64 architecture.

8.4.1 Install Docker Runtime Environment

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
sudo newgrp docker

8.4.2 Configure macvlan Network

# Check if existing docker networks include a macvlan network
docker network ls

# If there is no macvlan network, create one
# Modify the subnet, gateway, and interface name according to your actual network
docker network create -d macvlan \
    --subnet=10.1.1.0/24 \
    --gateway=10.1.1.1 \
    -o parent=eth0 \
    macvlan

8.4.3 Run Armbian Docker Container

Here, the armbian-trixie:arm64 image is used as an example to demonstrate how to run an Armbian container.

# Run the Armbian container in detached mode
# Modify the container name, IP address, image version, etc., according to your actual situation
docker run -itd --name=armbian-trixie \
    --privileged \
    --network macvlan \
    --ip 10.1.1.15 \
    --hostname=armbian-trixie \
    -e TZ=Asia/Shanghai \
    --restart unless-stopped \
    ophub/armbian-trixie:arm64

# View Armbian container logs
docker logs -f armbian-trixie

# Enter the Armbian container
docker exec -it armbian-trixie bash

# Exit the Armbian container
exit

# Stop and remove the Armbian container
docker rm -f armbian-trixie

9. Compiling Armbian Kernel Copy Chapter

Kernel compilation is supported on Ubuntu, Debian, and Armbian systems, both locally and via GitHub Actions. For details, refer to the Kernel Compilation Instructions.

9.1 How to Add Custom Kernel Patches Copy Section

When the kernel patch directory tools/patch contains a common patch directory (common-kernel-patches) or a directory matching the kernel source repository name (for example, linux-5.15.y), use -p true to automatically apply kernel patches. The directory naming convention is as follows:

~/amlogic-s9xxx-armbian
    └── compile-kernel
        └── tools
            └── patch
                ├── common-kernel-patches  # Fixed directory name: stores common kernel patches for all versions
                ├── linux-5.15.y           # Named after the kernel source library: stores dedicated patches
                ├── linux-6.1.y
                ├── linux-5.10.y-rk35xx
                └── more kernel directory...

• For local kernel compilation, manually create the corresponding directory and add your custom kernel patches.
• For GitHub Actions cloud compilation, use the kernel_patch parameter to specify the kernel patch directory in your repository. For example, see the usage in compile-beta-kernel.yml in the kernel repository:

- name: Compile the kernel
  uses: ophub/amlogic-s9xxx-armbian@main
  with:
    build_target: kernel
    kernel_version: 5.15.1_6.1.1
    kernel_auto: true
    kernel_patch: kernel-patch/beta
    auto_patch: true

When specifying a custom kernel patch via kernel_patch, follow the naming convention described above.

9.2 How to Make Kernel Patches Copy Section

• Obtained from repositories such as Armbian and OpenWrt: for example, armbian/patch/kernel and openwrt/rockchip/patches-6.1, lede/rockchip/patches-5.15 etc. Patches from these mainline kernel repositories can generally be used directly.
• Obtained from GitHub commit URLs: Appending .patch to a commit URL generates the corresponding patch file.

Before adding a custom kernel patch, compare it against the upstream kernel source repository unifreq/linux-k.x.y to verify it has not already been applied and to avoid conflicts. Tested kernel patches are encouraged to be submitted to the kernel repositories maintained by unifreq. Your contributions help make Armbian and OpenWrt more stable and functional for everyone.

9.3 How to Customize Compilation of Driver Modules Copy Section

Some drivers are not yet included in the mainline Linux kernel but can be compiled as custom modules. Only drivers compatible with the mainline kernel can be compiled; Android-specific drivers are generally unsupported. See the guide: How to Compile the rtl8189fs Driver Module⁠

For example:

/* Detailed source-code truncated for AI context efficiency. */

The illustration is as follows:

10. Updating Armbian Kernel Copy Chapter

Log in to the Armbian system → Enter the command:

# Run as root user (sudo -i)
# If no parameter is specified, it will be updated to the latest version.
armbian-update

Example: armbian-update -k 5.15 -u stable -d deb

The -k parameter accepts either an exact version number (e.g., armbian-update -k 5.15.50) or a version series (e.g., armbian-update -k 5.15), which automatically selects the latest version in that series.

During kernel updates, the current kernel is automatically backed up to /ddbr/backup, retaining the three most recent versions. If a newly installed kernel is unstable, restore a backed-up kernel at any time:

# Enter the backup kernel directory, such as 6.6.12
cd /ddbr/backup/6.6.12
# Execute the kernel update command, which will automatically install the kernel in the current directory
armbian-update

[SOS]: If an incomplete update or other issue prevents the system from booting from eMMC/NVMe/sdX, boot Armbian from another disk (e.g., USB) with any kernel version, then run armbian-update -s to restore the kernel to eMMC/NVMe/sdX. Without a disk parameter, the kernel is restored from the USB device to eMMC/NVMe/sdX by default. For systems with multiple disks, specify the target disk name explicitly. Examples:

# Restore the kernel in eMMC
armbian-update -s mmcblk1
# Restore the kernel in NVMe
armbian-update -s nvme0n1
# Restore the kernel in a removable storage device
armbian-update -s sda
# Disk names can be abbreviated as mmcblk1/nvme0n1/sda, etc., or use the complete name such as /dev/sda
armbian-update -s /dev/sda
# When the device has only one built-in storage (eMMC/NVMe/sdX), the disk name parameter can be omitted
armbian-update -s

If network issues prevent downloading from github.com, manually download the kernel files, upload them to any directory on your Armbian system, navigate to that directory, and run armbian-update for local installation. The system automatically prioritizes local kernel files when a complete set is detected in the current directory. The kernel is available in tar and deb formats. Each requires 4 files:

• The 4 required files for tar format updates are: header-xxx.tar.gz, boot-xxx.tar.gz, dtb-xxx.tar.gz, and modules-xxx.tar.gz.
• The 4 required files for deb format updates are: linux-image-xxx.deb, linux-dtb-xxx.deb, linux-headers-xxx.deb, and linux-libc-dev-xxx.deb.
• Additional kernel files are optional and do not affect the update process, as the system accurately identifies the required files. Any supported kernel version can be installed, e.g., switching from 6.6.12 to 5.15.50.

Custom options set via -r/-u/-b/-d can be saved permanently in /etc/ophub-release to avoid re-entering them each time. The corresponding settings are:

# Assign values to custom parameters
-r  :  KERNEL_REPO='ophub/kernel'
-u  :  KERNEL_TAGS='stable'
-b  :  KERNEL_BACKUP='yes'
-d  :  DOWNLOAD_TYPE='deb'

11. Installing Common Software Copy Chapter

Log in to the Armbian system → Enter the command:

armbian-software

Use armbian-software -u to update the local software center list. Based on community feedback in Issue, commonly used software is gradually integrated with one-click installation, update, and uninstallation support. This includes docker images, desktop software, application services, etc. See more instructions.

Use armbian-apt to select an appropriate software mirror for your region, improving download speeds. For example, select the mirrors.tuna.tsinghua.edu.cn source in China:

/* Detailed source-code truncated for AI context efficiency. */

12. Frequently Asked Questions Copy Chapter

This section covers common issues encountered when using Armbian.

12.1 dtb and u-boot Correspondence Table for Each Box Copy Section

The supported TV box list is located in the /etc/model_database.conf configuration file in the Armbian system.

12.2 Instructions for LED Screen Display Control Copy Section

Please refer to the instructions.

12.3 How to Restore the Original Android TV System Copy Section

Back up and restore the Android TV system using armbian-ddbr.

Alternatively, flash the Android system to eMMC via USB cable. Android system images are available in Tools.

12.3.1 Backup and Restore Using Armbian-ddbr

Before installing Armbian on a new device, back up the original Android TV system in case restoration is needed later. Boot Armbian from TF/SD/USB, run armbian-ddbr, and enter b when prompted to create a backup. The backup is saved to /ddbr/BACKUP-arm-64-emmc.img.gz — download and keep it in a safe location. To restore, upload the backup file to the same path on the TF/SD/USB device, run armbian-ddbr, and enter r when prompted.

12.3.2 Recovering using Amlogic Flashing Tool

• If the device can still boot from USB after reinserting the power supply, simply reinstall. Retry multiple times if necessary.

• If the screen remains black and the device cannot boot from USB, a short-circuit recovery is required. First restore the original Android system, then reinstall Armbian. Download and install the amlogic_usb_burning_tool recovery tool. Prepare a USB male-to-male cable and a paperclip.

• Using x96max+ as an example, locate the short-circuit point on the motherboard and download the Android TV system package. Android TV system images and short-circuit point diagrams for other common devices are also available here.

Operating method:

1. Open USB Burning Tool:
   [ File → Import image ]: X96Max_Plus2_20191213-1457_ATV9_davietPDA_v1.5.img
   [ Select ]：Erase Flash
   [ Select ]：Erase bootloader
   Click on the [ Start ] button
2. Use the [ paperclip ] to short-circuit the [ two short-circuit points ] on the box's motherboard,
   and at the same time use the [ USB double male data cable ] to connect the [ box ] with the [ computer ].
3. When you see the [ progress bar starts moving ], remove the paperclip, no longer short-circuit.
4. When you see [ progress bar at 100% ], the flashing is complete, the box has been restored to the Android TV system.
   Click on the [ Stop ] button, unplug the [ USB double male data cable ] between the [ box ] and [ computer ].
5. If any of the above steps fail, try again until successful.
   If the progress bar does not move, you can try plugging in the power supply. Normally, you don't need power support for flashing, only the power supply from the USB double male can meet the requirements.

Once factory settings are restored, follow the same steps as the initial Armbian installation.

12.4 Setting the box to boot from USB/TF/SD Copy Section

Depending on your situation, use either the initial installation or reinstallation method.

12.4.1 Initial Installation of Armbian System

• Insert the USB/TF/SD with the installed system into the box.
• Enable developer mode: Settings → About device → Version number (e.g., X96max plus...), tap the version number 5 times rapidly until You are now a developer appears.
• Enable USB debugging: System → Advanced options → Developer options → enable USB debugging and ADB debugging.
• Install ADB: Download adb and extract it. Copy adb.exe, AdbWinApi.dll, and AdbWinUsbApi.dll to c:\windows\system32 and c:\windows\syswow64. Verify the installation by running adb --version in a command prompt.
• Open a command prompt and run adb connect 192.168.1.137 (replace with your device's IP, found in your router's admin panel). A successful connection displays connected to 192.168.1.137:5555.
• Run adb shell reboot update — the device will reboot from the inserted USB/TF/SD. Access the system via its IP address in a browser or through SSH.

12.4.2 Reinstallation of Armbian System

• In normal situations, simply insert the USB drive with Armbian and boot from it. USB takes boot priority over eMMC.
• If the device does not boot from USB, rename the boot.scr file in the eMMC's /boot directory (e.g., to boot.scr.bak), then insert the USB drive and boot again.

12.5 Disable Infrared Receiver Copy Section

Infrared receiver support is enabled by default. If using the device as a server, disable the IR kernel module to prevent accidental shutdowns. To disable IR completely, add the following line:

blacklist meson_ir

to /etc/modprobe.d/blacklist.conf and restart.

12.6 Boot file selection Copy Section

• Among known devices, only T95(s905x) / T95Z-Plus(s912) / BesTV-R3300L(s905l-b) and a few others require the /bootfs/extlinux/extlinux.conf file, which is included by default in the system. If other devices require it, write the system to USB, open the boot partition, and rename /boot/extlinux/extlinux.conf.bak by removing the .bak extension. When installing to eMMC, armbian-install automatically detects and creates the extlinux.conf file if needed.

• All other devices boot using /boot/uEnv.txt only — do not modify the extlinux.conf.bak file.

12.7 Network Configuration Copy Section

12.7.1 Network Configuration Using Interfaces

The default content of the network configuration file /etc/network/interfaces is as follows:

source /etc/network/interfaces.d/*
# Network is managed by Network manager
auto lo
iface lo inet loopback

12.7.1.1 IP Address Assignment via DHCP

source /etc/network/interfaces.d/*

auto eth0
iface eth0 inet dhcp

12.7.1.2 Manual Setup of Static IP Address

Adjust the IP, gateway, and DNS values to match your network configuration.

source /etc/network/interfaces.d/*

auto eth0
allow-hotplug eth0
iface eth0 inet static
hwaddress ether 12:34:56:78:9A:DA
address 192.168.1.100
netmask 255.255.255.0
gateway 192.168.1.1
dns-nameservers 192.168.1.1

12.7.1.3 Establish Interconnected Network Using OpenWrt in Docker

Modify the MAC address as needed.

source /etc/network/interfaces.d/*

allow-hotplug eth0
no-auto-down eth0
auto eth0
iface eth0 inet manual

auto macvlan
iface macvlan inet dhcp
        pre-up ip link add macvlan link eth0 type macvlan mode bridge
        post-down ip link del macvlan link eth0 type macvlan mode bridge

auto lo
iface lo inet loopback

12.7.2 Network Management Using NetworkManager

12.7.2.1 Create a New Network Connection

Prerequisites for creating or modifying a network connection.

12.7.2.1.1 Get Network Interface Name

Check available network interfaces.

nmcli device | grep -E "^[e].*|^[w].*|^[D].*|^[T].*" | awk '{printf "%-19s%-19s\n",$1,$2}'

The DEVICE column displays the network interface name, and the TYPE column displays the network interface type.

eth0 is the first Ethernet interface, eth1 is the second, and so on. Wireless interfaces follow the same convention.

DEVICE             TYPE
eth0               ethernet
eth1               ethernet
eth2               ethernet
eth3               ethernet
wlan0              wifi
wlan1              wifi

12.7.2.1.2 Get Existing Network Connection Name

List existing network connections on the device, both active and inactive. Avoid reusing existing connection names when creating new ones.

nmcli connection show | grep -E ".*|^[N].*" | awk '{printf "%-19s%-19s\n", $1,$3}'

The NAME column displays the name of the existing network connection, and the TYPE column displays the network interface type.

ethernet = wired, wifi = wireless, bridge = bridge

NAME               TYPE
cnc                ethernet
lan                ethernet
lte                ethernet
tel                ethernet
docker0            bridge
titanium           wifi
cpe                wifi

12.7.2.1.3 Create a Wired Network Connection

Create a new network connection on interface eth0 with immediate activation (Dynamic IP Address - IPv4 / IPv6).

# Set ENV
MYCON=ether1                  # New network connection name
MYETH=eth0                    # Network interface name = eth0 / eth1 / eht2 / eth3
IPV6AGM=stable-privacy        # IPv6 address status mode = stable-privacy / eui64

# Add ETH
nmcli connection add \
con-name $MYCON \
type ethernet \
ifname $MYETH \
autoconnect yes \
ipv6.addr-gen-mode $IPV6AGM
nmcli connection up $MYCON
ip -c -br address

Create a new network connection on interface eth0 with immediate activation (Static IP Address - IPv4).

# Set ENV
MYCON=ether1                  # Network connection name
MYETH=eth0                    # Network interface name = eth0 / eth1 / eht2 / eth3
IP=192.168.67.167/24          # HOST IP address, where 24 is the subnet mask corresponding to 255.255.255.0
GW=192.168.67.1               # Gateway
DNS=119.29.29.29,223.5.5.5    # DNS server address

# Chg CON
nmcli connection add \
con-name $MYCON \
type ethernet \
ifname $MYETH \
autoconnect yes \
ipv4.method manual \
ipv4.addresses $IP \
ipv4.gateway $GW \
ipv4.dns $DNS
nmcli connection up $MYCON
ip -c -br address

12.7.2.1.4 Creating a Wireless Network Connection

Create a network connection on the wlan0 interface with immediate activation (Dynamic IP address - IPv4 / IPv6).

# Set ENV
MYCON=ssid                    # Name of the new network connection, it is recommended to use WiFi SSID to specify the connection name
MYSSID=ssid                   # WiFi SSID, case sensitive
MYPSWD=passwd                 # WiFi password
MYWSKM=wpa-psk                # Security selection WPA-WPA2 = wpa-psk or WPA3 = sae (see which encryption method is in the wireless router or AP)
MYWLAN=wlan0                  # Network interface name = wlan0 / wlan1
IPV6AGM=stable-privacy        # IPv6 address status mode = stable-privacy / eui64

# Add WLAN
nmcli connection add \
con-name $MYCON \
type wifi \
ifname $MYWLAN \
autoconnect yes \
ipv6.addr-gen-mode $IPV6AGM \
wifi.ssid $MYSSID \
wifi-sec.key-mgmt $MYWSKM \
wifi-sec.psk $MYPSWD
nmcli connection up $MYCON
ip -c -br address

12.7.2.2 Modify WiFi SSID or PASSWD in Wireless Network Connection

Update the WiFi SSID or password in the wireless network connection ssid with immediate activation.

# Set ENV
MYCON=ssid                    # Wireless network connection name
MYSSID=ssid                   # WiFi SSID, case sensitive
MYPSWD=passwd                 # WiFi password
MYWSKM=wpa-psk                # Security selection WPA-WPA2 = wpa-psk or WPA3 = sae

# Add WLAN
nmcli connection modify $MYCON \
wifi.ssid $MYSSID \
wifi-sec.key-mgmt $MYWSKM \
wifi-sec.psk $MYPSWD
nmcli connection up $MYCON
ip -c -br address

12.7.2.3 Modify Network Address Allocation Method

12.7.2.3.1 Static IP address - IPv4

Change the IP allocation method to Static IP address for network connection ether1 with immediate activation.

*Applicable to both wired and wireless connections

# Set ENV
MYCON=ether1                  # Network connection name
IP=192.168.67.167/24          # HOST IP address, where 24 is the subnet mask corresponding to 255.255.255.0
GW=192.168.67.1               # Gateway
DNS=119.29.29.29,223.5.5.5    # DNS server address

# Chg CON
nmcli connection modify $MYCON \
ipv4.method manual \
ipv4.addresses $IP \
ipv4.gateway $GW \
ipv4.dns $DNS
nmcli connection up $MYCON
ip -c -br address

12.7.2.3.2 DHCP Obtains Dynamic IP Address - IPv4 / IPv6

Change the IP allocation method to DHCP for network connection ether1 with immediate activation.

*Applicable to both wired and wireless connections

# Set ENV
MYCON=ether1                  # Network connection name

# Chg CON
nmcli connection modify $MYCON \
ipv4.method auto \
ipv6.method auto
nmcli connection up $MYCON
ip -c -br address

12.7.2.4 Modify Network Connection MAC Address

Change the MAC address on a network connection to resolve MAC address conflicts.

12.7.2.4.1 Method 1: Use the `nmcli` command to change the MAC address

# Use the `nmcli connection show` command to view the network interface name
nmcli connection show
# The returned result contains the network interface name, such as 'Wired connection 1'
NAME                UUID                                  TYPE      DEVICE
Wired connection 1  24d63dc7-c46f-3bf1-912f-1c33eb94338b  ethernet  eth0
lo                  35ca24e5-bdc0-4658-8ac8-435ee22e07f3  loopback  lo
Wired connection 2  59660b21-b460-30e0-8cb3-89b886556955  ethernet  --

# Set ENV
MYCON='Wired connection 1'    # Network connection name, note to match the network interface type
MYTYPE='802-3-ethernet'       # Network interface type = Wired network card / Wireless network card
                              #                        = 802-3-ethernet     / 802-11-wireless
MYMAC='12:34:56:78:9A:BC'     # Set new MAC address

# Chg CON
nmcli connection modify "${MYCON}" ${MYTYPE}.cloned-mac-address ${MYMAC}
nmcli connection up "${MYCON}"
ip -c a show "${MYCON}"

• Modifying certain network parameters may temporarily disconnect and reconnect the network.
• Depending on the hardware and software environment, changes take 1–15 seconds to apply. If changes do not take effect within this period, check your hardware and software configuration.

12.7.2.4.2 Method 2: Modify the MAC address via a configuration file

Create a MAC address override configuration file.

sudo mkdir -p /etc/systemd/network/
sudo nano /etc/systemd/network/10-mac-override.link

Add the following content:

[Match]
# Specify the network interface name whose MAC address needs to be changed
OriginalName=eth0

[Link]
# Set a valid MAC address
MACAddress=02:55:66:77:88:99

Changes take effect after reboot.

12.7.2.5 How to Disable IPv6

Use nmcli to disable IPv6 from the command line. Please refer to disable-ipv6 for the source.

Step 1: View the network connection list:

NAME                 UUID                                   TYPE       DEVICE
Wired connection 1   8a7e0151-9c66-4e6f-89ee-65bb2d64d366   ethernet   eth0
...

Step 2: Set the connection's ipv6.method parameter to disabled:

nmcli connection modify "Wired connection 1" ipv6.method "disabled"

Step 3: Reconnect to the network:

nmcli connection up "Wired connection 1"

Step 4: Verify the connection status. If no inet6 entry appears, IPv6 is disabled:

ip address show eth0

Step 5: Confirm that /proc/sys/net/ipv6/conf/eth0/disable_ipv6 contains 1:

# cat /proc/sys/net/ipv6/conf/eth0/disable_ipv6
1

Alternatively, disable IPv6 system-wide by adding the following to /etc/sysctl.conf:

# Disable IPv6 by default
net.ipv6.conf.all.disable_ipv6 = 1
net.ipv6.conf.default.disable_ipv6 = 1
net.ipv6.conf.lo.disable_ipv6 = 1

12.7.3 How to Enable Wireless

Some devices support wireless connectivity. For instructions on using the wireless AP mode, please refer to the guide. For details on configuring the DHCP service in conjunction with this mode, please refer to the guide. To use the wireless client mode, please refer to the instructions below:

# Install management tool
sudo apt-get install network-manager

# Check network devices
sudo nmcli dev

# Enable wireless
sudo nmcli r wifi on

# Scan wireless
sudo nmcli dev wifi

# Connect to wireless
sudo nmcli dev wifi connect "wifi name" password "wifi password"

# Display the saved network connection list
sudo nmcli connection show

# Disconnect
sudo nmcli connection down "wifi name"

# Forget the connection and cancel automatic connection
sudo nmcli connection delete "wifi name"

12.7.4 How to Enable Bluetooth

Some devices support Bluetooth. Enable it as follows:

# Install Bluetooth support
armbian-config >> Network >> BT: Install Bluetooth support

# Reboot the system
reboot

After rebooting, verify the Bluetooth driver is functioning. Desktop environments can connect Bluetooth devices via the menu. Terminal-based configuration is also available.

dmesg | grep Bluetooth

# Connect Bluetooth device
armbian-config >> Network >> BT: Discover and connect Bluetooth devices

Bluetooth can also be managed via terminal commands:

# Check the Bluetooth service running status
sudo systemctl status bluetooth

# If not started, start the Bluetooth service first
sudo systemctl enable bluetooth
sudo systemctl start bluetooth

# Scan nearby Bluetooth devices
bluetoothctl scan on

# Enable Bluetooth discovery
bluetoothctl discoverable on

# Pair the Bluetooth MAC address
bluetoothctl pair 12:34:56:78:90:AB

# Check the paired Bluetooth devices
blluetoothctl paired-devices

# Connect to the Bluetooth device
bluetoothctl connect 12:34:56:78:90:AB

# Trust the device for easy connection next time
bluetoothctl trust 12:34:56:78:90:AB

# Disconnect the Bluetooth device
bluetoothctl disconnect 12:34:56:78:90:AB

# Unpair the Bluetooth device
bluetoothctl remove 12:34:56:78:90:AB

# Block the connected device
bluetoothctl block 12:34:56:78:90:AB

12.8 How to Add Startup Tasks Copy Section

A startup task script is included in the system. In Armbian, the path is /etc/custom_service/start_service.sh. Add your custom startup tasks to this script as needed.

12.9 How to Update Service Scripts in the System Copy Section

Run armbian-sync to update all local service scripts to the latest version.

If armbian-sync fails, the installed version may be outdated. Update it manually:

wget https://raw.githubusercontent.com/ophub/amlogic-s9xxx-armbian/main/build-armbian/armbian-files/common-files/usr/sbin/armbian-sync -O /usr/sbin/armbian-sync

chmod +x /usr/sbin/armbian-sync

armbian-sync

12.10 How to Get Android System Partition Information on eMMC Copy Section

Before writing Armbian to eMMC, confirm the device's Android partition table to ensure data is written to safe areas. Damaging the partition table may prevent the system from booting. Writing to unsafe areas can cause boot failures or errors like the one shown below:

12.10.1 Obtaining Partition Information

For Armbian versions released from this repository after November 2022, run the following command to generate a URL containing complete partition information (no internet connection required on the device):

ampart /dev/mmcblk2 --mode webreport 2>/dev/null

The webreport mode was introduced in ampart v1.2 (released 2023.02.03). If the above command produces no output, your version may be older. Use this alternative command instead:

echo "https://7ji.github.io/ampart-web-reporter/?dsnapshot=$(ampart /dev/mmcblk2 --mode dsnapshot 2>/dev/null | head -n 1)&esnapshot=$(ampart /dev/mmcblk2 --mode esnapshot 2>/dev/null | head -n 1)"

The generated URL will look similar to this:

https://7ji.github.io/ampart-web-reporter/?esnapshot=bootloader:0:4194304:0%20reserved:37748736:67108864:0%20cache:113246208:754974720:2%20env:876609536:8388608:0%20logo:893386752:33554432:1%20recovery:935329792:33554432:1%20rsv:977272832:8388608:1%20tee:994050048:8388608:1%20crypt:1010827264:33554432:1%20misc:1052770304:33554432:1%20instaboot:1094713344:536870912:1%20boot:1639972864:33554432:1%20system:1681915904:1073741824:1%20params:2764046336:67108864:2%20bootfiles:2839543808:754974720:2%20data:3602907136:4131389440:4&dsnapshot=logo::33554432:1%20recovery::33554432:1%20rsv::8388608:1%20tee::8388608:1%20crypt::33554432:1%20misc::33554432:1%20instaboot::536870912:1%20boot::33554432:1%20system::1073741824:1%20cache::536870912:2%20params::67108864:2%20data::-1:4

Open this URL in a browser to view the DTB and eMMC partition information:

12.10.2 Sharing Partition Information

When sharing partition information (e.g., reporting a new device or seeking help), share the URL rather than a screenshot. Use a URL shortener if the link is too long.

• The partition information on the webpage is dynamically generated on each visit, so annotations and table formatting may be updated over time.
• Additionally, partition parameters cannot be easily copied from screenshots for analysis.

The webpage's table layout is designed for easy copy-paste into Excel or LibreOffice Calc, eliminating the need to manually organize parameters.

12.10.3 Interpreting Partition Information

The DTB table records the desired partition layout defined in the Android DTB. This layout typically ends with a data partition that fills the remaining space, so devices with the same system (and model) share identical DTB layouts. The actual partition layout may vary due to different eMMC capacities, but is always derived from the DTB partition layout (i.e., given the DTB layout and exact eMMC size, the eMMC partition layout can be determined. Did you notice that the DTB and eMMC partition examples above come from different devices?).

The eMMC table shows the actual partition layout on the device. Each row represents a storage area — either a partition or an inter-partition gap (Amlogic reserves at least 8MB between partitions, originally intended for other purposes but unused even in the latest S905X4, effectively wasting space). Partition rows appear in black with offset and mask values. Gap rows appear in grey with no offset or mask values and are labeled gap.

The last column indicates write safety: green/yes = writable, red/no = non-writable, yellow with a label = conditionally or partially writable.

Using the above table as an example, the 0+4M (0M~4M) area of the bootloader partition is non-writable, the 32M gap (4M~36M) after it is writable, the 36M+64M (36M~100M) reserved partition is non-writable, and the gap from there to the gap before env (100M~836M) is fully writable. From 1M after env (837M to the end), the area is writable if the Android boot logo is not needed. The writable ranges on eMMC are:

• 4M~36M
• 100M~836M
• 837M~end

If the Android boot logo is needed, the 852M + 32M (852M~884M) logo partition is additionally non-writable, reducing the writable ranges to:

• 4M~36M
• 100M~836M
• 837M~852M
• 884M~end

12.10.4 For eMMC Installation

If your device fails when using armbian-install and the -a parameter (use ampart to adjust the eMMC partition layout) is yes (default value), then your box cannot use the optimal layout (that is, adjust the DTB partition information to only have data, then generate eMMC partition information from this, and then move all remaining partitions forward. In this way, the space from 117M onwards can be used). You need to modify the corresponding partition information in armbian-install.

In this file, the key parameters for declaring the partition layout are three: BLANK1, BOOT, BLANK2. Among them, BLANK1 represents the unusable size starting from the beginning of eMMC; BOOT represents the size of the partition created after BLANK1 for storing the kernel, DTB, etc., preferably not less than 256M, BLANK2 represents the unusable size after BOOT. The space after this will be used to create the ROOT partition to store all the data outside the /boot mount point in the system. All three should be integers, and the unit is MiB (1 MiB = 1024 KiB = 1024^2 Byte)

In the case discussed in the previous paragraph where the logo partition is not needed, we naturally hope to use all the usable space, but the area of 4M~36M is too small to be used as BOOT, so it can only be counted in the unusable BLANK1. The area of 100M~836M is more than enough to be used as BOOT, so this 736M can be allocated to BOOT entirely. After this, there is an unusable area of 836M~837M, which is given to BLANK2, so the parameters to be used should be as follows (only s905x3 is used as an example in the following text, if your SoC is other, you need to modify other corresponding code blocks):

# Set partition size (Unit: MiB)
elif [[ "${AMLOGIC_SOC}" == "s905x3" ]]; then
    BLANK1="100"
    BOOT="736"
    BLANK2="1"

12.11 How to build the u-boot file Copy Section

The u-boot file is a crucial component for system startup. The process of obtaining source code and the compilation workflow varies slightly across Amlogic, Allwinner, and Rockchip platforms.

12.11.1 How to build the u-boot file for Amlogic devices

Since most Amlogic device manufacturers keep their source code closed, u-boot related files must be extracted from the device before compilation. The method presented here is derived from the tutorial shared by unifreq.

12.11.1.1 How to extract the bootloader and dtb files

Extraction requires the HxD software. Download it from the official site or the backup link.

Run the following commands in the cmd panel to extract the relevant files and download them to your local computer.

# Use adb tool to enter the box
adb connect 192.168.1.111
adb shell

# Export bootloader command
dd if=/dev/block/bootloader of=/data/local/bootloader.bin

# Export dtb command
cat /dev/dtb >/data/local/mybox.dtb

# Export gpio command
cat /sys/kernel/debug/gpio >/data/local/mybox_gpio.txt

# Download the bootloader, dtb, and gpio files to the root directory of the C drive on your local computer in the mybox folder
adb pull /data/local/bootloader.bin C:\mybox
adb pull /data/local/mybox.dtb C:\mybox
adb pull /data/local/mybox_gpio.txt C:\mybox

12.11.1.2 How to create the acs.bin file

The most important part of the mainline u-boot is the acs.bin, which initializes memory. The original factory u-boot is located at the beginning of the system at the 4MB position. Use the bootloader.bin file obtained earlier to extract the acs.bin file.

Open the HxD software, open the exported bootloader.bin file, Right click - Select range, start position F200, length 1000, select hexadecimal.

Copy the selected result, then create a new file, paste in insert mode, ignore the warning, and save it as the acs.bin file.

If the bootloader is locked, the code in this area is garbled and useless. Normally, there should be many 0s as in the picture above, cfg will appear several times in succession, and ddr related words will appear in the middle. This normal code can be used.

12.11.1.3 How to build the u-boot file

Building u-boot requires the source repositories https://github.com/unifreq/amlogic-boot-fip and https://github.com/unifreq/u-boot to compile two u-boot files for your device.

Within the amlogic-boot-fip source code, the only file that varies by device model is acs.bin, all other files are universal.

For build instructions, see the device-specific documentation at https://github.com/unifreq/u-boot/tree/master/doc/board/amlogic.

Building u-boot using unifreq's method requires the device's acs.bin, dts, and config files. The dts exported from the Android system cannot be directly converted to Armbian format, so a corresponding dts file must be written manually. Based on your device's specific hardware differences (switches, LEDs, power control, TF card, SDIO wifi module, etc.), modify and create a dts file from similar ones in the kernel source repository.

For example, building u-boot for X96Max Plus:

~/make-uboot
    ├── amlogic-boot-fip
    │   ├── x96max-plus                                     # Create directory yourself
    │   │   ├── asc.bin                                     # Self-made source file
    │   │   └── other-copy-files...                         # Copy files from other directories
    │   │
    │   ├── other-source-directories...
    │   └── other-source-files...
    │
    └── u-boot
        ├── configs
        │   └── x96max-plus_defconfig                       # Self-made source file
        ├── arch
        │   └── arm
        │       └── dts
        │           ├── meson-sm1-x96-max-plus-u-boot.dtsi  # Self-made source file
        │           ├── meson-sm1-x96-max-plus.dts          # Self-made source file
        │           └── Makefile                            # Edit
        ├── fip
        │   ├── u-boot.bin                                  # Generated file
        │   └── u-boot.bin.sd.bin                           # Generated file
        ├── u-boot.bin                                      # Generated file
        │
        ├── other-source-directories...
        └── other-source-files...

• Download the amlogic-boot-fip source code. In the root directory, create a x96max-plus directory. Other than the asc.bin file that you created, all other files can be copied from other directories.
• Download the u-boot source code. Create a corresponding x96max-plus_defconfig file and put it into the configs directory. Create the corresponding meson-sm1-x96-max-plus-u-boot.dtsi and meson-sm1-x96-max-plus.dts files and put them in the arch/arm/dts directory, then edit the Makefile in this directory to add the meson-sm1-x96-max-plus.dtb file index.
• In the root directory of the u-boot source code, follow the steps in the document https://github.com/unifreq/u-boot/blob/master/doc/board/amlogic/x96max-plus.rst.

Two types of files are generated: the u-boot.bin in the u-boot root directory is an incomplete u-boot for the /boot directory (corresponds to the overload directory); the u-boot.bin and u-boot.bin.sd.bin in the fip directory are complete u-boot files for /usr/lib/u-boot/ (corresponds to the bootloader directory). The two complete versions differ by 512 bytes — the larger one has 512 bytes of zeros prepended.

💡 Tip: Before writing to eMMC for testing, review section 12.3 for recovery methods. Ensure you know the short-circuit point location, have the original .img format Android system file, and have verified the short-circuit flashing process. Master all recovery methods before proceeding.

12.11.2 How to build the u-boot file for Rockchip devices

Since most Rockchip device manufacturers have open-sourced their u-boot code, the relevant source code can be obtained directly from their repositories. Additionally, some open-source contributors have shared user-friendly u-boot compilation scripts. Below are several examples illustrating different compilation methods.

12.11.2.1 How to use Radxa's u-boot building script

Taking compiling Rock5b(rk3588) as an example.

# 01.Install the necessary build dependencies
sudo apt-get update
sudo apt-get install -y git device-tree-compiler libncurses5 libncurses5-dev build-essential libssl-dev mtools bc python dosfstools flex bison

# 02.Set up your workspace and get the source code from the Radxa Git repositories
mkdir ~/rk3588-sdk && cd ~/rk3588-sdk
git clone -b stable-5.10-rock5 https://github.com/radxa/u-boot.git
git clone -b master https://github.com/radxa/rkbin.git
git clone -b debian https://github.com/radxa/build.git

# Explanation of the source code:
# ~/rk3588-sdk/build/: Radxa helper script files and configuration files for building U-Boot, Linux kernel and rootfs.
# ~/rk3588-sdk/rkbin/: Pre-built Rockchip binaries, including first stage loader and ATF (Arm Trustzone Firmware)
# ~/rk3588-sdk/u-boot/: Second stage bootloader used to start the OS (e.g. Linux or Android)

# 03.Build u-boot （For ROCK 5B）
cd ~/rk3588-sdk
./build/mk-uboot.sh rk3588-rock-5b

# 04.After a successful build, the ~/rk3588-sdk/out/u-boot directory will be populated
~/rk3588-sdk/out/u-boot
├── idbloader.img
├── rk3588_spl_loader_v1.08.111.bin
├── spi
│   └── spi_image.img
└── u-boot.itb

By adding more options in board_configs.sh and mk-uboot.sh within the radxa/build source code, u-boot files for other devices can also be compiled. For example, see the instructions for compiling the Beelink-IPC-R(rk3588) device.

12.11.2.2 How to use cm9vdA's u-boot building script

cm9vdA provides scripts and instructions for compiling u-boot and the kernel in his open-source project cm9vdA/build-linux. The following are documented compilation processes for various Rockchip devices:

• Build u-boot for Lenovo-Leez-P710 (rk3399) device: Link
• Build u-boot for DLFR100 (rk3399) device: Link
• Build u-boot for ZYSJ (rk3399) device: Link

12.12 Error in Memory Size Recognition Copy Section

If the memory size is recognized incorrectly (4GB recognized as 1–2GB is abnormal; 3.7GB is normal), try manually copying a /boot/UBOOT_OVERLOAD file (note: "copy", not "rename" — renaming will prevent the system from booting after installation and updates). When used from USB, save it as /boot/u-boot.ext; when used from eMMC, save it as /boot/u-boot.emmc.

Do not manually copy the u-boot file for any other purpose. Incorrect u-boot files will cause boot failures and various other issues.

12.13 How to Decompile dtb Files Copy Section

12.13.1 Directly Decompile dtb Files

You can directly decompile existing dtb files and adapt by adjusting related parameters.

# Install dependencies
sudo apt-get update
sudo apt-get install -y device-tree-compiler

# 1. Decompilation command (generate dts source code using dtb file)
dtc -I dtb -O dts -o xxx.dts xxx.dtb

# 2. Compilation command (generate dtb file using dts)
dtc -I dts -O dtb -o xxx.dtb xxx.dts

# 3. Save data and reboot
sync && reboot

12.13.2 Export Full-State DTS from a Running Device (Recommended)

During the adaptation and maintenance of certain devices, we may only have access to the compiled binary device tree file (.dtb), while the corresponding kernel source code (.dts) is unavailable. In such cases, it is recommended to run the following command on a properly functioning Armbian system to directly decompile and export the currently active device tree from the kernel runtime environment:

dtc -I fs -O dts /sys/firmware/devicetree/base > my_runtime.dts

This command extracts device tree data directly from kernel memory, producing a more accurate and complete text output than simply decompiling the static .dtb file on disk. This is because the bootloader (such as U-Boot) or system firmware dynamically modifies or injects the device tree based on actual hardware detection results during the boot phase (for example: updating bootargs boot parameters in real time, dynamically toggling the status of specific peripherals, or adjusting reg register addresses). Decompiling the static file on disk directly will not capture these runtime changes.

The Runtime device tree obtained through this method represents the final applied form used by the kernel, accurately reflecting the actual topology and operational state of the hardware at the system's low level. When referencing, fixing, or re-adapting the .dts source code for the device, this file is of great reference value, making conflict troubleshooting and peripheral configuration completion more accurate and efficient.

12.14 How to Modify cmdline Settings Copy Section

In Amlogic devices, add/modify/delete settings in /boot/uEnv.txt. In Rockchip and Allwinner devices, configure in /boot/armbianEnv.txt (via the extraargs or extraboardargs parameters). Devices using /boot/extlinux/extlinux.conf configure in that file. A reboot is required after each change.

• For instance, Home Assistant Supervisor only supports docker cgroup v1, while the default Docker installation uses v2. To switch to v1, add systemd.unified_cgroup_hierarchy=0 to cmdline and reboot.

• Adding mmc_core.max_freq=50000000 to cmdline limits the maximum frequency of eMMC to 50MHz. The eMMC in certain S905L2 boxes is unstable at high frequencies (HS200/HS400, 100MHz+); downclocking can resolve issues such as boot failures, random crashes, read/write errors, and general instability.

• Adding max_loop=128 to cmdline adjusts the maximum number of loop mounts.

• Adding usbcore.usbfs_memory_mb=1024 to cmdline increases the USBFS memory buffer from the default 16 mb (cat /sys/module/usbcore/parameters/usbfs_memory_mb), improving large USB file transfers.

• Adding usbcore.usb3_disable=1 to cmdline disables all USB 3.0 devices.

• Adding usbcore.autosuspend=-1 to cmdline disables USB auto-suspend (prevents USB devices from powering down to save energy); adding rootdelay=120 makes the system wait 120 seconds before mounting the root partition at boot (giving USB devices time to become ready); adding mitigations=off disables CPU vulnerability mitigations (Spectre/Meltdown), improving performance.

• Adding extraargs=video=HDMI-A-1:1920x1080@60 to cmdline forces the display to 1080p.

12.15 How to Add New Supported Devices Copy Section

Building an Armbian system for a device requires a device configuration file, system files, u-boot files, and process control files. The methods for adding each are described below:

12.15.1 Add Device Configuration File

In the configuration file /etc/model_database.conf, add device configuration based on its test support status. Devices with BUILD set to yes are built by default; the corresponding BOARD value must be unique. These devices can use the default Armbian system directly.

Devices set to no are not packaged by default. To use them, download the Armbian system with the same FAMILY, write it to USB, open the USB boot partition on your computer, and modify the FDT dtb name in /boot/uEnv.txt to match your device.

12.15.2 Add System Files

Common files are placed in build-armbian/armbian-files/common-files, shared across all platforms.

Platform-specific files are placed in build-armbian/armbian-files/platform-files/: Amlogic, Rockchip, and Allwinner. The bootfs directory contains /boot partition files, and the rootfs directory contains Armbian system files.

For devices with special configuration requirements, add an independent directory named after the BOARD in build-armbian/armbian-files/different-files. Create bootfs and rootfs subdirectories as needed to add files under the system's /boot partition or other system paths. All folder names correspond to actual paths in the Armbian system. These files can add new files or override files from common and platform directories.

12.15.3 Add u-boot Files

Amlogic series devices, share bootloader files and u-boot files. If there are new files, put them in the corresponding directory. The bootloader files will automatically be added to the Armbian system's /usr/lib/u-boot directory during system construction, and u-boot files will be automatically added to the /boot directory.

Rockchip and Allwinner series devices, add an independent u-boot file directory named after BOARD for each device, and the corresponding series files are placed in this directory.

During the Armbian image construction, these u-boot files will be written into the corresponding Armbian image files by the rebuild script according to the configuration in /etc/model_database.conf.

For devices that can use standard U-Boot files, using them directly is strongly recommended. However, some devices may lack a suitable U-Boot. If such a device can already run other Linux systems like Ubuntu, you can try preserving key boot-related partitions to install Armbian or OpenWrt. The critical partitions that typically need preservation include bootloader, reserved, and env.

These partitions can be backed up and written back to their corresponding locations when creating a new Armbian or OpenWrt image. The resulting image, containing the original system's boot partitions, can be written to eMMC directly via the dd command or through the built-in installation tools (e.g., Armbian's armbian-install or OpenWrt's Amlogic Service plugin).

Currently, devices using this method include oes(a311d), oes-plus(s922x), and oec-turbo(rk3566). The following uses the oes(a311d) device as an example to detail the procedure.

12.15.3.1 Check the Partition Layout

ampart /dev/mmcblk2

# The partition information obtained is as follows:
# ===================================================================================
# IO seek EPT: Seeking to 37748736
# EPT report: 20 partitions in the table:
# ===================================================================================
# ID| name            |          offset|(   human)|            size|(   human)| masks
# -----------------------------------------------------------------------------------
#  0: bootloader                      0 (   0.00B)           400000 (   4.00M)      0
#     (GAP)                                                 2000000 (  32.00M)
#  1: reserved                  2400000 (  36.00M)          4000000 (  64.00M)      0
#     (GAP)                                                  800000 (   8.00M)
#  2: cache                     6c00000 ( 108.00M)         20000000 ( 512.00M)      2
#     (GAP)                                                  800000 (   8.00M)
#  3: env                      27400000 ( 628.00M)           800000 (   8.00M)      0
#     (GAP)                                                  800000 (   8.00M)
#  ... other partitions ...
# ===================================================================================

12.15.3.2 Back Up Key Partitions

dd if=/dev/mmcblk2 of=bootloader.bin bs=1M count=4 skip=0
dd if=/dev/mmcblk2 of=reserved.bin bs=1M count=8 skip=36
dd if=/dev/mmcblk2 of=env.bin bs=1M count=1 skip=628

Place the backed-up files in the corresponding directory of the u-boot repository: u-boot/amlogic/bootloader/a311d-oes.

You might have noticed that the reserved partition is 64MB in size, yet only 8MB was backed up. On the oes(a311d) device, only the first 8MB contains critical data; the remaining 56MB is empty. Here is how to verify this:

# First, back up the complete 64MB file of the reserved partition:
dd if=/dev/mmcblk2 of=reserved_64M.bin bs=1M count=64 skip=36

# Then, extract the first 8MB from the backed-up file reserved_64M.bin:
dd if=reserved_64M.bin of=reserved_first_8M.bin bs=1M count=8

# Next, check the hexadecimal contents:
hexdump -C reserved_first_8M.bin | less

# Now, examine the last few lines of the output:
0071ffd0  4c 5e a8 1f fc 5b 5b 98  ae ef b0 97 0c 3b e8 c2  |L^...[[......;..|
0071ffe0  c8 e0 b2 74 3d 67 d5 3d  24 7b 63 b7 c7 73 f5 d8  |...t=g.=${c..s..|
0071fff0  a1 b8 38 a7 57 d6 b4 b5  e8 1c ba c0 07 0f f5 79  |..8.W..........y|
00720000  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
*
00800000

Analyzing the output, the address of the last line containing non-zero data is 0071fff0. Starting from address 00720000, all content is 00 (zero). The hexdump utility uses an asterisk (*) to indicate repeated lines, meaning everything from 00720000 to the end of the file at 00800000 (the 8MB mark) is zero. Converting 0x00720000 to decimal gives 7,471,104 bytes (7.125 MB). Therefore, rounding up to 8MB for the backup is sufficient. Similarly, only the first 80KB of the env partition contains valid data, so 1MB is adequate.

12.15.3.3 Add a Special Partition Writing File

For implementation details, refer to the write_board_bootloader function in /etc/armbian-board-release.conf. This function is called during the image rebuild process. This configuration file also serves as a powerful device customization hub — it allows precise control over image partition layout and size via parameters like skip_mb="700", and supports custom scripts for kernel or system file operations. All advanced, device-specific customizations are centrally managed in this file.

12.15.4 Add Process Control Files

Add the corresponding BOARD option to armbian_board in the yml workflow control file, which supports use in Actions on github.com.

12.16 How to Resolve the Issue of I/O Errors While Writing to eMMC Copy Section

Some devices can boot Armbian normally from USB/SD/TF but report I/O write errors when writing to eMMC, such as the case in Issues:

[  284.338449] I/O error, dev mmcblk2, sector 0 op 0x1:(WRITE) flags 0x800 phys_seg 1 prio class 2
[  284.341544] Buffer I/O error on dev mmcblk2, logical block 0, lost async page write
[  284.446972] I/O error, dev mmcblk2, sector 0 op 0x1:(WRITE) flags 0x800 phys_seg 1 prio class 2
[  284.450074] Buffer I/O error on dev mmcblk2, logical block 0, lost async page write
[  284.497746] I/O error, dev mmcblk2, sector 0 op 0x1:(WRITE) flags 0x800 phys_seg 1 prio class 2
[  284.500871] Buffer I/O error on dev mmcblk2, logical block 0, lost async page write

In such cases, adjust the working mode speed and frequency of the dtb to stabilize storage read/write support. In SDR mode, the frequency is twice the speed; in DDR mode, the frequency equals the speed. For example:

sd-uhs-sdr12
sd-uhs-sdr25
sd-uhs-sdr50
sd-uhs-ddr50
sd-uhs-sdr104

max-frequency = <208000000>;

Take the code snippet in the dts file of the kernel source code as an example:

/* SD card */
&sd_emmc_b {
	status = "okay";

	bus-width = <4>;
	cap-sd-highspeed;
	sd-uhs-sdr12;
	sd-uhs-sdr25;
	sd-uhs-sdr50;
	max-frequency = <100000000>;
};

/* eMMC */
&sd_emmc_c {
	status = "okay";

	bus-width = <8>;
	cap-mmc-highspeed;
	max-frequency = <100000000>;
};

Generally, reducing the frequency of &sd_emmc_c from max-frequency = <200000000>; to max-frequency = <100000000>; resolves the issue. If not, try 50000000. Adjust &sd_emmc_b for USB/SD/TF settings, and use sd-uhs-sdr to limit speed. Modify the dts file and compile to get a test file, or use the decompilation method in Section 12.13 to modify an existing dtb file. When modifying decompiled dtb files, use hexadecimal values: decimal 200000000 = hex 0xbebc200, 100000000 = 0x5f5e100, 50000000 = 0x2faf080, 25000000 = 0x17d7840. Alternatively, refer to the cmdline configuration method in Section 12.14 and add the mmc_core.max_freq=50000000 parameter to the cmdline to limit the maximum frequency of the eMMC, thereby resolving read/write errors and instability issues.

In addition to software-layer solutions, this issue can also be resolved through hardware upgrades or physical modifications.

12.17 How to Solve the Issue of No Sound in the Bullseye Version Copy Section

Error log information for the sound issue:

Mar 29 15:47:18 armbian-ct2000 kernel:  fe.dai-link-0: ASoC: dpcm_fe_dai_prepare() failed (-22)
Mar 29 15:47:18 armbian-ct2000 kernel:  fe.dai-link-0: ASoC: no backend DAIs enabled for fe.dai-link-0

Please refer to the method in Bullseye NO Sound for settings.

curl -fsSOL https://github.com/ophub/kernel/releases/download/tools/bullseye_g12_sound-khadas-utils-4-2-any.tar.gz
tar -xzf bullseye_g12_sound-khadas-utils-4-2-any.tar.gz -C /

systemctl enable sound.service
systemctl restart sound.service

Restart Armbian for testing. If the sound still doesn't work, your device may be using an older audio output configuration. Comment out the new configuration at L137-L142 in /usr/bin/g12_sound.sh (primarily for G12B / S922X; the older G12A/S905X2 and most SM1/S905X3 based on G12A cannot use it), and uncomment the old configuration at L130-L134.

12.18 How to build the boot.scr file Copy Section

In the Armbian system, the boot.scr file in /boot is the compiled boot script. boot.scr is generated from the boot.cmd source file. Modify boot.cmd to make changes, then compile it into boot.scr using the mkimage command.

Normally, these files do not need modification. If adjustments are necessary, follow the steps below.

# Install dependencies
sudo apt-get update
sudo apt-get install -y u-boot-tools

# Edit the boot.cmd file
cd /boot
copy /boot/boot.cmd /boot/boot.cmd.bak
copy /boot/boot.scr /boot/boot.scr.bak
nano boot.cmd

# Compile the boot.scr file
mkimage -C none -A arm -T script -d boot.cmd boot.scr

# Restart to test
sync
reboot

# Additional Explanation
# For Amlogic devices, the file used in USB is /boot/boot.scr, while the file used for writing to eMMC is /boot/boot-emmc.scr.

12.19 How to Enable Remote Desktop and Modify the Default Port Copy Section

In the software center armbian-software, selecting 201 installs a desktop environment. During installation, you will be prompted to enable remote desktop — enter y to enable. The default remote desktop port is 3389. To use a custom port:

sudo nano /etc/xrdp/xrdp.ini
# Change to a custom port, for example 5000
port=5000

12.20 TCP Congestion Control Optimization Guide Copy Section

Different network stack configurations are recommended based on device performance to ensure the best user experience. Please configure your device according to its hardware capabilities by editing /etc/sysctl.conf and modifying (or adding) the following lines:

• Gigabit Devices (High Performance/Modern Arch): The fq + bbr combination is recommended to maximize throughput and improve packet loss resilience.
• 100Mbps Devices (Low Performance/Legacy Arch): The fq_codel + cubic combination is suggested to minimize CPU load and maintain low-latency stability.

# Option A: Recommended for Gigabit/High Performance Devices
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

# Option B: Recommended for 100Mbps/Low Performance Devices
# net.core.default_qdisc = fq_codel
# net.ipv4.tcp_congestion_control = cubic

12.21 How to Fix HDMI EDID Detection Problems Copy Section

Use cases: On some devices the HDMI port cannot read the EDID from the monitor (the monitor's EDID chip never answers on the DDC bus — a board-level hardware trait), so the kernel never obtains the monitor's capability list. The symptom is no display output at all, or output only at the 1024x768 fallback resolution (a typical case is bdy-g98; see ophub/fnnas#606 for details). Similarly, EDID can be lost or corrupted when using a KVM switch or an HDMI adapter/capture device; or in headless (no-monitor) setups you may want the system to always output at a fixed resolution. All of these cases can be solved by force-feeding an EDID firmware file via kernel parameters, bypassing the read from the monitor.

How it works: The system image ships with a built-in initramfs hook that automatically bundles all EDID firmware files under /lib/firmware/edid/ (about 30 common resolutions pre-installed) into the initramfs every time it is generated/rebuilt. The mechanism stays dormant by default — unless the kernel parameter is added, the bundled files have no effect at all.

How to enable: Edit /boot/armbianEnv.txt and append to the end of the extraargs= line (6.x kernel example):

extraargs=video=HDMI-A-1:e drm.edid_firmware=HDMI-A-1:edid/1920x1080.bin

Here video=HDMI-A-1:e force-enables the interface (optional), and drm.edid_firmware= specifies the EDID file to use (path relative to /lib/firmware/). Three common pitfalls:

• The config file may be /boot/armbianEnv.txt, /boot/uEnv.txt, or /boot/extlinux/extlinux.conf, etc. — modify whichever one your device actually uses.
• The parameter prefix depends on the kernel version: 6.x kernels use drm.edid_firmware, while earlier kernels use drm_kms_helper.edid_firmware. If unsure, check on the device: if /sys/module/drm/parameters/edid_firmware exists, use the drm. prefix; otherwise look for the file with the same name under /sys/module/drm_kms_helper/parameters/. A wrong prefix is silently ignored by the kernel — no error, no effect.
• The interface name is not necessarily HDMI-A-1; check the actual name on your device with ls /sys/class/drm/ | grep HDMI.

After saving, rebuild the initramfs and reboot:

# If you see "update-initramfs: Not updating initramfs.", run this first:
sed -i 's/^update_initramfs=.*/update_initramfs=yes/' /etc/initramfs-tools/update-initramfs.conf

update-initramfs -u -k $(uname -r)
reboot

Verification:

lsinitramfs /boot/initrd.img-$(uname -r) | grep edid   # the edid files should be visible in the initramfs
dmesg | grep -i edid                                   # confirm the firmware was loaded by the kernel
cat /sys/class/drm/card0-HDMI-A-1/modes                # the target resolution appears = it works

Changing the resolution: Pick another pre-installed file from the list shown by ls /lib/firmware/edid/ (e.g. 1920x1080_50hz.bin), point the kernel parameter at the new file name, then re-run the update-initramfs command above and reboot. You can also drop in a custom EDID file (a 128-byte base block, or a multi-block file with extension blocks) — the procedure is the same.

Notes:

• The pre-installed EDID files contain no CTA extension block, so HDMI audio will not work; if you need audio, use an EDID file with an extension block.
• The kernel must be built with CONFIG_DRM_LOAD_EDID_FIRMWARE=y (already enabled in the kernels compiled from this repository).
• To restore automatic monitor detection: remove the two parameters from extraargs and reboot — nothing else is needed.