ghc

gree-hvac-client

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

Showing:

Popularity

Downloads/wk

17

GitHub Stars

21

Maintenance

Last Commit

1yr ago

Contributors

10

Package

Dependencies

2

Size (min+gzip)

3.8KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

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

CommandValuesDescription
temperatureany integerIn degrees Celsius by default
currentTemperatureany integerIn degrees Celsius by default. (Read-only)
modeauto, cool, heat, dry, fan_onlyOperation mode
fanspeedauto, low, mediumLow, medium, mediumHigh, highFan speed
swinghordefault, full, fixedLeft, fixedMidLeft, fixedMid, fixedMidRight, fixedRightHorizontal Swing
swingvertdefault, full, fixedTop, fixedMidTop, fixedMid, fixedMidBottom, fixedBottom, swingBottom, swingMidBottom, swingMid, swingMidTop, swingTopVetical swing
poweroff, onTurn device on/off
healthoff, onHealth ("Cold plasma") mode, only for devices equipped with "anion generator", which absorbs dust and kills bacteria
powersaveoff, onPower Saving mode
lightsoff, onTurn on/off device lights
quietoff, mode1, mode2, mode3Quiet modes
blowoff, onKeeps the fan running for a while after shutting down (also called "X-Fan", only usable in Dry and Cool mode)
airoff, inside, outside, mode3Fresh air valve
sleepoff, onSleep mode
turbooff, onTurbo 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.

ParamType
optionsCLIENT_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

ParamType
propertiesObject.<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

ParamType
propertyPROPERTY
valuePROPERTY_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

NameTypeDefaultDescription
hoststring"192.168.1.255"GREE device ip-address
portnumber7000GREE device UDP port
connectTimeoutnumber3000Reconnect to device if no success timeout
autoConnectbooleantrueAutomatically connect to device when client is created. Alternatively method connect() can be used.
pollbooleantruePoll device properties
pollingIntervalnumber3000Device properties polling interval
pollingTimeoutnumber1000Device properties polling timeout, emits no_response events in case of no response from HVAC device for a status request
debugbooleanfalseTrace debug information

PROPERTY_VALUE

Device properties value constants

Kind: global constant
Read only: true
Properties

NameTypeDescription
power.onstring
power.offstring
mode.autostring
mode.drystring
mode.fan_onlystring
mode.heatstring
temperatureUnit.celsiusstring
temperatureUnit.fahrenheitstring
fanSpeed.autostring
fanSpeed.lowstring
fanSpeed.mediumLowstringNot available on 3-speed units
fanSpeed.mediumstring
fanSpeed.mediumHighstringNot available on 3-speed units
fanSpeed.highstring
air.offstring
air.insidestring
air.outsidestring
air.mode3string
blow.offstring
blow.onstring
health.offstring
health.onstring
sleep.offstring
sleep.onstring
lights.offstring
lights.onstring
swingHor.defaultstring
swingHor.fullstringSwing in full range
swingHor.fixedLeftstringFixed in leftmost position (1/5)
swingHor.fixedMidLeftstringFixed in middle-left postion (2/5)
swingHor.fixedMidstringFixed in middle position (3/5)
swingHor.fixedMidRightstringFixed in middle-right postion (4/5)
swingHor.fixedRightstringFixed in rightmost position (5/5)
swingHor.fullAltstringSwing in full range (seems to be same as full)
swingVert.defaultstring
swingVert.fullstringSwing in full range
swingVert.fixedTopstringFixed in the upmost position (1/5)
swingVert.fixedMidTopstringFixed in the middle-up position (2/5)
swingVert.fixedMidstringFixed in the middle position (3/5)
swingVert.fixedMidBottomstringFixed in the middle-low position (4/5)
swingVert.fixedBottomstringFixed in the lowest position (5/5)
swingVert.swingBottomstringSwing in the downmost region (5/5)
swingVert.swingMidBottomstringSwing in the middle-low region (4/5)
swingVert.swingMidstringSwing in the middle region (3/5)
swingVert.swingMidTopstringSwing in the middle-up region (2/5)
swingVert.swingTopstringSwing in the upmost region (1/5)
quiet.offstring
quiet.mode1string
quiet.mode2string
quiet.mode3string
turbo.offstring
turbo.onstring
powerSave.offstring
powerSave.onstring

PROPERTY

Device properties constants

Kind: global constant
Read only: true
Properties

NameTypeDescription
powerstringPower state of the device
modestringMode of operation
temperatureUnitstringTemperature unit (must be together with set temperature)
temperaturestringSet temperature (must be together with temperature unit)
currentTemperaturestringGet current temperature from the internal (?) sensor (This value can not be set, only received. HVAC must support this feature otherwise the value is 0)
fanSpeedstringFan speed
airstringFresh air valve
blowstringKeeps the fan running for a while after shutting down (also called "X-Fan", only usable in Dry and Cool mode)
healthstringControls Health ("Cold plasma") mode, only for devices equipped with "anion generator", which absorbs dust and kills bacteria
sleepstringSleep mode, which gradually changes the temperature in Cool, Heat and Dry mode
lightsstringTurns all indicators and the display on the unit on or off
swingHorstringControls the swing mode of the horizontal air blades (not available on all units)
swingVertstringControls the swing mode of the vertical air blades
quietstringControls the Quiet mode which slows down the fan to its most quiet speed. Not available in Dry and Fan mode
turbostringSets fan speed to the maximum. Fan speed cannot be changed while active and only available in Dry and Cool mode
powerSavestringPower saving mode

License

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

Acknowledgments

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100