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

v0.4.1

Browse Source
This commit is contained in:
Mateusz Gruszczyński
2026-08-23 23:20:00 +02:00
parent 8bb12a1782
commit b23578a0c8
34 changed files with 2300 additions and 447 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+47 -8
View File
@@ -4,7 +4,7 @@
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.8**.
Current version: **0.4.1**.
## Highlights
@@ -13,10 +13,14 @@ Current version: **0.3.8**.
- 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,
- weekly schedules including ranges that cross midnight,
- temperature/time automations,
- smart thermostat zones with global house Heat/Cool/Off mode and per-zone overrides,
- setpoint modulation that keeps indoor units powered during normal operation instead of repeatedly cycling power,
- Comfort/Sleep/Away profiles, temporary overrides and one-tap **Sleep now**,
- editable weekly schedules plus Family/Child room/Bedroom/Workday/Always-comfort templates,
- temperature/time automations for advanced exceptions,
- per-zone optional Home Assistant room-temperature sensors with GREE fallback,
- optional Home Assistant outdoor-temperature assist for setpoint/fan decisions,
- opt-in support for self-signed/invalid HTTPS certificates on the outbound HA sensor connection,
- combined zone temperature using configurable GREE/external sensor weighting and discrepancy protection,
- REST API and WebSocket updates,
- responsive PWA optimized for phones,
@@ -35,7 +39,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.8.zip
unzip gree-controller-v0.4.1.zip
cd gree-controller
chmod +x scripts/*.sh
./scripts/dev.sh
@@ -81,7 +85,18 @@ Appearance selector:
- Light,
- Dark.
The selected appearance is stored in the `gree_controller_theme` cookie. The interface uses flat surfaces and borders; decorative UI shadows were removed in v0.2.0.
The selected appearance is stored in the `gree_controller_theme` cookie. Version 0.4.1 refreshes the interface with a Supabase-inspired dashboard language: layered neutral surfaces, compact controls, thin borders, small radii, a restrained green brand accent, a desktop sidebar, mobile bottom navigation, and theme-aware scrollbars. The design remains original to GREE Controller and does not copy Supabase branding or application code.
### Offline Tailwind workflow
The running controller never loads Tailwind, fonts, JavaScript, or CSS from a CDN. `web/styles.css` is embedded directly into the Rust binary. Tailwind is an optional local build tool for UI development:
```bash
./scripts/build-web.sh --install
./scripts/build-web.sh
```
`package.json`, `tailwind.config.js`, and `web/tailwind.input.css` contain the local Tailwind build configuration. `node_modules/` is intentionally not packaged or committed. LXC installation/update does not require Node.js because the prebuilt `web/styles.css` ships with the release. If local Tailwind dependencies are present, `dev.sh`, `install.sh`, and `update.sh` rebuild the CSS before compiling Rust.
## Connecting a physical GREE device
@@ -139,9 +154,13 @@ Use `--skip-tests` with `install.sh` or `update.sh` only when you explicitly wan
| `GREE_CONTROLLER_DISCOVERY_BROADCAST` | `255.255.255.255:7000` | Discovery broadcast target |
| `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` |
| `GREE_CONTROLLER_HOUSE_MODE` | `cool` | Initial seasonal house mode: `cool`, `heat` or `off` |
| `GREE_CONTROLLER_OUTDOOR_ASSIST_ENABLED` | `true` | Initial outdoor-temperature assist state |
| `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 |
| `HA_ENTITY_ID` | empty | Optional default HA room-temperature sensor |
| `HA_OUTDOOR_ENTITY_ID` | empty | Optional HA outdoor-temperature sensor |
| `HA_ALLOW_INVALID_TLS` | `false` | Opt in to invalid/self-signed HA HTTPS certificates |
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.
@@ -167,7 +186,17 @@ 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.
Zone cards are fast thermostats: `- / +`, **Auto schedule / Comfort / Sleep now / Away**, and **House / Heat / Cool** are available without opening the edit dialog. Temporary overrides automatically end at the next schedule boundary. The zone engine, not the browser, owns device commands so schedules, sensors and manual overrides cannot fight each other.
## Smart thermostat and schedules
Version 0.4.0 is designed around a simple rule: during normal heating/cooling, keep the indoor unit powered and modulate its target instead of repeatedly switching the unit OFF and ON. When a room is satisfied, cooling moves the device target above the comfort target and heating moves it below the comfort target. When hysteresis requests conditioning again, the working target is restored. **House Off** remains an explicit hard-off mode.
Choose one seasonal **House mode** — Cooling in summer, Heating in winter, or Off. Zones follow the house mode by default, while a zone may explicitly override Heat/Cool when required. Each zone has separate Comfort/Sleep/Away temperatures for cooling and heating.
Schedules store profiles rather than duplicating temperatures. Ready-made **Family**, **Child room**, **Bedroom**, **Workday** and **Always comfort** templates generate ordinary editable schedule entries. For example, a child room template can enter Sleep earlier; if the child goes to bed even earlier, press **Sleep now** and that zone remains in Sleep until its next schedule boundary. Whole-house **Comfort all / Sleep all / Away all / Auto schedule** actions are also available.
The optional HA outdoor sensor is an assist signal only. It never replaces the room-control temperature. In extreme weather it can make the active device setpoint slightly more assertive and let Smart Fan increase airflow.
## Home Assistant
@@ -178,6 +207,8 @@ There are two independent HA directions:
For the HA client connection, open **Settings -> Home Assistant integration access** in GREE Controller and press **Create new token**. The secret is shown once. Paste that token into the Home Assistant `GREE Controller` integration together with the controller URL. Managed HA tokens are stored as SHA-256 hashes and are scoped to the dedicated HA device/command API; they cannot change controller settings or manage other tokens.
The outbound HA sensor client also supports local HTTPS endpoints such as `https://10.87.65.2`. If the server uses a self-signed, expired or hostname-mismatched certificate, enable **Settings -> Allow invalid/self-signed HTTPS certificate**. This disables certificate/hostname validation only for the controller's outbound Home Assistant sensor client and should only be used on a trusted LAN.
The second option is designed to replace the built-in/default GREE integration without changing automation/dashboard references.
Example migration target:
@@ -229,6 +260,10 @@ POST /api/devices/:id/poll
POST /api/devices/:id/command
GET /api/zones
POST /api/zones
POST /api/zones/:id/control
POST /api/zones/:id/schedule-template
POST /api/house/control
POST /api/house/preset
GET /api/schedules
POST /api/schedules
GET /api/automations
@@ -326,3 +361,7 @@ The systemd service explicitly allows `AF_NETLINK`. This is required by Linux `g
### v0.3.8 legacy V1 device compatibility
GREE protocol identifiers are now emitted as canonical lowercase hexadecimal in `tcid` and `pack.mac`. This improves compatibility with older V1 Wi-Fi modules (including devices in the `502cc6...` family) that can answer discovery but silently ignore bind/status packets when MAC casing differs from their discovery identity. Stored device IDs and friendly names are not changed.
### v0.4.0 smart thermostat
Zones now use setpoint modulation, global seasonal house mode, cooling/heating Comfort/Sleep/Away profiles, temporary per-zone overrides, ready-made editable schedule templates, whole-house preset actions and optional outdoor-temperature assist. The UI also uses theme-aware thin scrollbars and can opt in to invalid/self-signed certificates for the outbound Home Assistant sensor connection. Existing zones remain readable; a legacy zone keeps its previous setpoint as its comfort target until it is edited and saved with the new profile fields.