Skip to content

MQTT Bridge for controlling Gree smart air conditioners, e.g. with Home Assistant or OpenHAB


Notifications You must be signed in to change notification settings


Repository files navigation

Gree HVAC MQTT bridge

Bridge service for communicating with Gree air conditioners using MQTT broadcasts. It can also be used as a addon.


  • NodeJS (>=11.0.0) with NPM
  • An MQTT broker and Gree smart HVAC device on the same network
  • Docker (for building addon)

Running locally

Make sure you have NodeJS (>=8.11.0) installed and run the following (adjust the arguments to match your setup):

npm install
node index.js \
    --hvac-host="" \
    --mqtt-broker-url="mqtt://localhost" \
    --mqtt-topic-prefix="home/greehvac" \
    --mqtt-username="" \

Supported commands

MQTT topic scheme:


Note: boolean values are set using 0 or 1

Command Values Description
temperature any integer In degrees Celsius by default
mode off, auto, cool, heat, dry, fan_only Operation mode
fanspeed auto, low, mediumLow, medium, mediumHigh, high Fan speed
swinghor default, full, fixedLeft, fixedMidLeft, fixedMid, fixedMidRight, fixedRight Horizontal Swing
swingvert default, full, fixedTop, fixedMidTop, fixedMid, fixedMidBottom, fixedBottom, swingBottom, swingMidBottom, swingMid, swingMidTop, swingTop Vetical swing
power 0, 1 Turn device on/off
health 0, 1 Health ("Cold plasma") mode, only for devices equipped with "anion generator", which absorbs dust and kills bacteria
powersave 0, 1 Power Saving mode
lights 0, 1 Turn on/off device lights
quiet 0, 1, 2, 3 Quiet modes
blow 0, 1 Keeps the fan running for a while after shutting down (also called "X-Fan", only usable in Dry and Cool mode)
air off, inside, outside, mode3 Fresh air valve
sleep 0, 1 Sleep mode
turbo 0, 1 Turbo mode addon

The service can be used as a 3rd party addon for the MQTT climate platform, although not all commands are supported.

  1. Install the addon
  2. Customize addon options (HVAC host, MQTT broker URL, MQTT topic prefix)
  3. Add the following to your configuration.yaml
  - platform: mqtt

    # Change to whatever you want
    name: Gree HVAC

    # Change MQTT_TOPIC_PREFIX to what you've set in addon options
    current_temperature_topic: "MQTT_TOPIC_PREFIX/temperature/get"
    temperature_command_topic: "MQTT_TOPIC_PREFIX/temperature/set"
    temperature_state_topic: "MQTT_TOPIC_PREFIX/temperature/get"
    mode_state_topic: "MQTT_TOPIC_PREFIX/mode/get"
    mode_command_topic: "MQTT_TOPIC_PREFIX/mode/set"
    fan_mode_state_topic: "MQTT_TOPIC_PREFIX/fanspeed/get"
    fan_mode_command_topic: "MQTT_TOPIC_PREFIX/fanspeed/set"
    swing_mode_state_topic: "MQTT_TOPIC_PREFIX/swingvert/get"
    swing_mode_command_topic: "MQTT_TOPIC_PREFIX/swingvert/set"
    power_state_topic: "MQTT_TOPIC_PREFIX/power/get"
    power_command_topic: "MQTT_TOPIC_PREFIX/power/set"

    # Keep the following as is
    payload_off: 0
    payload_on: 1
      - "off"
      - "auto"
      - "cool"
      - "heat"
      - "dry"
      - "fan_only"
      - "default"
      - "full"
      - "fixedTop"
      - "fixedMidTop"
      - "fixedMid"
      - "fixedMidBottom"
      - "fixedBottom"
      - "swingBottom"
      - "swingMidBottom"
      - "swingMid"
      - "swingMidTop"
      - "swingTop"
      - "auto"
      - "low"
      - "mediumLow"
      - "medium"
      - "mediumHigh"
      - "high"

How to power on/off doesn't supply separate on/off switch. Use the dedicated mode for that.

Running addon locally

Create an ./data/options.json file inside the repo with persistent addon configuration.

docker build \
    --build-arg BUILD_FROM="homeassistant/amd64-base:latest" \
    -t gree-hvac-mqtt-bridge .

docker run --rm -v "$PWD/data":/data gree-hvac-mqtt-bridge

Run single device as a service

To run it when the PC starts, a systemd service has to be created by following the following commands.

sudo cp /opt/gree-hvac-mqtt-bridge/gree-bridge.service /etc/systemd/system/gree-bridge.service
sudo chmod +x /etc/systemd/system/gree-bridge.service
sudo systemctl enable gree-bridge
sudo systemctl start gree-bridge

Multiple devices

As of 1.2.0 the Hassio addon supports multiple devices by running paralell NodeJS processes in PM2. Old configurations will work, but will run without PM2.

config example:

    "mqtt": {
        "broker_url": "mqtt://localhost",
        "username": "user",
        "password": "pass",
        "retain": false
    "devices": [
        "hvac_host": "",
        "mqtt_topic_prefix": "/home/hvac01"
        "hvac_host": "",
        "mqtt_topic_prefix": "/home/hvac02"

Configuring HVAC WiFi

  1. Make sure your HVAC is running in AP mode. You can reset the WiFi config by pressing MODE +WIFI (or MODE + TURBO) on the AC remote for 5s.
  2. Connect with the AP wifi network (the SSID name should be a 8-character alfanumeric, e.g. "u34k5l166").
  3. Run the following in your UNIX terminal:
echo -n "{\"psw\": \"YOUR_WIFI_PASSWORD\",\"ssid\": \"YOUR_WIFI_SSID\",\"t\": \"wlan\"}" | nc -cu 7000

Note: This command may vary depending on your OS (e.g. Linux, macOS, CygWin). If facing problems, please consult the appropriate netcat manual.



  • Updated NPM dependency versions to more current (~2 years old!)
  • Defined fsevents as optional for linux based platforms
  • as of 4/26/2021 "found 0 vulnerabilities"
  • UDP Datagram warning is fixed with later versions


  • Fix run script for single device with same configuration
  • Run single device as a systemd service
  • Add option to MQTT for retain flag


  • Fix incorrect state checks


  • Add multiple device support
  • Update config with supported architectures
  • Fix state being published even if nothing changed


  • Discovered codes added for Air and Quiet to avoid errors
  • Added swingHor mode codes


  • Add Turbo mode


  • Add support for MQTT authentication
  • BREAKING: Update MQTT mode state names to match defaults
  • Add support for new modes: Air, Power Save, Lights, Health, Quiet, Sleep, Blow
  • Fix deprecated Buffer() use


  • Add API security role


  • Bump NodeJS version to 8.11.2


  • Fix power off command


  • Bump NodeJS version to 8.9.3


  • Update MQTT version
  • Add UDP error handling
  • Extend Readme

[1.0.0] First release


This project is licensed under the GNU GPLv3 - see the file for details