❄️ homebridge-gree-unified

A complete Homebridge plugin for Gree air conditioners. One HomeKit tile per AC with the full feature set in a single accessory — no switch-clutter on your room screen.

🎛️ Thermostat + 7 switches inside a single tile — Screen · Sleep Mode · Ionizer · Boost · Silent · Dry Coil · Eco

What it exposes

Each AC becomes one accessory with:

• HeaterCooler (primary tile) — power, mode (Auto / Cool / Heat), target temp, current temp, fan speed slider (Auto + 5 steps), swing toggle
• 7 built-in switches inside the same tile:
  • Screen — front-panel LED on/off (perfect for "display off at night" automations)
  • Sleep Mode — quieter, gentler overnight operation
  • Ionizer — Cold Plasma / health mode
  • Boost — Turbo / max-power
  • Silent — lowest fan noise
  • Dry Coil — post-cooling fan to dry the evaporator (prevents mildew)
  • Eco — energy-saving mode

Auto-discovery over UDP, per-device request locking so simultaneous HomeKit writes never race, ghost devices can be filtered by MAC.

Why this exists

The existing homebridge-gree-ac plugin is great for the basics but doesn't expose Display Light, Sleep, Health, Turbo, Quiet, X-Fan or Energy Saving. Adding those as a second plugin means 7 loose switch tiles per AC on your room screen. This plugin gives you all of it inside a single clean tile, like the Xiaomi and Ariston HomeKit integrations do.

Install

npm install -g homebridge-gree-unified

Or from the Homebridge UI → Plugins → search "Gree Unified" → Install.

Config

Add to config.json under platforms:

{
  "platform": "GreeUnified",
  "name": "Gree",
  "pollInterval": 15,
  "broadcast": "192.168.1.255",
  "minTemp": 16,
  "maxTemp": 30,
  "devices": [
    { "mac": "f4911ed3ebde", "name": "Living Room AC" },
    { "mac": "f4911ed504ac", "name": "Bedroom AC" },
    { "mac": "f4911ed50002", "name": "Office AC" }
  ]
}

Or configure it from the Homebridge UI — config.schema.json ships with the plugin.

Options

| Key | Default | Notes | |---|---|---| | broadcast | 255.255.255.255 | Use your subnet broadcast (e.g. 192.168.1.255) for reliability | | pollInterval | 15 | Seconds between state refreshes per AC | | minTemp / maxTemp | 16 / 30 | HomeKit slider bounds (°C) | | devices[].mac | — | MAC as shown in Gree / Ewpe Smart app (lowercase, no separators) | | devices[].name | — | Shown as the HomeKit accessory name |

If devices is empty, all discovered ACs are added automatically. If devices is provided, only those MACs are used — unknown ACs on the LAN are ignored (handy for filtering neighbours' units).

🗣️ Siri

Because each AC is a standard HomeKit HeaterCooler, Siri understands it out of the box — no setup, no Shortcuts needed. Some examples:

| Say | What happens | |---|---| | "Hey Siri, turn on the Living Room AC" | Powers it on | | "Hey Siri, turn off the Bedroom AC" | Powers it off | | "Hey Siri, set the Office AC to 22 degrees" | Sets target temperature | | "Hey Siri, set the Living Room AC to cool" | Switches to Cool mode | | "Hey Siri, set the Bedroom AC to heat" | Switches to Heat mode | | "Hey Siri, set all air conditioners to 23 degrees" | Targets every AC at once | | "Hey Siri, what's the temperature in the Bedroom?" | Reads back the AC's current temp sensor |

Siri for the extra switches (Screen, Sleep Mode, Boost, etc.)

Siri can trigger the inner switches too, but because multiple ACs share the same switch names (e.g. every AC has a "Screen"), qualify with the room:

• "Hey Siri, turn off Screen in the Bedroom"
• "Hey Siri, turn on Sleep Mode in the Living Room"
• "Hey Siri, turn on Boost in the Office"

Pro tip: one-shot scenes

For the best Siri experience, create a Home app Scene that wraps several actions, then call the scene by name:

• "Good Night" scene → Bedroom AC 21°C + Sleep Mode on + Screen off
• "Movie Time" scene → Living Room AC 23°C + Silent on + Screen off
• "Leaving" scene → all ACs off

Then just say "Hey Siri, good night" and the whole AC state flips in one shot.

HomeKit mode mapping

HomeKit's HeaterCooler only supports Auto / Cool / Heat. Dry and Fan-only modes on the AC are still respected if set from the physical remote — the plugin just shows them as Cool / Auto respectively in Home app.

Finding your AC's MAC

• Gree+ or Ewpe Smart app → device info → MAC
• Or just install the plugin with no devices, check the Homebridge log — it will print every discovered MAC on the LAN.

Troubleshooting

• Switches don't respond — HomeKit won't send writes to a powered-off HeaterCooler. Turn the AC on first, then try the switches.
• "Gree request timed out" in log — AC is offline or on a different VLAN. Verify the MAC's IP is reachable with ping.
• Feature has no effect on your unit — not all Gree firmwares support all features (especially Turbo / Quiet in certain modes). The AC silently ignores unsupported commands.

Credits

Protocol reverse-engineering shoulders-of-giants credit goes to the homebridge-gree-ac and gree-hvac-mqtt-bridge projects.

License

MIT