Stable v1.1.1 | Native OpenWrt 23.05.5 for ZLT X28 & X28 PRO

Open Core.
Real OpenWrt for your 5G CPE.

Replace the stock interface of your ZLT X28 or X28 PRO with real OpenWrt. OpenWrt 23.05.5 userspace on the MediaTek MT6890, 5G band & cell locking, SMS conversations & a local HTTP API, LuCI over HTTPS, and WireGuard, OpenVPN and Passwall2 preinstalled.

23.05.5
Real OpenWrt, standard LuCI & UCI
5G + LTE
Band & Cell Locking in LuCI
SMS & API
Conversations + HTTP API
A/B Safe
Signed A/B Firmware Upgrades
ZLT X28 5G CPE, front
Front
ZLT X28 5G CPE, back: power, four LAN ports, SIM slot and the USB-C debug port, with a penguin pointing at the debug port
Back
Firmware
Signed A/B upgrades
Cellular Link (5G)
Band & cell lock • LuCI
Telephony & SMS API
LuCI • HTTP API

Built for Control, Stability and Freedom

The stock interface is replaced by OpenWrt userspace. The vendor kernel and the 5G modem backend stay, so the modem keeps working.

SMS & Local HTTP API v1.1

Text messages in LuCI (Services → Telephony) as conversations, with a phone book and a local HTTP API with API keys for machines on your LAN. Received messages move to the router, so the SIM does not fill up.

HTTP API + Push to Your Address

5G Cellular Control

APN, operator selection with a network scan, 4G and 5G band locks, cell lock and signal status on a standard LuCI interface page.

x28_mipc netifd Protocol

VoIP In development

The stock firmware makes voice calls. We are building VoIP for OpenWrt, with a VoIP server on the router and more. It is not ready yet: voice calls are not supported in the current release.

Work in progress

Standard LuCI over HTTPS

The standard OpenWrt LuCI web interface with UCI configuration, SSH, netifd, dnsmasq and firewall3. Vendor daemons run only as the modem backend.

OpenWrt 23.05.5 Userspace

VPN & Proxy

Passwall2, WireGuard, OpenVPN, L2TP, PPTP and SSH tunnels, managed from LuCI.

Preinstalled

Signed A/B Firmware Upgrades

Signed upgrades write and verify the slot that is not running, then switch to it; x28-bootok manages the boot counter. Use x28-upgrade or the LuCI update notice. Nothing installs by itself; back up your settings first.

Signed Images + Signed opkg Feed
https://192.168.70.1/cgi-bin/luci/admin/status/overview
LuCI status page of the X28 running OpenWrt 23.05.5
LuCI on a real X28: OpenWrt 23.05.5 on the vendor 4.19.205 kernel.

SMS Conversations & Local HTTP API

The x28-telephony package adds Services → Telephony to LuCI and an HTTP API for machines on your LAN. Voice calls are not supported yet. Documentation

Messages

Conversations by number as in a messaging app: a paged list on the left, the thread with a reply box on the right. A new message takes its recipient from the phone book or a typed number. Delete a message or a whole conversation.

Phone book

Names for numbers, kept on the router and not on the SIM. Received and sent messages are stored on the router too, root-only, and kept across firmware upgrades.

The SIM does not fill up

The SIM has 50 slots. The service looks at it every 15 seconds, copies each received message to the router and only then deletes it from the SIM. Long messages (up to 10 parts) arrive in parts and are shown joined.

LuCI › Services › Telephony › Messages
LuCI Services, Telephony, Messages tab: a New message button, a recipient chosen from the phone book or typed, and a message box
LuCI › Services › Telephony › Phone book
LuCI Telephony Phone book tab: names for numbers, kept on the router, with Message and Delete buttons and an Add row
LuCI › Services › Telephony › API
LuCI Telephony API tab: API keys, the address that received messages are sent to, and curl usage examples

Local HTTP API

Any machine on your LAN (Home Assistant, n8n, Node-RED, a curl script) can send and list messages, and received messages can be pushed to an address you set. No cloud service is involved.

