pyinternetbox 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. pyinternetbox-0.1.0/.gitignore +128 -0
  2. pyinternetbox-0.1.0/LICENSE +21 -0
  3. pyinternetbox-0.1.0/PKG-INFO +390 -0
  4. pyinternetbox-0.1.0/README.md +359 -0
  5. pyinternetbox-0.1.0/internetbox_client/__init__.py +14 -0
  6. pyinternetbox-0.1.0/internetbox_client/cli.py +296 -0
  7. pyinternetbox-0.1.0/internetbox_client/client.py +85 -0
  8. pyinternetbox-0.1.0/internetbox_client/exporter.py +220 -0
  9. pyinternetbox-0.1.0/internetbox_client/metrics.py +479 -0
  10. pyinternetbox-0.1.0/internetbox_client/resources/__init__.py +73 -0
  11. pyinternetbox-0.1.0/internetbox_client/resources/ap_services.py +26 -0
  12. pyinternetbox-0.1.0/internetbox_client/resources/carddav.py +10 -0
  13. pyinternetbox-0.1.0/internetbox_client/resources/debug.py +15 -0
  14. pyinternetbox-0.1.0/internetbox_client/resources/dect.py +60 -0
  15. pyinternetbox-0.1.0/internetbox_client/resources/devices.py +68 -0
  16. pyinternetbox-0.1.0/internetbox_client/resources/dhcp.py +42 -0
  17. pyinternetbox-0.1.0/internetbox_client/resources/dns.py +35 -0
  18. pyinternetbox-0.1.0/internetbox_client/resources/dyndns.py +20 -0
  19. pyinternetbox-0.1.0/internetbox_client/resources/events.py +182 -0
  20. pyinternetbox-0.1.0/internetbox_client/resources/firewall.py +25 -0
  21. pyinternetbox-0.1.0/internetbox_client/resources/genlog.py +25 -0
  22. pyinternetbox-0.1.0/internetbox_client/resources/history.py +15 -0
  23. pyinternetbox-0.1.0/internetbox_client/resources/http_service.py +10 -0
  24. pyinternetbox-0.1.0/internetbox_client/resources/lan.py +63 -0
  25. pyinternetbox-0.1.0/internetbox_client/resources/led.py +172 -0
  26. pyinternetbox-0.1.0/internetbox_client/resources/mitigation.py +10 -0
  27. pyinternetbox-0.1.0/internetbox_client/resources/mst.py +38 -0
  28. pyinternetbox-0.1.0/internetbox_client/resources/nmc.py +50 -0
  29. pyinternetbox-0.1.0/internetbox_client/resources/oops_tracker.py +15 -0
  30. pyinternetbox-0.1.0/internetbox_client/resources/password_recovery.py +10 -0
  31. pyinternetbox-0.1.0/internetbox_client/resources/phonebook.py +23 -0
  32. pyinternetbox-0.1.0/internetbox_client/resources/power_management.py +10 -0
  33. pyinternetbox-0.1.0/internetbox_client/resources/scheduler.py +14 -0
  34. pyinternetbox-0.1.0/internetbox_client/resources/security.py +20 -0
  35. pyinternetbox-0.1.0/internetbox_client/resources/speedtest.py +52 -0
  36. pyinternetbox-0.1.0/internetbox_client/resources/static.py +15 -0
  37. pyinternetbox-0.1.0/internetbox_client/resources/sysbus.py +70 -0
  38. pyinternetbox-0.1.0/internetbox_client/resources/temperature.py +10 -0
  39. pyinternetbox-0.1.0/internetbox_client/resources/user_management.py +10 -0
  40. pyinternetbox-0.1.0/internetbox_client/resources/voice.py +35 -0
  41. pyinternetbox-0.1.0/internetbox_client/resources/vpn.py +15 -0
  42. pyinternetbox-0.1.0/internetbox_client/resources/webui.py +15 -0
  43. pyinternetbox-0.1.0/internetbox_client/resources/wifi.py +157 -0
  44. pyinternetbox-0.1.0/internetbox_client/resources/wireguard.py +29 -0
  45. pyinternetbox-0.1.0/internetbox_client/resources/wwan.py +25 -0
  46. pyinternetbox-0.1.0/internetbox_client/utils/APIClient.py +223 -0
  47. pyinternetbox-0.1.0/internetbox_client/utils/__init__.py +0 -0
  48. pyinternetbox-0.1.0/internetbox_client/utils/helpers.py +41 -0
  49. pyinternetbox-0.1.0/pyproject.toml +90 -0
  50. pyinternetbox-0.1.0/tests/__init__.py +0 -0
  51. pyinternetbox-0.1.0/tests/conftest.py +35 -0
  52. pyinternetbox-0.1.0/tests/test_api_client.py +234 -0
  53. pyinternetbox-0.1.0/tests/test_e2e.py +846 -0
  54. pyinternetbox-0.1.0/tests/test_exporter.py +87 -0
  55. pyinternetbox-0.1.0/tests/test_helpers.py +29 -0
  56. pyinternetbox-0.1.0/tests/test_internetbox_client.py +45 -0
  57. pyinternetbox-0.1.0/tests/test_resources.py +732 -0
