Modern OpenWrt build targeting the UZ801v3 LTE dongle with full modem and USB gadget support.

Table of Contents

• About OpenWrt
• 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.

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
  • Note: LEDs are swapped in default kernel DTS
  • WiFi LED: 99-modem-led
  • Modem LED: 99-wifi-led

Storage & Recovery

• SquashFS Root: Compressed root filesystem
• OverlayFS: ext4 overlay partition for user data
• Factory Reset: firstboot mechanism enabled

Additional Packages

• Tailscale: LuCI app included in /root (manual installation required)
  • Install with: apk add --allow-untrusted /root/luci-app-tailscale*.apk
  • Not auto-installed to save space

Prerequisites

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

Building

1. Enter the build environment:

cd devenv
docker compose run --rm builder

2. Configure and build:

cp /repo/diffconfig .config
echo "# CONFIG_SIGNED_PACKAGES is not set" >> .config  # Optional: disable signature verification
make defconfig
make -j$(nproc)

Installation

Flashing from OEM Firmware

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

2. Enter EDL mode: See PostmarketOS wiki guide

3. Backup original firmware:

   edl rf backup.bin
   

4. Flash OpenWrt:

   ./openwrt-msm89xx-msm8916-yiming-uz801v3-flash.sh
   

   The script automatically backs up device-specific partitions, flashes the firmware, and restores critical data.

Accessing Boot Modes

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

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
  • Removed feed: https://downloads.openwrt.org/snapshots/targets/msm89xx/msm8916/packages/packages.adb
• Investigate lpac for eSIM support
• Memory expansion: swap/zram configuration

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