## Gree Climate
Discover, connect and control Gree based mini-split systems.
**greenclimat** is a ***fully async*** Python3 based package for controlling Gree based ACs and heat pumps. Gree is a common brand for mini-split systems and is licensed and resold under many product names. This module should work for any device that also works with the Gree+ app, but has been tested on
- Proklima mini-splits units
- Trane mini-split heat pump (4TXK38)
_If you have tested and know of others systems that work, please fork and submit a PR with the make and model_
**Based on the following work**
- [Gree Remote by tomikaa87](https://github.com/tomikaa87/gree-remote)
## Getting the package
The easiest way to grab **greeclimate** is through PyPI
`pip3 install greeclimate`
## Use Gree Climate
### Finding and binding to devices
Scan the network for devices, select a device and immediately bind. See the notes below for caveats.
```python
discovery = Discovery()
for device_info in await discovery.scan(wait_for=5):
try:
device = Device(device_info)
await device.bind() # Device will auto bind on update if you omit this step
except CannotConnect:
_LOGGER.error("Unable to bind to gree device: %s", device_info)
continue
_LOGGER.debug(
"Adding Gree device at %s:%i (%s)",
device.device_info.ip,
device.device_info.port,
device.device_info.name,
)
```
#### Caveats
Devices have and use 2 encryption keys. 1 for discovery and setup which is the same on all gree devices, and a second which is negotiated during the binding process.
Binding is incredibly finnicky, if you do not have the device key you must first scan and re-bind. The device will only respond to binding requests immediately proceeding a scan.
### Update device state
It's possible for devices to be updated from external sources, to update the `Device` internal state with the physical device call `Device.update_state()`
### Properties
There are several properties representing the state of the HVAC. Setting these properties will command the HVAC to change state.
Not all properties are supported on each device, in the event a property isn't supported commands to the HVAC will simply be ignored.
When setting a value it is cached but not pushed to the device until `Device.push_state_update()` is called.
```python
device = Device(...)
device.power = True
device.mode = Mode.Auto
device.target_temperature = 25
device.temperature_units = TemperatureUnits.C
device.fan_speed = FanSpeed.Auto
device.fresh_air = True
device.xfan = True
device.anion = True
device.sleep = True
device.light = True
device.horizontal_swing = HorizontalSwing.FullSwing
device.vertical_swing = VerticalSwing.FullSwing
device.quiet = True
device.turbo = True
device.steady_heat = True
device.power_save = True
device.target_humidity = 45
# Send the state update to the HVAC
await device.push_state_update()
```
## Debugging
Maybe the reason you're here is that you're working with Home Assistant and your device isn't being detected.
There are a few tools to help investigate the various compatibility problems that Gree based devices present.
Below is a series of tests, please run them and use their output in issue reports. Additionally using [Wireshark](https://www.wireshark.org) or tcpdump to capture the network traffic can greatly assist in investigations.
### Setup
This presumes you have python installed
```bash
pip install -r requirements.txt
```
### Getting some basic information about your network
#### Linux / OSX
```bash
sudo route -n
sudo ifconfig
```
#### Windows command line
```
route print -4
ipconfig
```
### Running the discovery tests
First test is to check the response of devices when trying to discovery them, writes the results to **discovery_results.txt**. Use [Wireshark](https://www.wireshark.org) here if you can.
```bash
python gree.py --discovery > discovery_results.txt
```
Raw data
{
"_id": null,
"home_page": "https://github.com/cmroche/greeclimate",
"name": "greeclimate",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Clifford Roche",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/c6/2e/89771015a1d1c4aa0e4707dc139d6f6a21404c5156f9b93d096e7e629505/greeclimate-1.4.1.tar.gz",
"platform": null,
"description": "\n\n## Gree Climate\n\nDiscover, connect and control Gree based mini-split systems.\n\n**greenclimat** is a ***fully async*** Python3 based package for controlling Gree based ACs and heat pumps. Gree is a common brand for mini-split systems and is licensed and resold under many product names. This module should work for any device that also works with the Gree+ app, but has been tested on\n\n- Proklima mini-splits units\n- Trane mini-split heat pump (4TXK38)\n\n_If you have tested and know of others systems that work, please fork and submit a PR with the make and model_\n\n**Based on the following work**\n\n- [Gree Remote by tomikaa87](https://github.com/tomikaa87/gree-remote)\n\n## Getting the package\n\nThe easiest way to grab **greeclimate** is through PyPI\n`pip3 install greeclimate`\n\n## Use Gree Climate\n\n### Finding and binding to devices\n\nScan the network for devices, select a device and immediately bind. See the notes below for caveats.\n\n```python\ndiscovery = Discovery()\nfor device_info in await discovery.scan(wait_for=5):\n try:\n device = Device(device_info)\n await device.bind() # Device will auto bind on update if you omit this step\n except CannotConnect:\n _LOGGER.error(\"Unable to bind to gree device: %s\", device_info)\n continue\n\n _LOGGER.debug(\n \"Adding Gree device at %s:%i (%s)\",\n device.device_info.ip,\n device.device_info.port,\n device.device_info.name,\n )\n```\n\n#### Caveats\n\nDevices have and use 2 encryption keys. 1 for discovery and setup which is the same on all gree devices, and a second which is negotiated during the binding process.\n\nBinding is incredibly finnicky, if you do not have the device key you must first scan and re-bind. The device will only respond to binding requests immediately proceeding a scan.\n\n### Update device state\n\nIt's possible for devices to be updated from external sources, to update the `Device` internal state with the physical device call `Device.update_state()`\n\n### Properties\n\nThere are several properties representing the state of the HVAC. Setting these properties will command the HVAC to change state.\n\nNot all properties are supported on each device, in the event a property isn't supported commands to the HVAC will simply be ignored.\n\nWhen setting a value it is cached but not pushed to the device until `Device.push_state_update()` is called.\n\n```python\ndevice = Device(...)\ndevice.power = True\ndevice.mode = Mode.Auto\ndevice.target_temperature = 25\ndevice.temperature_units = TemperatureUnits.C\ndevice.fan_speed = FanSpeed.Auto\ndevice.fresh_air = True\ndevice.xfan = True\ndevice.anion = True\ndevice.sleep = True\ndevice.light = True\ndevice.horizontal_swing = HorizontalSwing.FullSwing\ndevice.vertical_swing = VerticalSwing.FullSwing\ndevice.quiet = True\ndevice.turbo = True\ndevice.steady_heat = True\ndevice.power_save = True\ndevice.target_humidity = 45\n\n# Send the state update to the HVAC\nawait device.push_state_update()\n```\n\n## Debugging\n\nMaybe the reason you're here is that you're working with Home Assistant and your device isn't being detected.\n\nThere are a few tools to help investigate the various compatibility problems that Gree based devices present.\n\nBelow is a series of tests, please run them and use their output in issue reports. Additionally using [Wireshark](https://www.wireshark.org) or tcpdump to capture the network traffic can greatly assist in investigations.\n\n### Setup\n\nThis presumes you have python installed\n\n```bash\npip install -r requirements.txt\n```\n\n### Getting some basic information about your network\n#### Linux / OSX\n```bash\nsudo route -n\nsudo ifconfig\n```\n#### Windows command line\n```\nroute print -4\nipconfig\n```\n\n### Running the discovery tests\n\nFirst test is to check the response of devices when trying to discovery them, writes the results to **discovery_results.txt**. Use [Wireshark](https://www.wireshark.org) here if you can.\n\n```bash\npython gree.py --discovery > discovery_results.txt\n```\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Discover, connect and control Gree based minisplit systems",
"version": "1.4.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4e8dbe90c33ee8992a78d1f9760f5c2a261dcd0384b8830fe338b8dfae8d7706",
"md5": "6a92f3955129a27b2e269a9959e3b9f7",
"sha256": "62f832f9078d94ebf26d30a301395c244890c63ea49e8f9f106864b72a042626"
},
"downloads": -1,
"filename": "greeclimate-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6a92f3955129a27b2e269a9959e3b9f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 26023,
"upload_time": "2023-02-05T21:13:04",
"upload_time_iso_8601": "2023-02-05T21:13:04.866110Z",
"url": "https://files.pythonhosted.org/packages/4e/8d/be90c33ee8992a78d1f9760f5c2a261dcd0384b8830fe338b8dfae8d7706/greeclimate-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c62e89771015a1d1c4aa0e4707dc139d6f6a21404c5156f9b93d096e7e629505",
"md5": "d6827396e3fc8479d1208bb507a98cad",
"sha256": "864f138e385afb0947b544a07120a0921b0e38e8a1c3e8f6811ea462abff7f32"
},
"downloads": -1,
"filename": "greeclimate-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "d6827396e3fc8479d1208bb507a98cad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 26548,
"upload_time": "2023-02-05T21:13:07",
"upload_time_iso_8601": "2023-02-05T21:13:07.655458Z",
"url": "https://files.pythonhosted.org/packages/c6/2e/89771015a1d1c4aa0e4707dc139d6f6a21404c5156f9b93d096e7e629505/greeclimate-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-05 21:13:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "cmroche",
"github_project": "greeclimate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "netifaces",
"specs": []
},
{
"name": "pycryptodome",
"specs": [
[
"~=",
"3.10"
]
]
}
],
"lcname": "greeclimate"
}
JSON
