feat: support community-contributed modem drivers via module system (#145)

* feat(drivers): add DriverRegistry class for unified driver lookup

Introduces a central DriverRegistry that supports both built-in drivers
(lazy-loaded via class paths) and module-contributed drivers (eager-loaded
classes). Module drivers take priority, enabling community overrides.

* refactor(drivers): wire DriverRegistry into all consumers

Replace hardcoded DRIVER_REGISTRY/DRIVER_DISPLAY_NAMES dicts and
standalone load_driver() with the unified DriverRegistry singleton.
Backward-compatible load_driver() wrapper kept for safety.

* feat(modules): add "driver" contribution type to module loader

Modules can now declare a "driver" contribution in their manifest.
Driver modules are security-restricted from also contributing
collectors or publishers.

* feat(drivers): add GenericDriver for no-modem mode

Returns empty but structurally valid DOCSIS data, enabling all
modem-agnostic features (Speedtest, BQM, Journal, etc.) to work
standalone without a physical modem.

* feat(ui): show fun placeholder when no DOCSIS data is available

When running with GenericDriver or a non-DOCSIS modem, the dashboard
shows a humorous "He's dead, Jim" message instead of empty channel
tables. Translated to all 4 supported languages.

* fix(config): treat generic driver as configured without password

The is_configured() check required modem_password to be set, but
GenericDriver doesn't need credentials. Now recognizes modem_type
"generic" as a valid configured state.

* fix(ui): hide credentials for generic driver, fix setup light mode, auto-refresh on first load

- Hide URL/username/password/test-connection when Generic Router selected
  (both setup wizard and settings page)
- Fix setup page light mode by including tokens.css and adding
  box-sizing: border-box reset
- Add background/color CSS variables to setup body
- Auto-refresh dashboard every 5s while waiting for first poll
  (stops once data arrives or after 5 minutes)

* feat(ui): show non-DOCSIS cards on dashboard for generic router

Move speedtest health calculations before the has_docsis conditional
so they're available in both DOCSIS and non-DOCSIS views. When using
Generic Router, the dashboard now shows the no-DOCSIS placeholder
for signal metrics but still renders speedtest, BNetzA, and module
cards below it when configured.

* test(web): add no-DOCSIS dashboard tests, redesign placeholder

Add tests verifying the no-DOCSIS placeholder appears with empty
channels and that the speed card renders when speedtest is configured.
Redesign the placeholder to use a Lucide icon in a circular wrap
matching the existing hero card design language.

* fix(i18n): replace meme placeholder with informative generic router message

Explain that DOCSIS channel data is unavailable in generic router mode
and that metrics below (speedtest, BNetzA, etc.) show connection quality
for fiber, DSL, or satellite users. Updated all 4 languages and changed
icon from radio-tower to router.

---------

Co-authored-by: itsDNNS <itsDNNS@users.noreply.github.com>

Author: itsDNNS

app/blueprints/polling_bp.py

@@ -31,9 +31,9 @@ def api_test_modem():
         password = data.get("modem_password", "")
         if password == PASSWORD_MASK and _config_manager:
             password = _config_manager.get("modem_password", "")
-        from app.drivers import load_driver
+        from app.drivers import driver_registry
         modem_type = data.get("modem_type", "fritzbox")
-        driver = load_driver(
+        driver = driver_registry.load_driver(
             modem_type,
             data.get("modem_url", "http://192.168.178.1"),
             data.get("modem_user", ""),

app/collectors/__init__.py

@@ -51,10 +51,10 @@ def discover_collectors(config_mgr, storage, event_detector, mqtt_pub, web, anal
         ))
     # Modem collector (available if modem configured)
     elif config_mgr.is_configured():
-        from ..drivers import load_driver
+        from ..drivers import driver_registry
 
         modem_type = config.get("modem_type", "fritzbox")
-        driver = load_driver(
+        driver = driver_registry.load_driver(
             modem_type,
             config["modem_url"],
             config["modem_user"],

app/config.py

@@ -283,8 +283,12 @@ def save(self, data):
         log.info("Config saved to %s", self.config_path)
 
     def is_configured(self):
-        """True if modem_password is set or demo_mode is active."""
-        return bool(self.get("modem_password")) or self.is_demo_mode()
+        """True if modem is configured (password set or generic driver) or demo mode."""
+        if self.is_demo_mode():
+            return True
+        if self.get("modem_type") == "generic":
+            return True
+        return bool(self.get("modem_password"))
 
     def is_demo_mode(self):
         """True if DEMO_MODE is enabled."""

app/drivers/__init__.py

@@ -1,38 +1,19 @@
 """Modem driver abstractions."""
 
-import importlib
-import logging
+from .registry import DriverRegistry
 
-log = logging.getLogger("docsis.drivers")
+driver_registry = DriverRegistry()
 
-DRIVER_REGISTRY = {
-    "fritzbox": "app.drivers.fritzbox.FritzBoxDriver",
-    "tc4400": "app.drivers.tc4400.TC4400Driver",
-    "ultrahub7": "app.drivers.ultrahub7.UltraHub7Driver",
-    "vodafone_station": "app.drivers.vodafone_station.VodafoneStationDriver",
-    "ch7465": "app.drivers.ch7465.CH7465Driver",
-    "cm3500": "app.drivers.cm3500.CM3500Driver",
-}
-
-DRIVER_DISPLAY_NAMES = {
-    "fritzbox": "AVM FRITZ!Box",
-    "tc4400": "Technicolor TC4400",
-    "ultrahub7": "Vodafone Ultra Hub 7",
-    "vodafone_station": "Vodafone Station",
-    "ch7465": "Unitymedia Connect Box (CH7465)",
-    "cm3500": "Arris CM3500B",
-}
+# Register built-in drivers
+driver_registry.register_builtin("fritzbox", "app.drivers.fritzbox.FritzBoxDriver", "AVM FRITZ!Box")
+driver_registry.register_builtin("tc4400", "app.drivers.tc4400.TC4400Driver", "Technicolor TC4400")
+driver_registry.register_builtin("ultrahub7", "app.drivers.ultrahub7.UltraHub7Driver", "Vodafone Ultra Hub 7")
+driver_registry.register_builtin("vodafone_station", "app.drivers.vodafone_station.VodafoneStationDriver", "Vodafone Station")
+driver_registry.register_builtin("ch7465", "app.drivers.ch7465.CH7465Driver", "Unitymedia Connect Box (CH7465)")
+driver_registry.register_builtin("cm3500", "app.drivers.cm3500.CM3500Driver", "Arris CM3500B")
+driver_registry.register_builtin("generic", "app.drivers.generic.GenericDriver", "Generic Router (No DOCSIS)")
 
 
 def load_driver(modem_type, url, user, password):
-    """Instantiate a modem driver by type name."""
-    qualified = DRIVER_REGISTRY.get(modem_type)
-    if not qualified:
-        supported = ", ".join(sorted(DRIVER_REGISTRY))
-        raise ValueError(
-            f"Unknown modem_type '{modem_type}'. Supported: {supported}"
-        )
-    module_path, class_name = qualified.rsplit(".", 1)
-    mod = importlib.import_module(module_path)
-    cls = getattr(mod, class_name)
-    return cls(url, user, password)
+    """Backward-compatible wrapper around driver_registry.load_driver()."""
+    return driver_registry.load_driver(modem_type, url, user, password)

app/drivers/generic.py

@@ -0,0 +1,30 @@
+"""Generic driver for non-DOCSIS / no-modem mode."""
+
+from .base import ModemDriver
+
+
+class GenericDriver(ModemDriver):
+    """No-op driver that returns empty but structurally valid data.
+
+    Allows all modem-agnostic features (Speedtest, BQM, Smokeping,
+    BNetzA, Weather, Journal) to work standalone.
+    """
+
+    def login(self) -> None:
+        pass
+
+    def get_docsis_data(self) -> dict:
+        return {
+            "channelDs": {"docsis30": [], "docsis31": []},
+            "channelUs": {"docsis30": [], "docsis31": []},
+        }
+
+    def get_device_info(self) -> dict:
+        return {
+            "model": "Generic Router",
+            "sw_version": "N/A",
+            "manufacturer": "N/A",
+        }
+
+    def get_connection_info(self) -> dict:
+        return {}

app/drivers/registry.py

@@ -0,0 +1,67 @@
+"""Unified driver registry for built-in and module-contributed modem drivers."""
+
+import importlib
+import logging
+
+from .base import ModemDriver
+
+log = logging.getLogger("docsis.drivers")
+
+
+class DriverRegistry:
+    """Central registry for all modem drivers (built-in and module-contributed).
+
+    Built-in drivers are stored as qualified class paths (lazy-loaded).
+    Module drivers are stored as already-loaded classes.
+    """
+
+    def __init__(self):
+        self._builtin: dict[str, str] = {}
+        self._module_drivers: dict[str, type] = {}
+        self._display_names: dict[str, str] = {}
+
+    def register_builtin(self, type_key: str, class_path: str, display_name: str) -> None:
+        self._builtin[type_key] = class_path
+        self._display_names[type_key] = display_name
+
+    def register_module_driver(self, type_key: str, cls: type, display_name: str) -> None:
+        self._module_drivers[type_key] = cls
+        self._display_names[type_key] = display_name
+
+    def load_driver(self, modem_type: str, url: str, user: str, password: str) -> ModemDriver:
+        # Module drivers take priority (community can override/extend)
+        if modem_type in self._module_drivers:
+            cls = self._module_drivers[modem_type]
+            return cls(url, user, password)
+
+        qualified = self._builtin.get(modem_type)
+        if not qualified:
+            supported = ", ".join(sorted(self.get_all_type_keys()))
+            raise ValueError(
+                f"Unknown modem_type '{modem_type}'. Supported: {supported}"
+            )
+        module_path, class_name = qualified.rsplit(".", 1)
+        mod = importlib.import_module(module_path)
+        cls = getattr(mod, class_name)
+        return cls(url, user, password)
+
+    def get_available_drivers(self) -> list[tuple[str, str]]:
+        all_keys = self.get_all_type_keys()
+        return sorted(
+            [(k, self._display_names.get(k, k)) for k in all_keys],
+            key=lambda x: x[1],
+        )
+
+    def get_all_type_keys(self) -> set[str]:
+        return set(self._builtin) | set(self._module_drivers)
+
+    def has_driver(self, modem_type: str) -> bool:
+        return modem_type in self._builtin or modem_type in self._module_drivers
+
+    def register_module_drivers(self, module_loader) -> None:
+        for mod in module_loader.get_enabled_modules():
+            if mod.driver_class and "driver" in mod.contributes:
+                type_key = mod.id
+                display_name = mod.name
+                self.register_module_driver(type_key, mod.driver_class, display_name)
+                log.info("Registered module driver: %s (%s)", type_key, display_name)

app/i18n/de.json

@@ -79,6 +79,8 @@
   "low": "niedrig",
   "error_label": "Fehler",
   "waiting_msg": "Warte auf erste DOCSIS-Abfrage...",
+  "no_docsis_title": "Generischer Router-Modus",
+  "no_docsis_msg": "DOCSIS-Kanaldaten sind in diesem Modus nicht verfügbar. Bei Verbindungen über Glasfaser, DSL oder Satellit zeigen die folgenden Metriken Ihre Verbindungsqualität.",
   "no_data": "Keine Daten für diesen Zeitraum vorhanden.",
   "trend_error": "Fehler beim Laden der Trenddaten.",
   "correctable": "Korrigierbar",

app/i18n/en.json

@@ -79,6 +79,8 @@
   "low": "low",
   "error_label": "Error",
   "waiting_msg": "Waiting for first DOCSIS query...",
+  "no_docsis_title": "Generic Router Mode",
+  "no_docsis_msg": "DOCSIS channel data is not available in this mode. If you connect via fiber, DSL, or satellite, the metrics below show your connection quality.",
   "no_data": "No data available for this period.",
   "trend_error": "Error loading trend data.",
   "correctable": "Correctable",

app/i18n/es.json

@@ -79,6 +79,8 @@
   "low": "bajo",
   "error_label": "Error",
   "waiting_msg": "Esperando la primera consulta DOCSIS...",
+  "no_docsis_title": "Modo router genérico",
+  "no_docsis_msg": "Los datos de canales DOCSIS no están disponibles en este modo. Si te conectas por fibra, DSL o satélite, las métricas a continuación muestran la calidad de tu conexión.",
   "no_data": "No hay datos disponibles para este período.",
   "trend_error": "Error al cargar los datos de tendencia.",
   "correctable": "Corregibles",

app/i18n/fr.json

@@ -79,6 +79,8 @@
   "low": "faible",
   "error_label": "Erreur",
   "waiting_msg": "En attente de la première requête DOCSIS...",
+  "no_docsis_title": "Mode routeur générique",
+  "no_docsis_msg": "Les données de canaux DOCSIS ne sont pas disponibles dans ce mode. Si vous êtes connecté par fibre, DSL ou satellite, les métriques ci-dessous indiquent la qualité de votre connexion.",
   "no_data": "Aucune donnée disponible pour cette période.",
   "trend_error": "Erreur lors du chargement des tendances.",
   "correctable": "Corrigeables",