Skip to content

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

License

Notifications You must be signed in to change notification settings

inwaar/gree-hvac-client

Repository files navigation

Gree HVAC client

NPM status Github Actions status

A client for communicating with Gree air conditioners.

Requirements

  • NodeJS (>=12)

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

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

ClientEventEmitter

Control GREE HVAC device by getting and setting its properties

ClientErrorError
ClientSocketSendErrorClientError

Connectivity problems while communicating with HVAC

ClientMessageParseErrorClientError

The message received from HVAC cannot be parsed

ClientMessageUnpackErrorClientError

The package from the message received from HVAC cannot be decrypt

ClientUnknownMessageErrorClientError

A message having an unknown format was received from HVAC

ClientNotConnectedErrorClientError

Request operations on not connected to the HVAC client

ClientConnectTimeoutErrorClientError
ClientCancelConnectErrorClientError

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

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

new ClientError(message, origin, props)

Param Type
message string
origin Error | undefined
props Object.<string, unknown>

ClientSocketSendError ⇐ ClientError

Connectivity problems while communicating with HVAC

Kind: global class
Extends: ClientError

new ClientSocketSendError(cause)

Param Type
cause Error

ClientMessageParseError ⇐ ClientError

The message received from HVAC cannot be parsed

Kind: global class
Extends: ClientError

new ClientMessageParseError(cause, props)

Param Type
cause Error
props Object.<string, unknown>

ClientMessageUnpackError ⇐ ClientError

The package from the message received from HVAC cannot be decrypt

Kind: global class
Extends: ClientError

new ClientMessageUnpackError(cause, props)

Param Type
cause Error
props Object.<string, unknown>

ClientUnknownMessageError ⇐ ClientError

A message having an unknown format was received from HVAC

Kind: global class
Extends: ClientError

new ClientUnknownMessageError(props)

Param Type
props Object.<string, unknown>

ClientNotConnectedError ⇐ ClientError

Request operations on not connected to the HVAC client

Kind: global class
Extends: ClientError

ClientConnectTimeoutError ⇐ ClientError

Kind: global class
Extends: ClientError

ClientCancelConnectError ⇐ ClientError

Connecting was cancelled by calling disconnect

Kind: global class
Extends: ClientError

CLIENT_OPTIONS : object

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 position (2/5)
swingHor.fixedMid string Fixed in middle position (3/5)
swingHor.fixedMidRight string Fixed in middle-right position (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
safetyHeating.off string
safetyHeating.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

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

Kind: global typedef

License

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

Acknowledgments