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

v0.9.3

Browse Source
This commit is contained in:
Mateusz Gruszczyński
2026-09-01 14:18:00 +02:00
parent 97c26c67b6
commit d0346dd797
33 changed files with 327 additions and 270 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+14 -13
View File
@@ -1,6 +1,6 @@
# GREE Controller API reference
HTTP and WebSocket API for GREE Controller **0.9.2**.
HTTP and WebSocket API for GREE Controller **0.9.3**.
[← Main documentation](../README.md)
@@ -139,7 +139,7 @@ Common statuses:
| DELETE | `/api/groups/{id}` | Delete a group. |
| POST | `/api/groups/{id}/control` | Group control enable/mode/preset/custom-temperature control. |
| POST | `/api/house/control` | Set global thermostat mode. |
| POST | `/api/house/power` | Set whole-house master power. |
| POST | `/api/house/power` | Send a one-shot ON/OFF command to all enabled units. |
| POST | `/api/house/preset` | Set/clear whole-house preset override. |
### Schedules and automations
@@ -195,7 +195,7 @@ Common statuses:
| POST | `/api/integrations/home-assistant/groups/{id}/control` | Restricted group control. |
| POST | `/api/integrations/home-assistant/house/control` | Restricted house mode. |
| POST | `/api/integrations/home-assistant/house/preset` | Restricted house preset. |
| POST | `/api/integrations/home-assistant/house/power` | Restricted master power. |
| POST | `/api/integrations/home-assistant/house/power` | Restricted one-shot all-units power action. |
| POST | `/api/integrations/home-assistant/zones/{id}/control` | Restricted thermostat-zone control. |
---
@@ -212,7 +212,7 @@ Response:
{
"status": "ok",
"name": "gree-controller",
"version": "0.9.2",
"version": "0.9.3",
"uptime_seconds": 1234,
"control_ready": true,
"time": "2026-08-30T06:54:00Z"
@@ -236,7 +236,7 @@ Returns the initial Web UI snapshot:
"settings": {},
"outdoor_temperature": null,
"system": {
"version": "0.9.2",
"version": "0.9.3",
"uptime_seconds": 1234,
"auth_required": false,
"control_ready": true,
@@ -667,15 +667,15 @@ All fields optional:
- `preset`: `auto`, `comfort`, `sleep`, `away`, `custom`,
- `setpoint`: custom group target in the `8–30°C` range; requires `preset: "custom"`.
A custom setpoint creates the same temporary manual override for every member zone and normally expires at that zone's next schedule boundary. Returns a group control/result object including updated members/state.
A custom setpoint creates the same override for every member zone. For explicit Web/Home Assistant group control it stays active until the group is changed/released; scheduled group automation remains bounded by the normal schedule hand-back. Returns a group control/result object including updated members/state.
Group `power` is a scoped bulk-power/control action. `power=false` immediately powers member units off and releases `group:*` ownership; members are stored as individually-off thermostats rather than being blocked by membership in an OFF group. This group-created OFF is indefinite (no 15-minute local hand-back), so the regulator cannot restart the unit by itself; a user can still turn an individual thermostat back on independently. `power=true` clears that scoped thermostat-OFF state and immediately re-runs group thermostat arbitration. Explicit Web/Home Assistant group power actions take over older member manual/temporary ownership; scheduled group automations still respect higher-priority manual/local ownership. Group mode/preset/setpoint changes are accepted only while the group is ON. Whole-house power remains independent and authoritative.
Group `power` is a scoped bulk-power/control action. `power=false` immediately powers member units off and releases `group:*` ownership; members are stored as individually-off thermostats rather than being blocked by membership in an OFF group. This group-created OFF is indefinite (no 15-minute local hand-back), so the regulator cannot restart the unit by itself; a user can still turn an individual thermostat back on independently. `power=true` clears that scoped thermostat-OFF state and immediately re-runs group thermostat arbitration. Explicit Web/Home Assistant group control has higher priority than house rules and schedules; scheduled group automations still respect higher-priority manual/local ownership. Group mode/preset/setpoint changes are accepted only while the group is ON. Global ON/OFF actions are one-shot physical commands and never create a persistent group/zone gate.
---
## Whole-house control
House thermostat mode and master power are intentionally separate.
House thermostat rules and global power actions are intentionally separate. Global ON/OFF is one-shot; it is not an automation enable/disable state.
### `POST /api/house/control`
@@ -687,8 +687,8 @@ House thermostat mode and master power are intentionally separate.
Valid modes: `cool`, `heat`, `off`.
- `cool`/`heat` are explicit whole-house activation requests: master power is enabled and the thermostat arbiter starts eligible managed zones. Existing per-group control enable/disable settings are preserved.
- `off` means **do not perform house-level thermostat control** for inherited zones. It does not itself change master power and does not forcibly power direct/manual devices down.
- `cool`/`heat` select the house rule used by zones that inherit the global mode and immediately re-run arbitration for free zones. Explicit local/group/direct ownership is preserved.
- `off` means **do not perform house-level thermostat control** for inherited free zones. It does not block local thermostats, groups, device-manual control or controller automations.
Returns public runtime settings.
@@ -700,13 +700,14 @@ Returns public runtime settings.
}
```
`false` is authoritative: it clears local/manual ownership markers as required and powers every enabled physical device down. It does **not** modify per-group control enable/disable settings. `true` resumes thermostat arbitration rather than blindly sending a bare ON frame.
This endpoint is a **one-shot physical command**. `false` sends OFF to every technically enabled unit; `true` sends ON to every technically enabled unit. It does not change group enablement, local thermostat ownership, direct/manual takeover, schedules, house mode or automation rules. Those controllers may issue a later command independently. Pending compressor-protection tasks from before the global action are cleared and may be recreated by a later fresh thermostat decision. When compressor protection is enabled, a global `true` request for a recently stopped thermostat-managed unit is queued until its safe start deadline and appears in the compressor queue; `false` is never delayed by compressor protection.
Response includes:
```json
{
"power": false,
"one_shot": true,
"devices": [],
"groups": [],
"settings": {},
@@ -724,7 +725,7 @@ Response includes:
Valid: `auto`, `comfort`, `sleep`, `away`.
A non-`auto` preset creates zone overrides that normally expire at each zone's next schedule boundary. `auto` clears them. Selecting a house preset explicitly re-enables master power while preserving each group's control enable/disable setting.
A non-`auto` preset creates overrides for free house-controlled zones and normally expires at each zone's next schedule boundary. `auto` clears those free-zone overrides. Explicit local thermostat, group, temporary thermostat and direct/manual ownership is not overwritten by a house profile action.
---
@@ -1108,7 +1109,7 @@ Modes: `problems`, `important`. Providers: `pushover`, `slack`, `discord`.
Accepts the complete `RuntimeSettings` document. Important behavior:
- `house_mode` and `house_power_enabled` cannot be changed here; use House Control API.
- `house_mode` cannot be changed here; use House Control API. `house_power_enabled` is a legacy compatibility field and is normalized to `true` because global ON/OFF is one-shot.
- polling interval is clamped `2..3600` seconds.
- zone interval is clamped `2..3600` seconds.
- discovery timeout is clamped `300..30000` ms.