Gree Climate Component: local control of Gree air conditioners in Home Assistant

Local control instead of a cloud round trip

The core claim in the README is about where the connection goes. This integration connects directly to your HVAC devices via their IP address on the local network, unlike the official mobile app, which establishes a direct connection only during initial setup and subsequently operates through Gree's servers.

That difference is the whole point of the project. A cloud-dependent air conditioner app means your AC stops working when the vendor's servers have a bad day, and it means your local network traffic is observable to someone else. A local integration keeps the whole path inside your house.

The mechanism has a catch, and the README is upfront about it. The integration attempts to obtain the encryption key by the initial setup protocol, which has been reverse-engineered. So the project is not talking to the unit in the clear; it is performing the same key exchange the vendor app performs, using a protocol that was worked out by inspection rather than documented.

The official apps this replaces are listed for reference: the Gree+ Android and iOS apps, and the EWPE Smart Android and iOS apps. The README also points to two companion projects, one for extracting encryption keys from an account on Gree's cloud server and one for configuring HVAC wifi without the mobile app.

The scope is narrow by design. It is a climate component for air conditioners that support the Gree protocol, written in Python 3 for Home Assistant, and it is not a general air conditioner integration. The topic tags say the same thing: air-conditioner, climate, gree, hacs, home-assistant, homeassistant-integration and python.

The key retrieval problem, and the documented workarounds

This is the single biggest practical obstacle in the project, and the README addresses it in a dedicated paragraph.

If your HVAC device was previously set up for remote access using a mobile app, the integration may fail to retrieve the encryption key automatically. The reason is structural: the key is derived during the initial setup handshake, so a unit that was already set up has already had its key consumed, and the reverse-engineered setup sequence will not produce a second one.

The README offers two routes around it. The first is to extract encryption keys from an account on Gree's cloud server, with a link to a separate client project for that purpose. The second is to provide the key yourself.

Providing the key yourself is documented in the manual installation section as an optional step, and the method given involves pulling the SQLite database from an Android device. The commands are:

adb backup -f ~/backup.ab -noapk com.gree.ewpesmart
dd if=data.ab bs=1 skip=24 | python -c "import zlib,sys;sys.stdout.write(zlib.decompress(sys.stdin.read()))" | tar -xvf -
sqlite3 data.ab 'select privateKey from db_device_20170503;' # but table name can differ a little bit.

The resulting value is then written into `climate.yaml` as `encryption_key: <key>`. The comment on the last line is worth noting, since the table name can differ a little between app versions.

The README also links a specific issue for the case where you hit a UTF-8 decode error while doing this, with the example error message included, so if the extraction fails on the character decoding, that issue is where the answer lives.

Two other optional parameters are documented. You can provide the `uid` parameter, which can be sniffed and which is not needed for all devices, and you can set custom icons by modifying the icon translation file `icons.json`, following the Home Assistant documentation on icon translations.

Installing with HACS or by copying the custom_components folder

This component is added to the HACS default repository list, and the README carries a HACS default badge, so the store route is the primary one.

The recommended setup is the UI config flow. The integration can be added from the Home Assistant UI: go to Settings, then Devices and Services, click Add Integration, search for Gree Climate, and fill in the desired `name`, `host`, `port` and `MAC address`. After setup you can open the integration options to configure additional parameters, and saving any changes in the options dialog automatically reloads the integration, so new settings take effect immediately without restarting Home Assistant.

That last behaviour is a genuine convenience that many custom integrations do not offer, and it is why the config flow is described as recommended.

The manual route is for anyone not using HACS. You copy the `custom_components` folder to your own hassio `/config` folder, and the README points to `manual-configuration.yaml` for a complete configuration example with all available options and detailed comments. The basic YAML is short:

gree:
  - name: "First AC"
    host: "192.168.1.101"
    mac: "20-FA-BB-12-34-56"
    encryption_version: 2

The YAML configuration is then included from your configuration.yaml:

climate: !include your_configuration.yaml

Debugging is one more optional step, and it is worth turning on the first time you set this up:

logger:
  default: error
  logs:
    custom_components.gree: debug
    custom_components.gree.climate: debug

The component was tested on Home Assistant 2025.6.3, and the README asks that bug reports include details about the device, the Home Assistant version and what exactly went wrong. A separate `supported-devices.md` file in the repository holds the comprehensive list of tested devices.

Cross-VLAN discovery, and the UDP 7000 constraint it creates

The cross-VLAN discovery feature is the most technically interesting part of the documentation, and it comes with explicit limits.

The problem it solves is that standard discovery relies on UDP broadcast, which routers do not forward between VLANs. If your AC is on a different subnet than Home Assistant, you pick Discover devices on other VLANs or subnets on the first setup screen and enter one or both of two fields. Networks takes comma-separated CIDRs to sweep via unicast, for example `192.168.30.0/24` or `10.10.20.0/24, 10.10.30.0/24`. Hosts takes comma-separated individual IPs, for example `192.168.30.50, 192.168.30.51`.

Each address is probed directly with a UDP unicast packet on port 7000, so inter-VLAN routing and any firewall between Home Assistant and the target subnet must allow UDP/7000. That is the operational requirement to check first if discovery finds nothing.

The limits are stated with unusual precision. A single network, and the combined total across networks plus hosts, may contain at most 65,536 addresses, which is a `/16` like `192.168.0.0/16`. Anything larger, such as `10.0.0.0/8` or `172.16.0.0/12`, must be split into multiple CIDRs or covered by the hosts field. The README also warns that scanning a whole `/16` fires tens of thousands of UDP packets and can stress consumer routers, and advises preferring the narrowest CIDR you can identify.

