gru/gree-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.3.5

Browse Source
This commit is contained in:
Mateusz Gruszczyński
2026-08-23 22:05:24 +02:00
parent 1d3dcba1a9
commit 9c9b7b272b
25 changed files with 902 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+32 -11
View File
@@ -4,13 +4,13 @@
Standalone local GREE air-conditioner controller written in Rust. It runs on a regular Linux host or an LXC container and provides a mobile-first web interface without depending on the vendor cloud.
Current version: **0.3.3**.
Current version: **0.3.5**.
## Highlights
- local GREE discovery over UDP/7000,
- V1 bind/status/command transport using AES-128-ECB,
- V2 AES-128-GCM envelope support,
- V1 AES-128-ECB and V2 AES-128-GCM discovery/bind/status/command transport,
- automatic ECB/GCM detection from discovery responses and bind fallback,
- power, HVAC mode, target temperature, fan, vertical/horizontal swing, quiet, turbo and display light,
- SQLite state/history/event storage,
- temperature zones with hysteresis and minimum ON/OFF protection,
@@ -35,7 +35,7 @@ See [`BUILD_REPORT.md`](BUILD_REPORT.md) for package validation details and [`do
On Debian, Ubuntu or an LXC container:
```bash
unzip gree-controller-v0.3.3.zip
unzip gree-controller-v0.3.5.zip
cd gree-controller
chmod +x scripts/*.sh
./scripts/dev.sh
@@ -87,10 +87,12 @@ The selected appearance is stored in the `gree_controller_theme` cookie. The int
1. Put the controller and AC in a network where UDP/7000 traffic is allowed.
2. Open the web interface and select **Discover**.
3. Use **Bind** or send a command so the controller can obtain/use the device key.
4. If LXC/VLAN broadcast does not pass, add the unit manually with IP and MAC/CID.
3. Start with **Auto (V1 + V2)** and 3 scan passes. The controller recognizes ECB responses and GCM responses carrying a `tag` and automatically binds discovered units.
4. If required, repeat discovery using **V1 AES-ECB** or **V2 AES-GCM** to isolate a model family.
5. New devices immediately open a naming step so you can enter room-friendly names such as **Salon** or **Sypialnia**. They can also be renamed later from **Devices -> Rename**. Re-discovery preserves your custom name.
6. If LXC/VLAN broadcast does not pass, add the unit manually with IP and MAC/CID.
Some GREE firmware families use protocol variations. V1 covers common Wi-Fi units. V2 implements the standard AES-GCM envelope but unusual firmware may require protocol-specific adaptation.
Version 0.3.5 uses the EWPE/GREE protocol constants for ECB and GCM, the fixed GCM nonce/AAD, standard `cid=app`, correct packet `i` values, and a fresh scan before bind. A single lost UDP response no longer marks a device offline; three consecutive communication failures are required.
## LXC/systemd installation and updates
@@ -129,18 +131,19 @@ Use `--skip-tests` with `install.sh` or `update.sh` only when you explicitly wan
| `GREE_CONTROLLER_BIND` | `0.0.0.0:8787` | HTTP/WebSocket bind address |
| `GREE_CONTROLLER_DATABASE` | `./data/gree-controller.db` | SQLite file |
| `GREE_CONTROLLER_APP_TOKEN` | empty | Bearer token; empty disables API authentication |
| `GREE_CONTROLLER_SIMULATE` | `true` | Enables simulator support |
| `GREE_CONTROLLER_AUTO_SEED` | `true` | Seeds a simulator into an empty database |
| `GREE_CONTROLLER_SIMULATE` | `false` | Enables simulator seeding for development/testing |
| `GREE_CONTROLLER_AUTO_SEED` | `false` | Seeds a simulator into an empty database when simulation is enabled |
| `GREE_CONTROLLER_POLL_INTERVAL_SECONDS` | `15` | Device polling interval |
| `GREE_CONTROLLER_ZONE_INTERVAL_SECONDS` | `5` | Zone-control interval |
| `GREE_CONTROLLER_DISCOVERY_TIMEOUT_MS` | `3000` | UDP discovery timeout |
| `GREE_CONTROLLER_DISCOVERY_BROADCAST` | `255.255.255.255:7000` | Discovery broadcast target |
| `GREE_CONTROLLER_ID` | `gree-controller` | GREE protocol client CID |
| `GREE_CONTROLLER_GREE_INTERFACE` | empty | Optional Linux interface used for all GREE UDP traffic, e.g. `eth1` |
| `GREE_CONTROLLER_ID` | `gree-controller` | Controller instance identifier used for logs/metadata; the GREE wire protocol uses the standard `cid=app` |
| `HA_URL` | empty | Optional Home Assistant URL |
| `HA_TOKEN` | empty | Optional Home Assistant Long-Lived Access Token |
| `HA_ENTITY_ID` | empty | Optional default HA temperature sensor |
Settings changed from the web panel are stored in SQLite. `GREE_CONTROLLER_APP_TOKEN` is loaded at process startup.
Settings changed from the web panel are stored in SQLite. `GREE_CONTROLLER_APP_TOKEN` is loaded at process startup. When `GREE_CONTROLLER_DISCOVERY_BROADCAST` is explicitly present in the service environment, it overrides the persisted discovery target. Use `auto` together with `GREE_CONTROLLER_GREE_INTERFACE` to derive the subnet broadcast automatically.
## Per-zone room temperature sensors
@@ -164,6 +167,8 @@ For combined control, `max_sensor_difference` protects against an obviously inco
The zone API exposes `device_temperature`, `external_temperature`, `current_temperature` (the actual control temperature) and `control_temperature_source` for diagnostics. Existing SQLite zone records remain compatible because the new fields have defaults and are stored in the existing JSON payload.
Zone cards also expose quick `- / +` target controls and Heat/Cool buttons. These update the zone without opening the edit dialog and immediately push the changed mode/setpoint to the paired GREE unit without forcing power ON/OFF. Active schedules may still replace the zone setpoint while their time window is active.
## Home Assistant
There are two independent HA directions:
@@ -297,3 +302,19 @@ systemd/ systemd service unit
## License
MIT. This project uses a community-reconstructed local device protocol and is not an official product of GREE Electric Appliances Inc.
## Multi-NIC / dedicated GREE interface
For LXC hosts with a management NIC and a separate GREE/VLAN NIC, bind GREE UDP traffic explicitly to the GREE interface:
```env
GREE_CONTROLLER_GREE_INTERFACE=eth1
GREE_CONTROLLER_DISCOVERY_BROADCAST=auto
GREE_CONTROLLER_SIMULATE=false
GREE_CONTROLLER_AUTO_SEED=false
```
`GREE_CONTROLLER_GREE_INTERFACE` is resolved to the interface current IPv4 address whenever a UDP socket is created, so DHCP address changes do not require hard-coding the source IP. `GREE_CONTROLLER_DISCOVERY_BROADCAST=auto` derives the subnet broadcast from the selected interface and overrides an older runtime value stored in SQLite.
Run `sudo ./scripts/network-debug.sh eth1 10.87.65.127` to verify addressing and routing.