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

v0.14.4

Browse Source
This commit is contained in:
Mateusz Gruszczyński
2026-09-15 18:47:20 +02:00
parent 7ffaba6c7a
commit 3d69e74319
37 changed files with 426 additions and 318 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+11 -17
View File
@@ -1,6 +1,6 @@
# GREE Controller API reference
HTTP and WebSocket API for GREE Controller **0.14.2**.
HTTP and WebSocket API for GREE Controller **0.14.4**.
[← Main documentation](../README.md)
@@ -196,7 +196,7 @@ Common statuses:
| GET/PUT | `/api/settings/debug` | Debug overlay/GREE frame settings. |
| GET | `/api/configuration/export` | Export full application configuration. |
| POST | `/api/configuration/import` | Import/replace application configuration. |
| POST | `/api/integrations/home-assistant/test` | Test HA temperature read. |
| POST | `/api/integrations/home-assistant/test` | Test HA server/API authentication without requiring an entity. |
| POST | `/api/integrations/home-assistant/entity` | Read raw HA entity state/attributes for shared Flow input diagnostics. |
| POST | `/api/integrations/notifications/test` | Send a test notification. |
@@ -232,7 +232,7 @@ Response:
{
"status": "ok",
"name": "gree-controller",
"version": "0.14.2",
"version": "0.14.4",
"uptime_seconds": 1234,
"control_ready": true,
"time": "2026-08-30T06:54:00Z"
@@ -283,7 +283,7 @@ Returns the initial Web UI snapshot:
"max_fan_speed": 1, "force_quiet": true, "use_native_sleep": true
},
"home_assistant": {
"url": "", "token_configured": false, "default_entity_id": "",
"url": "", "token_configured": false,
"outdoor_entity_id": "", "sensor_stale_after_seconds": 300,
"allow_invalid_tls": false, "sensor_aliases": {}, "flow_inputs": [],
"outdoor_assist_enabled": true
@@ -295,7 +295,7 @@ Returns the initial Web UI snapshot:
"control_plan": {"generated_at": "2026-09-04T08:00:00Z", "zones": [], "rules": []},
"control_plan_revision": 42,
"system": {
"version": "0.14.2",
"version": "0.14.4",
"uptime_seconds": 1234,
"auth_required": false,
"control_ready": true,
@@ -523,6 +523,7 @@ When the physical device belongs to a disabled thermostat zone, direct web/API c
"smart_fan": true,
"sensor_source": "combined",
"ha_entity_id": "sensor.living_room_temperature",
"ha_outdoor_entity_id": "sensor.garden_temperature",
"external_sensor_weight": 0.4,
"max_sensor_difference": 3.0,
"sensor_stale_after_seconds": 300,
@@ -540,6 +541,8 @@ Important rules:
- `separate_hysteresis`: when `true`, cooling uses `cool_hysteresis` and heating uses `heat_hysteresis`; both use the same `0.1..5.0` °C range.
- `standby_offset_c`: bounded thermostat offset.
- `sensor_source`: `device`, `home_assistant` or `combined`.
- for `home_assistant`/`combined`, `ha_entity_id` is the required Home Assistant room-temperature sensor for that zone.
- `ha_outdoor_entity_id` is optional; when empty, the zone uses global Home Assistant `outdoor_entity_id`, and when set it overrides the outdoor-temperature source only for that zone. If the override is unavailable, the global outdoor source is used.
- `external_sensor_weight`: `0..1`.
- `revision` is used for optimistic concurrency where supplied; stale updates can return `409`.
@@ -1182,7 +1185,6 @@ Times must use `HH:MM`; maximum fan speed is clamped to `1..5`.
{
"url": "http://homeassistant.local:8123",
"token_configured": true,
"default_entity_id": "sensor.room_temperature",
"outdoor_entity_id": "sensor.outdoor_temperature",
"sensor_stale_after_seconds": 300,
"allow_invalid_tls": false,
@@ -1194,7 +1196,7 @@ Times must use `HH:MM`; maximum fan speed is clamped to `1..5`.
}
```
`PUT` replaces `token_configured` with optional `token`. Omitted/`null` token preserves the saved token; an explicit empty string clears it. Sensor age is clamped to `30..86400` seconds. URLs, aliases, entity IDs and shared Flow inputs are normalized/validated before persistence. Shared inputs are value sources only; comparison operators and thresholds belong to Flow nodes.
`PUT` replaces `token_configured` with optional `token`. Omitted/`null` token preserves the saved token; an explicit empty string clears it. `outdoor_entity_id` is the optional global Home Assistant outdoor-temperature sensor. Each zone can set `ha_outdoor_entity_id` to override that source only for the zone; a blank override uses the global sensor. Home Assistant room-temperature sensors remain configured per zone with `ha_entity_id` when `sensor_source` is `home_assistant` or `combined`. Sensor age is clamped to `30..86400` seconds. URLs, aliases, entity IDs and shared Flow inputs are normalized/validated before persistence. Global/per-zone outdoor sensors and per-zone room sensors are exposed through the normal alias and sensor-history/metric surfaces, and the Web UI offers them as suggestions in Flow Home Assistant entity fields. Shared inputs are value sources only; comparison operators and thresholds belong to Flow nodes. The Home Assistant connection test validates only the server/API token and requires no entity.
### `/api/settings/debug`
@@ -1266,19 +1268,11 @@ Response:
### `POST /api/integrations/home-assistant/test`
```json
{
"entity_id": "sensor.room_temperature"
}
```
`entity_id` is optional; controller defaults/aliases are resolved. Response:
No request body is required. The endpoint validates the configured Home Assistant URL and access token against the Home Assistant API root; it does not read or require any entity. Response:
```json
{
"ok": true,
"temperature_c": 23.4,
"entity_id": "sensor.room_temperature"
"ok": true
}
```
docs/FLOW.md
+1 -1
View File
@@ -67,7 +67,7 @@ Actions include thermostat zone, GREE device, climate group, and generic Home As
The editor ships 37 editable presets grouped into seven categories: Comfort, Energy & cost, Protection & safety, Night, Reliability, Home Assistant / heat sources and Advanced. The library UI also provides search, Favorites, Recent, a mini graph preview and requirement checks before applying a preset. The library includes workday/weekend comfort, weather-aware demand, morning boost, presence and energy-price eco modes, peak-power limiting, open-window/humidity/overheat/frost guards, night profiles, sensor/device resilience, dual heating/cooling thresholds, multi-room group control, nested AND/OR/NOT Home Assistant scenarios, and gas-boiler/external-heat-source coordination including off, reduced-target, boost and fallback heating patterns.
Shared Flow inputs show the Flows that reference them and link directly to those editors. Home Assistant-backed shared inputs can be tested live in the input modal. Shared inputs report the current raw value/attribute. Each Flow reference defines its own comparison without changing the shared source.
Shared Flow inputs show the Flows that reference them and link directly to those editors. Home Assistant-backed shared inputs can be tested live in the input modal. Shared inputs report the current raw value/attribute. Each Flow reference defines its own comparison without changing the shared source. Home Assistant temperature entities remain normal HA entities: room-temperature sensors are configured per zone, while outdoor temperature has one global `outdoor_entity_id` plus an optional per-zone `ha_outdoor_entity_id` override. Their aliases are shared with the rest of the UI, outdoor overrides are recorded in sensor metrics/history, and all configured entities are offered as suggestions in Home Assistant Flow blocks; selecting a zone sensor does not create a separate shared input.
Presets are data files, not JavaScript definitions. Every preset lives in `presets/<id>.json` and contains `id`, `category`, localized `name`, localized `description`, and the complete `flow` graph (`nodes` + `edges`). `build.rs` validates and embeds the directory, exposes `/presets/index.json` plus `/presets/<file>.json`, and the Flow editor loads that library dynamically. Device/zone/group placeholders such as `$zone1`, `$zone2`, `$device1` and `$group1` are resolved when a preset is applied. Adding a preset therefore does not require adding graph-building code to `web/js/flows.js`.
docs/openapi.json
+36 -54
View File
@@ -2,9 +2,9 @@
"openapi": "3.1.0",
"info": {
"title": "GREE Controller API",
"version": "0.14.2",
"version": "0.14.4",
"summary": "Local HTTP/WebSocket API for GREE HVAC control",
"description": "Self-hosted API used by the GREE Controller Web UI and Home Assistant integration.\n\n### Authentication\nAdministrator endpoints accept `Authorization: Bearer <APP_TOKEN>` or `x-api-token: <APP_TOKEN>` when configured. Restricted Home Assistant control endpoints also accept generated integration tokens.\n\n### Local and GREE Cloud\nDevices use one API model and one command surface. `connection_type=local` is dispatched only to the existing LAN/UDP provider; `connection_type=gree_cloud` is dispatched only to the GREE Cloud provider. No automatic transport fallback is performed.\n\n### GREE Cloud security\nCloud passwords, REST/MQTT tokens, Authorization values and device cipher keys are never returned in normal API responses or Cloud diagnostics. MQTT uses TLS with certificate and hostname validation.\n\n### Energy\nGREE Cloud `ElcAll` and selected Home Assistant cumulative energy sensors are normalized to kWh and converted to consumption deltas before aggregation. Raw cumulative values are retained only as meter samples/baselines.\n\n### 0.14.2\nAdds independent vertical/horizontal swing controls across manual device control, thermostat zones, legacy automations, Visual Flow and Home Assistant zone climates. Swing is treated as an auxiliary one-shot unit setting and does not replace thermostat ownership.\n\n### 0.14.1\nAdds split/multisplit installation groups with shared energy and outdoor-temperature sources, multi-target energy charts with period comparison, cleaner Cloud status/alerts and safe MQTT cleanup after the last Cloud device is removed.\n\n### 0.14.0\nAdds first-class GREE Cloud MQTT status/control, reconnect/resubscribe lifecycle, Cloud diagnostics, per-device capabilities, Cloud/HA energy sources and energy-history aggregation while preserving the LAN transport contract.",
"description": "Self-hosted API used by the GREE Controller Web UI and Home Assistant integration.\n\n### Authentication\nAdministrator endpoints accept `Authorization: Bearer <APP_TOKEN>` or `x-api-token: <APP_TOKEN>` when configured. Restricted Home Assistant control endpoints also accept generated integration tokens.\n\n### Local and GREE Cloud\nDevices use one API model and one command surface. `connection_type=local` is dispatched only to the existing LAN/UDP provider; `connection_type=gree_cloud` is dispatched only to the GREE Cloud provider. No automatic transport fallback is performed.\n\n### GREE Cloud security\nCloud passwords, REST/MQTT tokens, Authorization values and device cipher keys are never returned in normal API responses or Cloud diagnostics. MQTT uses TLS with certificate and hostname validation.\n\n### Energy\nGREE Cloud `ElcAll` and selected Home Assistant cumulative energy sensors are normalized to kWh and converted to consumption deltas before aggregation. Raw cumulative values are retained only as meter samples/baselines.\n\n### 0.14.4\nHome Assistant connection tests validate only the configured server/API token and require no entity. `outdoor_entity_id` is the global Home Assistant outdoor-temperature sensor; zones can override it with `ha_outdoor_entity_id`. Room-temperature Home Assistant sensors remain configured per zone with `ha_entity_id`. Global/per-zone outdoor sensors are integrated with aliases, metrics/history and Visual Flow entity suggestions.\n\n### 0.14.2\nAdds independent vertical/horizontal swing controls across manual device control, thermostat zones, legacy automations, Visual Flow and Home Assistant zone climates. Swing is treated as an auxiliary one-shot unit setting and does not replace thermostat ownership.\n\n### 0.14.1\nAdds split/multisplit installation groups with shared energy and outdoor-temperature sources, multi-target energy charts with period comparison, cleaner Cloud status/alerts and safe MQTT cleanup after the last Cloud device is removed.\n\n### 0.14.0\nAdds first-class GREE Cloud MQTT status/control, reconnect/resubscribe lifecycle, Cloud diagnostics, per-device capabilities, Cloud/HA energy sources and energy-history aggregation while preserving the LAN transport contract.",
"license": {
"name": "MIT"
}
@@ -3076,19 +3076,9 @@
"tags": [
"Diagnostics"
],
"summary": "Test Home Assistant temperature",
"description": "Tests the configured Home Assistant connection and resolves a temperature from the supplied entity or controller default/alias.",
"summary": "Test Home Assistant connection",
"description": "Validates the configured Home Assistant URL and access token against the Home Assistant API root. No entity is required or read.",
"operationId": "testHomeAssistant",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HaTestRequest"
}
}
}
},
"security": [
{
"BearerToken": []
@@ -3099,7 +3089,7 @@
],
"responses": {
"200": {
"description": "Test result",
"description": "Connection test result",
"content": {
"application/json": {
"schema": {
@@ -3107,27 +3097,15 @@
"properties": {
"ok": {
"type": "boolean"
},
"temperature_c": {
"type": [
"number",
"null"
]
},
"entity_id": {
"type": "string"
}
},
"required": [
"ok",
"entity_id"
"ok"
],
"additionalProperties": false
},
"example": {
"ok": true,
"temperature_c": 23.4,
"entity_id": "sensor.room_temperature"
"ok": true
}
}
}
@@ -5497,7 +5475,7 @@
},
"version": {
"type": "string",
"example": "0.14.2"
"example": "0.14.4"
},
"uptime_seconds": {
"type": "integer",
@@ -6536,7 +6514,16 @@
"string",
"null"
],
"example": "sensor.living_room_temperature"
"example": "sensor.living_room_temperature",
"description": "Per-zone Home Assistant room-temperature entity. Required when sensor_source is home_assistant or combined."
},
"ha_outdoor_entity_id": {
"type": [
"string",
"null"
],
"example": "sensor.garden_temperature",
"description": "Optional per-zone Home Assistant outdoor-temperature override. When empty, the zone uses global outdoor_entity_id; when unavailable, control falls back to the global outdoor source."
},
"external_sensor_weight": {
"type": "number",
@@ -6586,6 +6573,20 @@
"type": "string",
"example": "gree-aabbccddeeff"
},
"ha_entity_id": {
"type": [
"string",
"null"
],
"description": "Per-zone Home Assistant room-temperature entity used by external/combined control."
},
"ha_outdoor_entity_id": {
"type": [
"string",
"null"
],
"description": "Optional per-zone Home Assistant outdoor-temperature override; empty uses global outdoor_entity_id."
},
"enabled": {
"type": "boolean"
},
@@ -7973,19 +7974,6 @@
],
"additionalProperties": false
},
"HaTestRequest": {
"type": "object",
"properties": {
"entity_id": {
"type": [
"string",
"null"
],
"description": "Optional. Defaults/aliases are resolved when omitted.",
"example": "sensor.room_temperature"
}
}
},
"HaEntityRequest": {
"type": "object",
"properties": {
@@ -8487,11 +8475,9 @@
"url": {
"type": "string"
},
"default_entity_id": {
"type": "string"
},
"outdoor_entity_id": {
"type": "string"
"type": "string",
"description": "Optional global Home Assistant outdoor-temperature entity. Zones use it by default and may override it with ha_outdoor_entity_id."
},
"sensor_stale_after_seconds": {
"type": "integer"
@@ -8521,7 +8507,6 @@
},
"required": [
"url",
"default_entity_id",
"outdoor_entity_id",
"sensor_stale_after_seconds",
"allow_invalid_tls",
@@ -8538,11 +8523,9 @@
"url": {
"type": "string"
},
"default_entity_id": {
"type": "string"
},
"outdoor_entity_id": {
"type": "string"
"type": "string",
"description": "Optional global Home Assistant outdoor-temperature entity. Zones use it by default and may override it with ha_outdoor_entity_id."
},
"sensor_stale_after_seconds": {
"type": "integer"
@@ -8576,7 +8559,6 @@
},
"required": [
"url",
"default_entity_id",
"outdoor_entity_id",
"sensor_stale_after_seconds",
"allow_invalid_tls",