Armbian

Read the Chinese version: 查看中文说明

Armbian is a lightweight Linux-based operating system based on Debian/Ubuntu built specifically for ARM devices. Armbian is lean, clean, 100% compatible and inherits the functions and rich software ecosystem of Debian/Ubuntu. It can run safely and stably from TF/SD/USB and can be installed to the eMMC on most TV boxes. Now you can replace the Android system of your TV box with Armbian, turning it into a powerful server.

This project relies on many contributors to build Armbian systems for Amlogic, Rockchip, and Allwinner boxes. It supports writing to eMMC, updating the kernel, and other functions. Please refer to the Armbian Documentation for more information on Armbian. The latest Armbian builds can be downloaded from Releases. Welcome to the Armbian Discussions to discuss and share. You are welcome to fork and personalize it. If it is useful to you then please click on the star in the upper right corner of the github repository page to show your support. Thanks!

Armbian system specific instructions

| SoC | Device | Kernel | Armbian |
| ---- | ---- | ---- | ---- |
| a311d | Khadas-VIM3 | All | amlogic_a311d.img |
| s922x | Beelink-GT-King, Beelink-GT-King-Pro, Ugoos-AM6-Plus, ODROID-N2, X88-King, Ali-CT2000 | All | amlogic_s922x.img |
| s905x3 | X96-Max+, HK1-Box, Vontar-X3, H96-Max-X3, Ugoos-X3, TX3(QZ), TX3(BZ), X96-Air, X96-Max+_A100, A95XF3-Air, Tencent-Aurora-3Pro(s905x3-b), X96-Max+Q1, X96-Max+100W, X96-Max+_2101, Infinity-B32, Whale | All | amlogic_s905x3.img |
| s905x2 | X96Max-4G, X96Max-2G, MECOOL-KM3-4G, Tanix-Tx5-Max, A95X-F2 | All | amlogic_s905x2.img |
| s912 | Tanix-TX8-Max, Tanix-TX9-Pro(3G), Tanix-TX9-Pro(2G), Tanix-TX92, Nexbox-A1, Nexbox-A95X-A2, A95X, H96-Pro-Plus, VORKE-Z6-Plus, Mecool-M8S-PRO-L, Vontar-X92, T95Z-Plus, Octopus-Planet, Phicomm-T1 | All | amlogic_s912.img |
| s905d | MECOOL-KI-Pro, Phicomm-N1 | All | amlogic_s905d.img |
| s905x | HG680P, B860H, TBee-Box, T95, TX9, XiaoMI-3S, X96 | All | amlogic_s905x.img |
| s905w | X96-Mini, TX3-Mini, W95, X96W/FunTV, MXQ-Pro-4K | All | amlogic_s905w.img |
| s905l2 | MGV2000, MGV3000, Wojia-TV-IPBS9505, M301A, E900v21E | All | amlogic_s905l2.img |
| s905l3 | CM211-1, CM311-1, HG680-LC, M401A, UNT400G1, UNT402A | All | amlogic_s905l3.img |
| s905l3a | E900V22C/D, CM311-1a-YST, M401A, M411A, UNT403A, UNT413A, ZTE-B863AV3.2-M | All | amlogic_s905l3a.img |
| s905l3b | CM211-1, CM311-1, E900V22D, E900V22E, M302A/M304A, Hisense-IP103H, TY1608 | All | amlogic_s905l3b.img |
| s905lb | Q96-mini, BesTV-R3300L, SumaVision-Q7 | All | amlogic_s905lb.img |
| s905 | Beelink-Mini-MX-2G, Sunvell-T95M, MXQ-Pro+4K, SumaVision-Q5 | All | amlogic_s905.img |
| rk3588 | Radxa-Rock5B, HinLink-H88K, Beelink-IPC-R | rk3588 | rockchip_boxname.img |
| rk3568 | FastRhino-R66S, FastRhino-R68S, HinLink-H66K, HinLink-H68K, HinLink-H69K, Radxa-E25, NanoPi-R5S | 6.x.y | rockchip_boxname.img |
| rk3566 | Panther-X2 | 6.x.y | rockchip_boxname.img |
| rk3399 | EAIDK-610, King3399, TN3399, Kylin3399, ZCube1-Max, CRRC, SMART-AM40, SW799, ZYSJ, DG-3399 | 6.x.y | rockchip_boxname.img |
| rk3328 | BeikeYun, L1-Pro, Station-M1, Bqeel-MVR9 | All | rockchip_boxname.img |
| h6 | Vplus, Tanix-TX6 | All | allwinner_boxname.img |

