homebridge-gree-hvac

Controls Gree and rebadged air conditioners from Apple Home, over UDP on your own network. No cloud account, no bridge hardware, no dependency outside Node.js itself. Units are found on their own: MAC address, name, model, IP address and encryption version all come from the unit.

What appears in HomeKit

One accessory per air conditioner, in the Air conditioner category.

| Service | What it carries | |---|---| | Heater Cooler | On/off, mode, current temperature, heating and cooling thresholds, fan speed, swing, display units, physical control lock | | Temperature sensor | Room temperature, plus Status Active and Status Fault | | Switches, on by default | Quiet, Turbo, Automatic fan, Dehumidify, Fan only, X-Fan, Sleep, Display light | | Switches, optional | Health/ioniser, Fresh air, Frost protection (8 °C), Energy saving, five vertical louvre positions, five horizontal louvre positions |

The fan slider covers the five real speeds only, at 20 % per step, with 0 % meaning automatic. Quiet, Turbo and automatic are independent properties of the unit, not extra notches on the slider: flattening them into one control makes the slider jump under your finger and hides which of the three is actually in effect. They get their own switches instead.

What this plugin does differently

Every row below comes from measurements taken on real units, not from reading other implementations. Several widely copied assumptions turned out to be wrong on this hardware.

| Point | Here | Commonly found elsewhere | |---|---|---| | Half-degree setpoint | SetTem + (Add0.5 × 0.5), established against a control unit | The TemRec bit, which does not carry the half degree on this firmware | | Quiet | Three states (off / auto / quiet); the value that really turns it on is 2 | A boolean, often writing 1, which the unit stores without turning quiet on | | Quiet, Turbo and fan speed | Every speed command carries Quiet:0, Tur:0 in the same opt | Sent separately, or not at all — the firmware enforces no exclusion, so asking for the lowest speed leaves Quiet on | | A unit that changes IP | Re-resolved from its MAC address, automatically | IP read once at start-up; the unit silently stops answering | | Encryption | V1 (AES-128-ECB) and V2 (AES-128-GCM), detected from the reply itself | A manual setting you have to get right | | Sockets | One UDP socket for the whole house | One per unit, plus one for discovery | | A malformed packet | Every datagram callback is wrapped; the packet is dropped | An uncaught exception in the socket callback terminates Homebridge, taking every other plugin with it | | A short network outage | Last known state is kept and the fault is raised on the temperature sensor | No Response, which is sticky: the Home app can stay blank long after the network is back | | Characteristic bounds | Re-applied at every start-up, including on accessories restored from cache | Written once; a cached accessory keeps stale bounds for life, which is where 26 exceeded maximum of 25 comes from | | Binding failure | Retried forever, 5 s to 300 s | Given up after a couple of tries, requiring a manual restart | | Configuration | Three optional fields per unit, everything else discovered | Twenty fields, MAC and IP included | | Dependencies | None. node:dgram, node:crypto, node:events | A cryptography package, sometimes a whole HTTP stack |

Supported hardware

Gree makes the Wi-Fi module found in a long list of rebadged units. Attested here:

• Gree (Gree+ app)
• Sinclair
• Inventor
• Any unit whose Wi-Fi module pairs with EWPE Smart — that is the reliable test, more so than the brand printed on the front panel.

If your unit is controlled by the Gree+, EWPE Smart or Sinclair app on your phone, it speaks this protocol. Brands sometimes listed by other projects without corroboration are deliberately not claimed here.

Not every unit has every feature. Two things in particular cannot be detected, because the protocol accepts and echoes back the commands even where no motor exists: side louvre swing and the half-degree setpoint. Both stay declarative, per unit, in the settings.

There is no outdoor temperature, no self-clean and no anti-direct-blow on this hardware. Those fields were probed one by one and the units do not answer them, so the plugin does not pretend to offer them.

Requirements

• Homebridge 1.8 or later, including Homebridge 2.
• Node.js 22 or 24.
• Homebridge and the air conditioners on the same IP subnet, or reachable directly (see Discovery below).

Installation

The Homebridge UI is the supported path: Plugins → search homebridge-gree-hvac → Install.

From a terminal on an hb-service installation:

sudo hb-service add homebridge-gree-hvac

Run it as a child bridge

Recommended, and it takes ten seconds: open the plugin's ⋮ menu in the Homebridge UI and choose Bridge Settings → Child Bridge. The plugin then runs in its own process, so an air conditioner that misbehaves cannot disturb the rest of your Homebridge instance. You will be asked to pair the child bridge once in the Home app.

Configuration

The minimum is one line. Everything else is discovered:

{
  "platforms": [
    {
      "platform": "GreeHVAC",
      "name": "Gree HVAC"
    }
  ]
}

