gree-ac-control

What gree-ac-control does

The Chinese-language README describes a roughly 300-line Python CLI that implements Gree's private LAN protocol, which uses UDP 7000 and AES-128 in ECB or GCM mode. Commands are list (scan the network), bind (obtain and save a per-device key), add (enter a known MAC and key by hand), status and set. A set command takes fields such as Pow, Mod, SetTem and WdSpd, for example to turn on cooling at 26 degrees with low fan speed. The only dependency is pycryptodome.

The air conditioner must already be on your home WiFi, and the first-time setup still needs the official Gree+ app, since the module ships without a network connection and usually supports only 2.4 GHz. After that, day-to-day control does not need the app. Device keys are saved to ~/.config/gree-ac-control/devices.json with best-effort chmod 600. The repository includes SKILL.md, a crypto demo script, protocol notes and 26 unit tests with mocked UDP traffic.

Key features

• Scan the LAN for Gree units with the list command
• Bind a unit and store its device key locally
• Read status and set power, mode, temperature and fan speed
• Automatic detection of AES-ECB or AES-GCM responses
• 26 unit tests that run without a real air conditioner
• Single dependency: pycryptodome

When to use it

• Ask an agent to switch the air conditioner on or off from chat
• Check the current state of a Gree unit without opening the app
• Use the skill as a starting point for other local smart-home skills

Who it is for: Owners of Gree WiFi air conditioners who want an agent to control them locally without a cloud account.

How it fits with Hermes Agent

Published as an agent skill with a SKILL.md and tagged hermes-skill on GitHub. The README does not describe Hermes-specific setup steps.

How to install gree-ac-control

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

pip install pycryptodome
python3 scripts/gree_ac.py list
python3 scripts/gree_ac.py bind 192.168.x.x

Requirements: Python with pycryptodome, and a Gree WiFi air conditioner already connected to your home 2.4 GHz network on the same LAN, with UDP 7000 allowed

Note: The README warns that Gree's protocol relies on a shared factory key, so anyone on your local network can control the unit, and first-time WiFi setup still needs the official Gree+ app.

FAQ