This morning, a user privately messaged me asking how to flash OpenWrt on a CPE I had never heard of before, which left me momentarily stumped. On one hand, the likelihood is 99% that the person asking this question is a beginner. Many people get into OpenWrt because they hear it can flash various firmware, but truly understanding this issue requires a lot of knowledge, and I worry that going into too much detail might scare them off. On the other hand, flashing firmware is highly hardware-dependent, and without the proper flashing tools, it can even depend on the current software version of the hardware. A small mistake could turn the device into a “brick,” making this a rather dangerous operation.This article aims to provide an overview of the issues surrounding “flashing firmware!Firmware, in English, refers to the software that is embedded in the device. You can think of it as the program that was originally flashed into the microcontroller’s EEPROM. With the rise of Linux, local storage devices in devices have gradually included file systems, making the reading and modification of software versions more flexible. The term “firmware” is rarely used anymore. Another reason is that the term itself is ambiguous; a complex system may involve many controller subsystems (heterogeneous systems), each requiring its own software program. These can often be written to by a main controller/CPU, such as Bluetooth firmware, Wi-Fi firmware, etc., so a qualifier is usually added before the term firmware. In the OpenWrt project, we often refer to the following two concepts:
- Upgrade package, which is the sysupgrade file, for example, openwrt-24.10.0-mediatek-filogic-glinet_gl-mt3000-squashfs-sysupgrade.bin. This is actually a file format that combines the kernel and rootfs into one package, which needs to be parsed and written to the specified partition in the device’s Flash according to the OpenWrt custom upgrade process, and then requires u-boot to assist in starting and loading the program.
- Flashing image file, which is constructed based on the characteristics of the Flash hardware (Nand Flash/Nor Flash) and contains all the data that the device needs to retain in order, such as boot, kernel, rootfs, rootfs_data, factory, etc. This file must be written into the Flash using a programmer and is often written before the Flash chip is mounted, making it suitable for large-scale production of products.
Since the knowledge involved in flashing image files is quite specialized, and even developers in this industry rarely understand it, I won’t elaborate on it here. More often than not, when people mention OpenWrt firmware, they are referring to the upgrade package mentioned earlier, which is the sysupgrade file.Therefore, the issue of flashing firmware is essentially about version upgrades. In OpenWrt, there is a universal command-line tool for upgrades: the sysupgrade command line, which provides a unified function and interface for upper-layer applications (such as luci). There is a dedicated introduction on the official website regarding this topic:https://openwrt.org/docs/techref/sysupgradeThis tool is actually composed of several related shell scripts, among which operations related to specific hardware are implemented separately in the platform.sh script. You can search the source code:
ruok@ruok-vm:~/Downloads/openwrt-24.10.0$ find . -name platform.sh./build_dir/target-aarch64_cortex-a53_musl/root-mediatek/lib/upgrade/platform.sh./build_dir/target-aarch64_cortex-a53_musl/linux-mediatek_filogic/base-files/.pkgdir/base-files/lib/upgrade/platform.sh./build_dir/target-aarch64_cortex-a53_musl/linux-mediatek_filogic/base-files/ipkg-aarch64_cortex-a53/base-files/lib/upgrade/platform.sh./build_dir/target-aarch64_cortex-a53_musl/root.orig-mediatek/lib/upgrade/platform.sh./build_dir/host/zstd-1.5.6/tests/cli-tests/common/platform.sh./staging_dir/target-aarch64_cortex-a53_musl/root-mediatek/lib/upgrade/platform.sh./target/linux/omap/base-files/lib/upgrade/platform.sh./target/linux/mpc85xx/base-files/lib/upgrade/platform.sh./target/linux/ipq806x/base-files/lib/upgrade/platform.sh./target/linux/ipq40xx/base-files/lib/upgrade/platform.sh./target/linux/octeon/base-files/lib/upgrade/platform.sh./target/linux/imx/cortexa7/base-files/lib/upgrade/platform.sh./target/linux/imx/cortexa9/base-files/lib/upgrade/platform.sh./target/linux/imx/cortexa53/base-files/lib/upgrade/platform.sh./target/linux/bcm53xx/base-files/lib/upgrade/platform.sh./target/linux/qoriq/base-files/lib/upgrade/platform.sh./target/linux/sunxi/base-files/lib/upgrade/platform.sh./target/linux/pistachio/base-files/lib/upgrade/platform.sh./target/linux/ramips/mt7620/base-files/lib/upgrade/platform.sh./target/linux/ramips/rt3883/base-files/lib/upgrade/platform.sh./target/linux/ramips/rt288x/base-files/lib/upgrade/platform.sh./target/linux/ramips/mt7621/base-files/lib/upgrade/platform.sh./target/linux/ramips/mt76x8/base-files/lib/upgrade/platform.sh./target/linux/ramips/rt305x/base-files/lib/upgrade/platform.sh./target/linux/bcm27xx/base-files/lib/upgrade/platform.sh./target/linux/mvebu/cortexa9/base-files/lib/upgrade/platform.sh./target/linux/mvebu/cortexa72/base-files/lib/upgrade/platform.sh./target/linux/mvebu/cortexa53/base-files/lib/upgrade/platform.sh./target/linux/apm821xx/base-files/lib/upgrade/platform.sh./target/linux/siflower/sf19a2890/base-files/lib/upgrade/platform.sh./target/linux/loongarch64/base-files/lib/upgrade/platform.sh./target/linux/bcm4908/base-files/lib/upgrade/platform.sh./target/linux/realtek/base-files/lib/upgrade/platform.sh./target/linux/sifiveu/base-files/lib/upgrade/platform.sh./target/linux/x86/base-files/lib/upgrade/platform.sh./target/linux/kirkwood/base-files/lib/upgrade/platform.sh./target/linux/tegra/base-files/lib/upgrade/platform.sh./target/linux/gemini/base-files/lib/upgrade/platform.sh./target/linux/bcm47xx/base-files/lib/upgrade/platform.sh./target/linux/armsr/base-files/lib/upgrade/platform.sh./target/linux/stm32/base-files/lib/upgrade/platform.sh./target/linux/qualcommax/ipq60xx/base-files/lib/upgrade/platform.sh./target/linux/qualcommax/ipq807x/base-files/lib/upgrade/platform.sh./target/linux/lantiq/falcon/base-files/lib/upgrade/platform.sh./target/linux/lantiq/xway/base-files/lib/upgrade/platform.sh./target/linux/lantiq/xrx200/base-files/lib/upgrade/platform.sh./target/linux/lantiq/xway_legacy/base-files/lib/upgrade/platform.sh./target/linux/lantiq/ase/base-files/lib/upgrade/platform.sh./target/linux/lantiq/xrx200_legacy/base-files/lib/upgrade/platform.sh./target/linux/mediatek/mt7622/base-files/lib/upgrade/platform.sh./target/linux/mediatek/mt7629/base-files/lib/upgrade/platform.sh./target/linux/mediatek/mt7623/base-files/lib/upgrade/platform.sh./target/linux/mediatek/filogic/base-files/lib/upgrade/platform.sh./target/linux/ath79/tiny/base-files/lib/upgrade/platform.sh./target/linux/ath79/nand/base-files/lib/upgrade/platform.sh./target/linux/ath79/generic/base-files/lib/upgrade/platform.sh./target/linux/ath79/mikrotik/base-files/lib/upgrade/platform.sh./target/linux/bmips/bcm63268/base-files/lib/upgrade/platform.sh./target/linux/bmips/bcm6362/base-files/lib/upgrade/platform.sh./target/linux/bmips/bcm6358/base-files/lib/upgrade/platform.sh./target/linux/bmips/bcm6368/base-files/lib/upgrade/platform.sh./target/linux/bmips/bcm6318/base-files/lib/upgrade/platform.sh./target/linux/bmips/bcm6328/base-files/lib/upgrade/platform.sh./target/linux/rockchip/armv8/base-files/lib/upgrade/platform.sh.It can be seen that in OpenWrt, the execution of the upgrade package requires adaptation to specific hardware. Taking the MT7981 as an example, you can find the target/linux/mediatek/filogic/base-files/lib/upgrade/platform.sh file, which implements reading the device’s board_name and then selecting the Flash operation’s partition and size based on the board name. These are all closely related to the hardware and Flash partition.Advice for BeginnersI do not recommend that beginners start with such low-level operations, as this can easily dampen your enthusiasm for the technology. Instead, I recommend using OpenWrt-supported open-source hardware or devices from mainstream hardware manufacturers. You can first refer to the following article to get a preliminary understanding of how OpenWrt source code is compiled:Setting Up the OpenWrt Development EnvironmentFor other hardware, you can filter hardware using the make menuconfig menu, combining the conditions of Target System, Subtarget, and Target Profile. OpenWrt officially supports nearly 2000 hardware models, so you should be able to find a suitable one:
Additionally, considering that you might also have a fleeting interest, it is advisable to minimize the sunk cost of suddenly abandoning your investment later. It is better to buy a cheap second-hand device on Xianyu to experiment with. Here are a few factors to consider:
- If you have no special requirements for functionality and performance, I recommend devices based on the MT7621 platform.
- If you want to keep up with trends, I recommend the MT7981 platform, which is currently favored by mainstream users.
- If your goal is to tinker with soft routers, perhaps an x86 mini PC would be more suitable; you can start by experimenting with a virtual machine.
Of course, it is also possible that you already have hardware that is not supported by the official version, like the user who consulted me today. In that case, you can ask the hardware manufacturer for an SDK, as they have already adapted it for the hardware you have. First, familiarize yourself with the usage of the SDK business components provided by the manufacturer and the basics of compilation and debugging. Once you have a certain level of understanding of OpenWrt, you can consider whether to port and adapt the mainline version of OpenWrt.For beginners, it is not important which version of OpenWrt to use; the key is to choose the version with the most comprehensive documentation and the best support for the current hardware.Another approach is if you know the specifications of your hardware and the Flash partitioning, and you happen to find a device in the OpenWrt-supported hardware list that has the same hardware configuration, then choosing the sysupgrade upgrade package for that hardware configuration might work, but I do not recommend trying it lightly.