Gree HVAC client

A client for communicating with Gree air conditioners.

Requirements

NodeJS (>=8.11.0)

Installation

yarn add gree-hvac-client

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

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.
Connect with the AP wifi network (the SSID name should be a 8-character alfanumeric, e.g. "u34k5l166").
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

sigxcpu76/gree-hvac-client

Gree HVAC client

Requirements

Installation

Simple usage

Properties

Configuring HVAC WiFi

API Reference

Classes

Constants

Client

new Client(options)

client.connect()

client.disconnect()

client.setProperties(properties)

client.setProperty(property, value)

client.getDeviceId() ⇒ string | null

CLIENT_OPTIONS

PROPERTY_VALUE

PROPERTY

License

Acknowledgments

client.getDeviceId() ⇒ `string` | `null`