sigxcpu76 / gree-hvac-client

Client for controlling Gree (and other compatible) smart air conditioners

Gree HVAC client

A client for communicating with Gree air conditioners.

Requirements

• NodeJS (>=8.11.0)

Installation

yarn add gree-hvac-client

or

npm install --save gree-hvac-client

Simple usage

Set device properties:

const Gree = require('gree-hvac-client');

const client = new Gree.Client({host: '192.168.7.60'});

client.on('connect', () => {
    client.setProperty(Gree.PROPERTY.temperature, 25);
    client.setProperty(Gree.PROPERTY.lights, Gree.VALUE.lights.off);
});

Poll device properties:

const Gree = require('gree-hvac-client');

const client = new Gree.Client({host: '192.168.7.60'});

client.on('connect', (client) => {
    console.log('connected to', client.getDeviceId());
});
client.on('update', (updatedProperties, properties) => {
    console.log(updatedProperties, properties);
});
client.on('no_response', () => {
    console.log('no response');
});

Properties

Command	Values	Description
temperature	any integer	In degrees Celsius by default
currentTemperature	any integer	In degrees Celsius by default. (Read-only)
mode	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	off, on	Turn device on/off
health	off, on	Health ("Cold plasma") mode, only for devices equipped with "anion generator", which absorbs dust and kills bacteria
powersave	off, on	Power Saving mode
lights	off, on	Turn on/off device lights
quiet	off, mode1, mode2, mode3	Quiet modes
blow	off, on	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	off, on	Sleep mode
turbo	off, on	Turbo mode

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.

API Reference

Classes

Client

Control GREE HVAC device by getting and setting its properties

Constants

CLIENT_OPTIONS

Client options

PROPERTY_VALUE

Device properties value constants

PROPERTY

Device properties constants

Client

Control GREE HVAC device by getting and setting its properties

Kind: global class

• Client
  • new Client(options)
  • .connect()
  • .disconnect()
  • .setProperties(properties)
  • .setProperty(property, value)
  • .getDeviceId() ⇒ string | null

new Client(options)

Creates a new client, connect to device and start polling by default.

Param	Type
options	CLIENT_OPTIONS | Object

Example

const Gree = require('gree-hvac-client');

const client = new Gree.Client({host: '192.168.1.69'});
client.on('connect', () => {
    client.setProperty(Gree.PROPERTY.lights, Gree.VALUE.lights.off);
    client.setProperty(Gree.PROPERTY.temperature, 25);
});

client.connect()

Connect to a HVAC device and start polling status changes by default

Kind: instance method of Client

client.disconnect()

Disconnect from a HVAC device and stop status polling

Kind: instance method of Client

client.setProperties(properties)

Set a list of device properties at once by one request

Kind: instance method of Client

Param	Type
properties	Object.<PROPERTY, PROPERTY_VALUE>

Example

// use library constants

const properties = {};
properties[Gree.PROPERTY.lights] = Gree.VALUE.lights.off;
properties[Gree.PROPERTY.blow] = Gree.VALUE.blow.off;
properties[Gree.PROPERTY.fanSpeed] = Gree.VALUE.fanSpeed.high;
properties[Gree.PROPERTY.temperature] = 25;
client.setProperties(properties);

Example

// use plain objects

client.setProperties({
 lights: 'off',
 blow: 'off',
 fanSpeed: 'high',
 temperature: 25
});

client.setProperty(property, value)

Set device property

Kind: instance method of Client

Param	Type
property	PROPERTY
value	PROPERTY_VALUE

Example

// use library constants

client.setProperty(Gree.PROPERTY.swingHor, Gree.VALUE.swingHor.fixedLeft);
client.setProperty(Gree.PROPERTY.temperature, 25);

Example

// use plain values

client.setProperty('swingHor', 'fixedLeft');
client.setProperty('temperature', 25);

client.getDeviceId() ⇒ string | null

Returns devices MAC-address

Kind: instance method of Client

CLIENT_OPTIONS

Client options

Kind: global constant
Read only: true
Properties

