v0.5.0
This commit is contained in:
Mateusz Gruszczyński
+43
-19
@@ -25,9 +25,11 @@ The Home Assistant custom integration uses a restricted API surface:
|
||||
```text
|
||||
GET /api/integrations/home-assistant/devices
|
||||
POST /api/integrations/home-assistant/devices/{id}/command
|
||||
GET /api/integrations/home-assistant/control-plan
|
||||
POST /api/integrations/home-assistant/zones/{id}/control
|
||||
```
|
||||
|
||||
These two endpoints always require `Authorization: Bearer <generated-token>` (or the administrator `GREE_CONTROLLER_APP_TOKEN`). A generated HA token cannot update settings, run discovery, delete devices, manage tokens, or use the controller WebSocket.
|
||||
These endpoints always require `Authorization: Bearer <generated-token>` (or the administrator `GREE_CONTROLLER_APP_TOKEN`). A generated HA token cannot update settings, run discovery, delete devices, manage tokens, or use the controller WebSocket.
|
||||
|
||||
## Discovery
|
||||
|
||||
@@ -159,9 +161,40 @@ For trusted local Home Assistant servers with self-signed/invalid HTTPS certific
|
||||
|
||||
This setting is opt-in and applies only to the controller's outbound Home Assistant sensor client.
|
||||
|
||||
## Current control plan
|
||||
|
||||
`GET /api/control-plan` returns a machine-readable view of what the controller is doing now and what is expected next. It includes the house mode/strategy, each zone's active mode/preset/current and target temperatures, current schedule, manual override expiry, upcoming schedule transitions, enabled automation rules and predictable time-triggered automation events.
|
||||
|
||||
```bash
|
||||
curl "$BASE/api/control-plan" -H "$AUTH"
|
||||
```
|
||||
|
||||
The restricted Home Assistant equivalent is `GET /api/integrations/home-assistant/control-plan`. HA may change a zone target/preset/mode/enabled state through:
|
||||
|
||||
```bash
|
||||
curl -X POST "$BASE/api/integrations/home-assistant/zones/ZONE_ID/control" \
|
||||
-H 'Authorization: Bearer HA_TOKEN' -H 'Content-Type: application/json' \
|
||||
-d '{"setpoint":22.5}'
|
||||
```
|
||||
|
||||
## Settings backup and debug
|
||||
|
||||
`GET /api/settings/export` downloads configuration JSON (settings, devices, zones, schedules and automations). It intentionally excludes metric history, event logs and generated API-token records. The export includes GREE device binding keys plus configured Home Assistant and InfluxDB credentials, so treat it as a secret.
|
||||
|
||||
`POST /api/settings/import` accepts that JSON format and replaces application configuration while preserving metric history, events and generated API tokens.
|
||||
|
||||
Debug overlay state can be read or changed independently of the full settings document:
|
||||
|
||||
```text
|
||||
GET /api/debug
|
||||
PUT /api/debug
|
||||
```
|
||||
|
||||
Example body: `{"overlay_enabled":true,"gree_frames":true}`. With the overlay enabled, live `api.request` WebSocket events contain only HTTP method, path, status and duration. When GREE frame debug is enabled, sanitized `gree.frame` events are also emitted; the bound encryption key is not exposed.
|
||||
|
||||
## WebSocket
|
||||
|
||||
Connect to `ws://HOST:8787/ws?token=TOKEN`. The first message uses event type `bootstrap`; later events include `device.updated`, `zone.updated`, `settings.updated` and `log.created`.
|
||||
Connect to `ws://HOST:8787/ws?token=TOKEN`. The first message uses event type `bootstrap`; later events include `device.updated`, `zone.updated`, `settings.updated`, `debug.settings`, `api.request`, `gree.frame` and `log.created`.
|
||||
|
||||
## Localization assets
|
||||
|
||||
@@ -176,30 +209,21 @@ curl "$BASE/lang/en.json"
|
||||
|
||||
### `GET /api/history`
|
||||
|
||||
The history API exposes three independent data families and a combined overview. Common parameters are `hours=6|24|168|720` and `limit` up to 20,000 rows. Downsampling is performed in SQLite: 30-second buckets up to 6 hours, 2-minute buckets up to 24 hours, 10-minute buckets up to 7 days, and 30-minute buckets for longer ranges.
|
||||
The history API exposes three independent data families and a combined overview. `hours` may cover up to 10 years and `limit` is capped at 20,000 rows. Query buckets become progressively wider: 30 s (<=6 h), 2 min (<=24 h), 10 min (<=7 d), 30 min (<=30 d), 2 h (<=90 d), 6 h (<=1 y), then 24 h.
|
||||
|
||||
```text
|
||||
GET /api/history?scope=overview&hours=24
|
||||
GET /api/history?scope=devices&device_id=DEVICE_ID&hours=24
|
||||
GET /api/history?scope=zones&zone_id=ZONE_ID&hours=24
|
||||
GET /api/history?scope=devices&device_id=DEVICE_ID&hours=2160
|
||||
GET /api/history?scope=zones&zone_id=ZONE_ID&hours=8760
|
||||
GET /api/history?scope=sensors&entity_id=sensor.room_temperature&hours=24
|
||||
```
|
||||
|
||||
`scope=overview` returns:
|
||||
Local SQLite is the hot store. When compaction is enabled, full-resolution samples are kept for 24 h, then one sample per 10-minute bucket through day 7 and one per 30-minute bucket afterwards. `history_retention_days` controls final local pruning.
|
||||
|
||||
```json
|
||||
{
|
||||
"scope": "overview",
|
||||
"bucket_seconds": 120,
|
||||
"zones": [],
|
||||
"devices": [],
|
||||
"sensors": [],
|
||||
"counts": {"devices": 0, "zones": 0, "ha": 0}
|
||||
}
|
||||
```
|
||||
When InfluxDB is enabled, samples are written in parallel. Maintenance also backfills compacted legacy SQLite samples older than `influxdb.history_threshold_days`; those local rows are deleted only after the archive batch is accepted. Requests that cross the threshold read the older portion from InfluxDB 1.x or 2.x and merge it with recent SQLite data. If the Influx query fails, the endpoint falls back to the available SQLite history and returns `storage_warning`.
|
||||
|
||||
Device rows come from the existing `readings` table and contain `indoor_temperature`, optional GREE `outdoor_temperature`, `target_temperature`, `power`, and `source`. This makes old device history immediately available after an upgrade.
|
||||
`scope=overview` returns `zones`, `devices`, `sensors`, row `counts`, `bucket_seconds`, plus `storage`/optional `storage_warning`. Device rows contain indoor/outdoor/target/power; zone rows contain GREE/external/control/target/device-setpoint/outdoor/power/mode/fan/demand/source/preset; HA rows contain entity, optional zone, kind and temperature.
|
||||
|
||||
Zone rows contain `gree_temperature`, `external_temperature` (HA room sensor), `control_temperature`, `target_temperature`, `device_setpoint`, `outdoor_temperature`, `power`, `mode`, `fan_speed`, `demand`, `control_source`, and `active_preset`. If a zone has no rich samples yet, the API falls back to that zone's existing GREE device readings instead of returning an empty timeline.
|
||||
## InfluxDB long-term storage
|
||||
|
||||
Sensor rows contain `entity_id`, optional `zone_id`, `kind` (`room` or `outdoor`), `timestamp`, and `temperature`. New HA samples start being collected after the upgrade; where older rich zone samples contain the same HA values, the API can expose them as compatibility history.
|
||||
Runtime settings support either InfluxDB 1.x (`version=1`, URL, database and optional username/password) or InfluxDB 2.x (`version=2`, URL, org, bucket and token). The same values can be supplied with `GREE_CONTROLLER_INFLUX_*` environment variables; see `.env.example`. An explicitly configured environment value overrides the persisted setting at startup.
|
||||
|
||||
Reference in New Issue
Block a user