Skip to content

About

QManager Edition for PRAIRE and LEMUR modems (and other modems with similar architecture).

Resources

Stars

71 stars

Watchers

3 watching

Forks

Latest commit

 

History

2,271 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

QManager

QManager

A modern, custom GUI for Quectel modem management

Visualize, configure, and optimize your cellular modem's performance with an intuitive web interface

Version License Platform Next.js React


QManager Dashboard — Network Status and Device Information

QManager Dashboard — Carrier Aggregation, Device Metrics, Live Latency and Recent Activities

QManager Cellular and Radio Information page

QManager About Device page

Note: QManager is the successor to SimpleAdmin, rebuilt from the ground up with a modern tech stack and improved user experience. This branch targets the Quectel RM520N-GL modem running its internal Linux OS (SDXLEMUR, ARMv7l, kernel 5.4.210).

Other modems: This build is primarily developed and tested against the RM520N-GL (Qualcomm SDXLEMUR chipset), but since it targets the vanilla Linux OS running on the modem itself rather than a device-specific stack, it may also work on other Quectel modems with a similar internal architecture -- notably Qualcomm SDX55 / SDXPRAIRIE-based models. The Quectel RG501Q-EU (SDX55) is supported at the community tier: it is not validated by the maintainers, so your mileage may vary, and issue reports from RG501Q-EU or other SDX55/SDXPRAIRIE modems are welcome.


Features

Signal & Network Monitoring

  • Live Signal Dashboard — Real-time RSRP, RSRQ, SINR with per-antenna values (4x4 MIMO) and 30-minute historical charts
  • Antenna Statistics — Per-port signal breakdown with quality indicators for all 4 antenna ports
  • Antenna Alignment — 3-position recording tool that compares composite signal scores to recommend best antenna placement
  • Network Events — Automatic detection of band changes, cell handoffs, carrier aggregation changes, and connectivity events
  • Latency Monitoring — Real-time ping with 24-hour history, jitter, packet loss, and aggregated views (hourly/12h/daily)
  • Connectivity Engine — Configurable HTTP/HTTPS probe with primary-then-fallback, captive-portal detection, and a sensitivity preset (regions that block Google still come up clean by default)
  • Traffic Statistics — Live throughput (Mbps) and cumulative data usage

Cellular Configuration

  • Band Locking — Select and lock specific LTE/NR bands for optimal performance, with automatic band failover
  • Tower Locking — Lock to a specific cell tower by PCI, with automatic failover and scheduled changes
  • Frequency Locking — Lock to exact EARFCN/ARFCN channels
  • APN Management — Create, edit, delete APN profiles with MNO presets (T-Mobile, AT&T, Verizon, etc.)
  • Custom SIM Profiles — Save complete configurations (APN + TTL/HL + optional IMEI) per SIM, with auto-apply on SIM swap
  • Connection Scenarios — Save and restore full network configuration snapshots
  • Network Priority — Configure preferred network types and selection modes
  • Cell Scanner — Active and neighbor cell scanning with signal comparison
  • Frequency Calculator — EARFCN/ARFCN to frequency conversion tool
  • SMS Center — Send and receive SMS messages directly from the interface
  • IMEI Settings — Read, backup, and modify device IMEI, plus IMEI Generator & Validator (Luhn algorithm, TAC presets, imei.info lookup)
  • FPLMN Management — View and manage the Forbidden PLMN list
  • MBN Configuration — Select and activate modem broadband configuration files

Network Settings

  • TTL/HL Settings — IPv4 TTL and IPv6 Hop Limit configuration (iptables-based)
  • MTU Configuration — Dynamic MTU application for rmnet interfaces
  • IP Passthrough — Direct IP assignment to downstream devices

VPN & Remote Access

  • Tailscale VPN — One-click install, connect, and manage Tailscale mesh VPN directly from the UI; peer table, health warnings, boot persistence, and a one-toggle Tailscale SSH switch (gated by your admin-panel ACLs)
  • Port Firewall — Built-in firewall restricting web UI (80/443) to trusted interfaces; Tailscale-aware, enabled by default

