Skip to content

Add FRITZ!Box Cable DOCSIS monitoring - #1299

Merged
tvancott42 merged 2 commits into
Ozark-Connect:devfrom
gmdfalk:main
Oct 26, 2026
Merged

tvancott42 merged 2 commits into
Ozark-Connect:devfrom
gmdfalk:main

Conversation

@gmdfalk

@gmdfalk gmdfalk commented Oct 22, 2026

Copy link
Copy Markdown
Contributor

Hey,

love the software, thanks for your efforts!

I have a cable modem that is currently unsupported but very popular in Germany: FritzBox.

This PR adds a new FritzBoxCableProvider to be able to monitor it as cable modem in NetworkOptimizer.
I only have FritzBox 6690 and Firmware 8.40 to test on but I think auth and cable stats have remained largely unchanged over time.

Verification done via both unit tests and building the Docker image locally and verifying that adding and monitoring my FritzBox as cable modem works.

image image

This change is tightly scoped to just that new provider so we don't break anything outside of it.

Full disclaimer: The code is LLM generated.

Adds FRITZ!Box Cable as a selectable DOCSIS provider, using the existing modem monitor, encrypted credentials and site device dialer. Verified with a FRITZ!Box 6690 Cable running FRITZ!OS 8.40; other models and firmware remain unverified.

The provider uses AVM challenge-response authentication, reads `docInfo` channel data and logs out its own session after each operation. It maps downstream/upstream RF readings, normalizes MSE/MER and frequency units, and reads optional model/firmware metadata. Settings changes only add the provider option, labels and help; existing configuration defaults and credential/save/test workflows are unchanged.

Following the Netgear/UCI convention, FEC totals include DOCSIS 3.0 channels only. OFDM/OFDMA RF readings are included, with frequency bands represented by their midpoint. No shared interface, model, database, Influx, chart or scoring changes are required.

## Validation

- 40 new tests cover AVM authentication vectors, captured channel data, conversions, counter scope, device routing, failures, cancellation, overlapping sessions and logout.
- All 157 selected new/existing cable-modem, model-label and routed-device regression tests passed.
- Solution Release build passed with .NET SDK 10.0.200. On Apple Silicon, existing protobuf artifacts were generated using the pinned gRPC package's Linux ARM64 tools before the native build; no build-system changes are included.
- Full native solution run: 12,479 passed and 23 failed. The exact same 23 failing tests reproduced when rebuilding untouched base commit `6f116ec` and running the affected test classes under the same host conditions (locale-dependent formatting/parsing and macOS AES-CCM support).
- A harness referencing the actual compiled Web/Monitoring/Core assemblies successfully ran TestConnection and two polls against the 6690, returning 26 downstream and 4 upstream channels. Credentials and sessions are absent from the committed fixture.

## Remaining acceptance

The deployed Settings save → scheduled polling → dashboard/Influx history path has not been exercised. Live device access was tested from the development host; site routing is covered by tests. Lock status is inferred from assigned channels; registration state, uptime, event logs and upstream symbol rate are left unavailable where the source does not report them.
@gmdfalk

gmdfalk commented Oct 22, 2026

Copy link
Copy Markdown
Contributor Author

@tvancott42 could i get a review when you have some time? let me know if anything needs adjusting!

@tvancott42 tvancott42 self-assigned this Oct 22, 2026
@tvancott42

Copy link
Copy Markdown
Collaborator

@gmdfalk on it, but along with 6 other ONT/CM providers at the moment haha. Should have this in by next week, I'm out of town for a few days but have all of these providers queued up. Thanks for the PR

@tvancott42

Copy link
Copy Markdown
Collaborator

OK, preliminary review findings, here's the summary to address:

  • Retarget to dev. PRs here go into dev, not main. It merges cleanly onto current dev, builds with 0 warnings, and the cable modem tests pass (yours included).
  • HTTPS on port 443 has no certificate handling. Port 443 switches the scheme to https, but the handler sets no SslOptions.RemoteCertificateValidationCallback. A FRITZ!Box serves a self-signed certificate by default, so 443 will likely always fail TLS validation. The other HTTPS-capable cable modem providers (e.g. TechnicolorCgaProvider, SagemcomF3896Provider) accept the device's certificate; please match them, or drop the 443 switch.
  • Full login and logout on every poll. At the default 300 s interval that is 288 sign-ins a day. Does your 6690 record each one in its event log, or send login notifications if those are enabled? If it does, please keep the SID between polls and only sign in again when data.lua rejects it.
  • Add FRITZ!Box to the credential-declaration test. UniFiCableInternetTests.Provider_DeclaresItsCredentialNeeds pins every cable modem provider's Credentials and BlankUsernameMeansAdmin; add a row for FritzBoxCableProvider (Required, false).
  • Settings help placement (nit). "Error totals cover DOCSIS 3.0 channels; OFDM error counts are not collected." sits under the Status Page Path field, which it does not describe. It reads better as provider help near the top of the form.
  • README length (nit). The README bullet is four sentences where its neighbors are one line. Please trim it to the model and firmware; the detail can live in the PR. I'll handle the FEATURES.md wording at release time, so that edit can be dropped.

