Skip to content

Commit 7853ee9

Browse files
author
Dennis Braun
committed
Slim down README: move details to wiki
Reduced from 314 to 124 lines. Glossary, reference values, configuration, Home Assistant details, full roadmap, and modem support guide moved to wiki. README now serves as elevator pitch with feature table linking to wiki pages.
1 parent 57cfb84 commit 7853ee9

File tree

1 file changed

+36
-190
lines changed

1 file changed

+36
-190
lines changed

‎README.md‎

Lines changed: 36 additions & 190 deletions
Original file line numberDiff line numberDiff line change
@@ -26,30 +26,13 @@
2626

2727
---
2828

29-
## How It Works
30-
31-
**Step 1: Install** — Run one command to start DOCSight on your computer or NAS:
29+
## Quick Start
3230

3331
```bash
3432
docker run -d --name docsight -p 8765:8765 -v docsight_data:/data ghcr.io/itsdnns/docsight:latest
3533
```
3634

37-
> New to Docker? See the **[Installation Guide](INSTALL.md)** for step-by-step instructions (Windows, Mac, Linux, Synology NAS).
38-
39-
**Step 2: Connect your router** — Open `http://localhost:8765` in your browser. The setup wizard asks for your router login — that's it. Takes 2 minutes.
40-
41-
**Step 3: Sit back** — DOCSight monitors your connection around the clock. When something is wrong, you'll see it immediately — and you can generate a complaint letter backed by real data.
42-
43-
---
44-
45-
## Your Data Stays With You
46-
47-
| | |
48-
|---|---|
49-
| **Runs 100% locally** | No cloud, no external servers. DOCSight runs entirely on your own hardware. |
50-
| **Nothing leaves your network** | Your data is never uploaded anywhere. Everything stays on your machine. |
51-
| **Open source** | All code is public. Anyone can read it and verify exactly what it does. |
52-
| **Credentials encrypted** | Your router login is encrypted at rest (AES-128) and never stored in plain text. |
35+
Open `http://localhost:8765`, enter your router login, done. [Full installation guide →](https://github.com/itsDNNS/docsight/wiki/Installation)
5336

5437
---
5538

@@ -61,103 +44,42 @@ docker run -d --name docsight -p 8765:8765 -v docsight_data:/data ghcr.io/itsdnn
6144
| ✅ Your internet **drops out or is slower** than what you're paying for | DOCSight documents it |
6245
| ✅ Your ISP says **"everything is fine on our end"** | DOCSight gives you proof |
6346
| ❌ You have **DSL or fiber** | This tool won't work for you |
64-
| ✅ Your internet **works fine right now** | DOCSight builds a history — if problems start later, you already have proof of what "normal" looked like |
6547

6648
---
6749

68-
## Glossary — What Do These Numbers Mean?
69-
70-
The DOCSight dashboard shows technical measurements from your cable modem. Here's what they mean in plain language:
50+
## Your Data Stays With You
7151

72-
| Term | What it means |
52+
| | |
7353
|---|---|
74-
| **DOCSIS** | The technology that makes cable internet work. Your internet signal travels through the same coaxial cable as TV. |
75-
| **Downstream / Upstream** | Downstream = download direction (Netflix, browsing). Upstream = upload direction (video calls, sending files). |
76-
| **SNR (Signal-to-Noise Ratio)** | How clear your signal is. Think of it like radio reception — high SNR means a clear signal, low SNR means static and interference. Measured in dB. |
77-
| **Power Level** | How strong your signal is. Too weak or too strong and your internet suffers. Measured in dBmV. |
78-
| **Uncorrectable Errors** | Data packets that were lost and couldn't be recovered. A few are normal, but many of these cause buffering, dropouts, and slow speeds. |
79-
| **Correctable Errors** | Data packets that arrived damaged but were automatically repaired. Lots of these are a warning sign. |
80-
| **QAM / Modulation** | How much data is packed into each signal. Higher QAM (like 256QAM or 4096QAM) means more speed. If your modem drops to a lower QAM, something is wrong with the signal. |
81-
| **Channels** | Your cable connection uses many frequencies at once (like lanes on a highway). Each lane is a "channel." More healthy channels = more bandwidth. |
54+
| 🏠 **Runs 100% locally** | No cloud, no external servers |
55+
| 🔒 **Nothing leaves your network** | Your data is never uploaded anywhere |
56+
| 📖 **Open source** | All code is public and verifiable |
57+
| 🔐 **Credentials encrypted** | Router login encrypted at rest (AES-128) |
8258

8359
---
8460

8561
## Features
8662

87-
<details>
88-
<summary><strong>Monitoring & Diagnostics</strong></summary>
89-
90-
- **Web Dashboard**: Real-time channel data with health assessment, metric cards, and calendar navigation
91-
- **Health Assessment**: Automatic traffic-light evaluation with actionable recommendations
92-
- **Signal Trends**: Interactive charts with DOCSIS reference zones (color-coded thresholds) for day/week/month views
93-
- **Speedtest Tracker Integration**: Pull speed test results (download, upload, ping, jitter) from a self-hosted [Speedtest Tracker](https://github.com/alexjustesen/speedtest-tracker) instance with charts, sortable history, and anomaly highlighting
94-
- **Incident Report**: Two-step complaint flow with editable ISP letter + downloadable technical PDF
95-
- **LLM Export**: Generate structured reports for AI analysis (ChatGPT, Claude, Gemini, etc.)
96-
- **ThinkBroadband BQM**: Daily fetch and archive of broadband quality graphs with gallery view
97-
98-
</details>
99-
100-
<details>
101-
<summary><strong>Ease of Use</strong></summary>
102-
103-
- **Setup Wizard**: Browser-based configuration — no .env file needed
104-
- **4 Languages**: English, German, French, and Spanish UI (181+ translation keys each)
105-
- **Light/Dark Mode**: Persistent theme toggle
106-
- **URL Hash Routing**: Bookmark and share specific views (#trends, #speedtest, #bqm)
107-
- **Lightweight Frontend**: Single dependency (Chart.js) for interactive trend charts
108-
- **Optional Authentication**: Password-protected web UI with scrypt hashing
109-
110-
</details>
111-
112-
<details>
113-
<summary><strong>Smart Home Integration</strong> (optional)</summary>
114-
115-
- **MQTT Auto-Discovery**: Zero-config integration with Home Assistant
116-
- **Per-Channel + Summary Sensors**: Every DOCSIS channel and aggregated metrics as HA entities
117-
118-
</details>
63+
| Feature | Description |
64+
|---|---|
65+
| **[Live Dashboard](https://github.com/itsDNNS/docsight/wiki/Features-Dashboard)** | Real-time channel data with health assessment and metric cards |
66+
| **[Signal Trends](https://github.com/itsDNNS/docsight/wiki/Features-Signal-Trends)** | Interactive charts with DOCSIS reference zones (day/week/month) |
67+
| **[Event Log](https://github.com/itsDNNS/docsight/wiki/Features-Event-Log)** | Automatic anomaly detection with modulation watchdog |
68+
| **[Speedtest Integration](https://github.com/itsDNNS/docsight/wiki/Features-Speedtest)** | Speed test history from [Speedtest Tracker](https://github.com/alexjustesen/speedtest-tracker) |
69+
| **[Incident Journal](https://github.com/itsDNNS/docsight/wiki/Features-Incident-Journal)** | Document ISP issues with attachments |
70+
| **[Complaint Generator](https://github.com/itsDNNS/docsight/wiki/Filing-a-Complaint)** | Editable ISP letter + downloadable technical PDF |
71+
| **[Home Assistant](https://github.com/itsDNNS/docsight/wiki/Home-Assistant)** | MQTT Auto-Discovery with per-channel sensors |
72+
| **[BQM Integration](https://github.com/itsDNNS/docsight/wiki/Features-BQM)** | ThinkBroadband broadband quality graphs |
73+
| **[LLM Export](https://github.com/itsDNNS/docsight/wiki/Features-LLM-Export)** | Structured reports for AI analysis |
74+
75+
4 languages (EN/DE/FR/ES) · Light/Dark mode · Setup wizard · Optional authentication
11976

120-
<details>
121-
<summary><h2>Configuration</h2></summary>
122-
123-
Configuration is stored in `config.json` inside the Docker volume and persists across restarts. Environment variables override config.json values.
124-
125-
### Via Web UI (recommended)
126-
127-
1. Start the container - the setup wizard opens automatically
128-
2. Enter your modem URL, username, and password - test the connection
129-
3. Optionally configure MQTT broker for Home Assistant integration
130-
4. Set poll interval, history retention, and language
131-
5. Done - monitoring starts immediately
132-
133-
Access `/settings` at any time to change configuration, set an admin password, or toggle light/dark mode.
134-
135-
### Via Environment Variables (optional)
136-
137-
Copy `.env.example` to `.env` and edit:
138-
139-
| Variable | Default | Description |
140-
|---|---|---|
141-
| `MODEM_URL` | `http://192.168.178.1` | Modem URL |
142-
| `MODEM_USER` | - | Modem username |
143-
| `MODEM_PASSWORD` | - | Modem password |
144-
| `MQTT_HOST` | - | MQTT broker host (optional) |
145-
| `MQTT_PORT` | `1883` | MQTT broker port |
146-
| `MQTT_USER` | - | MQTT username (optional) |
147-
| `MQTT_PASSWORD` | - | MQTT password (optional) |
148-
| `MQTT_TOPIC_PREFIX` | `docsight` | MQTT topic prefix |
149-
| `POLL_INTERVAL` | `900` | Polling interval in seconds |
150-
| `WEB_PORT` | `8765` | Web UI port |
151-
| `HISTORY_DAYS` | `0` | Snapshot retention in days (0 = unlimited) |
152-
| `ADMIN_PASSWORD` | - | Web UI password (optional) |
153-
| `BQM_URL` | - | ThinkBroadband BQM share URL (.png, optional) |
154-
| `SPEEDTEST_TRACKER_URL` | - | Speedtest Tracker URL (optional) |
155-
| `SPEEDTEST_TRACKER_TOKEN` | - | Speedtest Tracker API token (optional) |
77+
---
15678

157-
</details>
79+
## Screenshots
15880

15981
<details>
160-
<summary><h2>Screenshots</h2></summary>
82+
<summary>Click to expand</summary>
16183

16284
| Dashboard (Dark) | Dashboard (Light) |
16385
|---|---|
@@ -167,111 +89,35 @@ Copy `.env.example` to `.env` and edit:
16789
|---|---|
16890
| ![Trends](docs/screenshots/trends.png) | ![Health](docs/screenshots/health-banner.png) |
16991

170-
| Speedtest Tracker | BQM Gallery |
92+
| Speedtest Tracker | Incident Journal |
17193
|---|---|
172-
| ![Speedtest](docs/screenshots/speedtest.png) | ![BQM](docs/screenshots/bqm.png) |
173-
174-
| Incident Journal |
175-
|---|
176-
| ![Journal](docs/screenshots/journal.png) |
94+
| ![Speedtest](docs/screenshots/speedtest.png) | ![Journal](docs/screenshots/journal.png) |
17795

17896
</details>
17997

180-
<details>
181-
<summary><h2>Home Assistant Integration</h2></summary>
182-
183-
DOCSight can optionally publish all channel data to Home Assistant via MQTT Auto-Discovery. This is not required to use DOCSight.
184-
185-
### Per-Channel (~37 DS + 4 US)
186-
187-
- `sensor.docsight_ds_ch{id}` - State: Power (dBmV), Attributes: frequency, modulation, snr, errors, docsis_version, health
188-
- `sensor.docsight_us_ch{id}` - State: Power (dBmV), Attributes: frequency, modulation, multiplex, docsis_version, health
189-
190-
### Summary (14)
191-
192-
| Sensor | Unit | Description |
193-
|---|---|---|
194-
| `docsight_health` | - | Overall health (good/marginal/poor) |
195-
| `docsight_health_details` | - | Detail text |
196-
| `docsight_ds_total` | - | Number of downstream channels |
197-
| `docsight_ds_power_min/max/avg` | dBmV | Downstream power range |
198-
| `docsight_ds_snr_min/avg` | dB | Downstream signal-to-noise |
199-
| `docsight_ds_correctable_errors` | - | Total correctable errors |
200-
| `docsight_ds_uncorrectable_errors` | - | Total uncorrectable errors |
201-
| `docsight_us_total` | - | Number of upstream channels |
202-
| `docsight_us_power_min/max/avg` | dBmV | Upstream power range |
203-
204-
</details>
205-
206-
<details>
207-
<summary><h2>Reference Values</h2></summary>
208-
209-
| Metric | Good | Marginal | Poor |
210-
|---|---|---|---|
211-
| DS Power | -7..+7 dBmV | +/-7..+/-10 | > +/-10 dBmV |
212-
| US Power | 35..49 dBmV | 50..54 | > 54 dBmV |
213-
| SNR / MER | > 30 dB | 25..30 | < 25 dB |
214-
215-
</details>
98+
---
21699

217100
## Requirements
218101

219102
- Docker (or any OCI-compatible container runtime)
220103
- A DOCSIS cable modem or router with web interface (tested with AVM FRITZ!Box 6690 Cable)
221-
- MQTT broker (optional) — only needed for Home Assistant integration
104+
- MQTT broker (optional, for Home Assistant)
222105

223-
## Roadmap
106+
## Documentation
224107

225-
### Modulation & Signal Intelligence
226-
- [x] **Modulation Watchdog**: Track and alert on QAM modulation changes per channel (e.g. 256QAM dropping to 16QAM) with severity based on QAM hierarchy — downgrades trigger warning/critical, upgrades show as info
227-
- [ ] **Channel Heatmap**: Visual grid of all channels color-coded by modulation quality — spot frequency-dependent issues at a glance
228-
- [ ] **OFDMA Analysis**: Detect whether the modem uses a wide OFDMA block vs. many narrow SC-QAMs; flag subcarrier count fluctuations as potential ingress indicators; track OFDMA enable/disable impact
229-
- [ ] **Adaptive Polling**: Automatically increase poll frequency (e.g. every 10-30s) when uncorrectable errors spike, to capture incidents in high resolution
230-
- [ ] **Upstream Channel Count Monitoring**: Alert when upstream channels drop (e.g. from 5 to 1) — early indicator of return path issues
231-
- [ ] **Ingress/Return Path Scoring**: Composite score based on upstream power levels, modulation quality, and channel count to detect return path interference before total failure
232-
233-
### Diagnosis & Reporting
234-
- [x] **Incident Report Export**: Two-step flow — editable ISP complaint letter with customer data fields + downloadable technical PDF with channel tables, worst values, and DIN threshold references (EN/DE/FR/ES)
235-
- [x] **Incident Journal**: Built-in log to document ISP issues over time — date, title, detailed description, screenshot uploads. Replaces spreadsheet-based tracking and feeds directly into complaint letters and reports.
236-
- [ ] **Ping Correlation**: Built-in latency monitor (ping to configurable targets) overlaid on error graphs to prove causality between physical layer issues and packet loss — replaces manual PingPlotter usage
237-
- [ ] **Before/After Comparison**: Side-by-side overlay of two time periods (e.g. week before vs. after technician visit) to quantify improvements
238-
- [ ] **FritzBox Event Log Parser**: Extract and display T3/T4 Timeout events, Ranging Request failures, and other DOCSIS error codes from the modem's event log
239-
- [ ] **Plain-Language Explanations**: "What does this mean?" tooltips translating technical values into actionable advice (e.g. "Your upstream power is critically high — this means the signal has to travel too far or passes through damaged cable")
240-
241-
### Alerting & Notifications
242-
- [ ] **Notification System**: Configurable alerts via webhook, Telegram, Discord, email, or Gotify/ntfy on health degradation, modulation drops, or connectivity loss
243-
- [ ] **Power Level Drift Detection**: Alert on relative changes (e.g. +3 dB in 24h) in addition to absolute thresholds — catch creeping degradation before it causes outages
244-
- [ ] **Scheduled Health Digest**: Daily/weekly summary email or message with connection quality score, error trends, and notable events
245-
- [ ] **Gaming/Real-Time Quality Index**: Dedicated score for latency-sensitive applications based on jitter, packet loss bursts, and modulation stability
246-
247-
### External Monitoring Integration
248-
- [x] **ThinkBroadband BQM**: Daily fetch and archive of external broadband quality graphs (latency, packet loss)
249-
- [x] **Speedtest Tracker**: Pull speed test results from self-hosted [Speedtest Tracker](https://github.com/alexjustesen/speedtest-tracker) with interactive charts, sortable history, anomaly highlighting, and incremental SQLite caching
250-
- [ ] **Smokeping Integration**: Import or display Smokeping latency data alongside DOCSIS metrics for end-to-end correlation
251-
252-
### Enhanced Dashboard
253-
- [x] **Update Changelog Splash**: Show a "What's New" dialog on first login after a version update — highlights new features and changes so users stay informed without reading GitHub Releases
254-
- [ ] Combined timeline: DOCSIS health + speed tests + BQM graph + ping data on a single time axis
255-
- [ ] Mobile-responsive layout
256-
- [ ] Segment load indicator: Visualize peak-hour degradation patterns (e.g. 20:00-23:00 slowdowns)
257-
- [ ] Network uptime calendar: Month-view heatmap showing daily connection quality at a glance
258-
- [ ] Power level drift detection: Alert on relative changes (e.g. +3 dB in 24h) in addition to absolute thresholds
259-
- [x] Manual poll buttons: Trigger FritzBox and Speedtest Tracker data refresh on demand
260-
261-
### Multi-Modem Support
262-
- [ ] Plugin architecture for modem drivers
263-
- [ ] **Vodafone Station / CommScope driver**: Support for the most common ISP-provided cable modem in Germany
264-
- [ ] **Arris / Technicolor / Sagemcom drivers**: Cover the long tail of ISP-provided hardware
265-
- [ ] SNMP-based generic driver for additional cable modem models
266-
- [ ] Community-contributed drivers with documentation template
108+
📚 **[Wiki](https://github.com/itsDNNS/docsight/wiki)** — Full documentation, guides, and DOCSIS glossary
267109

268110
## Contributing
269111

270-
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
112+
See [CONTRIBUTING.md](CONTRIBUTING.md). **Please open an issue before working on new features.**
113+
114+
## Roadmap
115+
116+
See the **[full roadmap](https://github.com/itsDNNS/docsight/wiki/Roadmap)** in the wiki.
271117

272118
## Changelog
273119

274-
See [GitHub Releases](https://github.com/itsDNNS/docsight/releases) for release notes and changelogs.
120+
See [GitHub Releases](https://github.com/itsDNNS/docsight/releases).
275121

276122
## License
277123

0 commit comments

Comments
 (0)