Introduction
This guide details the complete installation and configuration of OpenWrt 25.12.0-rc5 on the ZBT-Z800AX router. It specifically focuses on the initial TFTP flashing process, fixing the U-Boot kernel panic bootloop encountered after a fresh flash, and configuring the internal M.2 Quectel RM520N-GL 5G modem. Firmware images for Z800AX are avaliable here firmware-selector.openwrt.org
In many IPQ807x devices, the stock bootloader cannot directly "understand" or correctly partition the NAND for a full OpenWrt sysupgrade image. By flashing the .itb (Image Tree Blob) file first, you are booting a temporary initramfs version of OpenWrt directly into the router's RAM. This provides a fully functional Linux environment with the necessary tools (like sysupgrade) to safely and correctly write the permanent firmware to the internal flash.
Z800AX have 8MB SPI flash + 256 MB NAND storage.
Currently, the default OpenWrt sysupgrade image for the Z800AX lacks automated U-Boot environment mapping, which results in a hard bootloop after flashing. Furthermore, the M.2 slot routes the modem over the USB 3.0 bus rather than the PCIe/MHI bus, requiring manual installation of the correct USB driver stacks.
You will need usb TTL adapter 3.3V and terminal program TeraTerm or putty with serial port settings 115200, 8N1. Z800AX have easy accessible UART port with 3 dupont pins (GND,TX,RX)
Part 0: Initial Flashing and TFTP Recovery
Before proceeding to the environment fixes, you must get the firmware onto the device. If you are recovering a "bricked" unit or performing the first install from the stock QSDK, use a TFTP server.
Part 0: The Two-Step Installation (Initramfs to Sysupgrade)
We use a two-step process to transition from the stock QSDK environment to vanilla OpenWrt. The U-Boot environment is too limited to handle complex NAND partitioning, so we first boot a temporary "helper" environment.
Step 0.1: Booting the Initramfs (.itb)
The .itb file is a Flattened Image Tree (FIT) that contains the kernel and a small RAM-based root filesystem. We load this into RAM to gain access to the sysupgrade utility. This file is named as kernel at firmware selector kernel.itb
- Connect your PC to a LAN port on the Z800AX and set your static IP to 192.168.1.10.
- Place the .itb and sysupgrade.bin files in your TFTP server's root directory.
- Interrupt the U-Boot process via UART (115200 8N1) and configure the network:
setenv serverip 192.168.1.10
setenv ipaddr 192.168.1.1
saveenv
Transfer the image from your PC to the router's RAM
tftpboot 0x44000000 openwrt-ipq807x-zbtlink_zbt-z800ax-initramfs-uImage.itb
Boot the image from RAM (does not flash to NAND yet)
bootm 0x44000000
The Permanent Flash (Sysupgrade)
Once the router boots into the temporary OpenWrt environment (accessible at 192.168.1.1), you must perform the permanent installation.
- Transfer the sysupgrade.bin to the router's /tmp directory using SCP or go directly to luci web interface and upload firmware from there:
scp openwrt-z800ax-sysupgrade.bin root@192.168.1.1:/tmp/.
- SSH into the router and run the final flash command:
sysupgrade -n /tmp/openwrt-z800ax-sysupgrade.bin.
Part 1: Fixing the U-Boot Environment (Resolving Kernel Panics)
The Problem: When the stock Qualcomm QSDK firmware boots, its proprietary bootloader script (bootipq) dynamically passes the partition boundaries and root filesystem location to the kernel. When you flash a vanilla OpenWrt sysupgrade image, this script is bypassed. The OpenWrt kernel starts blind, cannot find the rootfs block, throws a VFS: Cannot open root device "/dev/ubiblock0_1" panic, and enters an infinite reboot loop.
Here we must manually define the partition layout (mtdparts) and inject the OpenWrt kernel arguments (bootargs) directly into the U-Boot environment variables.
1. While at the IPQ807x# uboot prompt, execute the following commands :
To define the kernel boot arguments (tells VFS where to find the squashfs root)
setenv bootargs 'console=ttyMSM0,115200n8 ubi.mtd=rootfs root=mtd:ubi_rootfs rootfstype=squashfs rootwait'
2. Define the boot sequence (injects the partition map, mounts the UBI, reads the kernel to RAM, and boots)
setenv bootcmd 'setenv mtdids nand0=nand0; setenv mtdparts mtdparts=nand0:0x3400000@0x0(rootfs); ubi part rootfs && ubi read 0x44000000 kernel && bootm 0x44000000'
3. Commit the variables to the SPI flash environment
saveenv
4. Perform a cold reboot
reset
After this rotuer should boot normally and luci web should be avaliable at http://192.168.1.1
Part 2: Installing the Quectel RM520N-GL 5G Modem
The Z800AX routes the M.2 cellular module over the internal USB 3.0 bus, not the PCIe bus. A fresh OpenWrt 25 installation lacks the required USB drivers and the ModemManager daemon to operate it.
-
Provide Temporary Internet: Connect the Z800AX to an existing network via the WAN Ethernet port (or configure a temporary Wi-Fi client connection, use wifi interface on router in client mode and connect it to your phone wifi hotspot or some other wifi network, don't forget to configure default route) so it can download packages.
-
Install Drivers: Connect to the router via SSH and utilize the
apkpackage manager (the new standard in OpenWrt 25+) to fetch the USB serial modules, QMI drivers, and ModemManager stack.
apk update
apk add usbutils usb-modeswitch kmod-usb-serial-option kmod-usb-net-qmi-wwan kmod-usb-net-cdc-mbim kmod-usb-net-cdc-mbim
apk add modemmanager luci-proto-modemmanager
- Reboot: The router must be restarted to allow the kernel to bind the new USB drivers to the M.2 hardware.
reboot
- Verify Hardware Detection: Reconnect via SSH and confirm the modem is recognized on the bus and claimed by the daemon:
lsusb
mmcli -L
Part 3: LuCI Network Configuration
With the backend fully operational, you can configure the connection through the web interface.
- Log into LuCI (
192.168.1.1). - Navigate to Network -> Interfaces and click Add new interface.
- Name the interface
wwan5gand select ModemManager as the Protocol. - Click Create interface. In the resulting configuration window:
- Modem Device: Select the Quectel RM520N-GL.
- APN: Enter your specific carrier APN (e.g.,
internet). - PIN: Leave blank unless your SIM has an active hardware lock.
- Click the Firewall Settings tab and assign the interface to the
wanzone. - Click Save, followed by Save & Apply on the main page.
