Open Driver SDK — pointer

Built 2026-05-13. The open driver platform lives at otonomo_drivers/ in this repo. It's intentionally isolated from the deploy paths (deploy_cloud.sh only ships cloud/app/; deploy_pi.sh only ships pi_energy_control/) so it won't accidentally end up anywhere yet. Future move: extract to github.com/otonomo/drivers once the brand and website are ready (BOIP opposition window closes ~2026-07-04).

What's in there

Layer	Lives at	Notes
Driver SDK base classes	`otonomo_drivers/otonomo_sdk/`	`Driver`, `Metric`, `Command`, `CommandResult`, `Capability`, `DriverStatus`, schema validator, dynamic loader, wire codec, site manifest loader
MQTT publisher + cmd subscriber	`otonomo_drivers/otonomo_sdk/mqtt/`	`MqttPublisher` (drives driver.poll() loop, emits wire-protocol v1 frames, retained site/manifest, LWT) + `MqttCommandSubscriber` (routes hems//cmd/ to driver.execute(), publishes replies, dedup + deadline guards). Optional dep: `pip install otonomo-sdk[mqtt]`.
Canonical metric schemas	`otonomo_drivers/otonomo_sdk/schemas/*.yaml`	10 device classes: pv_inverter, battery, grid_meter, heat_pump, gas_boiler, ev_charger, smart_plug, temperature_sensor, dehumidifier, smart_light
Reference drivers (home environment)	`otonomo_drivers/drivers/`	6 stable: solaredge_modbus, vaillant_ebus, daikin_local, shelly_rpc, qlima_local, wlbox2_local
Reference drivers (prospect environment, hems-900100)	`otonomo_drivers/drivers/`	alphaess_modbus (battery+inverter), vaillant_eebus (HP, read-only), control4_director (lights), smappee_mqtt (submeter), homewizard_p1 (grid_meter — LIVE 2026-06-08)
Grid-meter reference drivers	`otonomo_drivers/drivers/homewizard_p1/` + `otonomo_drivers/drivers/youless_p1/`	Both `grid_meter` device class, `beta`. homewizard_p1 v0.2.0 (local REST, 1 s poll, validated on hems-900100); youless_p1 v0.1.0 (local REST, frequency caveats in README).
Wire protocol v1.0 spec	`otonomo_drivers/docs/wire_protocol.md`	MQTT topic structure + canonical JSON payload shapes + security model
Site manifest example	`otonomo_drivers/examples/sites/home-brasschaat.yaml`	14 instances covering every device in the reference home
`otonomo` CLI	`otonomo_drivers/otonomo_sdk/cli.py`	`new-driver`, `validate`, `site validate`, `site capabilities`
Test suite	`otonomo_drivers/tests/`	126 tests, all green; SDK + every driver + wire + site manifest + CLI

How drivers know what to publish, cloud knows what to expect

The seam is the canonical metric schema in otonomo_drivers/otonomo_sdk/schemas/. Every PV inverter driver must emit pv.ac_power_w, pv.energy_today_wh, inverter.status regardless of brand. Vendor-specific quirks (SolarEdge meter offset 18 drift, eBUS authorization levels, QLIMA compressor temp contamination, etc.) are buried inside each driver's poll() implementation. Cloud control logic reads only canonical names; brand names never appear above the driver layer.

How driver capabilities reach the Pro UI

The chain is documented in detail in hems_capability_platform_plan_2026_05_13.md. Short version:

site manifest YAML
    ↓ (otonomo_sdk.site.load_site_manifest)
parsed SiteManifest
    ↓ (otonomo_sdk.site.derive_capabilities)
set[str] of capability names
    ↓ (published to hems/<box>/site/manifest, ingested by cloud)
ops-db.box_capabilities
    ↓ (queried by cloud/app/blocks/capabilities.py)
visible Pro UI tabs for this box

Status and publication

Public release: ON HOLD until the website + reference content is ready (the user's call: "no public stuff just yet"). Brand assets, BOIP word-mark status, otonomo.be reference content all need to land first.
Internal use: the SDK is the source of truth for driver behavior going forward. Phase C of the capability platform plan migrates the home Pi to this SDK.

When the time comes to publish

The extraction is mechanical:

git filter-repo --subdirectory-filter otonomo_drivers/
# push to github.com/otonomo/drivers
# publish to PyPI: otonomo-sdk + otonomo-driver-<name> for each driver

Until then, treat it as a private library that happens to be Apache 2.0 licensed.

Why this is in the main repo, not a separate one yet

Three reasons:

Active iteration on the contract — easier when drivers + cloud + spec are all in one place.
The "vendor-everything" rule applies once we ship to customers; until then, the SDK can be imported directly without PyPI plumbing.
The extraction is one command (git filter-repo) whenever we want.