Gree Climate
Discover, connect and control Gree based mini-split systems.
greeclimate 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
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.
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,
)
Automatic discovery uses ifaddr to enumerate IPv4 interfaces and derives their subnet broadcast addresses.
IPv6 and non-loopback /31 and /32 networks are skipped. Loopback is excluded unless
Discovery(allow_loopback=True) is used; then scans target the loopback host address.
Passing None or [] as scan(target_addresses=...) uses automatic enumeration. A non-empty list of
ipaddress.IPv4Address destinations bypasses enumeration and can select custom broadcast or
unicast targets. Automatic enumeration derives broadcasts from prefixes rather than
using OS-specific broadcast or peer fields.
To discover a device at a known address:
from ipaddress import IPv4Address
devices = await discovery.scan(wait_for=5, target_addresses=[IPv4Address(host)])
The existing bcast_ifaces parameter remains supported as a compatibility alias, including
positional calls. Supplying both parameters with non-None values raises ValueError.
search_devices(target_addresses=...) likewise retains its existing broadcastAddrs
keyword and positional calls, with the same conflict and automatic enumeration rules.
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.
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 or tcpdump to capture the network traffic can greatly assist in investigations.
Setup
This presumes you have python installed
pip install -r requirements.txt
Getting some basic information about your network
Linux / OSX
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 here if you can.
python gree.py --discovery > discovery_results.txt
1 maintainer
Metadata
1 maintainer
Release files for greeclimate 3.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| greeclimate-3.3.0.tar.gz | 44.0 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| greeclimate-3.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 75.9 kB
Release files / greeclimate-3.3.0.tar.gz
| Download URL | greeclimate-3.3.0.tar.gz |
|---|---|
| Size | 44.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3820f1a109e7033a3aa01cfb7ed3b2e7e478616f9933f3395537b1ee30a4e2f3
|
|
BLAKE2b-256 checksum How to use checksums |
3d6eec3870af4bd34b3e4f33562fc3ec0e303918c0966f86322b1010d469ea50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.8
|
Release files / greeclimate-3.3.0-py3-none-any.whl
| Download URL | greeclimate-3.3.0-py3-none-any.whl |
|---|---|
| Size | 31.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f7948abfb79929ba83be482302ccc27dc26bff0d77c1d0c6ba4d2fd1e17e4ab4
|
|
BLAKE2b-256 checksum How to use checksums |
c0114d5e28792b63afb6d280a3197eebb31af6f6ddd2c09de298a7ba63566f31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.8
|
Security for greeclimate 3.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
