# OpenWrt Production and Usage Guide
[English Instructions](README.md) | [中文说明](README.cn.md)
The method of using GitHub Actions to compile OpenWrt in the cloud, along with much of the content in this guide, comes from many technological innovators and resource contributors such as P3TERX, Flippy, and others. Thanks to their generous contributions, using OpenWrt on TV boxes has become remarkably straightforward.
GitHub Actions is a service provided by Microsoft that offers well-configured virtual server environments for building, testing, packaging, and deploying projects. It is available free of charge with no time limit for public repositories, and each compilation run can last up to 6 hours, which is more than sufficient for compiling OpenWrt (typically completed in about 3 hours). This document is shared for the purpose of exchanging experience. Please be understanding of any shortcomings, refrain from initiating any inappropriate attacks online, and do not abuse GitHub Actions.
# Table of Contents
- [OpenWrt Production and Usage Guide](#openwrt-production-and-usage-guide)
- [Table of Contents](#table-of-contents)
- [1. Register Your Own Github Account](#1-register-your-own-github-account)
- [2. Set Privacy Variable GITHUB\_TOKEN](#2-set-privacy-variable-github_token)
- [3. Fork the repository and set Workflow permissions](#3-fork-the-repository-and-set-workflow-permissions)
- [4. Personalized OpenWrt Firmware Customization File Description](#4-personalized-openwrt-firmware-customization-file-description)
- [4.1 .config File Description](#41-config-file-description)
- [4.1.1 First, Let the Firmware Support the National Language](#411-first-let-the-firmware-support-the-national-language)
- [4.1.2 Select Personalized Software Packages](#412-select-personalized-software-packages)
- [4.2 DIY Script Operations: diy-part1.sh and diy-part2.sh](#42-diy-script-operations-diy-part1sh-and-diy-part2sh)
- [Example 1, Adding Third-Party Software Packages](#example-1-adding-third-party-software-packages)
- [Example 2, Replace an Existing Same-Named Software Package in the Current Source Code Library with a Third-Party Software Package](#example-2-replace-an-existing-same-named-software-package-in-the-current-source-code-library-with-a-third-party-software-package)
- [Example 3, Achieve Certain Requirements by Modifying the Code in the Source Code Library](#example-3-achieve-certain-requirements-by-modifying-the-code-in-the-source-code-library)
- [4.3 Using Image Builder to Build Firmware](#43-using-image-builder-to-build-firmware)
- [4.4 How to keep your configuration when switching source code branches](#44-how-to-keep-your-configuration-when-switching-source-code-branches)
- [5. Firmware Compilation](#5-firmware-compilation)
- [5.1 Manual Compilation](#51-manual-compilation)
- [5.2 Scheduled Compilation](#52-scheduled-compilation)
- [5.3 Expanding Github Actions Compilation Space Using Logical Volumes](#53-expanding-github-actions-compilation-space-using-logical-volumes)
- [6. Saving Firmware](#6-saving-firmware)
- [6.1 Save to Github Actions](#61-save-to-github-actions)
- [6.2 Save to GitHub Releases](#62-save-to-github-releases)
- [6.3 Save to Third Party](#63-save-to-third-party)
- [7. Downloading Firmware](#7-downloading-firmware)
- [7.1 Download from Github Actions](#71-download-from-github-actions)
- [7.2 Download from Github Releases](#72-download-from-github-releases)
- [7.3 Download from Third Party](#73-download-from-third-party)
- [8. Install OpenWrt](#8-install-openwrt)
- [8.1 Integrating luci-app-amlogic Operation Panel at Compilation Time](#81-integrating-luci-app-amlogic-operation-panel-at-compilation-time)
- [8.2 Install Using the Operation Panel](#82-install-using-the-operation-panel)
- [8.3 Install the Docker Version of OpenWrt](#83-install-the-docker-version-of-openwrt)
- [8.3.1 Install Docker Runtime Environment](#831-install-docker-runtime-environment)
- [8.3.2 Configure macvlan Network](#832-configure-macvlan-network)
- [8.3.3 Run the OpenWrt Docker Container](#833-run-the-openwrt-docker-container)
- [9. Update OpenWrt system or kernel](#9-update-openwrt-system-or-kernel)
- [10. Advanced Tutorial on Personalized Firmware Customization](#10-advanced-tutorial-on-personalized-firmware-customization)
- [10.1 Getting to Know the Complete .config File](#101-getting-to-know-the-complete-config-file)
- [10.2 Understanding Workflow Files](#102-understanding-workflow-files)
- [10.2.1 Changing the Address and Branch of the Compilation Source Code Repository](#1021-changing-the-address-and-branch-of-the-compilation-source-code-repository)
- [10.2.2 Changing the Model and Kernel Version Number of the Box](#1022-changing-the-model-and-kernel-version-number-of-the-box)
- [10.3 Customizing Banner Information](#103-customizing-banner-information)
- [10.4 Customize feeds configuration file](#104-customize-feeds-configuration-file)
- [10.5 Customize OpenWrt default configuration files](#105-customize-openwrt-default-configuration-files)
- [10.5.1 First method is to add custom files during compilation](#1051-first-method-is-to-add-custom-files-during-compilation)
- [10.5.2 Second method is to use the openwrt\_files parameter to add custom files](#1052-second-method-is-to-use-the-openwrt_files-parameter-to-add-custom-files)
- [10.6 Opkg package management](#106-opkg-package-management)
- [10.7 Manage packages using the Web interface](#107-manage-packages-using-the-web-interface)
- [10.8 How to restore the original Android TV system](#108-how-to-restore-the-original-android-tv-system)
- [10.8.1 Backup and Recovery Using openwrt-ddbr](#1081-backup-and-recovery-using-openwrt-ddbr)
- [10.8.2 Recovery Using Amlogic Flashing Tool](#1082-recovery-using-amlogic-flashing-tool)
- [10.9 Unable to Boot After Installing Mainline u-boot](#109-unable-to-boot-after-installing-mainline-u-boot)
- [10.10 Setting up the Box to Boot from USB/TF/SD](#1010-setting-up-the-box-to-boot-from-usbtfsd)
- [10.10.1 Initial Installation of OpenWrt System](#10101-initial-installation-of-openwrt-system)
- [10.10.2 Reinstallation of OpenWrt System](#10102-reinstallation-of-openwrt-system)
- [10.11 Required OpenWrt Options](#1011-required-openwrt-options)
## 1. Register Your Own Github Account
Register your own account to proceed with firmware personalization. Click the `Sign up` button in the upper right corner of the github.com website and follow the prompts to complete registration.
## 2. Set Privacy Variable GITHUB_TOKEN
According to the [GitHub Docs](https://docs.github.com/en/actions/security-guides/automatic-token-authentication), GitHub automatically creates a unique GITHUB_TOKEN secret at the start of every workflow job for use within the workflow. You can use `{{ secrets.GITHUB_TOKEN }}` for authentication within the workflow job.
## 3. Fork the repository and set Workflow permissions
Now you can Fork the repository. Open https://github.com/ophub/amlogic-s9xxx-openwrt, click the Fork button in the upper right corner to copy the repository to your own account. After a moment, once the Fork is complete, navigate to the amlogic-s9xxx-openwrt repository under your account. Go to `Settings` > `Actions` > `General` > `Workflow permissions` in the left navigation bar, select `Read and write permissions` and save. The illustration is as follows:
## 4. Personalized OpenWrt Firmware Customization File Description
After completing the first 3 preparation steps, you can now begin personalizing firmware customization. The 3 files under the [config/lede_master](../config/lede_master) directory are used for OpenWrt firmware customization. This chapter provides only the most basic explanation to help you quickly experience the joy of personalized customization. More complex customization operations are covered in Section 10, which requires some foundational knowledge.
### 4.1 .config File Description
This file is the core file for OpenWrt software package customization, containing all configuration information. Each line of code in the file represents a configuration option. Although there are many options, management is straightforward. Let's begin with the practical operations.
#### 4.1.1 First, Let the Firmware Support the National Language
In # National language packs, luci-i18n-base: Taking France as an example, to enable French support, change
```shell
# CONFIG_PACKAGE_luci-i18n-base-fr is not set
```
to
```shell
CONFIG_PACKAGE_luci-i18n-base-fr=y
```
All personalizations in the .config file follow this same pattern. For items you don't need, add `#` at the beginning of the line and change `=y` at the end to `is not set`. For items you need, remove the `#` at the beginning and change `is not set` at the end to `=y`.
#### 4.1.2 Select Personalized Software Packages
In `#LuCI-app:`, the approach to enable and delete default software packages is the same as above. This time we delete the plugin `luci-app-zerotier` from the default software package list, just change
```shell
CONFIG_PACKAGE_luci-app-zerotier=y
```
to
```shell
# CONFIG_PACKAGE_luci-app-zerotier is not set
```
By now, you should have a clear understanding of how to perform personalized configuration. Each line in the .config file represents a configuration item that can be enabled or disabled using the method described above. The complete file spans several thousand lines; what is provided here is a simplified version. How to obtain the full configuration file for more complex customization will be covered in Section 10.
### 4.2 DIY Script Operations: diy-part1.sh and diy-part2.sh
The scripts diy-part1.sh and diy-part2.sh are executed before and after the feeds update and installation, respectively. When building personalized firmware from an OpenWrt source code repository, you may need to modify parts of the source code, add third-party packages, or delete/replace existing packages—such as changing the default IP, hostname, theme, or adding/removing software packages. These source code modification commands can be written into these two scripts. The following examples use the OpenWrt source code repository provided by coolsnowwolf.
Our operations below are all based on this source code library: [https://github.com/coolsnowwolf/lede](https://github.com/coolsnowwolf/lede)
#### Example 1, Adding Third-Party Software Packages
Step one, add the following code in diy-part2.sh:
```shell
git clone https://github.com/jerrykuku/luci-app-ttnode.git package/lean/luci-app-ttnode
```
Step two, add the activation code for this third-party software package to the .config file:
```shell
CONFIG_PACKAGE_luci-app-ttnode=y
```
This completes the integration of the third-party software package, expanding the software packages that the current source code library does not have.
#### Example 2, Replace an Existing Same-Named Software Package in the Current Source Code Library with a Third-Party Software Package
Step one, add the following code to diy-part2.sh: The first line of code removes the original software from the source code library, and the second line introduces a third-party software package with the same name.
```shell
rm -rf package/lean/luci-theme-argon
git clone https://github.com/jerrykuku/luci-theme-argon.git package/lean/luci-theme-argon
```
Step two, add the third-party software package to the .config file:
```shell
CONFIG_PACKAGE_luci-theme-argon=y
```
This achieves the replacement of an existing same-named software package in the current source code library with a third-party software package.
#### Example 3, Achieve Certain Requirements by Modifying the Code in the Source Code Library
We add support for `aarch64` to `luci-app-cpufreq` so that it can be used in our firmware (some modifications should be handled with caution—ensure you understand the impact of your changes).
Source file address: [luci-app-cpufreq/Makefile](https://github.com/coolsnowwolf/luci/blob/master/applications/luci-app-cpufreq/Makefile). Modify the code to add support for aarch64:
```shell
sed -i 's/LUCI_DEPENDS.*/LUCI_DEPENDS:=\@\(arm\|\|aarch64\)/g' package/lean/luci-app-cpufreq/Makefile
```
This completes the source code modification. Through the diy-part1.sh and diy-part2.sh scripts, we have added the necessary operation commands to make the compiled firmware better suit our personalized needs.
### 4.3 Using Image Builder to Build Firmware
The OpenWrt official website provides a pre-built `openwrt-imagebuilder-*-armsr-armv8.Linux-x86_64.tar.zst` file (download address: [https://downloads.openwrt.org/releases](https://downloads.openwrt.org/releases)). The official Image Builder can be used to add packages and plugins to this file, typically generating an openwrt-rootfs.tar.gz file in just a few minutes. For detailed instructions, refer to the official documentation: [Use Image Builder](https://openwrt.org/zh/docs/guide-user/additional-software/imagebuilder)
This repository provides a one-click build service. Simply pass the branch parameters into the [imagebuilder script](imagebuilder/imagebuilder.sh) to complete the build.
- Local build command: Run `sudo ./config/imagebuilder/imagebuilder.sh openwrt:24.10.4` in the `~/amlogic-s9xxx-openwrt` root directory. The parameter `24.10.4` is the currently available `releases` version number for [download](https://downloads.openwrt.org/releases). The generated file is located in the `openwrt/bin/targets/armsr/armv8` directory.
- Produce in `Actions` on github.com: [Build OpenWrt with Image Builder](../.github/workflows/build-openwrt-using-imagebuilder.yml)
### 4.4 How to keep your configuration when switching source code branches
The source code repositories for both [OpenWrt](https://github.com/openwrt/openwrt) and [ImmortalWrt](https://github.com/immortalwrt/immortalwrt) provide multiple branches to meet the needs of different users, which are mainly divided into Snapshot and Stable versions. Taking the official OpenWrt repository as an example, its `main` branch is the cutting-edge snapshot version. It contains the latest added features and software updates, primarily targeting developers and advanced users who want to experience new functionalities, but its stability has not been fully verified. On the other hand, versioned branches like `v24.10.4` are stable versions. They are based on a specific development point and have undergone comprehensive testing and bug fixing by the community. They are the officially recommended versions for the vast majority of regular users in production environments.
If you have previously customized a `.config` file on the `main` branch and wish to switch to the more stable `v24.10.4` branch for compilation, directly copying the `.config` file is not feasible because the configuration options and software versions may differ between the two branches. The following method is recommended, as it can safely preserve your personalized settings and apply them to the new branch:
```shell
# 1. In the main branch, generate the configuration difference file
# This command will extract all the modifications you have made relative to the default configuration.
./scripts/diffconfig.sh > myconfig.diff
# 2. Switch to the v24.10.4 stable branch
git checkout v24.10.4
git pull
# 3. Update and install the feeds for the new branch
./scripts/feeds update -a
./scripts/feeds install -a
# 4. Apply the configuration difference file to the new branch
# This will become the basis for generating the full configuration.
cp -f myconfig.diff .config
# 5. Generate the complete .config file
# The system will generate a complete configuration file based on your differentiated configuration and the defaults of the stable branch.
make defconfig
# 6. (Important) Check and fine-tune the configuration
# Open the menu to check if your packages and options have been applied correctly.
# Due to version differences, some packages in the main branch may not exist in the stable version and require manual adjustment.
make menuconfig
```
## 5. Firmware Compilation
The configuration information of the default system is recorded in the [/etc/model_database.conf](../make-openwrt/openwrt-files/common-files/etc/model_database.conf) file, where each `BOARD` name must be unique.
Devices with `BUILD` set to `yes` are packaged by default and can be used directly. Devices with `BUILD` set to `no` are not packaged by default; to use them, download a packaged system with the same `FAMILY`, write it to `USB`, then open the `boot partition` on a computer and modify the `FDT dtb name` in the `/boot/uEnv.txt` file to match your device.
When compiling locally, specify devices via the `-b` parameter; when compiling through GitHub Actions, use the `openwrt_board` parameter. Using `-b all` packages all devices whose `BUILD` is `yes`. When specifying `BOARD` parameters directly, devices can be packaged regardless of their `BUILD` value, for example: `-b r68s_s905x3-tx3_s905l3a-cm311`
### 5.1 Manual Compilation
In the navigation bar of your repository, click the Actions button, then click Build OpenWrt > Run workflow > Run workflow to start the compilation. Wait approximately 3 hours for all processes to complete. The illustration is as follows:
### 5.2 Scheduled Compilation
In the .github/workflows/build-openwrt-system-image.yml file, use Cron to set up scheduled compilation. The 5 different positions represent minute (0 - 59) / hour (0 - 23) / date (1 - 31) / month (1 - 12) / day of the week (0 - 6) (Sunday - Saturday) respectively. By modifying the values at different positions to set the time. The system defaults to UTC standard time, please convert according to the different time zones of your country.
```yaml
schedule:
- cron: '0 17 * * *'
```
### 5.3 Expanding Github Actions Compilation Space Using Logical Volumes
The default compilation space for GitHub Actions is 84G, with approximately 50G available after accounting for the system and necessary packages. When compiling all firmware, you may encounter insufficient space issues. This can be resolved by using logical volumes to expand the compilation space to approximately 110G. Refer to the method in [.github/workflows/build-openwrt-system-image.yml](../.github/workflows/build-openwrt-system-image.yml) and use the following commands to create a logical volume. Use the logical volume path during compilation.
```yaml
- 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
```
## 6. Saving Firmware
Firmware saving settings are also controlled in the .github/workflows/build-openwrt-system-image.yml file. Compiled firmware is automatically uploaded via scripts to GitHub's official Actions and Releases, or to third-party platforms (such as WeTransfer).
Currently, the maximum retention period for GitHub Actions artifacts is 90 days, Releases are permanent, and third-party platforms such as WeTransfer retain files for 7 days. We appreciate the free support provided by these service providers, and encourage responsible use of these free services.
### 6.1 Save to Github Actions
```yaml
- name: Upload artifact to Actions
uses: kittaakos/upload-artifact-as-is@master
if: ${{ steps.build.outputs.status }} == 'success' && env.UPLOAD_FIRMWARE == 'true' && !cancelled()
with:
path: ${{ env.FILEPATH }}/
```
### 6.2 Save to GitHub Releases
```yaml
- name: Upload OpenWrt Firmware to Release
uses: ophub/upload-to-release@main
if: ${{ env.PACKAGED_STATUS }} == 'success' && !cancelled()
with:
tag: openwrt_amlogic_s9xxx_lede_${{ env.PACKAGED_OUTPUTDATE }}
artifacts: ${{ env.PACKAGED_OUTPUTPATH }}/*
allow_updates: true
gh_token: ${{ secrets.GITHUB_TOKEN }}
body: |
This is OpenWrt firmware for Amlogic s9xxx tv box
* Firmware information
Default IP: 192.168.1.1
Default username: root
Default password: password
Default WIFI name: OpenWrt
Default WIFI password: none
Install to EMMC: Login to OpenWrt → System → Amlogic Service → Install OpenWrt
```
### 6.3 Save to Third Party
```yaml
- name: Upload OpenWrt Firmware to WeTransfer
if: ${{ steps.build.outputs.status }} == 'success' && env.UPLOAD_WETRANSFER == 'true' && !cancelled()
run: |
curl -fsSL git.io/file-transfer | sh
./transfer wet -s -p 16 --no-progress ${{ env.FILEPATH }}/{openwrt_s9xxx_*,openwrt_n1_*} 2>&1 | tee wetransfer.log
echo "WET_URL=$(cat wetransfer.log | grep https | cut -f3 -d" ")" >> $GITHUB_ENV
```
## 7. Downloading Firmware
Download the OpenWrt firmware that has been compiled and uploaded to the relevant storage locations.
### 7.1 Download from Github Actions
Click the Actions button in the repository navigation bar. In the All workflows list, click on the completed firmware list and select the firmware that corresponds to your box model. The illustration is as follows:
### 7.2 Download from Github Releases
Enter from the Release section in the lower right corner of the repository homepage, select the firmware that corresponds to your box model. The illustration is as follows:
### 7.3 Download from Third Party
In the .github/workflows/build-openwrt-system-image.yml file, uploading to third-party platforms is disabled by default. To enable it, change `false` to `true`, and the firmware will be uploaded to the third party after the next compilation. The third-party URL can be found in the compilation process logs or output to the compilation information.
```yaml
UPLOAD_COWTRANSFER: false
UPLOAD_WETRANSFER: false
```
The third-party upload support comes from https://github.com/Mikubill/transfer. If needed, you can add more third-party support according to the documentation (please use free resources responsibly). The illustration is as follows:
## 8. Install OpenWrt
### 8.1 Integrating luci-app-amlogic Operation Panel at Compilation Time
1. Get the source code of the plugin `luci-app-amlogic`:
```shell
rm -rf package/luci-app-amlogic
git clone https://github.com/ophub/luci-app-amlogic.git package/luci-app-amlogic
```
2. After executing `menuconfig`, you can select the plugin `LuCI ---> 3. Applications ---> <*> luci-app-amlogic`
For more instructions on the plugin, see: [https://github.com/ophub/luci-app-amlogic](https://github.com/ophub/luci-app-amlogic)
### 8.2 Install Using the Operation Panel
1. For the `Rockchip` platform, please refer to the introduction in the [Chapter 8](https://github.com/ophub/amlogic-s9xxx-armbian/blob/main/documents/README.md#8-installing-armbian-to-emmc) of the instruction manual, which is the same as the Armbian installation method.
2. For the `Amlogic` and `Allwinner` platforms, use tools like [Rufus](https://rufus.ie/) or [balenaEtcher](https://www.balena.io/etcher/) to write the firmware into the USB, then insert the USB with the firmware into the box. Access the default IP of OpenWrt from the browser: 192.168.1.1 → `Log in to OpenWrt using the default account` → `System Menu` → `Amlogic Treasure Box` → `Install OpenWrt`.
### 8.3 Install the Docker Version of OpenWrt
You can use Docker versions of OpenWrt images on systems such as Ubuntu, Debian, and Armbian. These images are hosted on [Docker Hub](https://hub.docker.com/r/ophub) and can be downloaded directly for use.
#### 8.3.1 Install Docker Runtime Environment
Here, taking the Ubuntu system as an example, use the following commands to install the Docker runtime environment:
```shell
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
sudo newgrp docker
```
#### 8.3.2 Configure macvlan Network
```shell
# 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.3.3 Run the OpenWrt Docker Container
```shell
# Run the OpenWrt container in detached mode
docker run -d --name=openwrt \
--network macnet \
--privileged \
--restart always \
ophub/openwrt-armv8:latest
# View OpenWrt container logs
docker logs -f openwrt
# Enter the OpenWrt container
docker exec -it openwrt bash
# Modify IP, gateway, DNS, etc.
# After modification, press the ESC key, enter :wq! to save the changes.
vi /etc/config/network
# restart the network service
/etc/init.d/network restart
# Exit the OpenWrt container
exit
# Stop and remove the OpenWrt container
docker rm -f openwrt
```
## 9. Update OpenWrt system or kernel
Access the OpenWrt system via browser, navigate to `System` menu > `Amlogic Treasure Box`, and use the `Upgrade OpenWrt Firmware` or `Change OpenWrt Kernel` feature to upgrade. (You can downgrade from a higher version such as 5.15.50 to a lower version such as 5.10.125, or upgrade from a lower version to a higher version. The kernel version number does not affect the upgrade operation—you can freely upgrade or downgrade).
[SOS]: In cases where a kernel update is incomplete due to special reasons, causing the system to fail to boot from eMMC/NVMe/sdX, you can boot an OpenWrt system with any kernel version from USB or other disks. To perform kernel rescue, go to `System Menu` > `Amlogic Service` > `Online Download Update` > `Rescue Kernel` to restore the normal use of the original system. You can also use the command `openwer-kernel -s` in the `TTYD terminal` for kernel rescue. When no disk parameter is specified, it defaults to restoring the kernel from a USB device to eMMC/NVMe/sdX. If the device has multiple disks, you can specify the exact disk name that needs to be restored. An example is as follows:
```shell
# To recover the kernel in eMMC
openwer-kernel -s mmcblk1
# To recover the kernel in NVMe
openwer-kernel -s nvme0n1
# To recover the kernel in a removable storage device
openwer-kernel -s sda
# Disk names can be abbreviated as mmcblk0/mmcblk1/nvme0n1/nvme1n1/sda/sdb/sdc, etc., or use the full name, such as /dev/sda
openwer-kernel -s /dev/sda
# When the device has only one built-in storage among eMMC/NVMe/sdX, the disk name parameter can be omitted
openwer-kernel -s
```
## 10. Advanced Tutorial on Personalized Firmware Customization
If you have followed the tutorial to this point, you should already have a solid understanding of the basics. However, continuing to explore further will take you on a rewarding journey. You will encounter many challenges, which requires a mindset of continuous exploration, proficiency in using search engines to solve problems, and spending time learning in OpenWrt communities.
### 10.1 Getting to Know the Complete .config File
Use OpenWrt's official source code repository or another branch to perform a local compilation. For example, using the source code repository at https://github.com/coolsnowwolf/lede, follow its compilation instructions to install Ubuntu locally, set up the environment, and complete a local compilation. The local compilation configuration interface provides extensive descriptions that will deepen your understanding of the OpenWrt compilation process.
After completing personalized OpenWrt configuration locally, save and exit the configuration interface. You can find the .config file in the root directory of the local OpenWrt source code repository (run the `ls -a` command in the root directory to view all hidden files). You can upload this file directly to your repository on github.com, replacing the file at `config/lede_master/config`.
### 10.2 Understanding Workflow Files
GitHub provides detailed official documentation on how to use GitHub Actions. You can start learning about it here: [GitHub Actions Quick Start](https://docs.github.com/en/actions/quickstart)
Let's briefly examine the compilation process control file currently used in this repository: [build-openwrt-system-image.yml](https://github.com/ophub/amlogic-s9xxx-openwrt/blob/main/.github/workflows/build-openwrt-system-image.yml)
#### 10.2.1 Changing the Address and Branch of the Compilation Source Code Repository
```yaml
#On line 63: This is where the OpenWrt compile source code address is specified
REPO_URL: https://github.com/coolsnowwolf/lede
#On line 64: This is where the branch name is specified
REPO_BRANCH: master
```
You can modify it to the address of other source code repositories, such as using the official source code repository and its `openwrt-21.02` branch:
```yaml
REPO_URL: https://github.com/openwrt/openwrt
REPO_BRANCH: openwrt-21.02
```
#### 10.2.2 Changing the Model and Kernel Version Number of the Box
Around line 139, look for the compile step titled `Build OpenWrt firmware`, and its code block should look like this:
```yaml
- name: Build OpenWrt firmware
if: ${{ steps.compile.outputs.status }} == 'success' && !cancelled()
uses: ophub/amlogic-s9xxx-openwrt@main
with:
openwrt_path: openwrt/bin/targets/*/*/*rootfs.tar.gz
openwrt_board: ${{ inputs.openwrt_board }}
openwrt_kernel: ${{ inputs.openwrt_kernel }}
auto_kernel: ${{ inputs.auto_kernel }}
openwrt_size: ${{ inputs.openwrt_size }}
```
Refer to the [parameter instructions](../README.md#gitHub-actions-input-parameters-explanation) related to the packaging command. The above setting options can be set by writing in fixed values, or they can be selected through the `Actions` panel:
### 10.3 Customizing Banner Information
The default [/etc/banner](../openwrt-files/common-files/etc/banner) information is as follows, you can use a [banner generator](https://www.bootschool.net/ascii) to customize your own personalized banner information (the style below is `slant`). Use the method described in `10.5.2` to add a custom banner and other OpenWrt files when building OpenWrt.
```shell
____ _ __ __ __ ___ ____
/ __ \____ ___ ____| | / /____/ /_ / / / | / __ )
/ / / / __ \/ _ \/ __ \ | /| / / ___/ __/ / / / /| | / __ |
/ /_/ / /_/ / __/ / / / |/ |/ / / / /_ / /___/ ___ |/ /_/ /
\____/ .___/\___/_/ /_/|__/|__/_/ \__/ /_____/_/ |_/_____/
/_/ H E L L O - W O R L D @ W I R E L E S S - F R E E D O M
───────────────────────────────────────────────────────────────────────
```
### 10.4 Customize feeds configuration file
When looking at the feeds.conf.default file in the source code repository, you'll notice it includes many package source code repositories. Indeed, on GitHub you can find the official OpenWrt source code repositories as well as many community-contributed branches and packages. If you are familiar with these resources, you can add them here. For example, see the [feeds.conf.default](https://github.com/coolsnowwolf/lede/blob/master/feeds.conf.default) in the coolsnowwolf source code repository.
### 10.5 Customize OpenWrt default configuration files
#### 10.5.1 First method is to add custom files during compilation
During your use of OpenWrt, many software packages have already been configured. Most of this configuration data is stored in the /etc/config/ and other related directories. Copy these configuration files to the files folder in the root directory of your GitHub repository, maintaining the same directory structure and file names. During OpenWrt compilation, these configuration files will be compiled into your firmware. The specific implementation is in the .github/workflows/build-openwrt-system-image.yml file, as shown below:
```yaml
- name: Load custom configuration
run: |
[[ -d "files" ]] && mv -f files openwrt/files
[[ -e "${CONFIG_FILE}" ]] && cp -f ${CONFIG_FILE} openwrt/.config
chmod +x ${DIY_P2_SH}
cd openwrt
${GITHUB_WORKSPACE}/${DIY_P2_SH}
```
Do not copy configuration files that contain private information. If your repository is public, the files in the files directory will also be public—never expose sensitive data. Passwords and other sensitive information can be encrypted using the private key settings and other methods described in the GitHub Actions Quick Start Guide. Ensure you understand what you are doing.
#### 10.5.2 Second method is to use the openwrt_files parameter to add custom files
Using ophub to package OpenWrt, the `openwrt_files` parameter can be used to add or override custom files to ophub's [common-files](https://github.com/ophub/amlogic-s9xxx-openwrt/tree/main/make-openwrt/openwrt-files/common-files) directory. The directory structure must be consistent with the OpenWrt root directory to ensure that the files are correctly overwritten in the firmware (for example, default configuration files should be placed in the `etc/config/` subdirectory). An example of the setting method:
```yaml
- name: Packaging OpenWrt
uses: ophub/amlogic-s9xxx-openwrt@main
with:
openwrt_path: openwrt/output/*rootfs.tar.gz
openwrt_files: files
...
```
### 10.6 Opkg package management
Similar to most Linux distributions (or mobile operating systems such as Android or iOS), system functionality can be extended by downloading and installing packages from software repositories (local or online). The opkg utility is a lightweight package manager designed for adding software to embedded device firmware. Opkg is a full-featured package manager for the root filesystem, supporting kernel modules and drivers. It attempts to resolve package dependencies from the repository; if resolution fails, it reports an error and aborts the installation. Third-party packages may have missing dependencies, which can be obtained from the package source. To ignore dependency errors, use the `--force-depends` argument.
- If you are using a snapshot/trunk/latest version, package installation may fail when the kernel version used by repository packages is newer than your current kernel version. In this case, you will receive an error message such as `Cannot satisfy the following dependencies...`. For this scenario, it is strongly recommended to integrate the required packages directly during OpenWrt firmware compilation.
- Non-official openwrt.org plugins, such as `luci-app-uugamebooster` and `luci-app-xlnetacc`, must be integrated directly during firmware compilation. These packages cannot be installed from the mirror server using opkg, but you can manually upload them to OpenWrt and install them via opkg.
- On the trunk/snapshot, the kernel and kmod packages are marked as reserved, and the `opkg upgrade` command will not attempt to update them.
Common commands:
```shell
opkg update #Update the list of available packages
opkg upgrade #Upgrade packages
opkg install #Install packages
opkg install --force-reinstall #Force reinstallation of packages
opkg configure #Configure unpacked packages
opkg remove #Remove packages
opkg list #List available packages
opkg list-installed #List installed packages
opkg list-upgradable #List installed and upgradable packages
opkg list | grep #Search for packages matching keywords
```
For more help, please check [opkg](https://openwrt.org/docs/guide-user/additional-software/opkg)
### 10.7 Manage packages using the Web interface
After installing the OpenWrt firmware on the device, additional packages can be installed via the Web interface.
1. Login to OpenWrt → `System` → `Software packages`
2. Click the `Refresh list` button to update
3. Fill in the `Filter` field, and then click the `Find Package` button to search for specific packages
4. Switch to the `Available packages` tab to display the packages that can be installed
5. Switch to the `Installed packages` tab to display and delete installed packages
If you want to use LuCI to configure services, please search and install `luci-app-*` packages.
For more help, please check [packages](https://openwrt.org/packages/start)
### 10.8 How to restore the original Android TV system
The Android TV system on the device is usually backed up and restored using `openwrt-ddbr`.
In addition, the Android system can also be flashed into eMMC using the method of flashing via a cable. The download image of the Android system can be found in [Tools](https://github.com/ophub/kernel/releases/tag/tools).
#### 10.8.1 Backup and Recovery Using openwrt-ddbr
Before installing the OpenWrt system on a brand-new box, it is recommended to back up the original Android TV system for future recovery purposes. Boot the OpenWrt system from `TF/SD/USB`, enter the `openwrt-ddbr` command, then input `b` following the prompts to back up the system. The backup file is stored at `/ddbr/BACKUP-arm-64-emmc.img.gz`—please download and save it. When you need to restore the Android TV system, upload the backup file to the same path on the `TF/SD/USB` device, enter the `openwrt-ddbr` command, then input `r` to restore the system.
#### 10.8.2 Recovery Using Amlogic Flashing Tool
- Generally, if you can boot from USB by plugging in the power again, all you need to do is reinstall, try a few more times.
- If the box does not boot from the USB and the screen is black after being connected to a monitor, it's necessary to short-circuit the box for initialization. First, restore the box to the original Android system, then reflash the OpenWrt system. Firstly, download the [amlogic_usb_burning_tool](https://github.com/ophub/kernel/releases/tag/tools) system recovery tool and install it. Prepare a [USB A-A data cable](https://user-images.githubusercontent.com/68696949/159267576-74ad69a5-b6fc-489d-b1a6-0f8f8ff28634.png) and a [paper clip](https://user-images.githubusercontent.com/68696949/159267790-38cf4681-6827-4cb6-86b2-19c7f1943342.png).
- For example, for the x96max+ model, confirm the location of the [short-circuit point](https://user-images.githubusercontent.com/68696949/110590933-67785300-81b3-11eb-9860-986ef35dca7d.jpg) on the box's motherboard, download the [Android TV firmware package](https://github.com/ophub/kernel/releases/tag/tools) for the box. The Android TV system firmware and corresponding short-circuit point diagrams for other common devices can also be [downloaded and viewed here](https://github.com/ophub/kernel/releases/tag/tools).
```shell
Operation method:
1. Open the flashing software USB Burning Tool:
[ File → Import firmware package ]: X96Max_Plus2_20191213-1457_ATV9_davietPDA_v1.5.img
[ Select ]: Erase flash
[ Select ]: Erase bootloader
Click the [ Start ] button
2. Use the [ paperclip ] to [ short-circuit the two points on the box's motherboard ],
and simultaneously connect the [ box ] and [ computer ] with the [ USB A-A data cable ].
3. When you see the [ progress bar start moving ], remove the paperclip, no longer short-circuit.
4. When you see [ progress bar at 100% ], the flashing is complete, and the box has been restored to the Android TV system.
Click the [ Stop ] button, unplug the [ USB A-A data cable ] between the [ box ] and [ computer ].
5. If any step above fails, try again until successful.
If the progress bar does not move, you can try plugging in the power. Under normal circumstances, the power provided by the USB A-A alone is sufficient for flashing.
```
Once the factory reset is complete and the box has been restored to the Android TV system, the procedure for installing OpenWrt is the same as your initial installation—simply repeat the process.
#### 10.9 Unable to Boot After Installing Mainline u-boot
- A very small number of devices may not be able to boot after choosing to write the mainline `u-boot`. The prompt seen on the monitor ends with a `=>` symbol. At this point, you need to solder a 5-10 K pull-up or pull-down resistor on the TTL to solve the problem of the box being easily interfered by surrounding electromagnetic signals and failing to boot. After soldering the resistor, it can boot from the EMMC.
If you chose to install the mainline `u-boot` and cannot boot, please connect your box to the screen and check if the prompt is as follows:
```shell
Net: eth0: ethernet0ff3f0000
Hit any key to stop autoboot: 0
=>
```
If your phenomenon is as shown above, then you need to solder a resistor on the TTL: [X96 Max Plus's V4.0 motherboard diagram](https://user-images.githubusercontent.com/68696949/110910162-ec967000-834b-11eb-8fa6-64727ccbe4af.jpg)
```shell
####################################################### ########################################################
# # # #
# Pull-Up Resistor: Solder between TTL RX and GND # # Pull-Down Resistor: Solder between TTL 3.3V and RX #
# # # #
# 3.3V RX TX GND # OR # 3.3V RX TX GND #
# ┖————█████████————┚ # # ┖————█████████————┚ #
# (5~10kΩ) # # (5~10kΩ) #
# # # #
####################################################### ########################################################
```
### 10.10 Setting up the Box to Boot from USB/TF/SD
Based on the situation of your own device, there are two methods to use: initial installation and reinstallation of the OpenWrt system.
#### 10.10.1 Initial Installation of OpenWrt System
- Insert the USB/TF/SD with the flashed firmware into the box.
- Enable developer mode: Settings → About Device → Version number (e.g., X96max plus...), quickly click the left mouse button 5 times on the version number, until the system shows a prompt saying `Developer mode is enabled`.
- Enable USB debugging mode: System → Advanced options → Developer options (set `Enable USB debugging` to enabled). Enable `ADB` debugging.
- Install the ADB tool: Download [adb](https://github.com/ophub/kernel/releases/tag/tools) and unzip it, copy the three files `adb.exe`, `AdbWinApi.dll`, `AdbWinUsbApi.dll` to both the `system32` and `syswow64` folders in the `c://windows/` directory, then open the `cmd` command panel, use the `adb --version` command, if it shows something, it means you can use it now.
- Enter `cmd` command mode. Type the `adb connect 192.168.1.137` command (modify the IP according to your box, you can check it in the router device that the box is connected to), if the connection is successful, it will display `connected to 192.168.1.137:5555`.
- Type the `adb shell reboot update` command, the box will restart and boot from the USB/TF/SD you inserted, access the firmware IP address from the browser, or SSH access to enter the firmware.
- Login to the OpenWrt system: Directly connect your box to your computer → Turn off the WIFI option of the computer, only use the wired network card → Set the network of the wired network card to the same segment as OpenWrt, if the default IP of OpenWrt is: `192.168.1.1`, you can set the computer's IP to `192.168.1.2`, the subnet mask is set to `255.255.255.0`, besides these 2 options, no other options need to be set. Then you can enter OpenWrt from the browser. The default IP: `192.168.1.1`, default account: `root`, default password: `password`.
#### 10.10.2 Reinstallation of OpenWrt System
- In normal situations, you can directly insert the USB flash drive with OpenWrt installed and boot from it. USB booting takes priority over eMMC.
- In some cases, the device may not boot from the USB flash drive. In such cases, you can rename the `boot.scr` file in the `/boot` directory of the OpenWrt system on the eMMC. For example, you can rename it to `boot.scr.bak`. After that, you can insert the USB flash drive and boot from it. This way, you will be able to boot from the USB flash drive.
### 10.11 Required OpenWrt Options
This list is organized based on the development guide from [unifreq](https://github.com/unifreq/openwrt_packit). To ensure that installation/update scripts can run normally in OpenWrt, when using `make menuconfig` for configuration, the following required options need to be added:
```shell
Target System -> Arm SystemReady (EFI) compliant
Subtarget -> 64-bit (armv8) machines
Target Profile -> Generic EFI Boot
Target Images -> tar.gz
OR
Target System -> QEMU ARM Virtual Machine
Subtarget -> QEMU ARMv8 Virtual Machine (cortex-a53)
Target Profile -> Default
Target Images -> tar.gz
Kernel modules -> Wireless Drivers -> kmod-brcmfmac(SDIO)
-> kmod-brcmutil
-> kmod-cfg80211
-> kmod-mac80211
Languages -> Perl
-> perl-http-date
-> perlbase-file
-> perlbase-getopt
-> perlbase-time
-> perlbase-unicode
-> perlbase-utf8
-> Python
-> Python3-ctypes
-> Python3-logging
-> Python3-yaml
Network -> File Transfer -> curl、wget-ssl
-> Version Control Systems -> git
-> WirelessAPD -> hostapd-common
-> wpa-cli
-> wpad-mesh-openssl
-> iw
Utilities -> Compression -> bsdtar、pigz
-> Disc -> blkid、fdisk、lsblk、parted
-> Editors -> nano、vim
-> Filesystem -> attr、btrfs-progs(Build with zstd support)、chattr、dosfstools、
e2fsprogs、f2fs-tools、f2fsck、lsattr、mkf2fs、xfs-fsck、xfs-mkfs
-> Shells -> bash
-> Time Zone info -> zoneinfo-america、zoneinfo-asia、zoneinfo-core、zoneinfo-europe (other)
-> acpid、coremark、coreutils(-> coreutils-base64、coreutils-dd、coreutils-df、coreutils-nohup、
coreutils-tail、coreutils-timeout、coreutils-touch、coreutils-tr、coreutils-truncate)、
gawk、getopt、jq、lm-sensors、losetup、pv、tar、uuidgen
```