Note on the Tailscale SSH toggle: QManager treats its SSH toggle as the source of truth and re-applies it on every reconnect, so it survives tailscale up --reset. If you carried a Tailscale install over from SimpleAdmin / the RGMII Toolkit, or you change SSH state via the tailscale CLI, the GUI won't see that change — and the next reconnect from the GUI will reset SSH back to whatever the toggle remembers. To resync after an out-of-band change, just toggle the switch off and on in the GUI once.

Reliability & Monitoring

  • Connection Watchdog — 4-tier auto-recovery: AT+COPS deregister/reregister -> CFUN toggle -> SIM failover -> full reboot (with token bucket rate limiting)
  • Email Alerts — Downtime notifications via Gmail SMTP (msmtp), sent on recovery with duration details
  • SMS Alerts — Downtime and recovery notifications delivered over the cellular control channel via qsms (QMI WMS); reaches you even while the data link is offline. Registration-guarded retry with dedup collapse, threshold-based suppression of transient blips, bounded failure logging
  • Low Power Mode — Scheduled CFUN power-down windows via cron
  • Software Updates — In-app OTA update checking, download, verification, installation, and rollback
  • System Logs — Centralized log viewer with search

Interface

  • Dark/Light Mode — Full theme support with OKLCH perceptual color system
  • Responsive Design — Works on desktop monitors and tablets in the field
  • Cookie-Based Auth — Secure session management with rate limiting
  • Web Console — Browser-based terminal (ttyd) integrated into the UI with connection status, fullscreen mode, and dark theme
  • AT Terminal — Direct AT command interface for advanced users
  • Initial Setup Wizard — Guided onboarding for first-time configuration

Prerequisites

  • A Quectel RM520N-GL modem with RGMII Ethernet connectivity
  • Entware installed at /opt (the installer will bootstrap Entware automatically if not present, but internet access is required)
  • ADB or SSH access to the modem

Note: QManager is fully independent — it does not require SimpleAdmin or the RGMII Toolkit to be pre-installed. The installer handles everything: Entware bootstrap, lighttpd, user/group creation, and service setup.


Quick Install

ADB or SSH into the modem and run:

curl -fsSL -o /tmp/qmanager-installer.sh \
  https://github.com/dr-dolomite/QManager-RM520N/raw/refs/heads/main/qmanager-installer.sh && \
  bash /tmp/qmanager-installer.sh

The interactive installer fetches the latest release, verifies the SHA-256 checksum, bootstraps Entware (if needed), installs lighttpd, deploys the QManager frontend and backend, configures systemd services, and optionally sets up SSH (dropbear). Bundled dependencies (qmanager_atd, jq, dropbear) are installed automatically. The SSH root password is automatically set to match the web UI password during first-time onboarding. A reboot is triggered after installation.

If curl isn't available on your modem (common on x5x/x6x firmwares like RM502, RM520, RM521), install it through Entware first, then call it by absolute path so the BusyBox shell's default PATH doesn't trip you up:

opkg update && opkg install curl
/opt/bin/curl -fsSL -o /tmp/qmanager-installer.sh \
  https://github.com/dr-dolomite/QManager-RM520N/raw/refs/heads/main/qmanager-installer.sh && \
  bash /tmp/qmanager-installer.sh

If you have wget but not curl, just use wget to fetch the installer — the installer's preflight will install curl from Entware automatically (Entware must already be bootstrapped) so future OTA updates work:

wget -O /tmp/qmanager-installer.sh \
  https://github.com/dr-dolomite/QManager-RM520N/raw/refs/heads/main/qmanager-installer.sh && \
  bash /tmp/qmanager-installer.sh

If wget and curl are not working, push the installer via ADB from local workstation:

via Windows