🔑
API keysCreated in LuCI and shown once; only the SHA-256 is stored.
📬
Push of received messagesEach complete received message is POSTed as JSON to the address you set.
⏱️
Rate limitAt most 30 messages sent per hour, API and LuCI together.
curl
# list messages, oldest first
curl -k -H "Authorization: Bearer $KEY" \
  https://192.168.70.1/cgi-bin/x28-telephony/messages

# send a message
curl -k -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+989121234567","text":"Hello"}' \
  https://192.168.70.1/cgi-bin/x28-telephony/messages
200done
400bad number, or empty or too long text
401no key, or a wrong one
429more than 30 messages sent in the last hour
502the modem refused the message; it is kept as failed

5G Band & Cell Locking

The modem is a normal netifd interface (proto x28_mipc) with its own LuCI page. Everything below is set on the interface page, under the Carrier tab. Documentation

Network mode

Automatic, 4G only or 5G only. Set before the data call, and read back from the modem.

Band locks

Allow or deny lists of LTE bands, and a 5G band mask set with x28-nrband. A mask outside the bands the modem supports is refused.

Cell lock

Lock to one cell by its EARFCN and PCI, or turn the lock off again.

Operator selection

Automatic or manual, with a network scan. A scan can take a few minutes and drops the data connection, which comes back by itself.

APN & IP type

IPv4, IPv6 or both. Leave the APN empty and it is taken from the SIM's operator. Roaming is off by default.

Modem status

Operator, registration, serving cell and neighbours with RSRP and RSRQ, carrier aggregation and the 5G (EN-DC) state.

LuCI › Network › Interfaces › wan › Carrier
LuCI interface page, Carrier tab: modem status with operator, registration, 5G signal and serving cell, then roaming, network selection, network mode, 4G band lock, 5G band lock and cell lock
The Carrier tab on a real X28, with 4G and 5G attached.

Bands the modem supports and the lock accepts

LTE
B1B3B5B7B8B20B28B32B38B40B41B42B43
5G NR
n1n3n5n7n8n20n28n38n40n41n77n78

Which of these your operator uses depends on your location. See the test log for what has been checked on real SIMs.

Tunnels and Proxies, Managed from LuCI

The router has what it takes to put your whole LAN through a tunnel or a proxy. Passwall2 setup notes and measured performance

🧭

Passwall2

Transparent proxy with xray: the whole LAN goes through the node you pick, switched from LuCI.

🔐

WireGuard

A module built for the vendor kernel, with LuCI support and the wireguard-tools.

🔑

OpenVPN

OpenVPN with OpenSSL and its LuCI page; the tunnels you enable start at boot.

🔗

L2TP

L2TP client, configured as a LuCI interface.

🔌

PPTP

PPTP client, configured as a LuCI interface.

🚇

SSH tunnels

Forward ports and tunnel traffic over SSH.

And more: other packages from OpenWrt's feeds and the signed X28 feed install with opkg or System → Software. Kernel modules from the official feeds do not load on the vendor kernel, so incompatible ones are refused instead of installed broken.

Install with x28-flasher

The flasher is the only supported way to install, back up and recover. These are the steps of the tutorial on the OpenWrt Forum; the screenshots are from flasher v0.4.0, later versions may look slightly different.

Discussion & Questions

The tutorial lives on the OpenWrt Forum

Questions, troubleshooting and progress notes are in the thread "ZLT X28 5G CPE (MT6890) custom OpenWrt 23.05 running as my daily router". This is community firmware, not an official OpenWrt image.

Read on OpenWrt Forum
⚠️
Flashing can brick your router. Never write partitions or change the boot order by hand. Read the recovery guide first. A firmware upgrade writes the inactive slot, so the first one can replace the stock fallback.
1

Download and launch the flasher

Download the latest X28 Flasher for your operating system, install it and launch it.

2

Connect to your device

Use a USB-A to USB-C cable; USB-C to USB-C does not work. Follow these steps in the exact order:

  1. Connect the USB cable between your computer and the ZLT X28.
  2. In the flasher, click Connect Device.
  3. Click Start.
  4. Wait about 10 seconds.
  5. Connect the router's power adapter.
  6. Wait until the device reading completes.

