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
Maintainers can publish from master through GitHub Actions with gh workflow run python-package.yml --repo cmroche/greeclimate --ref master. The workflow runs the test matrix before semantic-release selects a version and publishes to PyPI and GitHub; nightly publication remains enabled. Pushes and pull requests do not publish.
Use Gree Climate
Discover devices on the LAN and bind immediately after scanning.
import asyncio
from greeclimate.device import Device
from greeclimate.discovery import Discovery
async def main():
discovery = Discovery()
try:
for device_info in await discovery.scan(wait_for=5):
device = Device(device_info)
try:
await device.bind()
print(device_info.name, device_info.ip)
finally:
device.close()
finally:
discovery.close()
asyncio.run(main())
The following snippets run inside main(); device-control snippets go after binding and before closing device.
Scan a known IP address instead of broadcasting on the LAN.
from ipaddress import IPv4Address
devices = await discovery.scan(
wait_for=5, target_addresses=[IPv4Address("192.0.2.10")]
)
Discover a device listening on UDP port 7000, including loopback addresses.
discovery = Discovery(allow_loopback=True)
devices = await discovery.scan(wait_for=5)
Manually poll for updated device state.
await device.update_state()
Cool to 25°C and send updates to the device.
from greeclimate.device import Mode, TemperatureUnits
device.power = True
device.mode = Mode.Cool
device.temperature_units = TemperatureUnits.C
device.target_temperature = 25
await device.push_state_update()
Set a Fahrenheit target by selecting units before setting the temperature.
from greeclimate.device import TemperatureUnits
device.temperature_units = TemperatureUnits.F
device.target_temperature = 77
await device.push_state_update()
Set fan speed and swing positions.
from greeclimate.device import FanSpeed, HorizontalSwing, VerticalSwing
device.fan_speed = FanSpeed.Auto
device.horizontal_swing = HorizontalSwing.FullSwing
device.vertical_swing = VerticalSwing.FullSwing
await device.push_state_update()
Enable optional features where supported by the device.
device.light = True
device.xfan = True
device.quiet = True
await device.push_state_update()
Set a dehumidifier's target relative humidity.
device.target_humidity = 45
await device.push_state_update()
Turn the device off, then request a fresh status update.
device.power = False
await device.push_state_update()
await device.update_state()
Automatic discovery uses IPv4 subnet broadcasts via ifaddr, skipping IPv6, loopback, and non-loopback /31 and /32 networks. allow_loopback=True adds loopback host addresses; non-empty target_addresses bypasses interface enumeration, while None or [] uses it.
Legacy bcast_ifaces (scan) and broadcastAddrs (search_devices) keywords and positional calls remain supported; combining an alias with non-None target_addresses raises ValueError.
Use Gree Emulator
Run these commands from the repository root with Python 3.10+ and dependencies installed; each server runs until Ctrl-C.
List supported simulated profiles and their exact MID values.
python -m gree_emulator --list-profiles
Run one simulated AC on loopback, with stable identity across restarts.
python -m gree_emulator --profile sim-w04n-v17 --mid 10001 --seed demo --listen 127.0.0.1
Run three independently controlled simulated ACs on the same endpoint.
python -m gree_emulator --profile sim-w04n-v17 --mid 10001 --count 3 --seed demo --listen 127.0.0.1
Run the supplied mixed-device configuration, including gateways and child devices.
python -m gree_emulator --config examples/emulator-devices.json
Expose the simulated ACs to LAN discovery on UDP port 7000, on a trusted test network only.
python -m gree_emulator --profile sim-w04n-v17 --mid 10001 --count 3 --seed demo --listen 0.0.0.0 --port 7000
Capture packet logs on stderr while keeping startup announcements on stdout; scrub identities, addresses, and bind exchanges before sharing.
python -m gree_emulator --profile sim-w04n-v17 --mid 10001 --seed demo --listen 127.0.0.1 2> emulator-packets.log
These are simulated appliances, not complete firmware emulations. The library's push_state_update() currently adds an unsupported BuzzerCtrl field, so simulator commands can be rejected even when sending succeeds. See the emulator guide for configuration, protocol differences, and consumer-compatibility limits.
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.4.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.4.0.tar.gz | 77.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| greeclimate-3.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 144.5 kB
Release files / greeclimate-3.4.0.tar.gz
| Download URL | greeclimate-3.4.0.tar.gz |
|---|---|
| Size | 77.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e40273ac52e5801c73e6b1cef5418de1c3c7fec22313a5f4af8f746d8fe552d6
|
|
BLAKE2b-256 checksum How to use checksums |
9b169961cd981a68dfcd5953881e24f17836f9fec55dd44c01dc0b6aa3597ad1
|
| 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.4.0-py3-none-any.whl
| Download URL | greeclimate-3.4.0-py3-none-any.whl |
|---|---|
| Size | 66.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
043118658009d8f40ada260c7ca467318a0049c7e270fbbd8f2ed294a6ad555f
|
|
BLAKE2b-256 checksum How to use checksums |
9bf8edf6149e8438ea547cf4612802f7823a57f7c5775b2633c2bfae4d279ff5
|
| 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.4.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.
