Skip to content

Commit

Permalink
Added ability to configure additional Temperature Sensor (disabled / …
Browse files Browse the repository at this point in the history 
…child accessory / separate (independent) accessory)
  • Loading branch information
@eibenp
eibenp committed Aug 24, 2023
1 parent c40c260 commit 1a7a212
Show file tree
Hide file tree
Showing 10 changed files with 240 additions and 29 deletions.
65 changes: 47 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,37 +2,56 @@

[Homebridge GREE Air Conditioner Platform Plugin](https://github.com/eibenp/homebridge-gree-airconditioner) is a dynamic platform plugin for [Homebridge](https://github.com/homebridge/homebridge) which allows control of GREE Air Conditioner devices from [Apple's Home app](https://www.apple.com/home-app/). (Make GREE Air Conditioner HomeKit compatible.)

You can add all of your GREE Air Conditioner devices to the Home App by specifying the network broadcast address, and Homebridge will find all connected devices. Each device appears in the Home App as a Heater Cooler device and also as a separate Termperature Sensor (if temperature sensor is supported by the physical device). This allows to define automations (e.g. turn on) based on current temperature in the room.
You can add all of your GREE Air Conditioner devices to the Home App by specifying the network broadcast address, and Homebridge will find all connected devices. Each device appears in the Home App as a Heater Cooler device. It is also possible to add a separate Termperature Sensor (if temperature sensor is supported by the physical device). This allows to define automations (e.g. turn on) based on current temperature in the room. Be careful, if the device does not support internal temperature sensor but is added as a separate accessory, Home App will display the target temperature not the measured one. Child accessory does not appear in Home App if physical sensor is not available in the AC unit.

Quiet / Auto / Powerful mode is supported by the fan speed control. Minimum value turns on Quite mode. Next value is Auto mode. Maximum value is Powerful mode. All other values between them are exact fan speeds (Low, MediumLow**, Medium, MediumHigh**, High)
Quiet / Auto / Powerful mode is supported by the fan speed control. Minimum value turns on Quiet mode. Next value is Auto mode. Maximum value is Powerful mode. All other values between them are exact fan speeds (Low, MediumLow**, Medium, MediumHigh**, High)

** these values are supported only on 5-speed units

It is recommended, to add all devices to the Homebridge configuration. So you can control all parameters of the devices and also disable them, if not all of them should be controlled using the Home App. Devices are identified by MAC Address (Serial Number). It can be queried by the official [GREE+ mobile app](https://apps.apple.com/us/app/gree/id1167857672). (The app is required to connect the devices to the local WiFi network for the first time.)
It is recommended to add all devices to the Homebridge configuration, so that you can control all their parameters. If you don't want to control all of the devices in Home App, then you need to add to the configuration and disable the ones you don't need. Devices are identified by MAC Address (Serial Number). It can be queried using the official [GREE+ mobile app](https://apps.apple.com/us/app/gree/id1167857672). (The app is required to connect the devices to the local WiFi network for the first time.)

xFan function is also supported, but it works automatically if enabled in Homebridge configuration. If xFan is enabled for the device it is automatically turned on when you select a supported operating mode in Home App. If xFan is disabled then the Home App will not modify it's actual setting in any case.
xFan function is also supported, but it works automatically if enabled in Homebridge configuration. If xFan is enabled for the device, it is automatically turned on when you select a supported operating mode in Home App. If xFan is disabled, the Home App will not modify its actual setting in any case.

Temperature display units in the Home App are in sync with the AC unit's display. (Configuration settings are required to be specified always in Degrees Celsius, independently from the display units.)

Vertical swing mode can be turned on/off, but special swing settings can't be controlled using the Home App.

This plugin is designed to be as simple and clear as possible and supports primarily the functions of the Home App's Heater Cooler accessory.

## Requirements

* Node.js (>= 18.17.0) with NPM
* Node.js (>= 18.15.0) with NPM
* Homebridge (>= 1.6.0)

You need to specify the local network broadcast address (192.168.1.255 in many home environments) and also recommended to add the device and specify it's MAC address (Serial Number) in configuration file.
You need to specify the local network broadcast address (192.168.1.255 in many home environments) and it's also recommended to add the device and specify its MAC address (Serial Number) in the configuration file.

It is highly recommended to use static IP addresses for connected devices. Using a dynamic IP address may require a restart of the Homebridge service on an address change to reconnect the device. Most routers offer static DHCP leases. (Please look at your router's documentation!)

## Supported devices

* GREE Air Conditioners with WiFi support
* May work with other GREE compatible AC units

It is highly recommended to use static IP addresses for connected devices. Using dynamic IP address may require restarting the Homebridge service on address change to reconnect the device. Most routers offer static DHCP leases. (Please see your router documentation!)
## Known limitations

This plugin was designed to support the Home App's Heater Cooler functionality using GREE Air Conditioners. Some special features of GREE AC's are not supported natively by Apple and also dismiss support in this plugin.
* Fan and dry modes are not supported. They may work if set directly on the device until you change operating mode. They can't be turned on using Home App.
* Lights of the AC unit can't be controlled.
* Additional device functions (e.g. health mode, sleep, SE) are not supported.
* Horizontal swing control is not supported, it remains the same as set directly on the device.

## Installation instructions

It is recommended to install the plugin using the graphical user interface of Homebridge ([Homebridge Config UI X](https://www.npmjs.com/package/homebridge-config-ui-x)). You can find the plugin if you search on the Plugins page for GREE Air Conditioner. It is recommended to configure the plugin using the same GUI controls.
It is recommended to install the plugin using the graphical user interface of Homebridge ([Homebridge Config UI X](https://www.npmjs.com/package/homebridge-config-ui-x)). You can find the plugin if you search on the Plugins page for GREE Air Conditioner ('GREE AC' or '@eibenp/homebridge-gree-airconditioner' if you'd like an exact match). It is recommended to configure the plugin using the same GUI controls.

Command line install:
```
npm install @eibenp/homebridge-gree-airconditioner -g
```
If successfully installed and configured then your devices will appear on the Homebridge GUI Accessories page (2 items for supported devices (Heater Cooler and Temperature Sensor)) and also in Home App (if Homebridge is already connected to the Home App).
If successfully installed and configured, your devices will appear on the Homebridge GUI Accessories page and also in Home App (if Homebridge is already connected to the Home App). (If the additional temperature sensor is enabled, then 2 items will be displayed for supported devices (Heater Cooler and Temperature Sensor).)

## Example configuration
_Only relevant part of the configuration file is displayed:_
_Only the relevant part of the configuration file is displayed:_
```
"platforms": [
{
Expand All @@ -53,6 +72,7 @@ _Only relevant part of the configuration file is displayed:_
"minimumTargetTemperature": 16,
"maximumTargetTemperature": 30,
"xFanEnabled": true,
"temperatureSensor": "disabled",
"disabled": false
}
]
Expand All @@ -61,29 +81,38 @@ _Only relevant part of the configuration file is displayed:_
```
* name - Unique name of the platform plugin
* platform - **GREEAirConditioner** (fixed name, it identifies the plugin)
* port - free UDP port (homebridge will use this port for network communication; it is recommended to select a port which is not used and the next 256 ports are also available because devices will be bound to a separate port based on the last part of the device IPv4 address and the port specified in the configuration)
* scanAddress - local network broadcast address (some network knowledge is required to determine this address; in many cases it is default to 192.168.1.255)
* port - free UDP port (homebridge will use this port for network communication; it is recommended to select a port which is not used and the next 256 ports are also available because devices will be bound to a separate port based on the last part of the device's IPv4 address and the port specified in the configuration)
* scanAddress - local network broadcast address (some network knowledge is required to determine this address; in many cases its default value is 192.168.1.255)
* scanCount - number of retries for locating devices on the network (minimum 3 retries have to be specified)
* scanTimeout - time period in seconds between device query retries
* devices - devices should be listed in this block (specify as many devices as you have on your network)
* mac - MAC address (Serial Number) of the device
* name - custom name of the device (optional)
* model - model name, information only (optional)
* speedSteps - fan speed steps of the unit (valid values are: 3 and 5)
* statusUpdateInterval - device status will be refreshed based in this interval (in seconds)
* sensorOffset - device temperature sensor offset value for current temperature calibration (default is 40 celsius, must be specified in celsius)
* minimumTargetTemperature - minimum target temperature accepted by the device (default is 16 celsius, must be specified in celsius)
* maximumTargetTemperature - maximum target temperature accepted by the device (default is 30 celsius, must be specified in celsius)
* statusUpdateInterval - device status will be refreshed based on this interval (in seconds)
* sensorOffset - device temperature sensor offset value for current temperature calibration (default is 40 °C, must be specified in Degrees Celsius)
* minimumTargetTemperature - minimum target temperature accepted by the device (default is 16 °C, must be specified in Degrees Celsius)
* maximumTargetTemperature - maximum target temperature accepted by the device (default is 30 °C, must be specified in Degrees Celsius)
* xFanEnabled - automatically turn on xFan functionality in supported device modes (xFan actual setting is not modified by the Home App if disabled)
* temperatureSensor - control additional temperature sensor accessory in Home App (disabled = do not add to Home App / child = add as a child accessory / separate = add as a separate (independent) accessory)
* disabled - set to true if you do not want to control this device in the Home App (old devices can be removed using this parameter)

![Homebridge UI](./uiconfig.jpg)

## Tips

### MAC Address in GREE+ mobile app

Open selected device and in the upper right corner select menu symbol:

![AC device](./greedevice.jpg)![MAC Address](./greemac.jpg)

### Network broadcast address

All devices on the local network use the same broadcast address. Broadcast address can be calculated from the IP address and the subnet mask of any device which is connected to the LAN. (E.g. your router or computer) You can find several online calculators which help to determine the broadcast address.
All devices on the local network use the same broadcast address. The broadcast address can be calculated from the IP address and the subnet mask of any device which is connected to the LAN. (E.g. your router or computer) You can find several online calculators which help to determine the broadcast address.

On Unix like systems you can query the broadcast address using the following command:
On Unix-like systems you can query the broadcast address using the following command:
```bash
ifconfig | grep broadcast
# result
Expand Down
42 changes: 38 additions & 4 deletions config.schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,31 @@
"type": "boolean",
"default": false
},
"temperatureSensor": {
"type": "string",
"required": true,
"default": "disabled",
"oneOf": [
{
"title": "Disabled",
"enum": [
"disabled"
]
},
{
"title": "Child accessory",
"enum": [
"child"
]
},
{
"title": "Separate accessory",
"enum": [
"separate"
]
}
]
},
"disabled": {
"type": "boolean"
}
Expand Down Expand Up @@ -197,7 +222,7 @@
"key": "devices[].sensorOffset",
"flex": "1 1 50%",
"title": "Temperature offset:",
"description": "Temperature sensor calibration (in Celsius)",
"description": "Temperature sensor calibration (in Degrees Celsius)",
"condition": {
"functionBody": "return model.devices[arrayIndices].disabled !== true;"
}
Expand All @@ -206,7 +231,7 @@
"key": "devices[].minimumTargetTemperature",
"flex": "1 1 50%",
"title": "Minimum target temperature:",
"description": "Minimum target temperature (in Celsius)",
"description": "Minimum target temperature (in Degrees Celsius)",
"condition": {
"functionBody": "return model.devices[arrayIndices].disabled !== true;"
}
Expand All @@ -215,7 +240,7 @@
"key": "devices[].maximumTargetTemperature",
"flex": "1 1 50%",
"title": "Maximum target temperature:",
"description": "Maximum target temperature (in Celsius)",
"description": "Maximum target temperature (in Degrees Celsius)",
"condition": {
"functionBody": "return model.devices[arrayIndices].disabled !== true;"
}
Expand All @@ -224,7 +249,16 @@
"key": "devices[].xFanEnabled",
"flex": "1 1 50%",
"title": "xFan enabled",
"description": "If enabled then xFan functionality is turned on automatically on device",
"description": "If enabled, then xFan functionality is turned on automatically on the device",
"condition": {
"functionBody": "return model.devices[arrayIndices].disabled !== true;"
}
},
{
"key": "devices[].temperatureSensor",
"flex": "1 1 50%",
"title": "Temperature sensor:",
"description": "Additional temperature sensor in Home App",
"condition": {
"functionBody": "return model.devices[arrayIndices].disabled !== true;"
}
Expand Down
Binary file added greedevice.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added greemac.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"private": false,
"displayName": "GREE Air Conditioner",
"name": "@eibenp/homebridge-gree-airconditioner",
"version": "1.0.0",
"version": "1.0.1",
"description": "Control GREE Air Conditioners from Homebridge",
"license": "Apache-2.0",
"repository": {
Expand Down
Loading

7 comments on commit 1a7a212

@ProudHeretic666
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for making this plugin. I am trying to get the configuration just right so that I can automate my temperature in my grow room. I have an external thermo/hygrometer that I am using to trigger my GREE portable air conditioner with automation rules in Homekit. Should I set Temperature sensor to Disabled or Separate?

@eibenp
Copy link
Owner Author

@eibenp eibenp commented on 1a7a212 Sep 20, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for making this plugin. I am trying to get the configuration just right so that I can automate my temperature in my grow room. I have an external thermo/hygrometer that I am using to trigger my GREE portable air conditioner with automation rules in Homekit. Should I set Temperature sensor to Disabled or Separate?

I think your external thermo/hygrometer is more accurate. You can safely set Temperature sensor to Disabled.

@ProudHeretic666
Copy link

@ProudHeretic666 ProudHeretic666 commented on 1a7a212 Sep 20, 2023 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eibenp
Copy link
Owner Author

@eibenp eibenp commented on 1a7a212 Sep 20, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the fast response.  What about Temperature offset?  It is at the default 40.  The problem I am having is that the unit is always reading much lower than the external sensor and therefore, it turns on but doesn't start cooling

40 is the factory default. If you set Temperature offset to 40 then Home App will get the same temperature value as measured by the GREE unit. (The same value is displayed in GREE+ app if you query the actual room temperature.)

This plugin is an interface between GREE AC units and the Home App. It is not possible to control how the AC unit works. Temperature offset is not in contact with cooling and heating. It controls only the value passed to the Home App from the AC units internal sensor. There is no way to turn on cooling if the internal sensor measures a lower temperature value. GREE AC units do not accept temperature values from external devices.

Internal sensor is always on. The plugin allows adding a separate Temperature sensor to the Home App, but if it is set to disabled then only the second, additional Temperature sensor is turned off. The heater-cooler control will continue to receive measured temperature values. These values can be modified by temperature offset. Unfortunately this is a one way communication. Temperature values are received from AC unit but can not be sent to it. And there is no way to tell with the AC unit that the internal sensor is not accurate.

@ProudHeretic666
Copy link

@ProudHeretic666 ProudHeretic666 commented on 1a7a212 Sep 20, 2023 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eibenp
Copy link
Owner Author

@eibenp eibenp commented on 1a7a212 Sep 20, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let me try to be more clear on what I am trying to do.  I have an external thermo/hygrometer which measures the temp and humidity in the room.  Both the GREE AC and this external thermo unit are listed in Homekit.   I have created an automation on the GREE AC in Homekit that says "if the temperature rises above 75 degrees, turn on the GREE AC and cool to 72 degrees, and turn off after 5 minutes". This does seems to work sometimes, but it is not consistent.  So in the plugin, should I put the Temp sensor to Disabled or Separate?  Does that make sense?

You can use your external thermo unit and set Temp sensor on GREE AC to disabled. Set up automation based on the external thermo unit. It measures more accurate and you can place it on an optimal location.

If you do not have an external thermo unit or you do not want to use it and you would like to set up temperature based automation then you need to enable the Temp sensor. It is up to you if you set it as separate or child. Separate and child differ in Home App appearance but they both can be used for automation purposes. Temperature based automation without an external thermo unit is the only preference for the additional temp sensor. Anybody who do not need temperature based automation or have an external thermo unit should set the additional temp sensor to disabled.

Unfortunately automation is controlled by the home kit, and temperature based events do not work consistent in the actual version (16.6). This is not GREE AC unit dependent, it's a problem of Apple.

@ProudHeretic666
Copy link

@ProudHeretic666 ProudHeretic666 commented on 1a7a212 Sep 20, 2023 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.