View Chinese description | 查看中文说明

The OpenWrt project is a Linux router operating system for embedded devices. OpenWrt is not a single and immutable firmware, but rather provides a fully writable filesystem with package management capabilities, allowing you to freely select the required software packages to customize the router system. For developers, OpenWrt is a framework that allows application development without having to build a complete firmware around it; for ordinary users, it means having the capability for complete customization, and the ability to use the device in unexpected ways. It has over 3000+ standardized application software packages and extensive third-party plugin support, allowing you to easily apply them to various supported devices. Now you can replace the Android TV system on your TV box with the OpenWrt system, turning it into a powerful router.

This project, thanks to numerous contributors, builds the OpenWrt system for Amlogic, Rockchip, and Allwinner boxes. It supports writing to eMMC for use, supports updating the kernel, and more. For detailed usage instructions, see the OpenWrt User Guide. The latest firmware can be downloaded from Releases. You are welcome to Fork and customize the software packages. If you find it useful, you can click the Star in the upper right corner of the repository to show your support.

Choose the OpenWrt firmware corresponding to your TV box model, and refer to the corresponding instructions for the use of different devices.

• Install OpenWrt

1. For the Rockchip platform, please refer to the Chapter 8 of the instruction manual, the installation method is the same as that of Armbian.

2. For the Amlogic and Allwinner platforms, use tools like Rufus or balenaEtcher to write the firmware to USB, then insert the USB with the written firmware into the box. Browser access to OpenWrt's IP (e.g. 192.168.1.1) → Log in to OpenWrt with the default account → System Menu → Amlogic Treasure Box → Install OpenWrt, select your box from the dropdown list of supported devices, click Install OpenWrt button to install.

• Update OpenWrt system or kernel

Browser access to OpenWrt's IP (e.g. 192.168.1.1) → Log in to OpenWrt with your account → System Menu → Amlogic Treasure Box → Manually Upload Update / Online Download Update

If you select Manually Upload Update OpenWrt Firmware, you can upload the compressed package of the compiled OpenWrt firmware, such as openwrt_xxx_k5.15.50.img.gz (recommended to upload the compressed package, the system will automatically decompress. If you upload the decompressed xxx.img format file, it may fail due to the large file size). After the upload is complete, the interface will display the operation button of Update Firmware, click to update.

If you select Manually Upload Update OpenWrt Kernel, you can upload the three kernel files: boot-xxx.tar.gz, dtb-xxx.tar.gz, modules-xxx.tar.gz (other kernel files are not needed, if uploaded simultaneously, it does not affect the update, the system can accurately identify the needed kernel files). After the upload is complete, the interface will display the operation button of Update Kernel, click to update. When a kernel update failure causes the system to be unbootable, you can use the openwrt-kernel -s command for kernel recovery. For the method, see Kernel Recovery.

If you select Online Download Update for OpenWrt firmware or kernel, it will be downloaded according to the firmware download address and kernel download address in the Plugin Settings. You can customize the download source. For specific operation methods, please refer to the compilation and usage instructions of luci-app-amlogic.

• Create swap for OpenWrt

If you feel that the current box's memory is not enough when using memory-intensive applications like docker, you can create a swap virtual memory partition, and use a certain capacity of the /mnt/*4 disk space as memory. The unit of the input parameter in the command below is GB, the default is 1.

Browser access to OpenWrt's IP (e.g. 192.168.1.1) → Log in to OpenWrt with the default account → System Menu → TTYD Terminal → enter the command

openwrt-swap 1

• Backup/Restore Original EMMC System

Supports backing up/restoring the EMMC to a SD card or a USB flash drive. We recommend that you backup the Android TV system that comes with the box before installing the OpenWrt system in a brand-new box for future use in restoring the TV system, etc.

Please boot OpenWrt system from a SD card or a USB flash drive, then from the browser, Browser access to OpenWrt's IP (e.g. 192.168.1.1) → Log in to OpenWrt with the default account → System Menu → TTYD Terminal → enter the command

openwrt-ddbr

Follow the prompts to enter b to backup the system, or enter r to restore the system.

• Control LED Display

Browser access to OpenWrt's IP (e.g. 192.168.1.1) → Log in to OpenWrt with the default account → System Menu → TTYD Terminal → enter the command

openwrt-openvfd

Refer to LED Screen Display Control Description for debugging.

• Restore to Initial State

Browser access to OpenWrt's IP (e.g. 192.168.1.1) → Log in to OpenWrt with the default account → System Menu → Amlogic Service → Backup Firmware Config → Snapshot Management → Select Initialize Snapshot, and click on Restore Snap to revert to the initial state.

Alternatively, you can navigate to System menu → TTYD Terminal → Enter the command firstboot to restore the system to its initial state. Both methods yield the same result.

• More Usage Instructions

Some common problems that might be encountered during the use of OpenWrt can be found in the User Guide

1. Install necessary packages (for Ubuntu 22.04 LTS users)

