joaovorocha/tmobile-g4ar-local-api

# T-Mobile TMO-G4AR 本地 API (Python) 一个轻量级、无依赖的 Python 客户端，用于 **T-Mobile TMO-G4AR** (Arcadyan) 5G 家庭/网关路由器的**本地 REST API**。直接从局域网内的网关 获取信号统计数据、已连接客户端列表、服务小区 ID、SIM 信息和固件版本—— 以及读写 WiFi SSID 配置， 无需云账号。 针对 **固件 1.00.18** 进行了逆向工程。仅使用标准库 (Python 3.9+)。 ## 相关项目 如果你需要**图形界面**，请使用 Zachary Wander 开发的 [**HINTControl**](https://github.com/zacharee/HINTControl) —— 一款精美的跨平台应用 (Android/iOS/桌面端)，可通过 相同的 `/TMI/v1/` API 控制 TMO-G4AR 以及其他几款 T-Mobile 家庭互联网网关。本项目则采取了相反的取舍：**没有图形界面**，仅提供一个小巧的、可脚本化的 Python 客户端 + CLI，适用于自动化、仪表盘、Home Assistant、 cron 任务和无头服务器。此处的 reboot endpoint 已根据 HINTControl 的 endpoint 映射进行了确认。 ## 快速开始 ``` cp .env.example .env # 编辑 .env 并设置 TMOBILE_ROUTER_PASSWORD（它在设备贴纸上） python3 cli.py signal python3 cli.py clients python3 cli.py cell ``` 或者将其作为库使用： ``` from tmobile_api import TMobileAPI api = TMobileAPI() print(api.fetch_gateway(get="signal")) # 4G/5G signal + bars print(api.fetch_clients_detail()) # connected devices, per band print(api.fetch_telemetry(get="cell")) # serving cell IDs ``` ## API Base：`http://192.168.12.1`（你网关的管理 IP）。所有内容均位于 `/TMI/v1/` 下。 **认证：** 发送 `POST /TMI/v1/auth/login` 并附带 `{"username": "admin", "password": ""}`， 将返回一个有效期约为 15 分钟的 JWT bearer token。客户端会自动缓存并刷新它， 并在遇到 `401` 时重试一次。 | Endpoint | 获取内容 | |---|---| | `gateway?get=all` / `?get=signal` | 设备信息、4G/5G 信号、运行时间 | | `network/telemetry?get=clients` | **真实的客户端列表**（见下方的坑点） | | `network/telemetry?get=cell` | 正在服务的 4G + 5G 小区 ID | | `network/telemetry?get=sim` | ICCID / SIM 状态 | | `network/configuration/v2?get=ap` / `?set=ap` | WiFi SSID 配置 | | `version` | 固件 / 软件版本 | | `gateway/reset?set=reboot` (POST) | 重启网关 (`reboot_gateway()`) | ## 响应示例 以下数值为**说明性**示例（编造/已脱敏）；字段*名称*和 结构均与固件 1.00.18 一致。 `python3 cli.py signal` → `gateway?get=signal`: ``` { "signal": { "4g": {"bars": 4, "bands": ["b2"], "cid": 12, "eNBID": 100000, "pci": 350, "rsrp": -92, "rsrq": -10, "rssi": -64, "sinr": 9}, "5g": {"bars": 3, "bands": ["n41"], "cid": 7, "gNBID": 1234567, "pci": 588, "rsrp": -97, "rsrq": -11, "rssi": -68, "sinr": 6}, "generic": {"apn": "FBB.HOME", "hasIPv6": true, "registration": "registered", "roaming": false} } } ``` `python3 cli.py clients` → `network/telemetry?get=clients`（注意双重嵌套的 `clients.clients`，并且有线设备的 `signal: null`）： ``` { "clients": { "clients": { "2.4ghz": [ {"connected": true, "name": "thermostat", "ipv4": "192.168.12.150", "ipv6": [], "mac": "AA:BB:CC:11:22:33", "signal": -58} ], "5.0ghz": [ {"connected": true, "name": "laptop", "ipv4": "192.168.12.142", "ipv6": [], "mac": "AA:BB:CC:44:55:66", "signal": -47} ], "ethernet": [ {"connected": true, "name": "nas", "ipv4": "192.168.12.101", "ipv6": [], "mac": "AA:BB:CC:77:88:99", "signal": null} ] } } } ``` ## 来之不易的坑点（固件 1.00.18） 弄清楚这些问题花费了大量时间——这也是创建此仓库的原因。 - **直接请求 endpoint 会报 400 错误。** 你必须传递一个查询参数，例如 `gateway?get=all`。单独的 `/TMI/v1/gateway` 会返回 `400 "No query specified"`。 - **`/network/clients` 总是返回 `{"clients": []}`**，无论连接了多少 设备。**真实的**列表位于 **`/network/telemetry?get=clients`** → `clients.{2.4ghz,5.0ghz,ethernet}` 数组，包含 `{name, ipv4, ipv6, mac, signal(dBm), connected}`。 - **WiFi 信道不可设置——仅支持自动信道。** 管理 Web UI 完全没有 信道控制功能，`get=ap` 报告 `channel: "Auto"`（这是一种模式，永远不是 数字），并且在手动指定信道时 `set=ap` 会返回 **400** 错误。你无法通过此网关解决 信道拥堵问题。 - **`set=ap` 仅能编辑 SSID 字段：** `ssidName`、`wpaKey`（在 `get=ap` 中为明文）、`isBroadcastEnabled`、`encryptionMode`、`guest`。为了安全写入： 请先读取完整的 `get=ap` 对象，修改其中一个字段，将其 POST 回去，然后再读取 以进行验证，如果不匹配则回滚。（`update_wifi_config()` 是 原始的 POST 操作——读取/验证/回滚的循环需要你自己实现。） - **没有邻区信息。** `telemetry?get=cell` 仅返回*正在服务的* 4G + 5G 小区（gNBID/PCI/TAC/ARFCN/ECGI/CID/RSRP/SINR/bars），从不返回邻区列表—— 因此仅凭此网关无法进行基站三角定位。SIM 的 `imsi` 包含 MCC/MNC（例如 T-Mobile US 的 `310/260`）。 - 此固件中**不存在 DHCP / 防火墙 / 端口转发**控制功能。 - 发生错误时，`request_json` 会抛出 `http_:`，以便你可以读取 网关自身的提示信息，而无需盲目猜测。 ## 安全提示 - 凭据从环境变量 / 本地 `.env` 文件中读取——没有任何内容被 硬编码。**切勿提交你的 `.env` 文件。** - 此代码仅与你局域网内的网关通信。它不会向任何地方发送遥测数据。 - 敏感标识符（IMEI/IMSI/MSISDN/ICCID）会由网关在 `sim` endpoint 上返回——在记录日志或发布之前请务必小心。 ## 许可证 [MIT](LICENSE)。与 T-Mobile 或 Arcadyan 无关，也未获得其认可。 "TMO-G4AR" 和 "T-Mobile" 是其各自所有者的商标；此处使用它们仅是为了 标识本代码所通信的硬件。