A fuller example, for a house where only one unit has side louvres and applies half degrees:

{
  "platforms": [
    {
      "platform": "GreeHVAC",
      "name": "Gree HVAC",
      "pollInterval": 30,
      "services": [
        "temperatureSensor", "quiet", "turbo", "fanAuto",
        "dry", "fanOnly", "xfan", "sleep", "light"
      ],
      "devices": [
        {
          "mac": "502cc628dc5a",
          "horizontalSwing": true,
          "temperatureStep": 0.5
        }
      ]
    }
  ]
}

| Setting | Default | Notes | |---|---|---| | pollInterval | 30 | Seconds between state reads, 15 to 600. A ±20 % jitter keeps units from being polled on the same second. Polling faster saturates the Wi-Fi module and causes dropouts. | | services | the nine listed above | Controls only the extra switches. The air conditioner itself is always exposed. | | devices[].mac | — | Printed in the Homebridge log by discovery. Separators optional. | | devices[].horizontalSwing | false | Tick only if the side louvres really move. Nothing can be detected. | | devices[].temperatureStep | 1 | 0.5 if half degrees are visibly applied by the unit. | | devices[].encryptionVersion | auto | Last resort. Detection is expected to work everywhere. | | broadcastAddresses | 255.255.255.255 | Your subnet's broadcast address, for containers or multi-homed hosts. | | unicastAddresses | — | A unit that broadcast cannot reach, on another subnet or behind a router. |

A unit that is not listed in devices is still discovered and controlled. Add an entry only to change one of the answers above.

Discovery

At start-up the plugin broadcasts a scan on UDP port 7000 and adopts everything that answers, then rescans every five minutes to catch units that were off and IP addresses that changed. Units already known are also queried directly, because some routers filter broadcast traffic.

Accessories restored from the Homebridge cache start being polled immediately, without waiting for the first scan, so control is back as soon as Homebridge is up.

A unit that stops answering is not removed. It keeps its accessory, its last known state, and raises the fault flag on its temperature sensor. An air conditioner that is unplugged for the winter is not an air conditioner you have thrown away.

About "100 % local"

Control is genuinely local. Commands, state reads and encryption keys never leave your network, and the plugin talks to no server of ours, of Gree's, or of anyone else's.

That is not the same as saying the air conditioner is offline. The Gree Wi-Fi module keeps its own connection to the Internet, independently of this plugin, and some firmware versions do not cope well with losing it: units have been reported to stop answering local commands, or to reboot their Wi-Fi module in a loop, hours or days after being blocked at the firewall.

If you want the units off the Internet anyway, expect to do it carefully rather than with a single blanket rule:

• Block outbound traffic from the units, and watch them for a few days before assuming it worked. Failures show up late.
• Keep ICMP to the gateway allowed. Several firmware versions use it to decide whether the network is up at all, and go into a reconnection loop when it fails.
• Answer, rather than drop. A local DNS override plus a dummy responder on the ports the module dials tends to keep it happy where a silent DROP does not. Silence is what upsets it.
• NTP matters. The module carries a clock and uses it; leave it a time source it can reach, local if you prefer.

None of this is required for the plugin to work — a unit with normal Internet access is controlled locally all the same, and never through a server. It is here so that nobody blocks their air conditioners on a promise this hardware does not keep.

Troubleshooting

| Symptom | What to check | |---|---| | No accessory appears | The log line Looking for air conditioners on the local network. should be followed within a minute by one discovered line per unit. If not, Homebridge is probably on a different subnet or in a container: set broadcastAddresses to your subnet's broadcast address, or list the units in unicastAddresses. | | One unit missing | It is off, or on a different subnet. Add its IP to unicastAddresses. | | Accessory present but greyed-out details | The unit stopped answering; the temperature sensor carries the fault. The plugin keeps retrying, forever. | | Half degrees ignored | The unit stores Add0.5 but does not apply it. Set temperatureStep back to 1 for that unit. | | Side louvre switches do nothing | That unit has no side motor. The protocol accepts the command regardless. Untick horizontalSwing. | | Lowest fan speed leaves it quiet | Fixed here: every speed command clears Quiet and Turbo in the same message. If you still see it, another controller — the remote, the phone app — is setting it back. | | Unit answers the app but not the plugin | Some units accept only one controller at a time. Close the Gree+ app and restart Homebridge. |

Changelog

CHANGELOG.md.

Support

Bugs and feature requests: GitHub issues.

If this plugin is useful to you, you can ☕ buy me a coffee.

Licence

MIT — see LICENSE. Not affiliated with Gree Electric Appliances, nor with any of the brands that resell its hardware.