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.
- pyinternetbox-0.1.0/.gitignore +128 -0
- pyinternetbox-0.1.0/LICENSE +21 -0
- pyinternetbox-0.1.0/PKG-INFO +390 -0
- pyinternetbox-0.1.0/README.md +359 -0
- pyinternetbox-0.1.0/internetbox_client/__init__.py +14 -0
- pyinternetbox-0.1.0/internetbox_client/cli.py +296 -0
- pyinternetbox-0.1.0/internetbox_client/client.py +85 -0
- pyinternetbox-0.1.0/internetbox_client/exporter.py +220 -0
- pyinternetbox-0.1.0/internetbox_client/metrics.py +479 -0
- pyinternetbox-0.1.0/internetbox_client/resources/__init__.py +73 -0
- pyinternetbox-0.1.0/internetbox_client/resources/ap_services.py +26 -0
- pyinternetbox-0.1.0/internetbox_client/resources/carddav.py +10 -0
- pyinternetbox-0.1.0/internetbox_client/resources/debug.py +15 -0
- pyinternetbox-0.1.0/internetbox_client/resources/dect.py +60 -0
- pyinternetbox-0.1.0/internetbox_client/resources/devices.py +68 -0
- pyinternetbox-0.1.0/internetbox_client/resources/dhcp.py +42 -0
- pyinternetbox-0.1.0/internetbox_client/resources/dns.py +35 -0
- pyinternetbox-0.1.0/internetbox_client/resources/dyndns.py +20 -0
- pyinternetbox-0.1.0/internetbox_client/resources/events.py +182 -0
- pyinternetbox-0.1.0/internetbox_client/resources/firewall.py +25 -0
- pyinternetbox-0.1.0/internetbox_client/resources/genlog.py +25 -0
- pyinternetbox-0.1.0/internetbox_client/resources/history.py +15 -0
- pyinternetbox-0.1.0/internetbox_client/resources/http_service.py +10 -0
- pyinternetbox-0.1.0/internetbox_client/resources/lan.py +63 -0
- pyinternetbox-0.1.0/internetbox_client/resources/led.py +172 -0
- pyinternetbox-0.1.0/internetbox_client/resources/mitigation.py +10 -0
- pyinternetbox-0.1.0/internetbox_client/resources/mst.py +38 -0
- pyinternetbox-0.1.0/internetbox_client/resources/nmc.py +50 -0
- pyinternetbox-0.1.0/internetbox_client/resources/oops_tracker.py +15 -0
- pyinternetbox-0.1.0/internetbox_client/resources/password_recovery.py +10 -0
- pyinternetbox-0.1.0/internetbox_client/resources/phonebook.py +23 -0
- pyinternetbox-0.1.0/internetbox_client/resources/power_management.py +10 -0
- pyinternetbox-0.1.0/internetbox_client/resources/scheduler.py +14 -0
- pyinternetbox-0.1.0/internetbox_client/resources/security.py +20 -0
- pyinternetbox-0.1.0/internetbox_client/resources/speedtest.py +52 -0
- pyinternetbox-0.1.0/internetbox_client/resources/static.py +15 -0
- pyinternetbox-0.1.0/internetbox_client/resources/sysbus.py +70 -0
- pyinternetbox-0.1.0/internetbox_client/resources/temperature.py +10 -0
- pyinternetbox-0.1.0/internetbox_client/resources/user_management.py +10 -0
- pyinternetbox-0.1.0/internetbox_client/resources/voice.py +35 -0
- pyinternetbox-0.1.0/internetbox_client/resources/vpn.py +15 -0
- pyinternetbox-0.1.0/internetbox_client/resources/webui.py +15 -0
- pyinternetbox-0.1.0/internetbox_client/resources/wifi.py +157 -0
- pyinternetbox-0.1.0/internetbox_client/resources/wireguard.py +29 -0
- pyinternetbox-0.1.0/internetbox_client/resources/wwan.py +25 -0
- pyinternetbox-0.1.0/internetbox_client/utils/APIClient.py +223 -0
- pyinternetbox-0.1.0/internetbox_client/utils/__init__.py +0 -0
- pyinternetbox-0.1.0/internetbox_client/utils/helpers.py +41 -0
- pyinternetbox-0.1.0/pyproject.toml +90 -0
- pyinternetbox-0.1.0/tests/__init__.py +0 -0
- pyinternetbox-0.1.0/tests/conftest.py +35 -0
- pyinternetbox-0.1.0/tests/test_api_client.py +234 -0
- pyinternetbox-0.1.0/tests/test_e2e.py +846 -0
- pyinternetbox-0.1.0/tests/test_exporter.py +87 -0
- pyinternetbox-0.1.0/tests/test_helpers.py +29 -0
- pyinternetbox-0.1.0/tests/test_internetbox_client.py +45 -0
- 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.
|