💡Tip: Currently s905 Boxes can only boot from TF/SD/USB. Most other TV boxes support installing Armbian to eMMC. Detailed configuration information of the device can be viewed in the device model database.

Generic installation instructions

The exact installation process for Armbian varies depending upon your devices chipset and model but these instructions are written to be as generic as possible and should apply to all TV boxes.

Hardware support

You need to know the exact make and model of your box and which .dtb (Device Tree Blob) file you need to use to get your box to boot with all supported devices working. Under Android, go to Settings -> System -> About phone to find out the exact model of your TV box.

If you have got your box working but its not listed on either page then see section 12.15 of the documentation for details on how to add support for new devices.

Write the Armbian image to a disk

For instructions covering installing Armbian on Rockchip TV boxes, please refer to Section 8 of the documentation.

For Amlogic and Allwinner boxes，you will have to uncompress the installation image using gunzip first before writing the image to a TF, SD or USB disk using Rufus, balenaEtcher or gnome-disk-utility. You could also use dd but that is not recommended.

After writing the Armbian image, you may need to edit the FDT line in uEnv.txt on the BOOT partition of the disk to use the correct .dtb file for your TV box.

To find the correct dtb to use with Armbian for your box, see Description of Supported Device List or search for your box in the list of system specific instructions at the top of this page.

Enable multi-boot mode - Amlogic TV boxes only

If this is your first time attempting to boot from a SD card or USB disk on an Amlogic TV box, you must first enable multi-boot mode. Insert the Armbian disk then hold down the button in the AV port by inserting a paper clip, a pin or something similar and keep it depressed while powering the device on. Keep the button pressed until you see the boot screen of your box. After a few seconds it should reboot from your SD card or USB disk. You are only required to enable multi-boot mode once.

Running armbian-install

On first boot, Armbian will resize its root partition to use all of the space available on its disk and it will ask you several system configuration questions like your timezone, keyboard layout, username and password etc. After logging in as root or using sudo run:

armbian-install

To start the eMMC installation script. The available options are:

| Optional | Default | Value | Description |
| --------- | ------- | -------- | -------------------- |
| -m | no | yes/no | Use Mainline u-boot |
| -a | yes | yes/no | Use ampart tool |
| -l | no | yes/no | List all .dtb files |

If you can boot Armbian fine from TF/SD/USB and the install script says it installed Armbian to eMMC OK but Armbian fails to boot from eMMC then you should try re-installing Armbian using mainline u-boot instead by running:

armbian-install -m yes

Updating the Armbian Kernel

You won't be able to use all of your hardware properly unless you are running the correct kernel and using the right .dtb. Unfortuntely Armbian cannot auto-detect these for you. In most cases, you are recommended to run the latest kernel version available for your TV box but some features on some devices will only work on specific kernels. For example, 4K HDMI output only works on the X96 Max+ 2T when running a 5.10 series kernel, 4K output doesn't currently work under the 5.15.x or 6.x kernels for that specific model.

Login in to Armbian and run:

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

armbian-update

armbian-update's options include:

| Optional | Default | Value | Description |
| --------- | ------------ | -------------- | ------------------------------------------------------------ |
| -r | ophub/kernel | <owner>/<repo> | Set the repository for downloading kernels from github.com |
| -u | automate | stable/flippy/dev/rk3588 | Set the tags suffix of the kernel used |
| -k | latest | kernel-version | Set the kernel version |
| -c | None | domain-name | Set the cdn domain name for accelerated access to github.com |
| -b | yes | yes/no | Automatically backup the current system kernel |
| -m | no | yes/no | Use Mainline u-boot |
| -s | None | None | [SOS] Restore eMMC with system kernel from USB |
| -h | None | None | View usage help |

Example: armbian-update -k 5.15.50 -u dev

When specifying the kernel version using the -k parameter, you can provide an exact version number, for example: armbian-update -k 5.15.50. Alternatively, you can provide a fuzzy specification to indicate the kernel series, for example: armbian-update -k 5.15. When using a fuzzy specification, the tool will automatically select the latest version available in the specified series.

See here for a list of all currently available stable kernel tarballs.

