ssbg04/msm8916-openwrt
1
0 Fork 0
Code Issues Packages Projects Releases Wiki Activity

readme.md

Browse Source
This commit is contained in:
Miguel Fuertes committed 2025-10-09 12:34:47 +02:00
1 parent 9ba322a97e
commit 90120e4377
1 file changed
+129 -86
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+129 -86
View File
@@ -1,106 +1,149 @@
# OpenWrt for UZ801v3
![OpenWrt logo](https://raw.githubusercontent.com/openwrt/openwrt/refs/heads/main/include/logo.png)
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.
For developers, OpenWrt is the framework to build an application without having
to build a complete firmware around it; for users this means the ability for
full customization, to use the device in ways never envisioned.
Modern OpenWrt build targeting the UZ801v3 LTE dongle with full modem and USB gadget support.
### This repository
Modern version of OpenWrt working on UZ801v3:
- Modem Working
- ModemManager not showing Rx/Tx in Luci
- Wifi Working
- USB gadget (NCM, RNDIS, MASS, ACM Shell)
- Configure via [uci](packages/uci-usb-gadget/readme.md) or `luci` app.
- TUN installed
- Wireguard Installed
- `hotplug.d` scripts to manage leds, only on/off if iface, no blinking:
- On default Linux Kernel `dts`, leds are swapped!
- Wifi Led: [packages/ledcontrol/files/99-modem-led](packages/ledcontrol/files/99-modem-led)
- Modem Led: [packages/ledcontrol/files/99-wifi-led](packages/ledcontrol/files/99-wifi-led)
- ~~Firmware is dumped on first boot from modem/persist partition:~~
- ~~Uses the binaries/firmware from the own device.~~
- __*This will return eventually...*__
- Leaves the `luci-app-tailscale` package in `/root` ready to be installed:
- It is not auto installed as it will install `tailscale` that is a heavy package and not everyone is using tailscale.
- `apk add --allow-untrusted /root/luci-app-tailscale*.apk`
- **SquashFS and OverlayFS**:
- The image no longer uses `ext4` for rootfs, instead it uses `squashfs`.
- This allows for an overlay `ext4` partition to be used and enables `firstboot` (factory reset) mechanism.
## Table of Contents
- [About OpenWrt](#about-openwrt)
- [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)
### How to build OpenWrt
Docker is required!
```bash
---
## 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](packages/uci-usb-gadget/readme.md) 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](packages/ledcontrol/files/99-modem-led)
- Modem LED: [99-wifi-led](packages/ledcontrol/files/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](https://github.com/bkerler/edl)
## Building
1. Enter the build environment:
```
cd devenv
docker compose run --rm builder # This will open bash inside a build environment
cp /repo/diffconfig .config # Copies the config on to the working folder
echo "# CONFIG_SIGNED_PACKAGES is not set" >> .config # Optional: Disable APK signature verification
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)
```
### How to flash from OEM
- Install `edl`: https://github.com/bkerler/edl
- Put the device in `edl` mode: https://wiki.postmarketos.org/wiki/Zhihe_series_LTE_dongles_(generic-zhihe)#How_to_enter_flash_mode
- Do a full backup: `edl rf backup.bin`
- Run `./openwrt-msm89xx-msm8916-yiming-uz801v3-flash.sh`: The script will backup the important partitions specific for your device, will flash everything and will restore de previously saved partitions.
## Installation
After the succesful flash if you:
- Want to enter `fastboot`, just insert the device with the button pressed.
- Want to enter `edl`, boot into fastboot and execute: `fastboot oem reboot-edl`.
### Flashing from OEM Firmware
### No Network/Modem Stuck at Searching
1. **Install EDL tool**: https://github.com/bkerler/edl
2. **Enter EDL mode**: See [PostmarketOS wiki guide](https://wiki.postmarketos.org/wiki/Zhihe_series_LTE_dongles_(generic-zhihe)#How_to_enter_flash_mode)
First, extract the contents of `modem.bin` from your firmware dump. You can do `eld r modem modem.bin`. In linux, its a simple image, you can mount it. Once you have it mounted, navigate to this directory: `image/modem_pr/mcfg/configs/mcfg_sw/generic/` and choose the folder according to your region:
3. **Backup original firmware**:
```
edl rf backup.bin
```
- **APAC** - Asia Pacific
- **CHINA** - China
- **COMMON** - Use this if your region is not listed
- **EU** - Europe
- **NA** - North America
- **SA** - South America
- **SEA** - South East Asia
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.
Once you have selected your region, you'll find folders typically representing Telcos in your area. Navigate through the appropriate folder until you locate `mcfg_sw.mbn`. If your telco is not listed, just grab a generic as it is done in this project for europe:
```makefile
# packages/msm8916-firmware/Makefile
define Build/Compile
...
::image/modem_pr/mcfg/configs/mcfg_sw/generic/common/default/default/mcfg_sw.mbn $(PKG_BUILD_DIR)
...
endef
```
### Accessing Boot Modes
#### To apply the fix:
1. Transfer the file to your dongle: `scp -O mcfg_sw.mbn root@192.168.1.1:/lib/firmware/MCFG_SW.MBN`
- **Capitalization matters!** Modem expects it to be all caps.
3. Reboot the device.
- **Fastboot mode**: Insert device while holding the button
- **EDL mode**: Boot to fastboot first, then execute: `fastboot oem reboot-edl`
### TODO:
- Recover `msm-firmware-dumper`.
- Clean up overview page (`eth0` does not need to be there...)
- Investigate `lpac` and eSIM.
- Reboot to edl/bootloader from linux/luci.
- Swap? Zram?... expand ram with eMMC?
## Troubleshooting
### Future:
- Custom package server for msm89xx/msm8916
- Any target specific module not present might require to be built from sources. This repo can be used to do that, run `make menuconfig` before `make -j$(nproc)` and select it from the menu.
- Feed: `https://downloads.openwrt.org/snapshots/targets/msm89xx/msm8916/packages/packages.adb` has been removed from distfeeds file.
### 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 https://github.com/ghosthgy/openwrt-msm8916
- Starting point for this project.
- @lkiuyu https://github.com/lkiuyu/immortalwrt
- Almost all the msm8916 folder + patches + openstick feeds.
- @Mio-sha512 https://github.com/Mio-sha512/OpenStick-Builder
- `usb-gadget` and `msm-firmware-loader` idea (now `msm-firmware-dumper`).
- @AlienWolfX https://github.com/AlienWolfX/UZ801-USB_MODEM/wiki/Troubleshooting
- For the carriers policy troubleshooting.
- @gw826943555 and @asvow https://github.com/gw826943555/luci-app-tailscale
- Application for controlling tailscale from luci.
- **[@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