Status, history and "is it stuck?" checks for a T-Mobile Home Internet gateway, for an OpenWrt router sitting behind it. There's a LuCI app for the router's web interface and a command line tool underneath it.
tmhi used to be called tmog4ar; see Upgrading from tmog4ar.
My gateway occasionally gets "stuck" on n25 with a 20 MHz channel instead of n41 at 100 MHz, leaving about a third of the usual bandwidth until it's rebooted. Short drops to another band are normal handovers and fix themselves. tmhi logs a sample every minute so it can tell those two cases apart, tells you when a reboot is worth it, and can do that reboot itself overnight if you want.
- Status → Cellular in LuCI: the band, channel width and signal (RSRP, RSRQ, SINR, etc), each with a one-line explanation of what it means and what counts as good. Plus a health verdict, a refresh button and a reboot button that asks first.
- History for the last 24 hours, 7 days or 30 days: which band you were on over time, SINR and RSRP charts, a good-samples-by-hour heatmap, time on each band and tower, and every band / tower change, gateway reboot and gateway software update.
- Optional automatic reboot at night. When a reboot is recommended, tmhi can reboot the gateway itself between 02:00 and 05:00, once nobody's been using the internet for 15 minutes, at most once a night. Off by default; see Automatic reboot at night.
- Notifications when a reboot becomes recommended, when the connection recovers and around automatic reboots and when the gateway's software is updated, through syslog, ubus and your own scripts in
/etc/hotplug.d/tmhi/(an ntfy example is included). See Notifications. - Tower names, distance and direction. Name the towers you connect to (it links to CellMapper to find them) and the page shows "Water tower · 4.0 mi S" with an arrow pointing at it, which helps when you're deciding which window to put the gateway in.
- A card on Status → Overview and two dashboard widgets (if you use luci-mod-dashboard; it needs a version from September 2026 or later, so run
apk upgrade luci-mod-dashboardif the dashboard stops loading after installing tmhi). - A command line tool,
tmhi, with the same status and history in a terminal.
- OpenWrt 25.12 or newer. The packages are
.apkfiles, which is the package format from 25.12 on; 24.10 and older use opkg and I don't build for them. Any router model works (the packages are architecture-independent). - A gateway with T-Mobile's local API. It's developed and tested on the Arcadyan TMO-G4AR. The Arcadyan KVD21, Sagemcom Fast 5688W and Sercomm TMO-G4SE use the same API and should work; if you have one, please say how it went, working or not. The Nokia 5G21 uses a different API and isn't supported.
- The router's WAN port plugged into one of the gateway's LAN ports, so the router can reach the gateway at
192.168.12.1. That's the normal setup. If your gateway uses a different address, you can change it in Settings. - The gateway's admin password (the one for its web page at
http://192.168.12.1). It's printed on the label on the back of the gateway, unless you've changed it. Without it you still get the band, signal and history, but not the channel width, PCI / channel / CQI, or the reboot button.
-
Open a shell on the router. From a terminal (on Windows, PowerShell has
sshbuilt in), using your router's address and the root password you use for LuCI:ssh root@192.168.1.1
-
Add my package repository and install. Paste these three lines:
uclient-fetch -O /etc/apk/keys/tmog4ar.pem https://dave-atx.github.io/g4arctrl/tmog4ar.pem echo https://dave-atx.github.io/g4arctrl/packages.adb >> /etc/apk/repositories.d/customfeeds.list apk update && apk add tmhi luci-app-tmhi
The first line installs the key the packages are signed with (it should match openwrt/tmog4ar.pem). The install pulls in
curlandjqand starts thetmhiservice, which takes a sample once a minute. On a router without LuCI, leave outluci-app-tmhi. -
Set the gateway's admin password (on the label on the back of the gateway, unless you've changed it). In LuCI, go to Status → Cellular → Settings, enter it under Admin password, and click Save & Apply.
-
Wait a minute and reload Status → Cellular. History builds up from here: the first useful hour-by-hour picture takes a day or so.
apk update && apk upgradeYour settings and history are kept.
tmog4ar was renamed tmhi in 0.4.0. apk upgrade (or image-upgrade -v tmhi upgrade on the Pi images; see Upgrading) moves you over: the tmog4ar and luci-app-tmog4ar packages become empty ones that install tmhi and luci-app-tmhi, and the first time they're installed they move your settings (/etc/config/tmhi), history (/etc/tmhi/, if you kept the default history_dir) and notification scripts (/etc/hotplug.d/tmhi/) across. Afterwards you can remove them with apk del tmog4ar luci-app-tmog4ar; tmog4ar stays a shortcut for tmhi until you do.
What changes for you: the page is still Status → Cellular. The command is tmhi, the syslog tag and ubus event are tmhi (logread -e tmhi, ubus listen tmhi), and hook scripts run from /etc/hotplug.d/tmhi/. Anything of your own that watches for tmog4ar in the log or listens for the tmog4ar ubus event needs the new name.
If you installed the .apk files from Releases rather than the repository, install all four from the new release (tmhi, luci-app-tmhi, tmog4ar, luci-app-tmog4ar) so the old ones are replaced rather than left running alongside.
Download the tmhi and luci-app-tmhi .apk files from Releases, copy them to the router, and:
apk add --allow-untrusted ./tmhi-*.apk ./luci-app-tmhi-*.apkYou won't get updates through apk upgrade this way.
apk del luci-app-tmhi tmhiHistory stays in /etc/tmhi/ and settings in /etc/config/tmhi until you delete them.
A sample is good when the gateway is registered on a preferred band (n41 by default) and, if the width is known, at least 40 MHz wide. The page shows:
- OK when the latest sample is good.
- Degraded when it isn't, but not for long. Short drops are normal handovers.
- Reboot recommended once samples have been bad for 30 minutes straight and a good one was seen in the past week. The week rule keeps it from recommending reboots when the n41 site itself is down.
- Unreachable when the gateway doesn't answer.
The preferred bands, minimum width and 30 minutes are all in Settings → Health. Unless you turn on the automatic reboot below, tmhi never reboots the gateway by itself; the reboot button asks first.
Settings → Automatic reboot (off by default; needs the admin password). With it on, tmhi reboots the gateway by itself when a reboot is recommended, but only:
- between 02:00 and 05:00 router time,
- once the internet connection has been quiet (under 1 Mbit/s both ways, each minute) for 15 minutes, so nobody's in the middle of something,
- at most once a night. If it's still degraded afterwards, it tries again the next night.
The router can't see who's home, so "quiet" means the traffic on its WAN device (eth1 on a Pi 5, found automatically unless you pick one). A big download or a backup running all night keeps it from rebooting that night. All of these are settings. Reboots, automatic or from the button, show up in the history's changes.
tmhi sends nothing off the router itself. When a reboot becomes recommended, when the connection recovers after that, before and after an automatic reboot, and when the gateway comes back with new software, it:
- writes a line to the system log (
logread -e tmhi; forward it with the router's remote syslog setting), - sends a ubus event (
ubus listen tmhi), - runs the scripts in
/etc/hotplug.d/tmhi/, withACTION,MESSAGE,LEVEL,BAND,WHYandDURATIONset.
/etc/hotplug.d/tmhi/50-example is a commented-out example that pushes to ntfy with curl; uncomment it and change the topic, or add your own script next to it. Scripts in that directory are kept across sysupgrade. tmhi notify-test sends a test. Brief drops don't notify: the first notification comes when a reboot is recommended (30 minutes by default).
The system log also gets a line when the gateway stops answering and when it's back, for reboots from the button or tmhi reboot, and when the night window closes with a recommended reboot not done, saying why; those don't run the scripts. Lines use the daemon facility: warning for a recommended reboot, a failed or unsuccessful automatic reboot, a failed manual reboot and the gateway not answering, notice for the rest.
Next to the tower number (gNB) on Status → Cellular:
- Find on CellMapper opens CellMapper's map around your gateway. Towers are labelled with their numbers; click the one that matches.
- Name it…: type a name and paste the CellMapper page's link into Location (after you click a tower, the map is centred on it). An Apple or Google Maps link, or plain
latitude, longitude, works too.
Towers you've used before can be named from History → Time on each tower. Names live in /etc/config/tmhi on the router, nothing is looked up online, and your position only leaves the router if you click one of the map links.
tmhi status [--json] band, channel width, signal quality and health (default)
tmhi watch [-i SECS] live view, refreshed every 15s by default
tmhi health is it stuck? exit 0 ok, 2 degraded, 3 reboot recommended, 1 unreachable
tmhi history [-s 7d] time per band and tower, quality per hour / day, band and tower changes
(--json for the numbers behind the LuCI charts)
tmhi reboot [--force] reboot the gateway
tmhi notify-test send a test notification (syslog, ubus, hotplug scripts)
tmhi raw [gateway|cell] raw JSON from the gateway
$ tmhi status
TMO-G4AR fw 1.00.18 · up 4h 21m · 2026-11-02 17:55:51
● registered · 5G SA · APN FBB.HOME · IPv6 yes
5G n41
Width 100 MHz ██████████ good
RSRP -93 dBm █████░░░░░ fair
RSRQ -10 dB █████░░░░░ good
SINR 22 dB ███████░░░ good
Bars 4.0 /4 ██████████ good
Tower Water tower · 4.0 mi ↓ S (167°)
gNB 1234567 · CID 101 · PCI 500 · ARFCN 520110 · CQI 12 · RSSI -82 · Internal_omni
Health OK on n41 100 MHz
tmhi health exits 3 when a reboot is recommended, so you can build your own alerting or automation around it. tmhi help lists every command and setting.
Channel width says "n/a". The admin password isn't set, or it's wrong. The Admin login row on Status → Cellular says which.
"Admin login failed". Check the password in Settings. After a failed login tmhi waits 15 minutes before trying that same password again, so it can't get the gateway to lock the account. Saving a different password tries it right away.
"No sample yet" or the history is empty. The service samples once a minute. Check it's running under System → Startup (tmhi), or from a shell: /etc/init.d/tmhi status.
Is this hard on the gateway? Each sample is one or two small requests a minute. The LuCI pages read the router's copy of the latest sample rather than asking the gateway, however many browsers have them open; Refresh asks the gateway only if that copy is more than 15 seconds old.
What about my flash / SD card? Samples wait in RAM and go to flash in one write an hour, one file per day, about 3 MB a month. Old days are deleted whole, so nothing on flash is rewritten. A power cut can lose up to an hour of history (Settings → History can change that).
A tower number CellMapper has never heard of. The gateway sometimes reports the tower number with one bit missing for a few minutes. It can also briefly repeat the previous tower's number (one bit off) after moving to a new tower. History ignores both: while the PCI and channel stay the same, a new number is held back for up to 5 minutes before it counts as a tower change. If you see another odd one, CellMapper not knowing it is a good hint it's bogus.
Does anything leave my network? No. tmhi talks to the gateway and nothing else. The only outside links are CellMapper and Apple Maps, and only when you click them.
Each release also has OpenWrt 25.12 images for the Pi 5 (ext4 or squashfs, factory or sysupgrade) built with the Image Builder, in two flavours:
tmhi: tmhi, the LuCI app, the packages in openwrt/image/packages.txt and the repository above.tmhi-cake-adapt: the same plus cake-adapt and its LuCI app, an adaptive SQM shaper for connections whose speed changes, like 5G home internet. cake-adapt isn't in the OpenWrt feeds, soapk upgradewon't update it; the next image will.
They carry no configuration, so after flashing set the gateway password as in step 3. A sysupgrade keeps /etc/config/tmhi and the history. The release notes list the packages that changed since the previous release, and each image's .manifest lists all of them.
The images include image-upgrade, which compares the router with the latest release and upgrades to it:
image-upgrade # what the latest release would change; exit 2 if anything
image-upgrade upgrade # the same, then asks, downloads, checks the sha256 and runs sysupgradeIt lists the OpenWrt version and every package that would be updated, added or removed, including packages you installed yourself that the image doesn't have (they'd be gone after upgrading). It picks squashfs or ext4 to match the router and keeps your configuration as sysupgrade normally does. If /etc/image-upgrade/pre-upgrade exists and is executable, it runs first (to copy a backup somewhere, say), and a failure stops the upgrade; sysupgrade keeps that directory.
On a router not installed from these images, copy the script over and give it the image you want the first time: sh image-upgrade -v tmhi-cake-adapt.
Up to 0.3.4 the images were called tmog4ar and tmog4ar-cake-adapt, and the image-upgrade in those images only looks for that name. Give it the new one once, image-upgrade -v tmhi upgrade (or -v tmhi-cake-adapt); the image you upgrade to knows its new name.
The online firmware builders (firmware selector, owut, Attended Sysupgrade) only know about official packages, so their images can't include tmhi or cake-adapt. Reinstall them after upgrading with those, or upgrade with these images instead.
The CLI is a single POSIX shell script (busybox ash, also dash / bash) that needs curl and jq and reads its settings from UCI. The LuCI app is in openwrt/luci-app-tmhi. AGENTS.md has the conventions and the traps.
apk add curl jq
cp tmhi /usr/bin/ && cp openwrt/tmhi/files/tmhi.init /etc/init.d/tmhi
cp openwrt/tmhi/files/tmhi.config /etc/config/tmhi && chmod 600 /etc/config/tmhi
/etc/init.d/tmhi enable && /etc/init.d/tmhi startWith the OpenWrt SDK for 25.12 or main (any target). The LuCI app builds with luci.mk, so keep the default feeds, which include luci:
echo "src-link tmhi /path/to/g4arctrl/openwrt" >> feeds.conf
./scripts/feeds update -a && ./scripts/feeds install tmhi luci-app-tmhi
sh /path/to/g4arctrl/openwrt/source-tarball.sh dl
make defconfig && make package/tmhi/compile package/luci-app-tmhi/compile PKG_HASH=skipThe tmhi package is built from a source archive (tmhi-<version>.tar.xz) that each release uploads, the way packages in openwrt/packages are; source-tarball.sh makes the same archive from your checkout. PKG_HASH=skip is only needed if you've changed tmhi or LICENSE since the hash in the Makefile was set.
CI (.github/workflows/build.yml) builds the packages and the Pi 5 images on every push, and checks that the packages also build and install on OpenWrt main. To release, bump VERSION in tmhi and PKG_VERSION in openwrt/tmhi/Makefile, openwrt/luci-app-tmhi/Makefile and openwrt/tmog4ar/Makefile, set PKG_HASH in openwrt/tmhi/Makefile to the hash sh openwrt/source-tarball.sh /tmp prints, then push a vX.Y.Z tag. That creates the GitHub release (with the source archive) and updates the repository on GitHub Pages, signed with the key in the APK_PRIVATE_KEY secret.
- openwrt/image/packages.txt: packages in every image.
- openwrt/image/variants/: one file per image, with its own packages, plus
apk <url> <sha256>lines for packages that aren't in any feed. A new file is a new image. - openwrt/image/minimum-versions.txt: the build fails if an image has an older version of a package listed here. Use it when a fix is merged in openwrt/packages but the release feed hasn't been rebuilt yet.
To rebuild only the images, without a new tmhi version (for example when an OpenWrt package gets a security fix), push a vX.Y.Z-rN tag on the current version: v0.2.0-r1, v0.2.0-r2. That makes a release with the images and leaves the repository on Pages alone.
The gateway API details come from zacharee/HINTControl, which did the reverse engineering.
This isn't affiliated with or endorsed by T-Mobile. Licensed under Apache 2.0 (LICENSE).