When updating the kernel, the current kernel will be automatically backed up. The three most recently used kernels are stored in the /ddbr/backup directory. If the newly installed kernel is unstable, the backed up kernel can be restored at any time. If the update fails and the system cannot be started, you can start any version of Armbian via USB/TF/SD to recover the system in eMMC. For more instructions, see the help documentation.

Update Armbian scripts

To update all Armbian scripts to the latest versions, run:

armbian-sync

armbian-software store

armbian-software can be used to install various popular apps, added to the Armbian software center according to user demand and feedback given in github Issues, gradually integrating commonly used software to achieve one-click install/update/uninstall of popular programs such as docker images, desktop software, popular server solutions, etc. See more here.

Armbian config tool

Armbian has a handy TUI config tool for changing key system settings:

armbian-config

Create swap for Armbian

If you feel that your TV box has insufficient memory for running demanding applications such as docker, you can create a swap virtual memory partition. armbian-swap lets the user configure how much disk space is reserved for swap memory. The input parameter defines how many gigabytes of space you want to reserve for swap. The default is 1 GB.

armbian-swap 1

Configuring the TV box LED display

It is worthwhile configuring your LED display, if your box has one, if only so that you know when your TV box has finished booting when it is not connected to a HDMI screen.

armbian-openvfd

Full configuration instructions for the LED display are here.

Backup and restore the original eMMC Android OS

Armbian supports backing up and restoring your TV box's Android eMMC OS partition to TF/SD/USB. It is recommended that you back up the Android system that comes with your box before installing Armbian so that you have the option to restore your TV box to its original state.

You may back up your TV box's Android OS by running:

armbian-ddbr

Following the prompt, enter b to perform a system backup or r to perform a system recovery.

Compile the kernel in Armbian

To build your own Armbian kernel, see the compile-kernel documentation. Please login in to armbian → input command:

armbian-kernel -u
armbian-kernel -k 5.10.125

Local build instructions

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

2. Install the necessary packages (The script has only been tested on x86_64 Ubuntu-20.04/22.04)

sudo apt-get update -y
sudo apt-get full-upgrade -y
For Ubuntu-22.04

sudo apt-get install -y $(cat compile-kernel/tools/script/ubuntu2204-build-armbian-depends)

3. Enter the ~/amlogic-s9xxx-armbian root directory, create the build/output/images folder and then upload the Armbian image ( Eg: Armbian_21.11.0-trunk_Odroidn2_current_5.15.50.img ) to this ~/amlogic-s9xxx-armbian/build/output/images directory. Please keep the release version number (e.g. 21.11.0) and kernel version number (e.g. 5.15.50) in the name of the original Armbian image file, It will be used as the name of the armbian system after rebuilding.

4. Enter the ~/amlogic-s9xxx-armbian root directory, and then run, for example sudo ./rebuild -b s905x3 -k 5.10.125 to build armbian for amlogic s9xxx. The generated Armbian image is in the build/output/images directory under the root directory.

Description of localized packaging parameters

| Optional | Meaning | Description |
| -------- | ---------- | ----------------------------------------- |
| -b | Board | Specify the Build system type. Write the build system name individually, such as -b s905x3 . Multiple system use _ connect such as -b s905x3_s905d . Use all for all board models. The model code is detailed in the BOARD setting in model_database.conf file. Default value: all |
| -r | KernelRepo | Specifies the <owner>/<repo> of the github.com kernel repository. Default value: ophub/kernel |
| -u | kernelUsage | Set the tags suffix of the kernel used, such as stable, flippy, dev. Default value: stable |
| -k | Kernel | Specify the kernel version, Such as -k 5.10.125 . Multiple kernel use _ connection such as -k 5.10.125_5.15.50 . The kernel version freely specified by the -k parameter is only valid for the kernel in the stable/flippy/dev. Other kernel families such as rk3588 can only use specific kernels. |
| -a | AutoKernel | Set whether to automatically adopt the latest version of the kernel of the same series. When it is true, it will automatically find in the kernel library whether there is an updated version of the kernel specified in -k such as 5.10.125 version. If there is the latest version of same series, it will automatically Replace with the latest version. When set to false, the specified version of the kernel will be compiled. Default value: true |
| -t | RootfsType | Set the file system type of the ROOTFS partition of the system, and the options are ext4 or btrfs type. Such as -t btrfs. Default value: ext4 |
| -s | Size | Specify the ROOTFS partition size for the system, and the specified size must b