search

arthurkrupa / gree-hvac-mqtt-bridge

MQTT Bridge for controlling Gree smart air conditioners, e.g. with Home Assistant or OpenHAB
GNU General Public License v3.0
131 stars 63 forks source link
hassio hassio-repository home-assistant homeassistant hvac mqtt openhab

readme

Gree HVAC MQTT bridge

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

Requirements

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="192.168.1.255" \
    --mqtt-broker-url="mqtt://localhost" \
    --mqtt-topic-prefix="home/greehvac" \
    --mqtt-username="" \
    --mqtt-password=""

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, _fanonly 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

Hass.io addon

The service can be used as a 3rd party addon for the Hass.io 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
climate:
  - 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
    modes:
      - "off"
      - "auto"
      - "cool"
      - "heat"
      - "dry"
      - "fan_only"
    swing_modes:
      - "default"
      - "full"
      - "fixedTop"
      - "fixedMidTop"
      - "fixedMid"
      - "fixedMidBottom"
      - "fixedBottom"
      - "swingBottom"
      - "swingMidBottom"
      - "swingMid"
      - "swingMidTop"
      - "swingTop"
    fan_modes:
      - "auto"
      - "low"
      - "mediumLow"
      - "medium"
      - "mediumHigh"
      - "high"

How to power on/off

Hass.io 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": "192.168.0.255",
        "mqtt_topic_prefix": "/home/hvac01"
      },
      {
        "hvac_host": "192.168.0.254",
        "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 192.168.1.1 7000

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

Changelog

[1.2.4]

[1.2.3]

[1.2.2]

[1.2.0]

[1.1.2]

[1.1.1]

[1.1.0]

[1.0.5]

[1.0.4]

[1.0.3]

[1.0.2]

[1.0.1]

[1.0.0] First release

License

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

Acknowledgments