@@ -0,0 +1,128 @@
1
+ # https://raw.githubusercontent.com/github/gitignore/refs/heads/main/Python.gitignore
2
+
3
+ legacy/
4
+ .DS_Store
5
+
6
+ # Byte-compiled / optimized / DLL files
7
+ __pycache__/
8
+ *.py[codz]
9
+ *$py.class
10
+
11
+ # C extensions
12
+ *.so
13
+
14
+ # Distribution / packaging
15
+ .Python
16
+ build/
17
+ develop-eggs/
18
+ dist/
19
+ downloads/
20
+ eggs/
21
+ .eggs/
22
+ lib/
23
+ lib64/
24
+ parts/
25
+ sdist/
26
+ var/
27
+ wheels/
28
+ share/python-wheels/
29
+ *.egg-info/
30
+ .installed.cfg
31
+ *.egg
32
+ MANIFEST
33
+
34
+ # PyInstaller
35
+ *.manifest
36
+ *.spec
37
+
38
+ # Installer logs
39
+ pip-log.txt
40
+ pip-delete-this-directory.txt
41
+
42
+ # Unit test / coverage reports
43
+ htmlcov/
44
+ .tox/
45
+ .nox/
46
+ .coverage
47
+ .coverage.*
48
+ .cache
49
+ nosetests.xml
50
+ coverage.xml
51
+ *.cover
52
+ *.py.cover
53
+ .hypothesis/
54
+ .pytest_cache/
55
+ cover/
56
+
57
+ # PyBuilder
58
+ .pybuilder/
59
+ target/
60
+
61
+ # IPython
62
+ profile_default/
63
+ ipython_config.py
64
+
65
+ # pyenv
66
+ .python-version
67
+
68
+ # pipenv
69
+ Pipfile.lock
70
+
71
+ # poetry
72
+ poetry.lock
73
+ poetry.toml
74
+
75
+ # pdm
76
+ pdm.lock
77
+ pdm.toml
78
+ .pdm-python
79
+ .pdm-build/
80
+
81
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
82
+ __pypackages__/
83
+
84
+ # SageMath parsed files
85
+ *.sage.py
86
+
87
+ # Environments
88
+ .env
89
+ .envrc
90
+ .venv
91
+ env/
92
+ venv/
93
+ ENV/
94
+ env.bak/
95
+ venv.bak/
96
+
97
+ # Spyder project settings
98
+ .spyderproject
99
+ .spyproject
100
+
101
+ # mkdocs documentation
102
+ /site
103
+
104
+ # mypy
105
+ .mypy_cache/
106
+ .dmypy.json
107
+ dmypy.json
108
+
109
+ # Pyre type checker
110
+ .pyre/
111
+
112
+ # pytype static type analyzer
113
+ .pytype/
114
+
115
+ # Cython debug symbols
116
+ cython_debug/
117
+
118
+ # Abstra
119
+ .abstra/
120
+
121
+ # Visual Studio Code
122
+ .vscode/
123
+
124
+ # Ruff stuff:
125
+ .ruff_cache/
126
+
127
+ # PyPI configuration file
128
+ .pypirc
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Timothy Pillow
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,390 @@
1
+ Metadata-Version: 2.5
2
+ Name: pyinternetbox
3
+ Version: 0.1.0
4
+ Summary: Internet Box API client and exporter for Swisscom and Wingo routers.
5
+ Project-URL: Homepage, https://github.com/oregonpillow/pyinternetbox
6
+ Project-URL: Repository, https://github.com/oregonpillow/pyinternetbox
7
+ Project-URL: Issues, https://github.com/oregonpillow/pyinternetbox/issues
8
+ Project-URL: Releases, https://github.com/oregonpillow/pyinternetbox/releases
9
+ Project-URL: Docker image, https://hub.docker.com/r/oregonpillow/pyinternetbox
10
+ Author-email: Timothy Pillow <oregonpillow@gmail.com>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: exporter,internet-box,prometheus,router,swisscom,sysbus,wingo
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: System Administrators
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: System :: Monitoring
25
+ Classifier: Topic :: System :: Networking
26
+ Requires-Python: >=3.12
27
+ Requires-Dist: prometheus-client>=0.14.0
28
+ Requires-Dist: requests>=2.33.0
29
+ Requires-Dist: typer>=0.24.1
30
+ Description-Content-Type: text/markdown
31
+
32
+ <div align="center">
33
+ <img src="https://raw.githubusercontent.com/oregonpillow/pyinternetbox/master/docs/logo.svg" width="400px" alt="Grafana Dashboard" />
34
+ <h1 style="font-size: 28px; margin: 10px 0;">pyinternetbox</h1>
35
+ <p>Python library and CLI tool (with built in exporter) for Swisscom / Wingo Internet Box routers.</p>
36
+ </div>
37
+ <br>
38
+
39
+ ## 📚 Table of Contents
40
+
41
+ <!-- START doctoc generated TOC please keep comment here to allow auto update -->
42
+ <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
43
+ <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
44
+
45
+ - [🚀 Getting Started](#-getting-started)
46
+ - [Installation](#installation)
47
+ - [CLI usage](#cli-usage)
48
+ - [Library usage](#library-usage)
49
+ - [📡 Running the Exporter](#-running-the-exporter)
50
+ - [Traffic metrics: which one to use](#traffic-metrics-which-one-to-use)
51
+ - [Environment Variables](#environment-variables)
52
+ - [Usage without authentication](#usage-without-authentication)
53
+ - [🧑‍💻 Development](#-development)
54
+ - [How to contribute](#how-to-contribute)
55
+ - [Creating more complex methods](#creating-more-complex-methods)
56
+ - [Supported Internet Box Models](#supported-internet-box-models)
57
+ - [Model Information](#model-information)
58
+ - [Development Requirements](#development-requirements)
59
+ - [🪝 Pre-commit Hooks](#-pre-commit-hooks)
60
+ - [🏷️ Releasing](#-releasing)
61
+ - [🧪 Tests](#-tests)
62
+ - [End-to-End (E2E) Tests](#end-to-end-e2e-tests)
63
+ - [Related Projects](#related-projects)
64
+ - [Disclaimer](#disclaimer)
65
+
66
+ <!-- END doctoc generated TOC please keep comment here to allow auto update -->
67
+
68
+ ## 🚀 Getting Started
69
+
70
+ ### Installation
71
+
72
+ **from PyPI**:
73
+
74
+ ```sh
75
+ pip install pyinternetbox # library + `ibox` CLI
76
+ uv tool install pyinternetbox # or: just the `ibox` CLI, in its own environment
77
+ ```
78
+
79
+ **with Docker** (runs the exporter):
80
+
81
+ ```sh
82
+ docker run -d -p 9101:9101 -e IB_PASSWORD=secret oregonpillow/pyinternetbox:latest
83
+ ```
84
+
85
+ **from source** (for development) **with uv**:
86
+
87
+ ```sh
88
+ uv sync
89
+ ```
90
+
91
+ **from source with pip**:
92
+
93
+ ```sh
94
+ python3 -m venv .venv
95
+ source .venv/bin/activate
96
+ pip install -e .
97
+ ```
98
+
99
+ ### CLI usage
100
+
101
+ **with uv** (from source)
102
+
103
+ ```sh
104
+ uv run ibox --help
105
+ ```
106
+
107
+ **with pip / uv tool**:
108
+
109
+ ```sh
110
+ ibox --help
111
+ ibox --version
112
+ ```
113
+
114
+ The CLI outputs pretty JSON but can still be piped to popular tools like `jq`.
115
+
116
+ ### Library usage
117
+
118
+ ```python
119
+ from internetbox_client import InternetBoxClient
120
+
121
+ with InternetBoxClient() as ibox:
122
+ print(ibox.nmc.status()) # no auth required
123
+ print(ibox.wifi.status()) # no auth required
124
+ print(ibox.devices.topology()) # auth required
125
+ print(ibox.vpn.status()) # auth required
126
+ ```
127
+
128
+ ## 📡 Running the Exporter
129
+
130
+ The exporter exposes router metrics in [Prometheus](https://prometheus.io/) format on port `9101`.
131
+ Only a sample of metrics are currently implemented - contributions are welcome!
132
+
133
+ **with uv / pip**:
134
+
135
+ ```sh
136
+ ibox export
137
+ ```
138
+
139
+ **with Docker Compose**:
140
+
141
+ Set environment variables in `docker-compose.yml`, then:
142
+
143
+ ```sh
144
+ docker compose up -d
145
+ ```
146
+
147
+ Images are published to Docker Hub as [`oregonpillow/pyinternetbox`](https://hub.docker.com/r/oregonpillow/pyinternetbox):
148
+
149
+ | **Tag** | **Contents** |
150
+ | -------------- | ------------------------------------------------ |
151
+ | `latest` | Most recent release |
152
+ | `X.Y.Z`, `X.Y` | A specific release / the latest patch of a minor |
153
+ | `edge` | Latest commit on `master` (may be unstable) |
154
+
155
+ Metrics will be available at `http://localhost:9101/metrics`.
156
+
157
+ example Prometheus config:
158
+
159
+ ```yaml
160
+ scrape_configs:
161
+ - job_name: "pyinternetbox"
162
+ scrape_interval: 30s
163
+ metrics_path: /metrics
164
+ static_configs:
165
+ - targets: ["localhost:9101"]
166
+ ```
167
+
168
+ ### Traffic metrics: which one to use
169
+
170
+ The router exposes several traffic figures that look similar but measure different things. `rx`/`tx` are always from the
171
+ **router's point of view**: `rx` is what the router _received_ on that interface, `tx` is what it _sent_.
172
+
173
+ | Metric | Interface | What it counts | `rx` means | `tx` means | Type | Includes wired devices | Includes traffic between home devices |
174
+ | ----------------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------ | ------------------------------------- | ----------------------- | ------------------------------------- |
175
+ | `internetbox_wan_rx_bytes_total` / `internetbox_wan_tx_bytes_total` | `veip0` (XGS-PON fibre, WAN) | All traffic between your home and the internet, from every device | **Downloaded** from the internet | **Uploaded** to the internet | Counter (bytes since router boot) | ✅ | ❌ |
176
+ | `internetbox_wifi_rx_bytes_total` / `internetbox_wifi_tx_bytes_total` | `wl0` (5 GHz), `wl1` (2.4 GHz) | All traffic over each Wi-Fi radio, to the internet _and_ to other devices at home | Sent **by Wi-Fi devices** (their upload) | Sent **to Wi-Fi devices** (their download) | Counter (bytes since router boot) | ❌ | ✅ (Wi-Fi devices only) |
177
+ | `internetbox_device_rx_bandwidth_last{day,week,month}_bytes` / `…_tx_…` | Per device (router device list) | The router's own per-device usage over a **rolling** window (last 24 h / 7 d / 30 d), recalculated about hourly | Received from the device | Sent to the device | Gauge (rolling total, goes up & down) | ❌ (Wi-Fi devices only) | ❓ not verified |
178
+ | `internetbox_veip_downstream_curr_rate_kbps` / `internetbox_veip_upstream_curr_rate_kbps` | `veip0` (XGS-PON fibre, WAN) | The **link speed** the fibre connection is synced at (capacity), not traffic. Constant unless the link resyncs | – | – | Gauge (kbps) | – | – |
179
+
180
+ Notes:
181
+
182
+ - **"How much did I download today?"** → `increase(internetbox_wan_rx_bytes_total[<seconds since midnight>s])`.
183
+ - **"How fast am I downloading right now?"** → `rate(internetbox_wan_rx_bytes_total[5m]) * 8` (bits per second). The
184
+ `veip_*_curr_rate_kbps` metrics stay at the line speed (e.g. ~10 Gbit/s) no matter how much you download.
185
+ - **Wired traffic between home devices is not measured anywhere**: it is switched by the router's Ethernet switch and
186
+ never counted, and per-port Ethernet counters (`eth0`-`eth4`) are not accessible with the `admin` user (HTTP 401).
187
+ - The router's `bridge` interface is **not** exported: it only sees traffic routed through the router (i.e. internet
188
+ traffic, counted again from the LAN side with `rx`/`tx` swapped), so it duplicates the WAN counters.
189
+ - Counters restart from zero when the Internet Box reboots; Prometheus' `rate()` and `increase()` handle this.
190
+ - The per-device rolling totals are only reported for Wi-Fi devices. The direction of their `rx`/`tx` follows the
191
+ router's naming and has not been independently verified.
192
+
193
+ Dashboards can be found in the Grafana folder.
194
+
195
+ <p align="center">
196
+ <img src="https://raw.githubusercontent.com/oregonpillow/pyinternetbox/master/grafana/internetbox4.jpg" alt="Grafana Dashboard" width="49%"/>
197
+ <img src="https://raw.githubusercontent.com/oregonpillow/pyinternetbox/master/grafana/internetbox4_2.jpg" alt="Grafana Traffic Dashboard" width="49%"/>
198
+ </p>
199
+
200
+ ## Environment Variables
201
+
202
+ | **Variable** | **Description** | **Required** |
203
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
204
+ | `IB_HOSTNAME` | Hostname or IP address of the Internet Box router, e.g. `192.168.1.1` or `https://192.168.1.1`. `http://` is upgraded to `https://`. Defaults to `https://internetbox.swisscom.ch`. | No |
205
+ | `IB_USERNAME` | Username for router authentication. Defaults to `admin`. | No |
206
+ | `IB_PASSWORD` | Password for router authentication. Defaults to an empty string. Without a password many of the client methods will not work. See below for complete list of methods that don't require authentication. | No |
207
+ | `IB_EXPORTER_PORT` | TCP port the Prometheus `/metrics` endpoint listens on. Defaults to `9101`. | No |
208
+ | `IB_EXPORTER_INTERVAL` | Seconds between data collection cycles when running the exporter. Defaults to `30`. | No |
209
+ | `IB_SSL_VERIFY` | `true` / `false` to force SSL certificate verification on or off (CLI: `--insecure` / `-k`). When unset, verification is on for hostnames and automatically off for IP addresses, since the router's certificate is only valid for `internetbox.swisscom.ch`. | No |
210
+
211
+ ## Usage without authentication
212
+
213
+ A limited selection of methods are available without authentication, which means they can be used even if you don't have the password to your router.
214
+
215
+ | **Method** | **API** | **CLI** |
216
+ | ----------------------- | --------------------------------- | ------------------------------- |
217
+ | Devices.info | `ibox.devices.info()` | `ibox devices info` |
218
+ | DNS.status | `ibox.dns.status()` | `ibox dns status` |
219
+ | Mitigation.status | `ibox.mitigation.status()` | `ibox mitigation status` |
220
+ | NMC.status | `ibox.nmc.status()` | `ibox nmc status` |
221
+ | NMC.ip_conflicts | `ibox.nmc.ip_conflicts()` | `ibox nmc ip-conflicts` |
222
+ | NMC.wan_status | `ibox.nmc.wan_status()` | `ibox nmc wan-status` |
223
+ | NMC.orientation | `ibox.nmc.orientation()` | `ibox nmc orientation` |
224
+ | PasswordRecovery.status | `ibox.password_recovery.status()` | `ibox password-recovery status` |
225
+ | Static.settings | `ibox.static.settings()` | `ibox static settings` |
226
+ | Static.translations | `ibox.static.translations()` | `ibox static translations` |
227
+ | Sysbus.gpios | `ibox.sysbus.gpios()` | `ibox sysbus gpios` |
228
+ | Sysbus.mibs | `ibox.sysbus.mibs()` | `ibox sysbus mibs` |
229
+ | Sysbus.veip | `ibox.sysbus.veip()` | `ibox sysbus veip` |
230
+ | Sysbus.veip_mibs | `ibox.sysbus.veip_mibs()` | `ibox sysbus veip-mibs` |
231
+ | Sysbus.net_dev_stats | `ibox.sysbus.net_dev_stats()` | `ibox sysbus net-dev-stats` |
232
+ | Voice.status | `ibox.voice.status()` | `ibox voice status` |
233
+ | Voice.trunks | `ibox.voice.trunks()` | `ibox voice trunks` |
234
+ | Wifi.status | `ibox.wifi.status()` | `ibox wifi status` |
235
+ | WWAN.status | `ibox.wwan.status()` | `ibox wwan status` |
236
+ | WWAN.mibs | `ibox.wwan.mibs()` | `ibox wwan mibs` |
237
+
238
+ \*Methods that do not require authentication have the following parameter set within their respective method: `auth_required=False`. Search for this in codebase if you need to identify them.
239
+
240
+ ## 🧑‍💻 Development
241
+
242
+ So far the project is in early stages and I'm the only contributor, but I welcome contributions from the community! If you want to contribute, please fork the repository and create a pull request with your changes. At the moment I've only tested with an IB4 box, if you have a different box any testing you can provide would be greatly appreciaited! :)
243
+
244
+ ### How to contribute
245
+
246
+ - Read the [MISSING_ENDPOINTS](https://github.com/oregonpillow/pyinternetbox/blob/master/docs/MISSING_ENDPOINTS.md) doc if you want to work on implementing missing endpoints that might work from the [LiveboxMonitor](https://github.com/p-dor/LiveboxMonitor)
247
+ - Try creating more complex methods, see below for more details
248
+ - Take a stab at implementing any bugs or features raised in the issues
249
+ - Test the library with different Swisscom/Wingo Internet Box models and report any issues you find - testers are much appreciaited!!
250
+ - Contribute more dashboards :)
251
+ - Add missing metrics in the exporter: only a subset of methods in this client are currently implemented
252
+ - Improve the pipeline
253
+ - Buy me a coffee ☕️ ;)
254
+
255
+ ### Creating more complex methods
256
+
257
+ When logged into the web interface, within developer tools you can see the REST-API logic within the js scripts.
258
+
259
+ Pretty much all the REST-API logic is contained within these. These scripts could be parsed to find missing endpoints and provide a template for how to interact and combine calls for more powerful dynamic methods.
260
+
261
+ The scripts likely differ based on the Web portal version.
262
+ The `Web portal version` can be found in the web gui: `Diagnostics > Internet-Box`.
263
+
264
+ To view the js scripts:
265
+
266
+ > 1. Open your Internet Box web interface (e.g. `https://internetbox.swisscom.ch`) and log in
267
+ > 2. Open your browser's Developer Tools (F12) → **Network** tab
268
+ > 3. Reload the page and filter by JS — download `app.min.js` and `core.min.js`
269
+
270
+ ### Supported Internet Box Models
271
+
272
+ | **Model** | **Tested** | **Notes** |
273
+ | ------------------ | ---------- | ----------------------------- |
274
+ | Internet Box 2 | No | Expected to work partially |
275
+ | Internet Box 3 | No | Expected to work partially |
276
+ | Internet Box 4 | ✅ | Tested and confirmed to work. |
277
+ | Internet Box 5 | No | Expected to work |
278
+ | Internet Box 5 Pro | No | Expected to work |
279
+
280
+ ### Model Information
281
+
282
+ | **Model** | **Manufacturer** | **Model Name** | **OUI Number** |
283
+ | -------------- | ---------------- | -------------- | -------------- |
284
+ | Internet Box 4 | Arcadyan | IB4-00 | 1883BF |
285
+
286
+ To check your model run `ibox devices info`. Submit a PR if you have a model not listed here.
287
+
288
+ ### Development Requirements
289
+
290
+ In order to run tests and pre-commit hooks you need to have the development dependencies installed.
291
+
292
+ In addition to UV, you will need [prettier](https://prettier.io/) and [doctoc](https://github.com/thlorenz/doctoc) to run pre-commit hooks. You can install npx with [npm](https://nodejs.org/en/download/) and then use npx to install the tools:
293
+
294
+ ```sh
295
+ npm install -g npx
296
+ npx install -g doctoc
297
+ npx install -g prettier
298
+ ```
299
+
300
+ Clone the repo and install all dependencies including dev tools:
301
+
302
+ ```sh
303
+ uv sync
304
+ ```
305
+
306
+ ### 🪝 Pre-commit Hooks
307
+
308
+ This project uses pre-commit hooks. To set it up:
309
+
310
+ - `uv tool install pre-commit --with pre-commit-uv`
311
+ - `uvx pre-commit install`
312
+ - test by running all hooks: `uvx pre-commit run -a`
313
+
314
+ ### 🏷️ Releasing
315
+
316
+ The version is defined **only by the git tag** — there is no version number to edit in any file.
317
+ [hatch-vcs](https://github.com/ofek/hatch-vcs) derives it at build time, and it flows into the PyPI package, `ibox --version`, the Docker image tags and the exporter's startup line.
318
+
319
+ ```sh
320
+ git checkout master && git pull
321
+ git tag v0.2.0
322
+ git push origin v0.2.0
323
+ ```
324
+
325
+ Pushing the tag runs [`release.yml`](https://github.com/oregonpillow/pyinternetbox/blob/master/.github/workflows/release.yml), which runs the tests and then:
326
+
327
+ - publishes `pyinternetbox==0.2.0` to PyPI
328
+ - pushes `oregonpillow/pyinternetbox:0.2.0`, `:0.2` and `:latest` to Docker Hub
329
+ - creates a GitHub Release with auto-generated notes and the built packages
330
+
331
+ Every push to `master` also publishes `oregonpillow/pyinternetbox:edge`. Untagged builds get a development version such as `0.2.1.dev3+g1a2b3c4`.
332
+
333
+ **Choosing the version** ([semver](https://semver.org/)): bump `PATCH` for bug fixes, `MINOR` for new endpoints/metrics/options, `MAJOR` for breaking changes. Use plain `vMAJOR.MINOR.PATCH` tags (no `-rc1` style suffixes). To see the version the current commit would get: `uv run ibox --version`.
334
+
335
+ **If a release fails** before anything is published (e.g. tests fail), fix the problem on `master`, then move the tag:
336
+
337
+ ```sh
338
+ git tag -d v0.2.0 && git push origin :refs/tags/v0.2.0
339
+ git tag v0.2.0 && git push origin v0.2.0
340
+ ```
341
+
342
+ PyPI never accepts the same version twice, so if the package was already uploaded, release a new patch version (`v0.2.1`) instead.
343
+
344
+ **One-time setup** (already done for this repo, kept here for reference):
345
+
346
+ - GitHub → Settings → Secrets and variables → Actions: `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` (a Docker Hub personal access token with _Read & Write_ access).
347
+ - pypi.org → Account → Publishing: trusted publisher for owner `oregonpillow`, repository `pyinternetbox`, workflow `release.yml`, environment `pypi`.
348
+
349
+ ## 🧪 Tests
350
+
351
+ | **Test** | **Description** | **Check** | **Fix** |
352
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------- |
353
+ | **Unit Tests** | Run unit tests | `uv run pytest` | N/A |
354
+ | **End-to-End** | Makes real HTTP requests to your router and verifies every endpoint returns a valid HTTP response code. Excluded from the default test run. Requires `IB_PASSWORD` to be set (see [Environment Variables](#environment-variables)). Read-only and destructive tests can be run separately (see below). | `uv run pytest tests/test_e2e.py -v` | N/A |
355
+ | **Coverage** | Check test coverage | `uv run pytest --cov` | N/A |
356
+ | **Linting** | Check code for linting issues | `uv run ruff check .` | `uv run ruff check --fix .` |
357
+ | **Formatting** | Check code formatting | `uv run ruff format --check .` | `uv run ruff format .` |
358
+ | **isort** | Check import sorting consistency | `ruff check --select I .` | `ruff check --select I --fix .` |
359
+ | **deptry** | Checks unused or missing dependencies | `uv run deptry .` | N/A |
360
+ | **prettier** | Check markdown formatting | `npx prettier --check .` | `npx prettier --write .` |
361
+ | **doctoc** | Auto-generate table of contents in markdown | `npx doctoc README.md` | `npx doctoc README.md` |
362
+
363
+ ### End-to-End (E2E) Tests
364
+
365
+ ⚠️ Use the E2E tests with caution especially if you have a production router (any router where downtime could expose you to the wrath of your partner or roommates).
366
+
367
+ The tests are designed to be safe but they do make real HTTP requests to your router and some of the tests are destructive (they change a setting on the router and then attempt to change it back). If you want to be extra cautious you can run only the read-only tests which shouldn't make any changes to the router.
368
+
369
+ ```sh
370
+ # 🔬 Read-only — should be safe for any environment (default when running e2e)
371
+ uv run pytest tests/test_e2e.py -m "not destructive" -v
372
+
373
+ # 💥 All tests including destructive (writes to the router, then reverts)
374
+ uv run pytest tests/test_e2e.py -v
375
+
376
+ # 💥 Only destructive tests
377
+ uv run pytest tests/test_e2e.py -m destructive -v
378
+ ```
379
+
380
+ Destructive tests write to the router but always revert the original value immediately after (LED brightness, Wi-Fi TX power, MST rules).
381
+
382
+ ## Related Projects
383
+
384
+ - [LiveboxMonitor](https://github.com/p-dor/LiveboxMonitor)
385
+ - [sysbus](https://github.com/rene-d/sysbus)
386
+ - [internetbox2-exporter](https://github.com/simonkrenger/internetbox2-exporter)
387
+
388
+ ## Disclaimer
389
+
390
+ While I work at Swisscom, this project is a personal endeavor and is not affiliated with or endorsed by Swisscom. The information provided in this project is based on my own research and experience from observing the REST-API calls the router makes when you login using developer tools in your browser. Use at your own risk. I don't work with the Internet Box team or have any affiliation with them.