sudo apt-get update -y
sudo apt-get full-upgrade -y
# For Ubuntu-22.04
sudo apt-get install -y $(curl -fsSL https://is.gd/depend_ubuntu2204_openwrt)

2. Clone repository to local git clone --depth 1 https://github.com/ophub/amlogic-s9xxx-openwrt.git
3. In the root directory of ~/amlogic-s9xxx-openwrt, create openwrt-armvirt folder, and upload the openwrt-armvirt-64-default-rootfs.tar.gz file to this directory.
4. Enter the packaging command in the root directory of ~/amlogic-s9xxx-openwrt, such as sudo ./remake -b s905x3 -k 6.1.10. The packaged OpenWrt firmware is placed in the out folder in the root directory.

• Explanation of Local Packaging Parameters

• sudo ./remake : Use default configuration, use the latest kernel package in the kernel library, and package all models of TV boxes.
• sudo ./remake -b s905x3 -k 6.1.10 : Recommended. Use default configuration for related kernel packaging.
• sudo ./remake -b s905x3 -k 6.1.y : Package the relevant kernels using the default configuration; the kernel utilizes the latest version of the 6.1.y series.
• sudo ./remake -b s905x3_s905d -k 6.1.10_5.15.50 : Use the default configuration and package multiple kernels at the same time. Use _ to connect multiple kernel parameters.
• sudo ./remake -b s905x3 -k 6.1.10 -s 1024 : Use the default configuration, specify a kernel, a model for packaging, and set the firmware size to 1024 MiB.
• sudo ./remake -b s905x3_s905d : Use default configuration, package all kernels for multiple models of TV boxes, use _ to connect multiple models.
• sudo ./remake -k 6.1.10_5.15.50 : Use the default configuration, specify multiple kernels, package all models of TV boxes, and connect kernel packages with _.
• sudo ./remake -k 6.1.10_5.15.50 -a true : Use the default configuration, specify multiple kernels, package all models of TV boxes, and connect kernel packages with _. Automatically upgrade to the latest kernel of the same series.
• sudo ./remake -s 1024 -k 6.1.10 : Use the default configuration, set the firmware size to 1024 MiB, and specify the kernel as 6.1.10 to package all models of TV boxes.

You can modify the related personalized firmware configuration files in the config directory, as well as the .yml file, customize and compile your OpenWrt firmware, and the firmware can be uploaded to Actions and Releases on github.com.

1. You can view the personalized firmware configuration instructions in the user documentation. The compilation process control file is .yml
2. New compilation: In github.com's Action select Build OpenWrt. Click the Run workflow button for one-stop firmware compilation and packaging.
3. Re-compilation: If there is already a compiled openwrt-armvirt-64-default-rootfs.tar.gz file in Releases, and you just want to remake other different boards, you can skip the compilation of OpenWrt source files and go directly to the second production. Select Use Releases file to Packaging on the Actions page, and click the Run workflow button to recompile.
4. More Support: The compiled openwrt-armvirt-64-default-rootfs.tar.gz file is a universal file for making firmware for different boards. It is also applicable for creating OpenWrt firmware using unifreq's packaging scripts. As the pioneer of using OpenWrt and Armbian systems in TV boxes, he provides support for more devices, such as OpenWrt (QEMU version) used in the Armbian system through a KVM virtual machine, and Amlogic, Rockchip, and Allwinner series, etc. For packaging methods, please refer to the instructions in his repository. In Actions, through packaging-openwrt-for-qemu-etc.yml, you can call his packaging scripts to create more firmware.

- name: Package Armvirt as OpenWrt
  uses: ophub/amlogic-s9xxx-openwrt@main
  with:
    openwrt_path: openwrt/bin/targets/*/*/*rootfs.tar.gz
    openwrt_board: s905x3_s905x2_s905x_s905w_s905d_s922x_s912
    openwrt_kernel: 6.1.y_5.15.y

• GitHub Actions Input Parameters Explanation

These parameters correspond to the local packaging command, please refer to the explanations above.

• GitHub Actions Output Variables Explanation

To upload to Releases, you need to set Workflow read/write permissions for repository. For details, see usage instructions.

For more information, please refer to the User Documentation

For instructions on how to compile the kernel, see compile-kernel.

- name: Compile the kernel
  uses: ophub/amlogic-s9xxx-armbian@main
  with:
    build_target: kernel
    kernel_version: 6.1.y_5.15.y
    kernel_auto: true
    kernel_sign: -yourname

When making the OpenWrt system, the files used, such as kernel and u-boot, are the same files used to create the Armbian system. In order to avoid repeated maintenance, related content has been classified and placed in the corresponding resource repositories, and will be automatically downloaded from the relevant repositories during use.

The u-boot, kernel and other resources used by this system mainly come from the unifreq/openwrt_packit project. Some files are shared by users in the Pull and Issues of the amlogic-s9xxx-openwrt / amlogic-s9xxx-armbian / luci-app-amlogic / kernel / u-boot and other projects. unifreq has opened the door for us to use OpenWrt in TV boxes. Deeply influenced by him, my firmware production and usage follow his consistent standards. To thank these pioneers and sharers, I have recorded them in CONTRIBUTORS.md. Once again, I want to thank everyone for giving new life and meaning to the boxes.

• unifreq has made OpenWrt systems for more boxes such as Amlogic, Rockchip, and Allwinner. It is a benchmark in the box circle, recommended for use.
• The amlogic-s9xxx-armbian project provides the Armbian system used in the box, which is also applicable in devices that support OpenWrt.

• unifreq
• OpenWrt
• coolsnowwolf
• immortalwrt

The amlogic-s9xxx-openwrt © OPHUB is licensed under the GPL-2.0 license