feat: add Sagemcom F3896LG driver (Virgin Media Hub 5 / Liberty Global REST API)

[sparkleHazard]

Summary

Adds a driver for the Liberty Global firmware variant of the Sagemcom F@st 3896 — the Virgin Media Hub 5 (F3896LG-VMB), also used by Ziggo (NL) and other LG-footprint ISPs.

This follows up on #163: the existing sagemcom driver targets the Tele2/Com Hem XMO JSON-RPC firmware (/cgi/json-req, SHA-512 login). On Liberty Global units that endpoint simply doesn't exist (404 — which is exactly how I found this, trying to add my Hub 5 with the existing driver). The LG firmware instead exposes a read-only REST API at /rest/v1/ that requires no authentication for cable-modem status. It's the same API documented by the community client ties/sagemcom-f3896-py, which you referenced in #163 before it turned out the Swedish units were the other firmware.

What the driver does

• login() — no real auth exists, so it verifies /rest/v1/cablemodem/registration answers, making the setup-wizard connection test meaningful
• Downstream: SC-QAM → docsis30, OFDM → docsis31 (channel ID, frequency, power, SNR/MER, corrected/uncorrected errors, modulation)
• Upstream: ATDMA → docsis30, OFDMA → docsis31
• Device info from /rest/v1/cablemodem/state_ (DOCSIS version, status, uptime)
• Provisioned max rates from /rest/v1/cablemodem/serviceflows → ConnectionInfo
• Firmware quirk handled: OFDM/OFDMA channel power is reported scaled ×10 (380 = 38.0 dBmV, -118 = −11.8 dBmV) while SC-QAM/ATDMA power is unscaled. Confirmed against the modem GUI values.
• rxMer: 0 on the OFDM channel is treated as "not reported" → None

Testing

• Unit tests in tests/drivers/f3896lg/ with fixture payloads captured from a real Hub 5 (identifiers anonymised): parsing for all four channel types, unlocked-channel skipping, the ×10 power quirk, device/connection info, registry entry
• pytest tests/drivers/ → 125 passed (Python 3.13)
• Verified live against a Virgin Media (UK) Hub 5 in modem mode running a production DOCSight container: 31 SC-QAM + 1 OFDM downstream, 5 ATDMA + 1 OFDMA upstream, all values matching the hub GUI; running in my own deployment right now

Notes

• Default URL is https://192.168.100.1 (modem-mode management IP, self-signed cert — driver uses verify=False like other HTTPS-modem drivers)
• credentials_required: False hint, since the API is unauthenticated
• Happy to iterate if you'd rather fold this into the existing sagemcom driver with auto-detection, but the two firmwares share literally nothing (transport, auth, schema), so a separate driver seemed cleaner.

[itsDNNS]

Thanks for the contribution. I’ve added a few corrections and regression tests to the branch.

Could you please test the current version against your Hub 5 and confirm that the downstream and upstream values, device information, and provisioned rates still look correct in DOCSight? If everything works as expected on your device, let us know and we’ll merge the PR after your feedback.

[sparkleHazard]

Tested the current branch (e8ba9a8 + your 249ea58) against a live Virgin Media Hub 5 (F3896LG, modem mode). All the values look correct and match the hub:

• DS: 31 SC-QAM + 1 OFDM — SC-QAM power/MER unscaled (256QAM); OFDM power ÷10 → −12.4 dBmV, 4096QAM.
• US: 5 ATDMA + 1 OFDMA — ATDMA unscaled (64QAM); OFDMA ÷10 → 38.5 dBmV, 256QAM.
• Provisioned rates: 1,230,000 / 110,000 kbps ✅
• Device info: Sagemcom F3896LG, operational, uptime present.
• tests/drivers/f3896lg passes (39) on 3.13.

Two notes: (1) OFDM/OFDMA frequency now renders firstActiveSubcarrier as MHz ("1108 MHz" / "74 MHz"), but that field looks like a subcarrier index — it pairs with numberOfActiveSubCarriers, and 208 × 50 kHz = 10.4 MHz = the OFDMA channelWidth. Values happen to fall in plausible RF ranges, but the true center would need the subcarrier-zero frequency (not exposed here); might be cleaner to leave it blank or label it as an index unless you have a spec ref. (2) OFDM rxMer is 0 on my hub so the new ÷10 there couldn't be exercised — falls through to None fine.

Otherwise functionally correct — happy for it to merge. Thanks for the quick review and extra tests.