Two smaller behaviours are documented. Values entered during one setup are remembered for the duration of the Home Assistant session, so adding several devices in a row does not require retyping them. And broadcast discovery on the local VLAN still runs alongside the unicast scan, so units on the same subnet as Home Assistant are also found.

The extra sensors and switches the unit exposes

Beyond the climate entity, the integration surfaces hardware features that Home Assistant would otherwise not see, and it does so automatically where the hardware supports it.

If the AC unit has an outside temperature sensor, it is automatically detected and exposed in two ways. As a climate entity attribute named `outside_temperature`, accessible in a template as `{{ state_attr('climate.your_ac', 'outside_temperature') }}`, and as a separate sensor entity named `sensor.your_ac_outside_temperature`.

The same pattern applies to a built-in room humidity sensor, exposed as the `room_humidity` climate entity attribute and as `sensor.your_ac_room_humidity`.

The two entities per reading are a deliberate design choice, and it is the kind of choice that saves time in a dashboard. The attribute form is what you use inside a template or a conditional, and the separate entity form is what you can put on a dashboard, put in a history graph, or hand to an energy monitoring stack. Most custom integrations offer one or the other.

The README also has a section on available switches and controls, which says the integration exposes various entities to configure additional features of the unit, that all entities are created by default when the integration is set up, and that their availability depends on the current HVAC mode and status. It adds the important caveat that entity availability may also vary depending on your specific Gree AC model and firmware version.

That last sentence tells you what this project is. The unit is a real appliance with a real firmware, and what the integration can do with it depends on what that firmware exposes.

Where the Gree Climate Component is the wrong tool

The first wrong-tool case is a unit that was already paired in the vendor app and whose key cannot be recovered. The README says the integration may fail to retrieve the encryption key automatically in that situation, and the manual recovery path involves pulling a database out of an Android device or an account export from Gree's cloud. If neither of those is available to you, this integration is not usable for that unit.

The second case is an air conditioner from another brand, or a Gree unit that does not speak the Gree protocol. The component is scoped to Gree units, and the supported device list lives in `supported-devices.md` in the repository, which is the first file to check.

The third is a Home Assistant instance where you cannot place a `custom_components` folder on the host, or where UDP 7000 is blocked between the host and the unit. HACS handles the file placement but not the network, and a VLAN-separated network with a restrictive firewall needs the port opened before anything is discovered.

The fourth is an expectation of full-feature parity with the vendor app. The integration gives you a climate entity, a few switches and, where the hardware has them, the two extra sensors. It does not promise the scheduling, the diagnostics or the firmware update features of a vendor app, and its README does not claim to.

The alternative worth naming is the vendor app on the local network path it already supports, or a different integration for a different protocol. The difference in approach is that the vendor app keeps its cloud dependency after setup, while this project removes the cloud from the path and accepts a key extraction chore as the price. If the cloud route is acceptable to you, the app requires no setup work at all; if it is not, this component is one of the few ways to keep a Gree unit under local control, and the effort in section two is the entry fee.

Maintenance, versioning and the licence

The release history shows a project iterating on compatibility rather than adding features, and the release notes themselves are the clearest evidence.

Version 4.0.12 is titled Go back from version 5 without setting up again, which tells you that a version 5 was tried, presumably with a breaking change, and reverted because it forced users through setup again. Version 4.0.11 is titled Detect sensors that report 0, which is a firmware quirk fix for the humidity and temperature sensors. Version 4.0.10 is titled Use the generic key for the generic-key subList request, which is a protocol detail change in how the unit's key list is requested.

All three are in the 4.0.x line, and all three are the kind of change that only exists because real units with real firmware were tested against. The last push to the default branch was on 2026-10-13, and the repository is not archived, with a Discord linked for questions, though the README asks that bugs be reported as GitHub issues rather than on Discord.

The repository also carries a `CLAUDE.md` file, the instruction file an AI coding assistant reads to learn a codebase's conventions, alongside a `manual-configuration.yaml` with a complete example and detailed comments, and the `supported-devices.md` list.

The licence is GPL-3.0, with a `LICENSE` file in the tree. For a Home Assistant custom component, GPL is the common choice because Home Assistant loads custom components as source into the user's own installation, so the copyleft does not create a distribution problem in the usual sense. It does mean that a modified component distributed to other users must be published under the same terms. This is a description of the published terms and not legal advice.

The practical note for anyone deploying this is the firmware. The component's behaviour depends on the unit's model and firmware, entity availability varies with it, and the last three releases are all about accommodating specific hardware. Read `supported-devices.md` before you buy a unit, and read it again if the entity list turns out to be shorter than you expected.

Editorial conclusion

Adopt the Gree Climate Component when you run your own Home Assistant instance, your Gree unit sits on a reachable network segment, and you want the air conditioner to work without Gree's cloud in the path. Do not adopt it if the unit was already paired with the Gree+ or EWPE Smart app and the key cannot be recovered, because the README says the integration may then fail to retrieve the encryption key automatically, and do not adopt it as a general air conditioner integration for other brands. Before you install, confirm the specific unit model against `supported-devices.md`, work out how you will supply the `encryption_key` if the automatic handshake fails, and check the port 7000 UDP path between Home Assistant and the unit if they are on different subnets.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. RobHofmann/HomeAssistant-GreeClimateComponent on GitHub