167 lines
5.9 KiB
Markdown
167 lines
5.9 KiB
Markdown
|
|
|
|
Modern OpenWrt build targeting MSM8916 devices with full modem, USB gadget, and WiFi support.
|
|
|
|
## Table of Contents
|
|
|
|
- [About OpenWrt](#about-openwrt)
|
|
- [Supported Devices](#supported-devices)
|
|
- [Features](#features)
|
|
- [Prerequisites](#prerequisites)
|
|
- [Building](#building)
|
|
- [Installation](#installation)
|
|
- [Flashing from OEM Firmware](#flashing-from-oem-firmware)
|
|
- [Accessing Boot Modes](#accessing-boot-modes)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [No Network / Modem Stuck at Searching](#no-network--modem-stuck-at-searching)
|
|
- [Roadmap](#roadmap)
|
|
- [Credits](#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](TBR/readme.md) 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](packages/uci-usb-gadget/readme.md) 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](https://github.com/bkerler/edl)
|
|
|
|
## Building
|
|
|
|
1. Enter the build environment:
|
|
```
|
|
cd devenv
|
|
docker compose run --rm builder
|
|
```
|
|
|
|
2. Configure and build:
|
|
```
|
|
cp /repo/diffconfig_uz801 .config
|
|
echo "# CONFIG_SIGNED_PACKAGES is not set" >> .config # Optional: disable signature verification
|
|
make defconfig
|
|
make -j$(nproc)
|
|
```
|
|
|
|
### Building standalone packages
|
|
|
|
A GitHub Actions workflow (`build-package.yml`) builds `luci-app-tailscale`, `uci-usb-gadget`, and `luci-app-usb-gadget` in both APK and IPK formats. Trigger it manually from the Actions tab.
|
|
|
|
## Installation
|
|
|
|
### Flashing from OEM Firmware
|
|
|
|
1. **Install EDL tool**: https://github.com/bkerler/edl
|
|
2. **Enter EDL mode**:
|
|
- **UZ801v3**: See [PostmarketOS wiki guide](https://wiki.postmarketos.org/wiki/Zhihe_series_LTE_dongles_(generic-zhihe)#How_to_enter_flash_mode)
|
|
|
|
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`
|
|
- Removed feed: `https://downloads.openwrt.org/snapshots/targets/msm89xx/msm8916/packages/packages.adb`
|
|
- [ ] Investigate `lpac` for eSIM support
|
|
- [x] Memory expansion: `kmod-zram` + `zram-swap` enabled on all devices
|
|
|
|
## Credits
|
|
|
|
- **[@ghosthgy](https://github.com/ghosthgy/openwrt-msm8916)** - Initial project foundation
|
|
- **[@lkiuyu](https://github.com/lkiuyu/immortalwrt)** - MSM8916 support, patches, and OpenStick feeds
|
|
- **[@Mio-sha512](https://github.com/Mio-sha512/OpenStick-Builder)** - USB gadget and firmware loader concepts
|
|
- **[@AlienWolfX](https://github.com/AlienWolfX/UZ801-USB_MODEM/wiki/Troubleshooting)** - Carrier policy troubleshooting guide
|
|
- **[@gw826943555](https://github.com/gw826943555/luci-app-tailscale) & [@asvow](https://github.com/asvow)** - Tailscale LuCI application
|