homebridge-midea-nethome

Homebridge plugin for Midea air conditioners — the ones you control with NetHome Plus, MSmartHome, Midea Air, Ariston Clima or OS Comfort.

Units are driven over your local network, so the Home app responds instantly and keeps working during an internet outage. The cloud is used to sign in, list your units and fetch their local keys, and remains available as a command fallback.

Local control is not optional on current hardware. On every protocol-3 unit tested, Midea's cloud relay accepts a command and the appliance never answers it — see docs/protocol.md for the measurements. Put Homebridge on the same network as your air conditioners. The cloud fallback is retained for older protocol-2 modules, which are expected to work but are untested.

Features

• Discovers every air conditioner on your account — no per-device configuration.
• Local control over TCP with automatic cloud fallback, decided per unit and re-checked periodically.
• Changes made on the infrared remote show up in HomeKit immediately on the local path.
• Heater Cooler with heat, cool and auto, half-degree setpoints, and per-mode temperature ranges read from the unit itself — so HomeKit never offers a mode or a temperature your hardware will refuse.
• Optional Fan accessory for fan speed, automatic fan speed and swing, which the Home app cannot show on a Heater Cooler.
• Optional switches for Eco, Turbo, Sleep, Dry and Fan-only.
• Optional indoor and outdoor temperature sensors, carrying fault and connectivity status.

Install

npm install -g @mgcrea/homebridge-midea-nethome

Then add the platform through the Homebridge UI, or by hand:

{
  "platforms": [
    {
      "platform": "MideaNetHome",
      "name": "Midea NetHome Plus",
      "account": "[email protected]",
      "password": "your-password"
    }
  ]
}

Use the same credentials as the app. That is all most setups need.

Configuration

| Option | Default | Notes | | --- | --- | --- | | account, password | — | Required. The same credentials as the app. | | app | netHomePlus | mideaAir, aristonClima or osComfort if sign-in fails. | | useLan | true | Local control. Falls back to the cloud on its own. | | pollInterval | 60 | Seconds. Clamped to a 30-second minimum. | | devices | [] | Pinned { id, host, port } for units broadcast cannot reach. | | exposeFanService | true | Fan speed and swing as a Fan accessory. | | exposeTemperatureSensors | false | Separate indoor sensor. | | exposeOutdoorSensor | false | Outdoor coil sensor, where fitted. | | exposeEcoSwitch … exposeFanModeSwitch | false | One switch each. | | debug | false | Full request trace, with credentials redacted. |

Local control

Local control needs Homebridge on the same network as the units. On protocol-3 firmware it also needs a per-device key that only the cloud can issue, and Midea does not grant this on every account. If yours is one of those, the log says so once per unit.

The cloud hands out a key for either byte order of the device id and only one of them is the key the unit holds; the plugin tries each and remembers which worked, so there is nothing to configure.

If your units sit on a subnet that UDP broadcast cannot cross, list them under devices with their IP addresses. The appliance id appears in the log when a unit is added.

Polling

Some Wi-Fi modules drop off the network entirely when polled hard, and only a power cycle brings them back — hence the 30-second floor. Units on the local path report changes as they happen, so a longer interval costs you very little there.

Development

pnpm install
pnpm test              # lint, typecheck, unit tests, format check
pnpm run build
pnpm run dev:homebridge

pnpm probe runs a live smoke test against a real account and prints what it finds, including whether that account can issue local keys:

[email protected] MIDEA_PASSWORD=secret pnpm probe

The wire protocol — cloud API, local network handshake, and the appliance frame layout — is documented in docs/protocol.md.

Credits

The protocol was pieced together from a packet capture of the official app plus the work of mill1000/midea-msmart, nbogojevic/midea-beautiful-air, kovapatrik/homebridge-midea-platform and reneklootwijk/node-mideahvac.

License

MIT