Important: Do not connect the power adapter before the 10-second wait. The order matters for the flasher to reach the device.

Flasher: Connect device pageFlasher: connection started, waiting for the deviceFlasher: device connectingFlasher: device information read
3

Back up your original firmware

Before flashing anything, back up the original firmware.

  1. Open the backup section in the flasher.
  2. Follow the instructions to create a backup.
  3. Save the backup somewhere safe, and keep a second copy offline.
  4. Make sure the backup completes successfully.

Important: Do not skip this step. The backup is how you restore the original vendor firmware if anything goes wrong. It takes about 20 to 50 minutes; if it fails, retry and it resumes.

Flasher: backup page
4

Download the signed OpenWrt image

  1. Go to Get an image.
  2. Select Download the signed image.
  3. Click Download and wait for it to finish.

You do not need Docker or files from your vendor firmware to get a flashable image.

Flasher: Get an image, download the signed image
5

Identify your current boot slot

In the Device read section, find the device information: MAC address, IMEI, serial number and the current boot slot (A or B). Note the slot; you select the same one when flashing.

Flasher: device information with the current boot slot
6

Configure the flash

  1. Go to Flash OpenWrt and select Built/Downloaded Images.
  2. Under Image to Flash, select the image at the top of the list: the latest one, downloaded or assembled locally.
  3. Select the path to your backup. It is required on purpose, so you cannot skip the backup.
  4. Select the slot your device is booting from, as found in step 5.

Warning: The selected slot must match the current boot slot. Flashing the wrong slot can cause boot problems.

Flasher: Flash OpenWrt configuration
7

Start flashing

  1. Click Start. Untick Rehearsal for the real write; a rehearsal writes your backup to that slot again to check that writing works.
  2. Read and accept the risk warning.
  3. Type the confirmation phrase the flasher asks for, and submit it.
  4. Wait until the flasher reports Finished.

Important: Do not disconnect the USB cable or interrupt power while flashing.

Flasher: start the flashFlasher: risk warningFlasher: confirmation phraseFlasher: flash finished
8

Disconnect and reboot

  1. Click Disconnect in the flasher.
  2. Disconnect the USB cable.
  3. Unplug the router's power adapter, then plug it in again.
  4. Wait for the router to boot.

The X28 now boots into OpenWrt. Open https://192.168.70.1/cgi-bin/luci, accept the self-signed certificate and set a root password. SSH is on port 22 from the LAN.

LuCI status page after the first boot

Recovery: restore the original vendor firmware

If the router does not boot correctly, you can restore the original firmware from your verified backup.

  1. Reconnect the device to the flasher as in step 2.
  2. Go to Flash OpenWrt and select Rootfs from a verified backup.
  3. Select your backup.
  4. Choose the rootfs partition of the slot you flashed: rootfs_a for slot A, rootfs_b for slot B.
  5. Start the restore and wait until it finishes.
  6. Disconnect the device and power-cycle the router.

This restores the selected rootfs from your backup. Whether the vendor firmware then runs fully depends on the backup and on the state of the other partitions. Developers can still assemble images locally from a vendor backup (needs Docker). Problems? Open an issue with the flasher and firmware versions, your device and the logs.

Latest Releases

Straight from GitHub releases. Verify downloads against the release's SHA256SUMS.

…GitHub stars
…total downloads
…feed packages
…tests passed

X28 Flasher

Backup, install and recovery.

Firmware

Image bundle and signed sysupgrade files.

Signed package feed · Test log

A Normal OpenWrt Shell

SSH in and use uci, opkg and the project's own tools. Click a command to run it in the simulated console; the output is what the tools print.

