Modern OpenWrt build targeting MSM8916 devices with full modem, USB gadget, and WiFi support.

Table of Contents

• About OpenWrt
• Supported Devices
• Features
• Prerequisites
• Building
• Installation
  • Flashing from OEM Firmware
  • Accessing Boot Modes
• Troubleshooting
  • No Network / Modem Stuck at Searching
• Roadmap
• Credits

---

About OpenWrt

OpenWrt Project is a Linux operating system targeting embedded devices. Instead of trying to create a single, static firmware, OpenWrt provides a fully writable filesystem with package management. This frees you from the application selection and configuration provided by the vendor and allows you to customize the device through the use of packages to suit any application.

Supported Devices

All devices use the Qualcomm MSM8916 SoC with 384 MB RAM and 4 GB eMMC.

• UZ801v3 (yiming-uz801v3) -- USB dongle form factor.
• UF02 (generic-uf02) -- USB dongle form factor, most likely with only asian bands. Can be somewhat changed via QPST and the qcn file from UZ801.

MF68E and M9S device support has been moved to the TBR directory for reference. See that README for re-integration instructions.

Features

Working Components

• Modem: Fully functional with cellular connectivity
  • ModemManager Rx/Tx stats not displayed in LuCI (known issue)
• WiFi: Complete wireless support
• USB Gadget Modes: NCM, RNDIS, Mass Storage, ACM Shell
  • Configure via UCI or LuCI app
• VPN Ready: TUN driver and WireGuard pre-installed
• LED Control: Managed via hotplug.d scripts (sysfs-based, no extra packages)

Storage & Recovery

• SquashFS Root: Compressed root filesystem
• OverlayFS: ext4 overlay partition for user data (formatted automatically via preinit)
• Factory Reset: firstboot mechanism enabled

Additional Packages

• Tailscale: LuCI app available as standalone package (APK and IPK)

Prerequisites

• Docker installed on your system
• Basic knowledge of Linux command line
• For flashing: edl tool

Building

GitHub Actions (release builds)

GHA workflows automatically resolve the latest OpenWrt 25.12.x tag. Trigger manually from the Actions tab:

• Build firmware: build.yml — select a device (uz801, uf02, or all)
• Build packages: build-package.yml — builds luci-app-tailscale, uci-usb-gadget, and luci-app-usb-gadget in APK and IPK formats

Local (snapshot builds)

1. Build the environment (defaults to OpenWrt main/snapshot):

cd devenv
docker compose build builder

2. Enter and build:

docker compose run --rm builder
cp /repo/diffconfig_uz801 .config
make defconfig
make -j$(nproc)

To build a specific release locally:

OPENWRT_VERSION=v24.10.2 docker compose build builder --no-cache

Supported versions: OpenWrt 25.12.x and current snapshots (kernel 6.12). OpenWrt 24.10.x (kernel 6.6) compiles but does not boot — the Makefile supports it via KERNEL_FOR_24 (currently commented out) if someone wants to investigate further.

Installation

Flashing from OEM Firmware

1. Install EDL tool: https://github.com/bkerler/edl

2. Enter EDL mode:

   • UZ801v3: See PostmarketOS wiki guide

3. Backup original firmware:

   edl rf backup.bin
   

4. Flash OpenWrt:

   ./openwrt-msm89xx-msm8916-*-flash.sh
   

   The script flashes entirely via EDL (no fastboot step). It automatically backs up radio partitions, writes the new GPT, firmware, boot and rootfs, and restores the backed-up partitions.

Accessing Boot Modes

UZ801v3

• Fastboot mode: Insert device while holding the button
• EDL mode: Boot to fastboot first, then execute: fastboot oem reboot-edl

UF02

• Fastboot mode:
  • From OEM: adb reboot bootloader.
  • From OpenWrt: Enter edl and erase boot partition (edl e boot).
• EDL mode:
  • From OEM: adb reboot bootloader, flash lk2nd aboot. Reboot pressing the button.
  • From OpenWrt: Insert device while holding the button.

Troubleshooting

No Network / Modem Stuck at Searching

The modem requires region-specific MCFG configuration files.

Extract MCFG from Your Firmware

1. Dump modem partition:

   edl r modem modem.bin
   

2. Mount and navigate:

   # Mount modem.bin (it's a standard Linux image)
   cd image/modem_pr/mcfg/configs/mcfg_sw/generic/
   

3. Select your region:

   • APAC - Asia Pacific
   • CHINA - China
   • COMMON - Generic/fallback
   • EU - Europe
   • NA - North America
   • SA - South America
   • SEA - South East Asia

4. Locate your carrier's MCFG: Navigate to your telco's folder and find mcfg_sw.mbn. If your carrier isn't listed, use a generic configuration from the common folder.

Apply the Configuration

Transfer to device (capitalization matters!):

scp -O mcfg_sw.mbn root@192.168.1.1:/lib/firmware/MCFG_SW.MBN
# ... and reboot the device ...

Roadmap

• Custom package server for msm89xx/msm8916
  • Note: Target-specific modules may require building from source via make menuconfig
  • The target-specific APK feed is automatically removed on first boot (msm89xx is not on downloads.openwrt.org)
• Investigate lpac for eSIM support
• Memory expansion: kmod-zram + zram-swap enabled on all devices

Credits

• @ghosthgy - Initial project foundation
• @lkiuyu - MSM8916 support, patches, and OpenStick feeds
• @Mio-sha512 - USB gadget and firmware loader concepts
• @AlienWolfX - Carrier policy troubleshooting guide
• @gw826943555 & @asvow - Tailscale LuCI application