# 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)

1. Open HACS in Home Assistant.
2. Add `https://github.com/otonomo/ha-otonomo` as a custom repository.
3. Install Otonomo, restart HA.
4. **Settings → Devices & Services → Add Integration → Otonomo**.
5. 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:

```json
{
  "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.