Otonomo — Home Assistant integration (v0.1)

Surfaces Otonomo's canonical-schema metrics as Home Assistant entities, auto-discovered from your Otonomo box's local MQTT broker.

Status

v0.1 — read-only. Sensors only; switches / per-capability override controls land in v0.2 once the local cmd contract is HTTP-exposed.

What it does

For every metric flowing on hems/<box_id>/telemetry/#, the integration creates a sensor entity with:

Friendly name + unit + device class from the canonical-schema lookup (Solar now, Battery, Hot water tank, Grid, EV power, …)
Auto-discovery — no YAML, no template sensors. Plug it in, entities appear as data flows.

What it doesn't do (yet)

Writes — no service calls to flip capabilities or set setpoints. Drives one-way: Otonomo → HA. v0.2 adds the other direction.
Cloud fallback — talks only to the LAN broker. For HA installs that can't reach the box's network, use the cloud REST sensor pattern documented in docs/otonomo_install_modes_detailed.md §5 Path B.
Driver setup — configure drivers on the Otonomo box first (via the local /drivers wizard, or by editing site_manifest.yaml). Only metrics from configured drivers show up.

Installation

Via HACS (recommended, once published)

Open HACS in Home Assistant.
Add https://github.com/otonomo/ha-otonomo as a custom repository.
Install Otonomo, restart HA.
Settings → Devices & Services → Add Integration → Otonomo.
Enter your box IP (e.g. 192.168.1.42) and box-id (e.g. hems-900037, shown on your Otonomo dashboard).

Manual

Copy custom_components/otonomo/ to your HA config/custom_components/ directory, restart HA, then run the config-flow step above.

Requirements

Home Assistant 2024.6 or newer.
HA's mqtt integration installed and configured. It does not need to point at the Otonomo broker as its primary — we subscribe through HA's MQTT helper so multiple brokers work in parallel.
Network: HA must be able to reach the Otonomo box on TCP/1883. If they're on different VLANs, open that port or use the cloud REST fallback.

How metric → entity mapping works

The integration listens on hems/<box_id>/telemetry/#. Each MQTT message looks like:

{
  "ts":         1716638400000,
  "box_id":     "hems-900037",
  "driver":     "vaillant_ebus.boiler",
  "metric_id":  "dhw.temp_c",
  "value":      47.2,
  "quality":    "ok"
}

The first time a new metric_id is seen, an entity is created. The entity name + unit + device class come from metric_metadata.py:METRICS — anything not in that table surfaces as a generic numeric sensor with the metric_id as its name.

A quality: "unavailable" message maps the entity state to unknown, so sensor-down vs sensor-reads-zero stays distinguishable.

Troubleshooting

Problem	Likely cause
No entities appear after setup	Otonomo box has no drivers configured yet, or its publisher is not running. SSH and check `systemctl status otonomo-publisher`.
Connection error in config flow	TCP/1883 blocked between HA and the box. Verify with `nc -vz <box-ip> 1883` from the HA host.
Entity stuck at last value	Battery sensor (Shelly H&T) — those publish only every 30–45 min. Compare to other entities to confirm it's a sensor cadence issue, not a broker issue.
Some entities missing for known hardware	The driver for that hardware isn't installed or configured on the Otonomo box. Open the box's local UI at `:8080/drivers`.

Roadmap

v0.2 — per-capability override switches: customer toggles switch.otonomo_dispatch_enabled and the cloud cuts that capability from active optimization for as long as the switch is off.
v0.3 — direct setpoint writes for heat-pump / boiler / DHW target temperatures from HA automations.
v0.4 — energy dashboard wiring (HA's built-in Energy panel picks up pv.energy_today_kwh, grid.import_today_kwh, etc. automatically once we tag them with the right state_class).

License

Apache-2.0. Source: installer/ha_integration/ in the otonomo_drivers repo.