tmo-monitor

A lightweight, cross-platform Python 3 script that can monitor the T-Mobile Home Internet Nokia, Arcadyan, and Sagecom 5G Gateways for 4G/5G bands, cellular site (tower), and internet connectivity and reboots as needed or on-demand.

By default, checks for n41 5G signal and connectivity to google.com via ping.

Getting Started

Install dependencies

pip3 install .

The command will then be available anywhere as tmo-monitor.py.

Windows

On Windows, open the folder where you downloaded the project.
Click File > Open Windows PowerShell
Run the above pip3 install . command.
To use, either:
- Run cmd.exe within PowerShell first
- Open cmd.exe (Command Prompt) instead of PowerShell
- Run python bin/tmo-monitor.py in PowerShell from inside the project directory

When in doubt, consult this document or run tmo-monitor.py --help.

Usage

Command line usage

usage: tmo-monitor.py [-h] [--connectivity-check {ping,http}]
                      [-I INTERFACE]
                      [--http-target HTTP_TARGET] [--status-code {[100,600)}]
                      [-H PING_HOST] [--ping-count PING_COUNT] [--ping-interval PING_INTERVAL] [-6]
                      [-R] [-r]
                      [--skip-bands] [--skip-5g-bands] [--skip-connectivity-check] [--skip-enbid]
                      [--uptime UPTIME]
                      [-4 {B2,B4,B5,B12,B13,B25,B26,B41,B46,B48,B66,B71}] [-5 {n41,n71}]
                      [--enbid ENBID]
                      [--print-config]
                      [--logfile LOGFILE] [--log-all] [--log-delta] [--syslog]
                      [--model {NOK5G21,ARCKVD21,FAST5688W}]
                      [username] [password]

Check T-Mobile Home Internet cellular band(s) and connectivity and reboot if necessary

positional arguments:
  username              the username (most likely "admin")
  password              the administrative password (will be requested at runtime if not passed as argument)

