Metadata-Version: 2.4
Name: greeclimate-davo22
Version: 2.7.4
Summary: Fork of greeclimate adding Gree Cloud (MQTT) support, for cloud-only devices
Home-page: https://github.com/davo22/greeclimate
Author: Clifford Roche
Author-email: 
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: netifaces>=0.11.0
Requires-Dist: pycryptodome>=3.23.0
Requires-Dist: aiohttp>=3.13.0
Requires-Dist: aiomqtt>=2.5.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

![Python package](https://github.com/davo22/greeclimate/actions/workflows/python-package.yml/badge.svg)
[![PyPI](https://img.shields.io/pypi/v/greeclimate-davo22.svg)](https://pypi.org/project/greeclimate-davo22/)

## Gree Climate

Discover, connect and control Gree based mini-split systems.

> **This is a fork.** It adds Gree Cloud (MQTT) support for devices that cannot be reached on the
> local network, and it is published as **`greeclimate-davo22`**, importing as **`greeclimate_davo22`**.
> The upstream project at [cmroche/greeclimate](https://github.com/cmroche/greeclimate) keeps the
> `greeclimate` name on PyPI. The names differ on purpose: Home Assistant's built-in `gree`
> integration installs upstream `greeclimate`, and two distributions writing to the same
> `site-packages/greeclimate/` directory would overwrite each other file by file.

**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_

## ⭐ New: Cloud-Only Device Support

This fork adds support for **cloud-only devices** that don't respond to local UDP discovery. These devices only work through the Gree cloud: over MQTT for modules with protocol `V3.2` and newer, or through the legacy TLS device gateway for older modules (`V2.x`, `V1.x`), which never join the MQTT broker. The transport is picked per device from its cloud record.

**Fork notice (GPL-3.0 §5a):** this is a modified version of
[cmroche/greeclimate](https://github.com/cmroche/greeclimate), maintained by
[davo22](https://github.com/davo22) since 2026-02 and published as the
`greeclimate-davo22` distribution / `greeclimate_davo22` module so it can be
installed next to the original. Copyright and the GPL-3.0 licence of the
original are unchanged; see `LICENSE.txt`.

**Features:**
- 🌐 Authenticate with Gree Cloud API
- 🔍 Discover cloud-only devices
- 📡 Control via MQTT broker (protocol >= 3.2) or the legacy TLS gateway (older modules)
- 🌍 Support for all regions (Europe, US, Asia, etc.)
- 🔒 Both CipherV1 (ECB) and CipherV2 (GCM)

See **[CLOUD_SUPPORT.md](CLOUD_SUPPORT.md)** for detailed documentation and examples.

**Quick Example:**
```python
from greeclimate_davo22.cloud_discovery import CloudDiscovery

discovery = CloudDiscovery('email@example.com', 'password', 'Europe')
devices = await discovery.scan()

device = await discovery.create_device(devices[0])
await device.bind()

device.power = True
device.target_temperature = 24
await device.push_state_update()
```

**Based on the following work**

- [Gree Remote by tomikaa87](https://github.com/tomikaa87/gree-remote)
- [greeclimate-js](https://github.com/davo22/greeclimate-js) - Cloud protocol reverse engineering

## Getting the package

`pip3 install greeclimate-davo22`

Releases are published to [PyPI](https://pypi.org/project/greeclimate-davo22/) from GitHub
releases via Trusted Publishing (`.github/workflows/publish.yml`). To install straight from git
instead: `pip3 install git+https://github.com/davo22/greeclimate.git@<tag>`

## Use Gree Climate

### Local Devices (UDP)

For devices that respond to local network discovery:

### 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()
```

### Cloud-Only Devices (MQTT)

For devices that only work through Gree Cloud (don't respond to local discovery):

```python
from greeclimate_davo22.cloud_discovery import CloudDiscovery

# Discover cloud devices
discovery = CloudDiscovery(
    username='your_email@example.com',
    password='your_password',
    server='Europe'  # or 'North American', 'Asia', etc.
)

devices = await discovery.scan()

# Connect to device
device = await discovery.create_device(devices[0])
await device.bind()
await device.update_state()

# Control device
device.power = True
device.target_temperature = 24
await device.push_state_update()

# Cleanup
await device.close()
await discovery.close()
```

**See [CLOUD_SUPPORT.md](CLOUD_SUPPORT.md) for complete cloud device documentation.**

## 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
```
