GithubHelp home page GithubHelp logo

inwaar / gree-hvac-client Goto Github PK

View Code? Open in Web Editor NEW
32.0 4.0 12.0 681 KB

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

License: GNU General Public License v3.0

JavaScript 100.00%
gree cooper hunter daitsu tosot ventilation heating air-conditioning

gree-hvac-client's Introduction

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

gree-hvac-client's People

Contributors

aivus avatar andrei-tatar avatar arthurkrupa avatar inwaar avatar mrblur avatar oroce avatar roleee avatar wjketting avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

gree-hvac-client's Issues

Error:1C800068:Provider routines: :Wrong final block

Error: error:1C80006B:Provider routines::wrong final block length
at Decipheriv.final (node:internal/crypto/cipher:193:29)
at EncryptionService.decrypt (C:\Users\xxxxxxxx.node-red\node_modules\gree-hvac-client\lib\encryption-service.js:43:42)
at Client._handleResponse (C:\Users\xxxxxxxx.node-red\node_modules\gree-hvac-client\lib\client.js:291:46)
at Socket. (C:\Users\xxxxxxxx.node-red\node_modules\gree-hvac-client\lib\client.js:113:52)
at Socket.emit (node:events:513:28)
at UDP.onMessage [as onmessage] (node:dgram:930:8)

I get this error when trying to connect to a gree Hi wall AC.

Emit noPollingResponse event when HVAC doesn't respond on polling

Hi

What do you think about adding noPollingResponse event (or something similar?) which can be emitted in case when HVAC doesn't respond to the polling request?

For example we have polling: true and pollingInterval: 3000.
Using setTimeout with pollingInterval*2 we emit noPollingResponse.

It allows library users to handle case when polling was not successful and mark device as offline (for example).

Any thoughts about this?

Constants for properties

Now we have constants like Gree.VALUE.power.on which is equal to 1, but during polling process we are getting parameters in string representations.

For example

client.on('update', (updatedProperties, properties) => {
     ...
     const value = updatedProperties[Gree.PROPERTY.power] === 'on';
     ...
});

For now we need to use on string value.

Do we need to add constants for such values, what do you think?

connection device to local wifi issue

Hi! I'm trying to connect AC device to local wifi using the command from read me ( echo -n "{"psw": "pass","ssid": "ssid","t": "wlan"}" | nc -cu 192.168.1.1 7000 tee console.log
)
I reset AC's wifi config, connected to his wifi, and used the command
I get response {"t":"ret","r":200} (which indicates success), but cant find AC's mac address in devices connected to my wifi

  1. I've done it with official app and device connected with this wifi so I know it's possible, no problems with wifi, its 2.4, pass and ssid is correct
  2. i double checked that i connected to the right wifi when I was searching for my AC mac address
  3. i know his mac address because I've sent him get request via Python, when was connected to his wifi and got this response:
    {'t': 'dev', 'cid': '502cc6689819', 'bc': '', 'brand': 'gree', 'catalog': 'gree', 'mac': '502cc6689819', 'mid': '13000', 'model': 'gree', 'name': 'c6689819', 'series': 'gree', 'vender': '1', 'ver': 'V1.2.1', 'lock': 0}

maybe I'm doing smth wrong or you faced the same issue before and know the answer? i would be really thankful for any help

'update' event not always triggered

Hi!

First, thank you a lot for your work!

So about the issue, the 'update' event is only triggered when I connect but after when I use setProperty or setProperties the event is never triggered (the property is set correctly on my Gree hvac).

But if I use the official app, the event is triggered.

Am I missing something ?

Error: error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt

Hey Igor 👋

I've found that some users are getting Error: error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt error in

Error: error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt
  File "crypto.js", line 183, col 26, in Decipheriv.final
  File "/node_modules/gree-hvac-client/lib/encryption-service.js", line 43, col 42, in EncryptionService.decrypt
    return JSON.parse(str + decipher.final('utf8'))
  File "/node_modules/gree-hvac-client/lib/client.js", line 291, col 46, in Client._handleResponse
    const pack = this._encryptionService.decrypt(message);
  File "/node_modules/gree-hvac-client/lib/client.js", line 113, col 52, in Socket._socket.on.message
    this._socket.on('message', message => this._handleResponse(message));
  File "events.js", line 126, col 13, in emitTwo
  File "events.js", line 214, col 7, in Socket.emit
  File "dgram.js", line 659, col 8, in UDP.onMessage [as onmessage]

I'm not sure why it happens as I don't have any additional data (wrong encryption key? broken data?), but can we somehow handle this? I mean allow developers who uses this library handle such cases somehow. Because it's happening inside the library now.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.