@luftloch/homebridge-mideaportasplit

Homebridge plugin that exposes the Midea PortaSplit air conditioner (and other Midea 0xAC appliances) to Apple HomeKit as a HeaterCooler accessory.

Control happens entirely over your local network using Midea's LAN protocol (TCP port 6444, protocol "V3"). Your Midea SmartHome (MSmartHome) account is contacted once per device to fetch the token/key pair required for the local handshake; after that the credentials are cached and no cloud connection is needed.

Features

• Power, mode (Auto / Cool / Heat), target temperature (16–31 °C in 0.5° steps)
• Current indoor temperature
• Fan speed (slider: 0 = Auto, then Silent/Low/Medium/High/Full in 20% steps)
• Louvre swing
• Temperature display units (°C/°F on the unit's panel)
• Optional: Boost (Turbo) switch, outdoor temperature sensor
• Automatic discovery via UDP broadcast, plus manual IPs for devices on other subnets/VLANs

Installation

npm install -g @luftloch/homebridge-mideaportasplit

or search for "Midea PortaSplit" in the Homebridge UI after publishing.

From this repository

npm install
npm run build
npm link

Then add the platform to your Homebridge config.json.

Homebridge UI

After installing the plugin, open Homebridge UI → Plugins → Midea PortaSplit → Settings. The form is driven by config.schema.json and groups account login, HomeKit features, optional devices, and advanced intervals. Changes are written to your Homebridge config.json.

Configuration

Minimal config.json platform block:

{
  "platform": "MideaPortaSplit",
  "name": "Midea PortaSplit",
  "account": "[email protected]",
  "password": "your-msmarthome-password"
}

All options:

| Option | Default | Description | | ------ | ------- | ----------- | | account / password | – | Midea SmartHome (MSmartHome) app login. Used only to fetch local credentials. | | refreshInterval | 30 | Seconds between status polls. | | heartbeatInterval | 10 | Seconds between keep-alive heartbeats. | | promptTone | false | Unit beeps on every command. | | boostSwitch | false | Adds a separate "Boost" switch. | | outdoorTemperatureSensor | false | Adds a temperature sensor for the outdoor coil sensor. | | swing | "vertical" | Which louvre axes the HomeKit swing toggle drives (vertical, horizontal, both, none). | | devices | [] | Per-device entries: ip, name, and optional manual token/key (hex). With manual credentials the cloud account is not needed at all. |

Fan speed mapping

HomeKit's fan slider maps to the PortaSplit's discrete speeds: 0 % = Auto, 20 % = Silent, 40 % = Low, 60 % = Medium, 80 % = High, 100 % = Full.

Manual credentials (no cloud)

If you already have a device token/key (for example from Home Assistant / msmart-ng):

{
  "platform": "MideaPortaSplit",
  "name": "Midea PortaSplit",
  "devices": [
    {
      "ip": "192.168.1.50",
      "name": "Living Room AC",
      "token": "YOUR_TOKEN_HEX",
      "key": "YOUR_KEY_HEX"
    }
  ]
}

Troubleshooting

• Device not found — the plugin discovers devices with a UDP broadcast (ports 6445/20086). If your AC is on another subnet or VLAN, add its IP under devices. Make sure the AC is connected to Wi-Fi in the Midea SmartHome app first.
• Authentication fails — double-check the account/password. The plugin tries both udpid variants (little/big endian) automatically. Enable Homebridge debug mode (-D) for details.
• "No Response" in the Home app — the plugin marks the accessory unavailable when the TCP connection drops; it reconnects automatically with backoff.

Development

npm install
npm test
npm run build

Protocol attribution

The Midea LAN/cloud protocol used here was reverse-engineered by the community. This implementation was written with reference to:

• kovapatrik/homebridge-midea-platform
• georgezhao2010/midea_ac_lan / wuwentao/midea_ac_lan
• nbogojevic/midea-beautiful-air
• mill1000/midea-msmart

Many thanks to those authors.

License

MIT