Quick Commands:
ssh root@192.168.70.1 OpenWrt 23.05.5
Click a command above.
root@X28:~#
ToolWhat it doesSynopsis, from the source
x28-upgradex28-updateUpgrade to the newest signed image. Without -y it only checks; with it, it writes the other slot and keeps your changed settings.x28-upgrade [--refresh | -y [-b]]
x28-update-checkx28-updateRead-only check for a newer signed release; prints JSON for LuCI.x28-update-check [--refresh]
x28-smsx28-telephonyText messages, phone book, API keys and the HTTP API. Output is JSON.x28-sms list | poll | send N TEXT | delete ID… | contacts | contact-set N NAME | contact-del N | keys | key-add LABEL | key-del ID | webhook [URL]
x28-apnx28-mipcThe APNs of the SIM's operator, from the database the stock firmware ships.x28-apn [imsi]
x28-modem-statusx28-mipcRead-only modem state for LuCI's Carrier tab: operator, registration, serving cell and signal.x28-modem-status
x28-plmn-scanx28-mipcScan for networks; the modem leaves its network meanwhile.x28-plmn-scan --start | --state | --last
x28-nrbandx28-nrbandThe 5G band mask and the 5G signal, over the modem's MIPC channel.x28-nrband get | set W0 W1 W2 | signal

Full --help output and man pages for every tool are planned: #570.

ZLT X28 & X28 PRO Specifications

Built around the MediaTek MT6890 platform. Full hardware notes

MT6890 4× Cortex-A55
4Cortex-A55 cores
2.0 GHzmax CPU speed
5G NR + LTEQuectel RG500L-EU
Wi-FiMT7915 dual band
1 GiBRAM
1 GiBNAND, A/B slots

Technical Specifications

ProcessorMediaTek MT6890 (T750), 4x Cortex-A55, 0.5 to 2.0 GHz
Architectureaarch64 (64-bit ARM, musl libc)
Kernel4.19.205 vendor kernel with OpenWrt 23.05.5 userspace
Cellular ModemQuectel RG500L-EU, 5G NR + LTE, on the SoC's modem processor; 4 antennas, one nano-SIM
SMS & Telephonyx28-telephony: text messages in LuCI + local HTTP API
Voice / VoIPIn development
Wi-Fi SubsystemMediaTek MT7915, dual band (X28: one MT7915D chip; X28 PRO: two MT7915 chips)
Ethernet4 LAN sockets: one 2.5 G, three 1 G
Memory1 GiB RAM; Linux gets about 628 MiB, the rest is the modem's
Flash1 GiB NAND, 51 partitions, A/B slots; about 288 MiB for installs and settings
Reset ButtonHold for 10 s to reset to defaults
Recovery PortUSB-C, MediaTek preloader; USB-A to USB-C cable only
Serial ConsoleUART, 921600 8N1, 1.8 V logic, unpopulated 3-hole footprint

Stock Firmware vs. X28 OpenWrt

What changes when you move from the stock firmware to this image.

Feature Category Stock Vendor Firmware X28 OpenWrt v1.1.1
Operating System Vendor firmware and web UI OpenWrt 23.05.5 userspace on the vendor 4.19 kernel
SMS & Telephony Vendor web page; messages stay on the SIM (50 slots) Conversations in LuCI + local HTTP API; messages kept on the router
VoIP & Voice Calls Voice calls through the vendor firmware In development VoIP with a VoIP server on the router; not ready yet
5G Band & Cell Locking Vendor UI Band & cell locking in LuCI
Web Management Interface Vendor web UI Standard LuCI over HTTPS + UCI
VPN & Proxy Not part of the vendor UI Passwall2, WireGuard, OpenVPN, L2TP, PPTP, SSH tunnels
Package Management No package manager Signed kernel-compatible opkg feed
Firmware Upgrade Safety Vendor updates Signed A/B sysupgrade to the inactive slot
Update Controls Vendor UI x28-upgrade command & LuCI update notice; nothing installs by itself
SSH & Root Access Not offered SSH on port 22 from the LAN

The engineering story, on Sisoog

An article series by Ali Naderi Parizi, in Persian, follows this project from the first look at the hardware to signed A/B upgrades. Part 1 is online: the hardware, the UART console and access to the 5G modem.

Read part 1 on Sisoog