Pi Architecture (v3.14) - Config-Driven Modem Support

[kwschulz]

Cable Modem Monitor currently supports 33 modems across 7 manufacturers. Adding each one required understanding the modem's web interface from scratch; different auth mechanisms, different page structures, different data formats.

v3.14 restructures the project so that most of this variety is handled by configuration, not code. A modem.yaml file and a HAR capture should be enough for most modems. Custom parser code is only needed for genuine structural quirks that can't be expressed declaratively.

Architecture

Three packages with strict dependency direction. Import boundaries are enforced by real Python packaging — violations are missing module errors, not lint warnings.

graph TD
    HA["<b>HA Integration</b><hr/>cable-modem-monitor"] --> Core["<b>Core Library</b><hr/>solentlabs-cable-modem-monitor-core"]
    HA --> Catalog["<b>Modem Catalog</b><hr/>solentlabs-cable-modem-monitor-catalog"]
    Catalog --> Core

Loading

• HA Integration — translates between Home Assistant and the core engine. No parsing, no auth, no modem-specific knowledge.
• Core — the complete engine: auth strategies, resource loaders, parser coordinator, data models, config schemas. Platform-agnostic — no homeassistant.* imports.
• Catalog — modem.yaml configs, parser.yaml extraction mappings, optional parser.py overrides, HAR captures. Each modem is isolated — adding one can't break another.

Transport and Format

The transport field in modem.yaml is the first config decision — it identifies the wire protocol and determines whether auth and format are free or locked.

graph TD
    T[transport] --> HNAP["<b>hnap</b><hr/>HNAPLoader to dict"]
    T --> HTTP["<b>http</b><hr/>HTTPLoader to BeautifulSoup or dict"]

    HNAP --> HA["<b>AUTH</b><hr/>HMAC challenge-response"]
    HA --> HS["<b>SESSION</b><hr/>uid cookie + HNAP_AUTH header"]
    HS --> HF["<b>FORMAT</b><hr/>hnap (JSON + delimiters)"]

    HTTP --> HTA["<b>AUTH</b><hr/>none, basic, form, form_nonce,<br/>url_token, form_pbkdf2, form_sjcl"]
    HTA --> HTS["<b>SESSION</b><hr/>stateless, cookie, CSRF, url_token"]
    HTS --> HTF["<b>FORMAT</b><hr/>table, table_transposed, javascript,<br/>javascript_json, html_fields, json, xml"]

Loading

HNAP modems are fully constrained — the protocol defines auth, session, and format. Only the HMAC algorithm and action names vary per modem. HTTP is where the variety lives, but auth, session, and format are independent config axes.

Auth is config, not code

Eight auth strategies cover all 33 supported modems:

Strategy	Config Flags
none	—
basic	challenge_cookie
form	encoding, CSRF, session cookie, hidden fields
form_nonce	nonce field, credential format, success/error prefixes
hnap	HMAC algorithm (MD5/SHA256)
form_pbkdf2	login_endpoint, PBKDF2 iterations/key length, double hash, CSRF
form_sjcl	login page/endpoint, PBKDF2 params, AES-CCM tag length, encrypt/decrypt AAD
url_token	login page, login prefix, success indicator, AJAX login

No per-modem auth hooks means a smaller security surface — one audited implementation per strategy, not per-modem overrides that could mishandle credentials.

What a modem needs

Artifact	Required?	Purpose
modem.yaml	Yes	Declares transport, auth, session, endpoints, hardware metadata
parser.yaml	Yes	Declarative extraction mappings — format, field names, selectors
har/modem.har	Yes	PII-scrubbed HAR capture — evidence base for the config
parser.py	Only if needed	Post-processor for quirks the declarative config can't express

The HAR capture is how we understand your modem. We analyze it to determine auth mechanism, session management, data format, and endpoints; then express all of that in modem.yaml and parser.yaml.

Two data models, two cadences

ModemData  — channels, system info, DOCSIS lock state    (heavy poll, e.g. every 5 min)
HealthInfo — ping latency, HTTP latency, derived status  (lightweight, e.g. every 30s)

A flaky modem gets fast heartbeats without hammering its web interface.

Current status

Core library and modem catalog are implemented. 33 modems across 7 manufacturers are configured and tested (1254 tests, ~96% coverage). The MCP onboarding pipeline (validate_har to analyze_har to generate_config to generate_golden_file to run_tests) automates most of the work of adding a new modem from a HAR capture.

Next: HA integration wiring (replacing the v3.13 parsing/auth code with Core) and release.

If you want to help, the most valuable thing is a HAR capture of your modem. Open an issue and we'll walk you through it.