Gree HVAC client

A client for communicating with Gree air conditioners.

Requirements

NodeJS (>=14)

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	Vertical 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 alphanumeric, 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 ⇐ EventEmitter: Control GREE HVAC device by getting and setting its properties
ClientError ⇐ Error
ClientSocketSendError ⇐ ClientError: Connectivity problems while communicating with HVAC
ClientMessageParseError ⇐ ClientError: The message received from HVAC cannot be parsed
ClientMessageUnpackError ⇐ ClientError: The package from the message received from HVAC cannot be decrypt
ClientUnknownMessageError ⇐ ClientError: A message having an unknown format was received from HVAC
ClientNotConnectedError ⇐ ClientError: Request operations on not connected to the HVAC client
ClientConnectTimeoutError ⇐ ClientError
ClientCancelConnectError ⇐ ClientError: Connecting was cancelled by calling disconnect

Constants

CLIENT_OPTIONS : object: Client options
PROPERTY_VALUE: Device properties value constants
PROPERTY: Device properties constants

Typedefs

PropertyMap : Object.<PROPERTY, (PROPERTY_VALUE|number)>

Client ⇐ `EventEmitter`

Control GREE HVAC device by getting and setting its properties

Kind: global class
Extends: EventEmitter
Emits: connect, update, error, disconnect

Client ⇐ EventEmitter
- new Client(options)
- .connect() ⇒ Promise
- .disconnect() ⇒ Promise
- .setProperties(properties) ⇒ Promise
- .setProperty(property, value) ⇒ Promise
- .getDeviceId() ⇒ string | null
- .setDebug(enable)
- "connect"
- "success" (updated, properties)
- "update" (updated, properties)
- "error" (error)
- "disconnect"

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() ⇒ `Promise`

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

Kind: instance method of Client
Emits: connect, error

client.disconnect() ⇒ `Promise`

Disconnect from a HVAC device and stop status polling

Kind: instance method of Client
Emits: disconnect

client.setProperties(properties) ⇒ `Promise`

Set a list of device properties at once by one request

Kind: instance method of Client
Emits: success, error

Param	Type
properties	`PropertyMap`

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) ⇒ `Promise`

Set device property

Kind: instance method of Client
Emits: success, error

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.setDebug(enable)

Set debug level

Kind: instance method of Client

Param	Type
enable	`Boolean`

"connect"

Emitted when successfully connected to the HVAC

Kind: event emitted by Client

"success" (updated, properties)

Emitted when properties successfully updated after calling setProperties or setProperty

Kind: event emitted by Client

Param	Type	Description
updated	`PropertyMap`	The properties and their values that were updated
properties	`PropertyMap`	All the properties and their values managed by the Client

"update" (updated, properties)

Emitted when properties successfully updated from HVAC (e.g. by a remote control)

Kind: event emitted by Client

Param	Type	Description
updated	`PropertyMap`	The properties and their values that were updated
properties	`PropertyMap`	All the properties and their values managed by the Client

"error" (error)

Emitted when an error happens

It is important to subscribe to the error event, otherwise the process will be terminated

Kind: event emitted by Client

Param	Type
error	`ClientError`

"disconnect"

Emitted when disconnected from the HVAC

Kind: event emitted by Client

ClientError ⇐ `Error`

Kind: global class
Extends: Error