Skip to main content

Discover, connect and control Gree based minisplit systems

Project description

Python package

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,
    )

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

greeclimate-2.1.0.tar.gz (35.2 kB view details)

Uploaded Source

Built Distribution

greeclimate-2.1.0-py3-none-any.whl (28.4 kB view details)

Uploaded Python 3

File details

Details for the file greeclimate-2.1.0.tar.gz.

File metadata

  • Download URL: greeclimate-2.1.0.tar.gz
  • Upload date:
  • Size: 35.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.19

File hashes

Hashes for greeclimate-2.1.0.tar.gz
Algorithm Hash digest
SHA256 fc97f70cf96006ae3f2bbf187a3a9251bcbd25c4c2a7bbf294fa2caf2f88bc57
MD5 ba9a421d0ea304f9afae987d9b539960
BLAKE2b-256 1c7f2285faf50df3c6e67bfad181215593ec0663a5b9e0a135274c6b5687998f

See more details on using hashes here.

File details

Details for the file greeclimate-2.1.0-py3-none-any.whl.

File metadata

  • Download URL: greeclimate-2.1.0-py3-none-any.whl
  • Upload date:
  • Size: 28.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.19

File hashes

Hashes for greeclimate-2.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 0c285f3d3347225e894027101fc0344fba2c2a04efc200b8aff7c8892ac1b522
MD5 0b534cd8dc532adccafec863382d4629
BLAKE2b-256 6ef1fc70d5d2f9a2ff82b7dcbdd05b7ebcdf5f4c80ef920ee4644d571fea3e4d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page