optional arguments:
  -h, --help            show this help message and exit
  --connectivity-check {ping,http}
                        type of connectivity check to perform (defaults to ping)
  -I INTERFACE, --interface INTERFACE
                        the network interface to use for ping. pass the source IP on Windows
  --http-target HTTP_TARGET
                        the URL to perform a http check against (defaults to https://google.com/generate_204)
  --status-code {[100,600)}
                        expected HTTP status code for http connectivity check (defaults to 204)
  -H PING_HOST, --ping-host PING_HOST
                        the host to ping (defaults to google.com)
  --ping-count PING_COUNT
                        how many ping health checks to perform (defaults to 1)
  --ping-interval PING_INTERVAL
                        how long in seconds to wait between ping health checks (defaults to 10)
  -6, --ping-6          use IPv6 ping
  -R, --reboot          skip health checks and immediately reboot gateway
  -r, --skip-reboot     skip rebooting gateway
  --skip-bands          skip check for connected 4g band
  --skip-5g-bands       skip check for connected 5g band
  --skip-connectivity-check, --skip-ping
                        skip connectivity check
  --skip-enbid          skip check for connected eNB ID
  --uptime UPTIME       how long the gateway must be up before considering a reboot (defaults to 90 seconds)
  -4 {B2,B4,B5,B12,B13,B25,B26,B41,B46,B48,B66,B71}, --4g-band {B2,B4,B5,B12,B13,B25,B26,B41,B46,B48,B66,B71}
                        the 4g band(s) to check
  -5 {n41,n71}, --5g-band {n41,n71}
                        the 5g band(s) to check (defaults to n41)
  --enbid ENBID         check for a connection to a given eNB ID
  --print-config        output configuration settings
  --logfile LOGFILE     output file for logging
  --log-all             always write connection details to logfile
  --log-delta           write connection details to logfile on change
  --syslog              log to syslog
  --model {NOK5G21,ARCKVD21,FAST5688W}
                        the gateway model (defaults to NOK5G21)

Options

Gateway Model

Gateway Model: --model

By default, the script will assume the silver-colored Nokia NOK5G21 gateway is being used.

Valid values are NOK5G21 for the Nokia gateway, ARCKVD21 for the square, black-colored Arcadyan gateway without top vent holes, or FAST5688W for the square, black-colored Sagecom gateway with top vent holes.

Connectivity check

Mode: --connectivity-check Defaults to ping. Can instead use a HTTP(S) based health check with the http value. The http health check defaults to checking https://google.com/generate_204 and checking its status code.

Interface: -I --interface Can be used to specify the network interface used by the ping command. Useful if T-Mobile Home Internet is not your default network interface: e.g., this is running on a dual WAN router. On Windows, pass the source IP address to use. http connectivity checks will be dictated by system routing rules.

HTTP check

Target: --http-target Defaults to https://google.com/generate_204 - both http and https targets are supported by the http value of the --connectivity-check flag.

Status Code: --status-code Defaults to 204 for use with https://google.com/generate_204 - in most common use cases, a 200 status code is expected instead. Expects a numeric value between 100-599 (inclusive).

Ping options

ping checks are the default connectivity check in tmo-monitor. It's possible to use HTTP(S)-based checks instead. Refer to the --connectivity-check flag.

Ping Host: -H --ping-host Defaults to google.com - override if you'd like to ping an alternate host to determine internet connectivity. Must specify a host if flag is provided - you can simply omit the flag if you'd like to use the default google.com ping check.

Ping Count: --ping-count Defaults to 1 - override if you'd like to perform multiple ping checks before rebooting. Short-circuits if a successful ping is encountered. Will reboot if all fail.

Ping Interval: --ping-interval Defaults to 10 seconds - override if you'd like to use a different interval.

Ping v6: -6 --ping-6 Use IPv6 ping.

Reboot options

Reboot: -R --reboot Skip health checks and immediately reboot gateway.

Skip Reboot: -r --skip-reboot Skip rebooting gateway.

Skip Bands: --skip-bands Skip check for connected 4g band.

Skip 5g Bands: --skip-5g-bands Skip check for connected 5g band.

Skip Ping: --skip-connectivity-check --skip-ping Skip check for successful connectivity check.

Uptime Threshold: --uptime Defaults to 90 seconds - Specify a required uptime for an implicit reboot to occur. Intended to allow sufficient time to establish a connection and stabilize band selection. Setting is used to avoid boot looping, but is not respected when the --reboot flag is used.

Connection configuration

4G Band Checking: -4 --4g-band Specify a 4G band you expect the gateway to be connected to. Repeat the flag to allow multiple acceptable bands. Case-sensitive.

5G Band Checking: -5 --5g-band Defaults to n41 - Specify a 5G band you expect the gateway to be connected to. Repeat the flag to allow multiple acceptable bands. Case-sensitive.

eNB ID: --enbid Specify the desired cell site you expect the gateway to be connected to. Expects a numeric eNB ID to be provided. cellmapper.net is a helpful resource for finding eNB ID values for nearby cell sites.

General settings

Logfile: --logfile LOGFILE Output file for logging. Defaults to tmo-monitor.log

Log all: --log-all Always write connection details to logfile. Checks all configuration settings.

Log delta: --log-delta Write connection details to logfile on change of any configuration setting or long ping time.

Default settings

Username == admin
Password -> interactive prompt
5G band == n41
Reboot on failure to ping google.com

Environment (`.env`) options

The script is normally run in batch mode, such as scheduled through a cron job. Interactive command-line options are meant to be used as overrides to defaults or environment settings.

A common usage pattern would be to configure the script using a .env file to reboot on 5G band and wifi check. When messing with the settings, a user might want to specify --skip-reboot. When a user knows that the reboot is needed they might specify --reboot for an immediate reboot.

Default settings have the lowest precendence.
Environment settings--whether in the shell environment or a .env file--override the defaults
Command line options have the highest precedence and override both default settings and environment settings

Environment settings are meant to be declarative. They fall into four categories:

Login settings (username, password)
Configuration settings
- Ping settings (target host/interface, number of pings, interval)
- Connection settings (preferred band, eNB ID, etc.)
Reboot settings: request reboot on any number of failed checks.
- Skip reboot overrides all reboot requests
- Reboot interval overrides all reboot requests
- There is no "reboot immediately" option
General settings:
- Default output/silent mode (not yet implemented)
- Logging settings

Exit Status

tmo-monitor uses the following exit status codes:

Clean execution: 0
GENERAL_ERROR: 1
CONFIGURATION_ERROR: 2
API_ERROR: 3
REBOOT_PERFORMED: 4

Roadmap

(Not yet implemented):

Alternate connectivity checks
systemd service configuration

Tip

Run this script with either a cronjob or as a systemd service to implement periodic recurring T-Mobile Home Internet health checks with automatic rebooting.

highvolt-dev / tmo-monitor

readme

tmo-monitor

Getting Started

Install dependencies

Windows

Usage

Command line usage

Options

Gateway Model

Connectivity check

HTTP check

Ping options

Reboot options

Connection configuration

General settings

Default settings

Environment (`.env`) options

Exit Status

Roadmap

Tip

highvolt-dev / tmo-monitor

readme

tmo-monitor

Getting Started

Install dependencies

Windows

Usage

Command line usage

Options

Gateway Model

Connectivity check

HTTP check

Ping options

Reboot options

Connection configuration

General settings

Default settings

Environment (.env) options

Exit Status

Roadmap

Tip

Environment (`.env`) options