feat(catalog): say whether a driver needs the internet, and who has to unlock it

[HuggeK]

protocol names a transport, and answers neither question an owner asks first: does this need the internet, and what do I have to get from the manufacturer before it works at all?

nibe_local and myuplink are both protocol: http, and both read a NIBE heat pump. They are opposites — one reads the pump over the LAN, the other reads NIBE's cloud. The catalog could not tell them apart.

connectivity: local        # local | cloud  — where it talks while running
setup: [device_screen]     # what a human must obtain first, and from whom

Why not http_local / http_online

That was the obvious move and the wrong one. protocol feeds PROTOCOL_PERMISSIONS, so new values change what permissions a package build grants; it doesn't generalise (MQTT can be a cloud broker); and it doubles the Protocol filter. Orthogonal fields compose on the page instead — "HTTP · Local · Enable on the device screen".

The backfill, from what the sources actually do

77 local, 3 cloud. myuplink, easee_cloud and tibber are the only drivers that hardcode a vendor endpoint. Every other HTTP driver builds its base URL from config, and the 51 Modbus, 8 MQTT and 4 serial drivers name a vendor only as homepage.

setup is the second axis, and the more interesting one — a driver can be local and still be locked until somebody unlocks the interface:

Gate	Drivers
device_screen	nibe_local — the pump's own installer menu; no app, no account
device_ui	sonnen (JSON API + token), ctek, ctek_v2, ctek_hybrid (ModbusTCPEnable)
installer	sma_pv — "one-time installer step in the WebUI / Sunny Portal"
vendor_portal	myuplink, easee_cloud, tibber
bridge	heishamon, opendtu, opendtu_mqtt, esphome_dsmr, esphome-dsmr, tesla_vehicle, zuidwijk_p1, goodwe

17 have a recorded gate. 63 do not, and absent means unrecorded — the page renders "Not recorded", never "Nothing to set up", and a driver with none drops out of the setup filter rather than passing as though it needed nothing. Only setup: [none] is a claim, and nothing claims it yet. Same principle as verification_status: report what is known, not what looks complete.

It is checkable, not decorative

tests/test_connectivity.py reads an asymmetry that is hard to fake: a cloud endpoint must be hardcoded, because there is nowhere else for it to come from, while a LAN address arrives from config. So a driver claiming local must build no request against a public hostname, and one claiming cloud must name the service it needs. On the current catalog it separates exactly the three from the other 77 — verified in both directions. A cloud driver must also record what its vendor demands, so nobody meets the account requirement only after installing.

No driver version moves — and why that is not the same call as #53

#55 had to version the ders correction from #53 because ders reaches the published bytes. These two fields do not: ftw_repository._load_channel copies an explicit allowlist into the artifact metadata (ders, protocol, manufacturer, model_family, and the DRIVER table), and connectivity/setup are not in it. So the channel republishes nothing and the release check has nothing to refuse. spec/manifest-v2.md records that, next to the CONTRIBUTING rule it qualifies.

If a host should ever see these fields at install time, that is a deliberate follow-up which does cost a version bump per driver.

Where a bridge ends and a device begins

bridge is a translator that is neither the device nor the vendor's own gateway product: a HeishaMon board, OpenDTU, an ESPHome build, TeslaBleHttpProxy, a serial-to-Ethernet bridge. A gateway the customer buys as part of the system — the Sourceful Zap, a Ferroamp EnergyHub — is the device. esphome_dsmr's own header draws exactly this line against zap.lua, so the rule is the repository's, not mine.

Ferroamp's local MQTT is granted per site on request, which is what vendor_approval exists for, but nothing in the repo states it — so it stays unrecorded rather than asserted.

Verification

• validate_manifest.py: 80 manifests, 0 errors
• pytest tests/: 614 passed, 60 skipped (was 293 before this branch; +321 new parametrised cases). One pre-existing Windows-only failure in test_blueprint.py, which invokes bash with a Windows path and fails identically on an untouched tree
• Page rebuilt with generate_site.py and inspected in the built output: Reach column present, both filter groups rendered (Local only / Needs the internet, and the five gates present), badges and the "To set up" card row in place. devices.yaml and the support status regenerate unchanged

🤖 Generated with Claude Code