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
Simple example showing how to discover and bind to devices on the LAN
import asyncio
from greeclimate.device_factory import create_device
from greeclimate.discovery import Discovery
async def main():
discovery = Discovery()
try:
for device_info in await discovery.scan(wait_for=5):
device = create_device(device_info)
try:
await device.bind()
print(device_info.name, device_info.ip)
finally:
device.close()
finally:
discovery.close()
asyncio.run(main())
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()
Request exact status columns and access raw protocol properties by name.
await device.update_state(["Pow", "Lig"])
# Read the cache after a DATA reply arrives.
print(device.get_property("Pow"))
device.set_property("Lig", 0)
await device.push_state_update()
Iterate through children from a Gateway device
from greeclimate.gateway import GatewayDevice
from greeclimate.network import Response
gateway = create_device(device_info)
if not isinstance(gateway, GatewayDevice):
raise TypeError("Select a MID 60 gateway")
try:
await gateway.bind()
for child in await gateway.get_sub_devices():
if not child.ready.is_set(): # Metadata-only commercial records.
continue
data_received = asyncio.Event()
def on_child_data(data):
if {"Pow", "Mod", "SetTem"} <= data.keys():
data_received.set()
child.add_handler(Response.DATA, on_child_data)
try:
await child.update_state(["Pow", "Mod", "SetTem"])
await asyncio.wait_for(data_received.wait(), timeout=5)
print(child.device_info.name, dict(child.raw_properties))
child.set_property("Mod", 2)
child.set_property("SetTem", 22)
child.set_property("Pow", 1)
await child.push_state_update()
data_received.clear()
await child.update_state(["Pow", "Mod", "SetTem"])
await asyncio.wait_for(data_received.wait(), timeout=5)
print(child.get_property("Pow"), child.get_property("SetTem"))
finally:
child.remove_handler(Response.DATA, on_child_data)
finally:
gateway.close() # Also closes every owned child.
For an AC, 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()
Use capability evidence to offer an optional AC control without treating unknown as unsupported.
if device.capabilities["quiet"] is True:
device.quiet = True
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()
Use Gree Emulator
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
Run the simulated air-to-water heat pump (the 9301 and 9302 profiles remain raw-client families).
python -m gree_emulator --profile sim-w06a-p3-v6.04-9300 --mid 9300 --seed demo --listen 127.0.0.1
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
Device and protocol reference
- Known MIDs: current polling contracts and gateway observations.
- Known HIDs: firmware-string segments, matching rules, and sourced firmware codes.
- Cloud-only firmware findings: inspected LAN/cloud boundaries, not upgrade recommendations.
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
Metadata
Release files for greeclimate 4.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 | Actions |
|---|---|---|---|---|
| greeclimate-4.3.0.tar.gz | 707.8 kB | With provenance | Details for greeclimate-4.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| greeclimate-4.3.0-py3-none-any.whl | Python 3 | none | any | Details for greeclimate-4.3.0-py3-none-any.whl |
Total release size: 1.1 MB
Release files / greeclimate-4.3.0.tar.gz
| Download URL | greeclimate-4.3.0.tar.gz |
|---|---|
| Size | 707.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ef04fb77b4534c78eec75f40b42f1c63000b5a6e8ad3a80529c15457da53f8ad
|
|
BLAKE2b-256 checksum How to use checksums |
4025929350f94a63ea1ba6e1f2175be9dfeeaf65614c949afda948b53bdded5a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / greeclimate-4.3.0-py3-none-any.whl
| Download URL | greeclimate-4.3.0-py3-none-any.whl |
|---|---|
| Size | 428.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4947d55189efd39e51e8f9e7acfbf1dba94e6301ab0e1091416e7818f322ad3
|
|
BLAKE2b-256 checksum How to use checksums |
6d00ea19e421cb61466849d448aaa851e3488b51e5d272e497ef9ff73756fd9c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for greeclimate 4.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for greeclimate-4.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA 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.
To learn more about protecting yourself from malicious actors, visit our package security documentation.