PS: what model are you using, just for my own learnings and knowledge (this was an Opus 5.5 review w/ all of my local memories/context that produced these findings)?

@gmdfalk

gmdfalk commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor Author

OK, preliminary review findings, here's the summary to address:

* **Retarget to `dev`.** PRs here go into `dev`, not `main`. It merges cleanly onto current `dev`, builds with 0 warnings, and the cable modem tests pass (yours included).

* **HTTPS on port 443 has no certificate handling.** Port 443 switches the scheme to `https`, but the handler sets no `SslOptions.RemoteCertificateValidationCallback`. A FRITZ!Box serves a self-signed certificate by default, so 443 will likely always fail TLS validation. The other HTTPS-capable cable modem providers (e.g. `TechnicolorCgaProvider`, `SagemcomF3896Provider`) accept the device's certificate; please match them, or drop the 443 switch.

* **Full login and logout on every poll.** At the default 300 s interval that is 288 sign-ins a day. Does your 6690 record each one in its event log, or send login notifications if those are enabled? If it does, please keep the SID between polls and only sign in again when `data.lua` rejects it.

* **Add FRITZ!Box to the credential-declaration test.** `UniFiCableInternetTests.Provider_DeclaresItsCredentialNeeds` pins every cable modem provider's `Credentials` and `BlankUsernameMeansAdmin`; add a row for `FritzBoxCableProvider` (`Required`, `false`).

* **Settings help placement (nit).** "Error totals cover DOCSIS 3.0 channels; OFDM error counts are not collected." sits under the Status Page Path field, which it does not describe. It reads better as provider help near the top of the form.

* **README length (nit).** The README bullet is four sentences where its neighbors are one line. Please trim it to the model and firmware; the detail can live in the PR. I'll handle the `FEATURES.md` wording at release time, so that edit can be dropped.

PS: what model are you using, just for my own learnings and knowledge (this was an Opus 5.5 review w/ all of my local memories/context that produced these findings)?

thanks for the quick review, i'll retarget the dev branch and address these. this is just stock sol 6.1 medium without any local c# history/setup (sorry if that shows)

@tvancott42
tvancott42 changed the base branch from main to dev October 22, 2026 14:49
@tvancott42

Copy link
Copy Markdown
Collaborator

@gmdfalk sorry about the delay, I've been out of town at an event for my other business. I'm getting this worked in for the next patch and preview releases, thanks again!

@tvancott42
tvancott42 merged commit 7fef3b1 into Ozark-Connect:dev Oct 26, 2026
1 check passed
tvancott42 pushed a commit that referenced this pull request Oct 26, 2026
* Add FRITZ!Box Cable DOCSIS monitoring (#1)

Adds FRITZ!Box Cable as a selectable DOCSIS provider, using the existing modem monitor, encrypted credentials and site device dialer. Verified with a FRITZ!Box 6690 Cable running FRITZ!OS 8.40; other models and firmware remain unverified.

The provider uses AVM challenge-response authentication, reads `docInfo` channel data and logs out its own session after each operation. It maps downstream/upstream RF readings, normalizes MSE/MER and frequency units, and reads optional model/firmware metadata. Settings changes only add the provider option, labels and help; existing configuration defaults and credential/save/test workflows are unchanged.

Following the Netgear/UCI convention, FEC totals include DOCSIS 3.0 channels only. OFDM/OFDMA RF readings are included, with frequency bands represented by their midpoint. No shared interface, model, database, Influx, chart or scoring changes are required.

## Validation

- 40 new tests cover AVM authentication vectors, captured channel data, conversions, counter scope, device routing, failures, cancellation, overlapping sessions and logout.
- All 157 selected new/existing cable-modem, model-label and routed-device regression tests passed.
- Solution Release build passed with .NET SDK 10.0.200. On Apple Silicon, existing protobuf artifacts were generated using the pinned gRPC package's Linux ARM64 tools before the native build; no build-system changes are included.
- Full native solution run: 12,479 passed and 23 failed. The exact same 23 failing tests reproduced when rebuilding untouched base commit `6f116ec` and running the affected test classes under the same host conditions (locale-dependent formatting/parsing and macOS AES-CCM support).
- A harness referencing the actual compiled Web/Monitoring/Core assemblies successfully ran TestConnection and two polls against the 6690, returning 26 downstream and 4 upstream channels. Credentials and sessions are absent from the committed fixture.

## Remaining acceptance

The deployed Settings save → scheduled polling → dashboard/Influx history path has not been exercised. Live device access was tested from the development host; site routing is covered by tests. Lock status is inferred from assigned channels; registration state, uptime, event logs and upstream symbol rate are left unavailable where the source does not report them.

* Reuse FRITZ!Box sessions and address upstream review feedback

---------

Co-authored-by: falkhq-admin <accounts@falkhq.de>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants