/gree-hvac-client

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

Primary LanguageJavaScriptGNU General Public License v3.0GPL-3.0

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

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