One temperature per room on a Mitsubishi MXZ multi-split — MXZ Coordinator (HACS)

Share your Projects! Custom Integrations
1

I built an integration for a problem that quietly ruins Mitsubishi MXZ multi-zone
systems, and after a fast, brutal public beta cycle on real hardware it’s stable — so here it is:
MXZ Coordinator.

Repo: GitHub - dkpnw/ha-mxz-coordinator: Home Assistant coordinator for Mitsubishi MXZ multi-zone mini-splits — fixes the AUTO idle-head deadlock; one explicit shared mode + a single target per room. · GitHub (MIT · HACS · one-click config flow · 2–8 heads per outdoor unit)

Two rooms as single-target dials plus the coordinator's live decision state
Two rooms as single-target dials plus the coordinator's live decision state972×486 66.9 KB

The problem: stock AUTO starves rooms

An MXZ outdoor unit has one compressor and one reversing valve — it can heat or cool at
any moment, never both. In hardware AUTO, each head votes from its own room, and an idle
head can hold the whole system neutral while another room calls and gets nothing.
Mitsubishi’s own manuals say not to run AUTO on an MXZ. Most people find that out the
hard way.

I measured it on my system: a room 6 °F past its cooling target drew ~26 W for over an
hour — parked in standby — because the other head was satisfied. The moment I turned
that satisfied head off, the starved room ramped to ~460 W and cooled. Coordinated, the
same scenario serves both rooms within minutes.

What it does

The coordinator becomes the sole writer of your heads, and three rules replace the
stock logic:

  1. Never hardware AUTO. Every head runs one explicit shared mode — cool or heat —
    chosen from your real room temperatures against your targets.
  2. A satisfied room steps aside. It idles in fan_only, which closes that head’s
    refrigerant valve (it’s in the service manual), instead of blocking its neighbors.
  3. When rooms disagree, your priority wins. The room you ranked first gets its mode;
    the other coasts. A 10-minute lockout gates every mode flip, so nothing oscillates.

On top of that, the parts I ended up caring about most day-to-day:

  • One number per room, Tesla-style — set a temperature, and mode, fan, and
    arbitration happen in the background. Clean single-setpoint tiles for
    HomeKit/Google/Assist.
  • A fan that responds to need — runs harder the farther the room is from target,
    eases off as it arrives, and returns to auto when satisfied. Pick a speed by hand and
    it’s your hold — the coordinator stops touching that fan until you hand it back (a
    per-room Fan auto switch bridges the handback into Apple Home). Holds survive
    restarts.
  • Local-weather changeover — point it at any weather.* entity and heating locks out
    in the warm season, cooling in the cold one, from your own forecast. No calendar, no
    cloud.
  • It tells the truth — a plan sensor exposes every decision input live (per-room
    demand, who’s coasting, who holds the fan), so “why did it do that?” always has an
    answer. If your firmware publishes real blower speed (CN105/ESPHome does), the tile
    shows actual airflow instead of freezing on the last commanded speed.
  • It doesn’t break — self-heals a head knocked off plan, fails to neutral on sensor
    dropout, survives restarts, clamps every setpoint to what each head actually accepts
    (including the °F/°C rounding trap where a head advertises 79 °F but rejects it),
    and one kill-switch hands your heads back instantly, frozen where they were.

Validation, honestly stated

Built and run in production on my own 2-zone system; validated through a public beta
cycle on a second real system — a 3-zone with single-setpoint heads, whose owner’s
bug reports are all regression tests now. 6-zone and 2×3-zone systems run it in the
field. The repo already carries fixes from users on hardware I don’t own (a ducted air
handler surfaced two real ones — both fixed within the day). ~200 tests, every bugfix
pinned by a regression test.

Works with any integration that exposes standard climate entities with heat/cool
modes. Built and validated against
echavet/MitsubishiCN105ESPHome;
Kumo Cloud and MELCloud expose the same entity type and should work, but are untested —
reports welcome. One requirement: a temperature sensor entity per room (a $20 Bluetooth
thermometer is the good answer — the head’s own thermistor reads warm when idle).

Install

  1. HACS → ⋮ → Custom repositories → add
    https://github.com/dkpnw/ha-mxz-coordinator, category Integration → Download.
    (A default-store submission is in HACS’s review queue.)
  2. Restart Home Assistant.
  3. Settings → Devices & Services → Add Integration → MXZ Coordinator — pick your
    heads (2–8; order is priority) and one room sensor per head. Vanes and airflow
    sensors are auto-detected; every option is shown at setup, pre-filled with sensible
    defaults. °F and °C both native.
  4. Turn on Coordinator enable, set each room’s target, enable the rooms. Done — no
    YAML.

Feedback welcome

If you’ve got an MXZ and a room that mysteriously never gets conditioned, this is
probably why, and I’d love to hear how the coordinator behaves on your hardware —
especially other head models/firmware. Issues, PRs, and “here’s what happened on my
setup” reports all welcome on the repo; the last three came from strangers and every one
made it better.

Built with AI assistance (Claude); every line reviewed, tested, and run in production on
my own system. Shared as-is, support is best-effort — but the issue tracker gets read.