msm8916-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)

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

cd devenv
docker compose build builder

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

Install EDL tool: https://github.com/bkerler/edl
Enter EDL mode:
- UZ801v3: See PostmarketOS wiki guide
Backup original firmware:
```
edl rf backup.bin
```
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

Dump modem partition:
```
edl r modem modem.bin
```

Mount and navigate:

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

Select your region:
- APAC - Asia Pacific
- CHINA - China
- COMMON - Generic/fallback
- EU - Europe
- NA - North America
- SA - South America
- SEA - South East Asia
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

readme.md

Table of Contents

About OpenWrt