Name	Type	Default	Description
host	string	"192.168.1.255"	GREE device ip-address
port	number	7000	GREE device UDP port
connectTimeout	number	3000	Reconnect to device if no success timeout
autoConnect	boolean	true	Automatically connect to device when client is created. Alternatively method connect() can be used.
poll	boolean	true	Poll device properties
pollingInterval	number	3000	Device properties polling interval
pollingTimeout	number	1000	Device properties polling timeout, emits no_response events in case of no response from HVAC device for a status request
debug	boolean	false	Trace debug information

PROPERTY_VALUE

Device properties value constants

Kind: global constant
Read only: true
Properties

Name	Type	Description
power.on	string
power.off	string
mode.auto	string
mode.dry	string
mode.fan_only	string
mode.heat	string
temperatureUnit.celsius	string
temperatureUnit.fahrenheit	string
fanSpeed.auto	string
fanSpeed.low	string
fanSpeed.mediumLow	string	Not available on 3-speed units
fanSpeed.medium	string
fanSpeed.mediumHigh	string	Not available on 3-speed units
fanSpeed.high	string
air.off	string
air.inside	string
air.outside	string
air.mode3	string
blow.off	string
blow.on	string
health.off	string
health.on	string
sleep.off	string
sleep.on	string
lights.off	string
lights.on	string
swingHor.default	string
swingHor.full	string	Swing in full range
swingHor.fixedLeft	string	Fixed in leftmost position (1/5)
swingHor.fixedMidLeft	string	Fixed in middle-left postion (2/5)
swingHor.fixedMid	string	Fixed in middle position (3/5)
swingHor.fixedMidRight	string	Fixed in middle-right postion (4/5)
swingHor.fixedRight	string	Fixed in rightmost position (5/5)
swingHor.fullAlt	string	Swing in full range (seems to be same as full)
swingVert.default	string
swingVert.full	string	Swing in full range
swingVert.fixedTop	string	Fixed in the upmost position (1/5)
swingVert.fixedMidTop	string	Fixed in the middle-up position (2/5)
swingVert.fixedMid	string	Fixed in the middle position (3/5)
swingVert.fixedMidBottom	string	Fixed in the middle-low position (4/5)
swingVert.fixedBottom	string	Fixed in the lowest position (5/5)
swingVert.swingBottom	string	Swing in the downmost region (5/5)
swingVert.swingMidBottom	string	Swing in the middle-low region (4/5)
swingVert.swingMid	string	Swing in the middle region (3/5)
swingVert.swingMidTop	string	Swing in the middle-up region (2/5)
swingVert.swingTop	string	Swing in the upmost region (1/5)
quiet.off	string
quiet.mode1	string
quiet.mode2	string
quiet.mode3	string
turbo.off	string
turbo.on	string
powerSave.off	string
powerSave.on	string

PROPERTY

Device properties constants

Kind: global constant
Read only: true
Properties

Name	Type	Description
power	string	Power state of the device
mode	string	Mode of operation
temperatureUnit	string	Temperature unit (must be together with set temperature)
temperature	string	Set temperature (must be together with temperature unit)
currentTemperature	string	Get current temperature from the internal (?) sensor (This value can not be set, only received. HVAC must support this feature otherwise the value is 0)
fanSpeed	string	Fan speed
air	string	Fresh air valve
blow	string	Keeps the fan running for a while after shutting down (also called "X-Fan", only usable in Dry and Cool mode)
health	string	Controls Health ("Cold plasma") mode, only for devices equipped with "anion generator", which absorbs dust and kills bacteria
sleep	string	Sleep mode, which gradually changes the temperature in Cool, Heat and Dry mode
lights	string	Turns all indicators and the display on the unit on or off
swingHor	string	Controls the swing mode of the horizontal air blades (not available on all units)
swingVert	string	Controls the swing mode of the vertical air blades
quiet	string	Controls the Quiet mode which slows down the fan to its most quiet speed. Not available in Dry and Fan mode
turbo	string	Sets fan speed to the maximum. Fan speed cannot be changed while active and only available in Dry and Cool mode
powerSave	string	Power saving mode

License

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

Acknowledgments

• tomikaa87 for reverse-engineering the Gree protocol
• oroce for inspiration
• arthurkrupa for inspiration