homebridge-echonet-hvac

homebridge-echonet-hvac

A Homebridge plugin for fully local control of ECHONET Lite HVAC units — in particular Mitsubishi Electric heat pumps fitted with a MAC-568/578/588IF-E Wi-Fi interface, common in New Zealand and Australia. There is no cloud dependency and no MELCloud account required — the plugin talks directly to your unit over your local network using the ECHONET Lite protocol.

Features

• Fully local — works with the vendor cloud unreachable, and keeps working if it goes away.
• HeaterCooler accessory per unit: power, auto/heat/cool, target temperature, current temperature, and fan speed.
• Fan speed with your unit's discrete levels, including automatic — represented either as the top of the slider (default) or as a separate Auto Fan switch.
• Dry and fan-only modes — which HomeKit cannot express on a heater-cooler — as optional switches.
• Outdoor temperature as a separate sensor accessory, for units that report it.
• Capability probing: every control is created only if the unit's own property maps advertise support for it. Units with different firmware get different (correct) accessories.
• Responsive updates via ECHONET push notifications, with polling for the properties units don't announce — or poll everything with alwaysPoll if your network drops multicast.
• Resilient: units are matched by their ECHONET identification number (accessories survive DHCP address changes), restored from cache when offline, and marked "not responding" rather than served stale.

Prerequisites

1. ECHONET Lite must be enabled on the unit first. On Mitsubishi Electric AU/NZ units it is off by default. Enable it in the official Wi-Fi Control app under [Edit Unit]. Only the MAC-568IF-E interface and newer support ECHONET Lite — see mitsubishi-electric.co.nz/wifi/learn_echonet.aspx for details.
2. UDP port 3610 must be open and reachable between the machine running Homebridge and the unit. This is the single most common cause of support issues — check firewalls, VLANs, and Wi-Fi client isolation if the plugin can't find or control your unit.
3. Security warning: ECHONET Lite has no authentication and no encryption whatsoever. Anyone who can reach UDP port 3610 on your unit can control it. Only run this on a trusted network or VLAN, not on shared or untrusted networks.

Known protocol limitations

• Temperatures are whole degrees Celsius only. This is a limitation of the ECHONET Lite protocol itself — the half-degree steps available in Mitsubishi's own apps are not exposed over ECHONET Lite. The plugin rounds predictably rather than faking half-degree precision.
• One setpoint. The protocol has a single target temperature, so HomeKit's heating and cooling thresholds both read and write the same value.
• Zone control is not possible. ECHONET Lite does not expose per-zone control, so multi-zone ducted systems can only be controlled as a single unit. This is out of scope for this plugin.
• Fan level count is not discoverable. ECHONET cannot report how many fan speeds a unit has; set fanSpeeds to match your remote (default 5).

Installation

Not yet published to npm. Once available, install via the Homebridge UI or:

npm install -g homebridge-echonet-hvac

Requires Homebridge 2 and Node 22 or 24.

Configuration

Configure via the Homebridge UI, or in config.json:

{
  "platforms": [
    {
      "platform": "EchonetHVAC",
      "name": "Echonet HVAC",
      "devices": [
        { "ip": "192.168.1.50", "name": "Living Room" }
      ],
      "pollInterval": 30
    }
  ]
}

Option	Default	Description
discover	true	Find units automatically with multicast. Turn off to use only the listed devices.
devices	[]	Units to connect to directly: { "ip": "…", "name": "…" }. Needed when multicast discovery cannot reach them (separate VLANs, IGMP-snooping switches). name sets the HomeKit display name.
pollInterval	30	Seconds between state polls (5–3600).
alwaysPoll	false	Poll every property instead of trusting push notifications. Turn on if changes made with the IR remote take a long time to appear in HomeKit.
fanSpeeds	5	Number of discrete fan levels your units support (check the remote).
fanAuto	"notch"	How automatic fan speed appears: "notch" = top of the fan slider; "switch" = a separate Auto Fan switch.
exposeDry	true	Switch that puts the unit into dry (dehumidify) mode. Turning it off powers the unit down.
exposeFanOnly	true	Switch that puts the unit into fan-only mode. Turning it off powers the unit down.
outdoorTemperature	true	Separate temperature sensor accessory for units that report outdoor temperature.

Running as a child bridge

Running this plugin as a child bridge is recommended: it keeps the plugin's UDP socket and polling isolated from other plugins, and a misbehaving network can never affect the rest of your bridge. Enable it from the plugin's settings in the Homebridge UI.

Troubleshooting

• No units found: almost always multicast not reaching the units. Add each unit's IP address under devices — direct queries don't need multicast. Confirm ECHONET Lite is enabled (prerequisite 1) and UDP 3610 is open (prerequisite 2).
• Probe the network yourself: npm run discover (from a checkout) sends a discovery query and dumps every responding unit's supported properties and current values. Use npm run discover -- --ip <address> to query a unit directly.
• State updates are slow after using the remote: your network is likely dropping the units' multicast notifications; set "alwaysPoll": true and/or lower pollInterval.
• Unit shows "Not Responding": the unit stopped answering UDP 3610 — power-cycle the unit's Wi-Fi adapter, and check nothing else on the machine is bound to port 3610.

Development

npm run build      # compile
npm test           # protocol-layer tests (golden frames from real hardware; no hardware needed)
npm run discover   # find units on the LAN and dump their properties
npm run monitor    # watch units' state changes live (read-only)
npm run watch      # run a development Homebridge with the plugin (test/hbConfig)

Credits

This plugin was informed by, and would not have been possible without, the work of:

• homebridge-echonet-lite-eolia by hamkichi — a reference for discovering ECHONET Lite HVAC devices on the local network.
• pychonet by Scott Phillips — the source of ECHONET Lite device knowledge and EPC (Echonet Property Code) maps used to interpret and control HVAC units.

See NOTICE for full attribution details.

License

Apache-2.0 — see LICENSE.