# Daikin air-to-air heat pump — `daikin_local` setup guide

Tested against the Daikin BRP069A41 WiFi adapter. Compatible with most
recent Daikin split / multi-split / VRV indoor units that ship with or
support the BRP-series LAN module.

---

## Prerequisites

1. **A Daikin BRP WiFi adapter** installed in your indoor unit.
   Look for a small board next to the air-handler PCB with a WiFi LED.
   If yours doesn't have one, retrofit the BRP069A41 (single-zone) or
   BRP069A78 (multi-zone) — ~€80 from a Daikin installer.
2. **The adapter on your network** with a reserved IP. Initial
   bring-up is via the Daikin Online Controller app or by joining its
   AP `DaikinAP*****` and configuring WiFi credentials.
3. **The local API exposed.** This is on by default on the BRP069
   firmware family — verify with:
   ```bash
   curl -fsS "http://<adapter-ip>/aircon/get_basic_info"
   ```
   Should return a single line of key=value pairs (`ret=OK,type=aircon,...`).

If `curl` returns nothing, the adapter's firmware may have disabled
the local API (some newer firmware revisions require enabling it via
the Online Controller → Settings → Allow LAN connection).

---

## Configuring the driver

1. Local UI → `/drivers` → **daikin_local** under "Heat Pump" → **Install**.
2. **Add instance**:

   | Field | Value | Why |
   |-------|-------|-----|
   | Instance ID | `daikin_local.living` (or similar — see Multi-zone below) | Unique |
   | `host` | `192.168.x.y` | Adapter IP (required) |
   | `timeout_s` | `3.0` | Local API typically responds in <500 ms |

3. **Create instance**.

The driver polls every ~10 s; first metrics appear within a minute.

---

## Multi-zone setups

If you have multiple Daikin indoor units (multi-split or
single-adapter-per-unit), add one driver instance PER UNIT. Each
instance:
- Has its own IP (one BRP per unit) OR
- Hits a different sub-path (`/aircon/get_basic_info?room=X`) if you
  have a single multi-zone adapter

Convention: name instances after the room — `daikin_local.living`,
`daikin_local.bedroom`, `daikin_local.office`. The local-UI's
overview groups them all under the heating page.

---

## Verifying

- `http://<box-ip>:8080/device/heating` — Daikin entries grouped with
  any other heat sources.
- `mosquitto_sub -h <box-ip> -t 'hems/+/telemetry/daikin_local.#' -v`

You should see metrics: room temp, target temp, fan speed, mode
(heating/cooling/dry/fan/auto), and on/off state.

---

## Common pitfalls

### "DeviceUnreachable" right after install

The adapter might be sleeping if no one has used the Daikin app
recently. Open the app, do anything, then retry — most BRP firmware
re-activates the local API when the app pings it.

### Two-stage / inverter compressor confusion

Daikin air-to-air inverter units report fan speed but not compressor
modulation — the heat-pump electronics keep that internal. The
`heating.modulation_pct` metric isn't available for daikin_local;
use SCOP estimates from the cloud `/pro/heating` page instead.

### Wrong room temp readings

The BRP reports the indoor unit's intake-air temperature, not the
room's. In rooms with poor air circulation (closed doors, high
ceilings), this can read 2–3 °C off from where you actually are. For
better control, pair with a Shelly H&T placed in the living area —
see `docs/drivers/shelly_rpc.md`. Otonomo's `daikin_orchestrator` in
the cloud will prefer the Shelly reading when both are present.

### DHW won't write (combined heating + DHW Altherma)

`daikin_local` is the **air-to-air** driver. For Daikin Altherma
heat-pump systems (air-to-water with DHW tank), use the upcoming
`daikin_altherma` driver (beta, see roadmap). The local API for
Altherma is at a different endpoint family.

---

## What Otonomo will do with this driver

**Observe mode**: poll mode, setpoint, room temp, fan speed.

**Active mode**, with `Heating setpoints` capability:
- Adjusts mode + setpoint to follow the cloud's room-temp target
  during expensive grid hours (pre-cool when cheap, drift up during peaks)
- Falls back to the customer's last manual setpoint on cloud-watchdog

**Active mode**, with `Cooling` capability (planned v0.3):
- Pre-cool during PV surplus midday, ride the thermal mass through evening

---

## References

- Daikin local API (community-documented):
  https://daikinapi.readthedocs.io/
- BRP069 family teardown + protocol:
  https://github.com/Apollon77/daikin-controller
- Otonomo driver source — `otonomo_drivers/drivers/daikin_local/`

Independent interoperability tool. Not affiliated with Daikin.