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

v0.13.0

Browse Source
This commit is contained in:
Mateusz Gruszczyński
2026-09-04 11:00:15 +02:00
parent 8152e63d63
commit 236540e0f0
27 changed files with 557 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+16 -5
View File
@@ -1,6 +1,6 @@
# GREE Controller API reference
HTTP and WebSocket API for GREE Controller **0.12.1**.
HTTP and WebSocket API for GREE Controller **0.13.0**.
[← Main documentation](../README.md)
@@ -206,6 +206,7 @@ Common statuses:
| GET | `/api/access-tokens` | List generated HA tokens without secrets. |
| POST | `/api/access-tokens` | Create restricted HA token. |
| DELETE | `/api/access-tokens/{id}` | Revoke token. |
| GET | `/api/integrations/home-assistant/snapshot` | Restricted devices + groups + control-plan snapshot in one request. |
| GET | `/api/integrations/home-assistant/devices` | Restricted device list. |
| POST | `/api/integrations/home-assistant/devices/{id}/command` | Restricted direct device command. |
| GET | `/api/integrations/home-assistant/control-plan` | Restricted control plan. |
@@ -230,7 +231,7 @@ Response:
{
"status": "ok",
"name": "gree-controller",
"version": "0.12.1",
"version": "0.13.0",
"uptime_seconds": 1234,
"control_ready": true,
"time": "2026-08-30T06:54:00Z"
@@ -253,8 +254,10 @@ Returns the initial Web UI snapshot:
"access_tokens": [],
"house": {"mode": "cool"},
"outdoor_temperature": null,
"control_plan": {"generated_at": "2026-09-04T08:00:00Z", "zones": [], "rules": []},
"control_plan_revision": 42,
"system": {
"version": "0.12.1",
"version": "0.13.0",
"uptime_seconds": 1234,
"auth_required": false,
"control_ready": true,
@@ -941,7 +944,8 @@ When InfluxDB is enabled, older history can be read from Influx and merged with
### `GET /api/control-plan`
Returns the resolved machine-readable thermostat plan:
Returns the latest materialized machine-readable thermostat plan. The response shape is unchanged; the bundled Web UI receives plan updates primarily through WebSocket and uses this endpoint for fallback/resynchronization.
Top-level fields:
@@ -1330,6 +1334,10 @@ Returns `Device[]`.
Accepts `DeviceCommand`. A direct command is rejected if the device belongs to a disabled thermostat zone; re-enable the zone for normal HA/controller ownership or use the administrator technical device endpoint deliberately.
### `GET /api/integrations/home-assistant/snapshot`
Returns `devices`, `groups`, `control_plan` and `control_plan_revision` in one restricted request. The bundled Home Assistant coordinator uses this endpoint to reduce its normal refresh from three HTTP requests to one. The existing restricted devices/groups/control-plan endpoints remain available.
### `GET /api/integrations/home-assistant/control-plan`
Same payload as administrator `GET /api/control-plan`.
@@ -1401,12 +1409,13 @@ Every server event uses:
}
```
The first frame is always `bootstrap` with the same payload as `GET /api/bootstrap`, unless bootstrap generation itself fails.
The first frame is always `bootstrap` with the same payload as `GET /api/bootstrap`, including `control_plan` and `control_plan_revision`, unless bootstrap generation itself fails. If the generic event queue is overrun, the server sends another full `bootstrap` to resynchronize the client instead of silently continuing with missed state.
Common live events include:
```text
bootstrap
control_plan.updated
device.created
device.updated
device.deleted
@@ -1439,6 +1448,8 @@ gree.frame
log.created
```
`control_plan.updated` uses `data.revision` plus `data.plan`. Revisions increase only when the materialized plan changes semantically; `generated_at` alone does not create a new revision.
Additional engine/integration events may be introduced without changing the envelope.
`api.request` data:
docs/openapi.json
+43 -6
View File
@@ -2,9 +2,9 @@
"openapi": "3.1.0",
"info": {
"title": "GREE Controller API",
"version": "0.12.1",
"version": "0.13.0",
"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\nNormal administrator endpoints accept `Authorization: Bearer <APP_TOKEN>` or `x-api-token: <APP_TOKEN>` when `GREE_CONTROLLER_APP_TOKEN` is configured. If the app token is empty, those endpoints intentionally run in trusted-LAN mode without authentication.\n\nThe restricted `/api/integrations/home-assistant/*` control surface always requires either a generated access token or the administrator app token. Generated tokens do **not** grant normal administrator API access.\n\nIn Swagger UI use **Authorize** and enter the token in either the bearer field or `x-api-token` field.\n\n### Control ownership\nThermostat zones, groups, house rules, direct device control, schedules and visual Flows share an ownership/arbitration model. Prefer zone/group/house endpoints for thermostat intent; direct device commands are technical/manual control and can deliberately take ownership.\n\n### 0.12.0 breaking API\nRuntime settings are split into functional `/api/settings/*` resources. The former `/api/settings`, `/api/debug`, `/api/events/retention`, `/api/settings/export` and `/api/settings/import` endpoints were removed without compatibility aliases.",
"description": "Self-hosted API used by the GREE Controller Web UI and Home Assistant integration.\n\n### Authentication\nNormal administrator endpoints accept `Authorization: Bearer <APP_TOKEN>` or `x-api-token: <APP_TOKEN>` when `GREE_CONTROLLER_APP_TOKEN` is configured. If the app token is empty, those endpoints intentionally run in trusted-LAN mode without authentication.\n\nThe restricted `/api/integrations/home-assistant/*` control surface always requires either a generated access token or the administrator app token. Generated tokens do **not** grant normal administrator API access.\n\nIn Swagger UI use **Authorize** and enter the token in either the bearer field or `x-api-token` field.\n\n### Control ownership\nThermostat zones, groups, house rules, direct device control, schedules and visual Flows share an ownership/arbitration model. Prefer zone/group/house endpoints for thermostat intent; direct device commands are technical/manual control and can deliberately take ownership.\n\n### 0.12.0 breaking API\nRuntime settings are split into functional `/api/settings/*` resources. The former `/api/settings`, `/api/debug`, `/api/events/retention`, `/api/settings/export` and `/api/settings/import` endpoints were removed without compatibility aliases.\n\n### 0.13.0\n`control-plan` keeps its existing HTTP response shape but is materialized in memory and pushed to WebSocket clients as `control_plan.updated`; HTTP remains the fallback/resync path. A restricted Home Assistant snapshot endpoint combines devices, groups and the control plan.",
"license": {
"name": "MIT"
}
@@ -122,7 +122,7 @@
"System"
],
"summary": "Get application bootstrap",
"description": "Returns the initial Web UI entity snapshot: devices, zones, groups, schedules, automations, Flows, access-token metadata, house mode, outdoor temperature and system diagnostics. Runtime settings are loaded from the functional `/api/settings/*` resources.",
"description": "Returns the initial Web UI entity snapshot: devices, zones, groups, schedules, automations, Flows, access-token metadata, house mode, outdoor temperature, the latest materialized control plan with its revision, and system diagnostics. Runtime settings are loaded from the functional `/api/settings/*` resources.",
"operationId": "bootstrap",
"security": [
{
@@ -2971,7 +2971,7 @@
"History"
],
"summary": "Get resolved control plan",
"description": "Machine-readable desired-vs-actual thermostat plan with ownership, blocking reasons, schedules, next events and per-zone control decisions. This is the preferred endpoint for clients that need to explain why a zone is or is not running.",
"description": "Machine-readable desired-vs-actual thermostat plan with ownership, blocking reasons, schedules, next events and per-zone control decisions. The response shape is unchanged; the bundled Web UI receives plan changes through WebSocket and uses this endpoint as a fallback/resynchronization surface.",
"operationId": "controlPlan",
"security": [
{
@@ -3511,7 +3511,7 @@
"Home Assistant"
],
"summary": "Get control plan for Home Assistant",
"description": "This restricted Home Assistant surface always requires either a generated controller access token or the administrator app token. Generated tokens are intentionally not accepted by normal administrator endpoints. Returns the same machine-readable control plan as the administrator endpoint.",
"description": "This restricted Home Assistant surface always requires either a generated controller access token or the administrator app token. Generated tokens are intentionally not accepted by normal administrator endpoints. Returns the same latest materialized machine-readable control plan as the administrator endpoint.",
"operationId": "haControlPlan",
"security": [
{
@@ -4799,6 +4799,43 @@
}
}
}
},
"/api/integrations/home-assistant/snapshot": {
"get": {
"tags": [
"Home Assistant"
],
"summary": "Get Home Assistant integration snapshot",
"description": "Returns devices, derived groups, the latest materialized control plan and its revision in one restricted request. Existing per-resource Home Assistant endpoints remain available for compatibility.",
"operationId": "haSnapshot",
"security": [
{
"BearerToken": []
},
{
"ApiTokenHeader": []
}
],
"responses": {
"200": {
"description": "Home Assistant integration snapshot",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
}
},
"components": {
@@ -4854,7 +4891,7 @@
},
"version": {
"type": "string",
"example": "0.12.1"
"example": "0.13.0"
},
"uptime_seconds": {
"type": "integer",