curl -fsSL -o qmanager-installer.sh `
  https://github.com/dr-dolomite/QManager-RM520N/raw/refs/heads/main/qmanager-installer.sh; `
  adb push .\qmanager-installer.sh /tmp/; `
  adb shell bash /tmp/qmanager-installer.sh

The QManager installer creates a /usr/bin/curl symlink during install, so subsequent commands and OTA updates pick up curl from the standard PATH without manual export.

Upgrading

From v0.1.5+, go to System Settings → Software Update and use the built-in OTA update flow — download, verify, and install without SSH. Rollback to the previous version is available if needed.

Note: The v0.1.4 → v0.1.5 hop requires ADB or SSH because v0.1.4's CGI lacks the sudo rule needed to invoke the update worker as root. From v0.1.5 onward, all future updates work via the UI.

Uninstalling

# SSH into the modem
bash /tmp/qmanager_install/uninstall_rm520n.sh

# Skip the confirmation prompt (non-interactive / scripted use):
bash /tmp/qmanager_install/uninstall_rm520n.sh --force

# Skip automatic reboot after uninstall:
bash /tmp/qmanager_install/uninstall_rm520n.sh --no-reboot

# Also remove config/profiles/passwords and Tailscale:
bash /tmp/qmanager_install/uninstall_rm520n.sh --purge

Entware (/opt/) is always preserved even with --purge — remove it manually if needed.

Password Reset

If you forget your QManager web GUI password, SSH into the modem as root and run:

qmanager_reset_password

This removes the stored password hash (/etc/qmanager/auth.json) and the active session, then prompts you to open the QManager web UI to set a new password — no reinstall needed.


Additional Dependencies

  • Bundled with installer: qmanager_atd (QManager's own Rust AT/SMS broker, static ARMv7; qcmd and qsms are links to it), jq (Entware package), dropbear (SSH server)
  • Downloaded during install: speedtest (Ookla Speedtest CLI, ARMv7 armhf — downloaded from install.speedtest.net)
  • Installed from Entware: lighttpd + lighttpd-mod-openssl, sudo, and coreutils-timeout (only on BusyBox older than 1.30, where timeout uses the legacy -t form)
  • Optional: msmtp (email alerts) -- can be installed from within the app

Tech Stack

Layer Technology
Frontend Next.js 16, React 19, TypeScript 5
Styling Tailwind CSS v4, OKLCH colors, Rethink Sans + JetBrains Mono
Components shadcn/ui (42+ components), Recharts, React Hook Form + Zod
Backend Shell scripts (Bash), CGI endpoints via lighttpd
AT Commands qcmd → qmanager_atd (Rust broker) on /dev/smd11 (direct, no socat); SMS via qsms
Init System systemd (.service units in /lib/systemd/system/)
Package Manager Bun (development), Entware opkg (device)

Architecture

Browser --- authFetch() --- lighttpd --- CGI Scripts --- qcmd --- qmanager_atd --- /dev/smd11 --- Modem
                |                  |                       |
                |          Shell Libraries (51)      flock serialization
                |
        reads /tmp/qmanager_status.json
                |
         qmanager_poller
   (~3.7-4.0s cycle; idle/deep tiers)

The frontend is a statically-exported Next.js app served by lighttpd from /usrdata/qmanager/www. The backend is shell scripts running on the modem's internal Linux -- CGI endpoints for API requests and systemd-managed daemons for data collection.

Key Data Flow:

  • Poller daemon queries the modem via AT commands each cycle (measured ~3.7-4.0s; per-antenna every 5 cycles, warm reads every 15) while a browser is polling, drops to idle and deep tiers with longer AT intervals when none is, and writes a JSON cache file (adaptive polling)
  • CGI endpoints (95 scripts) read the cache for GET requests, execute AT commands for POST requests
  • React hooks (72 custom hooks) poll the CGI layer and provide loading/error/staleness states
  • AT transport uses qcmd, a link to the qmanager_atd broker, on /dev/smd11 directly (no socat PTY bridge needed); all writes and live AT reads go this way
  • QMI lane (read-only, over QRTR) fills LTE signal on idle/deep cycles and data-call settings; SMS runs on QMI WMS via qsms with no AT lock (QMI lane, SMS)

Platform Details:

Concern RM520N-GL
OS Vanilla Linux (SDXLEMUR, ARMv7l, kernel 5.4.210)
Init systemd
Root FS Read-only by default (remounted RW when needed)
Persistent storage /usrdata/ partition
Web server lighttpd (Entware)
Firewall iptables
Config Files in /etc/qmanager/

Development

Prerequisites

  • Bun (recommended) or Node.js 18+

Getting Started

# Clone the repository
git clone https://github.com/dr-dolomite/QManager-RM520N.git
cd QManager-RM520N && git checkout development

# Install dependencies
bun install

# Start development server (proxies API to modem at 192.168.225.1)
bun run dev

Open http://localhost:3000 in your browser.

Production Build

# Static export to out/
bun run build

# Full package (frontend + backend tarball + checksum)
bun run package

The package script builds the frontend, bundles it with backend scripts and dependencies into a tarball, and generates a SHA-256 checksum -- ready for distribution via GitHub Releases.


Project Structure

QManager/
├── app/                        # Next.js App Router pages (51 routes)
│   ├── dashboard/              # Home — live signal monitoring
│   ├── cellular/               # Cellular info, SMS, profiles, band/tower/freq locking,
│   │                           #   cell scanner, APN, IMEI, FPLMN, network priority,
│   │                           #   antenna alignment/statistics
│   ├── local-network/          # IP passthrough, TTL, MTU
│   ├── monitoring/             # Network events, latency, email alerts, watchdog
│   ├── system-settings/        # System config, AT terminal, logs, software updates
│   └── (login, setup, reboot, about-device, support)
├── components/                 # React components (358 .tsx files)
│   ├── ui/                     # shadcn/ui primitives (42+ components)
│   ├── cellular/               # Cellular management UI
│   ├── dashboard/              # Home dashboard cards
│   ├── local-network/          # Network settings UI
│   ├── monitoring/             # Monitoring & alerts UI
│   └── system-settings/        # System configuration UI
├── hooks/                      # Custom React hooks (72 files)
├── types/                      # TypeScript interfaces
├── lib/                        # Utilities (auth-fetch, earfcn, csv)
├── constants/                  # Static data (MNO presets, event labels)
├── scripts/                    # Backend shell scripts
│   ├── etc/systemd/system/     # Systemd units (27)
│   ├── etc/sudoers.d/          # CGI privilege escalation rules
│   ├── etc/qmanager/           # Default config files
│   ├── usr/bin/                # Daemons & utilities (51)
│   ├── usr/lib/qmanager/       # Shared shell libraries (51)
│   ├── www/cgi-bin/quecmanager/ # CGI endpoints (95 scripts)
│   ├── install_rm520n.sh       # Device installation script
│   └── uninstall_rm520n.sh     # Clean removal script
├── dependencies/               # Bundled ARM binaries and packages
│   ├── qmanager_atd            # ARM binary (AT/SMS broker; qcmd and qsms link to it)
│   ├── jq.ipk                  # JSON processor
│   └── dropbear_*.ipk          # SSH server
├── docs/                       # Documentation
└── build.sh                    # Package builder (tarball + checksum)

Backend Services

QManager ships 27 qmanager-* systemd units (25 services, 2 timers: qmanager-auto-update.timer and qmanager-dpi-ensure.timer). All 25 services:

Service Purpose
qmanager-atd AT/SMS/QMI broker (qmanager_atd) — owns /dev/smd11; qcmd and qsms link to it
qmanager-auto-update Unattended update check (run daily by its timer)
qmanager-cfun-fix Boot-time CFUN=1 fix — radio recovery
qmanager-console Web console — ttyd on localhost:8080, reverse-proxied by lighttpd
qmanager-discord Discord bot (optional binary, started only when installed)
qmanager-dpi Traffic Engine — tpws DPI bypass daemon
qmanager-dpi-ensure Re-asserts the Traffic Engine REDIRECT rule (boot, then periodically via its timer)
qmanager-ethernet Re-applies the saved Ethernet link speed at boot
qmanager-firewall Port firewall — restricts 80/443 to trusted interfaces before lighttpd starts
qmanager-firewall-watch Keeps the IPv6 forward firewall rules in place
qmanager-imei-check IMEI integrity — verifies IMEI backup on boot
qmanager-mtu MTU — applies interface MTU settings at boot
qmanager-ping Latency monitor — 5s ping cycle, NDJSON history (24h)
qmanager-poller Main poller daemon — tiered AT polling, JSON cache, event detection
qmanager-scenario-schedule Applies scheduled connection-scenario changes
qmanager-scheduled-reboot Performs scheduled reboots
qmanager-setup One-shot boot setup — directories, permissions, config init
qmanager-sites Sites monitor daemon
qmanager-sms-forward SMS forwarding daemon
qmanager-sms-storage Boot self-heal for SMS storage routing
qmanager-tower-failover Tower failover — restores lock after cell loss (config-gated)
qmanager-tower-schedule-apply Applies scheduled tower locks
qmanager-tower-schedule-clear Clears scheduled tower locks
qmanager-ttl TTL/HL — applies iptables rules at boot
qmanager-watchcat Connection watchdog — 4-tier auto-recovery state machine

Tips for the Project

Support QManager's Development

Your contribution helps maintain the project and fund continued development, testing on new cellular networks, and hardware costs.


Donate via Wise   Donate via PayPal

You can also sponsor on GitHub.


The Mark

The QManager mark, a tonal Q

The ring is the network. The ray is the device, speaking from inside it.

QManager runs on the modem it manages, so the mark starts where the device is: a single ray leaves the center of a signal field and cuts a clean channel out through it. Nothing reaches in from the outside.

  • The ring is the network. Continuous and even, there whether or not you are looking at it.
  • The ray is the transmission leaving the device. It is anchored at the center because that is where QManager actually lives.
  • The notch is where the ring gives way. The two shapes never overlap or blur; the field makes a clean, measured space for what passes through it. That is the product's promise in one detail: the interface never claims something the modem is not doing.

It is a Q first, for QManager and Quectel. Two shapes, two tones, one hue, drawn on a 48 x 48 geometric grid at uniform stroke weight, with no gradient, shadow, or filter.

If you redraw it, keep the ray anchored at the center. Detached, a ring plus a 45 degree round-capped bar reads as a magnifying glass at every size below 48px. A magnifier's handle never reaches the lens center; a Q's tail does. That anchoring is what makes this a letterform instead of a search icon.

The two tones are the source pair for the entire design system, not consumers of it:

Part Value Role in the system
Ring oklch(0.623 0.214 259.815) Drives the dark-mode --primary-container and the active-nav tone
Tail oklch(0.488 0.243 264.376) "Signal Blue", the light-mode --primary, used literally

Every neutral in the interface carries a trace of that hue, so surfaces read as a family. Changing either tone is a system-wide change, not an asset tweak. See DESIGN.md under Colors > Source color.


License

This project is licensed under the MIT License with Commons Clause.

You are free to: use, modify, fork, and share QManager for personal and non-commercial purposes.

You may not: sell QManager, bundle it into a commercial product, or offer it as a paid service -- including forked versions.

Commercial Licensing

If you want to use QManager in a commercial product, OEM device, or reseller offering, commercial licenses are available. Contact DrDolomite directly to discuss terms.


Built with care by DrDolomite

About

QManager Edition for PRAIRE and LEMUR modems (and other modems with similar architecture).

Resources

Stars

71 stars

Watchers

3 watching

Forks

Releases

Packages

Contributors

Languages