v0.9.6
This commit is contained in:
Mateusz Gruszczyński
+26
-3
@@ -1,6 +1,6 @@
|
||||
# GREE Controller API reference
|
||||
|
||||
HTTP and WebSocket API for GREE Controller **0.9.5**.
|
||||
HTTP and WebSocket API for GREE Controller **0.9.6**.
|
||||
|
||||
[← Main documentation](../README.md)
|
||||
|
||||
@@ -212,7 +212,7 @@ Response:
|
||||
{
|
||||
"status": "ok",
|
||||
"name": "gree-controller",
|
||||
"version": "0.9.5",
|
||||
"version": "0.9.6",
|
||||
"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.5",
|
||||
"version": "0.9.6",
|
||||
"uptime_seconds": 1234,
|
||||
"auth_required": false,
|
||||
"control_ready": true,
|
||||
@@ -1482,6 +1482,15 @@ curl -H 'Authorization: Bearer gree_controller_RESTRICTED_TOKEN' \
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Visual Flow API
|
||||
|
||||
Flow is the source-of-truth representation for visual schedule/automation logic. `GET /api/flows` lists Flows; `GET /api/flows/:id`, `POST /api/flows`, `PUT /api/flows/:id` and `DELETE /api/flows/:id` manage them. A Flow payload contains `name`, `enabled`, optional `description`, `nodes` and `edges`.
|
||||
|
||||
Saving a Flow validates the DAG and compiles it atomically. A thermostat action driven only by one weekday block and one time-range block is emitted as a native schedule when its settings are schedule-compatible. More complex graphs are emitted as Flow-triggered automations. Generated schedules and automations expose `flow_id` / `flow_node_id` and cannot be edited or deleted through their legacy endpoints; edit the owning Flow instead.
|
||||
|
||||
Condition blocks support weekday, time/date ranges, application Night mode, outdoor/device/zone temperatures, house/device/zone/group state, and arbitrary Home Assistant state/numeric/attribute/availability sources. Logic blocks support AND, OR and NOT. Action blocks target thermostat zones, GREE devices or climate groups. Direct GREE actions map to the existing `DeviceCommand` fields including fan, swing, quiet, turbo, light, air, xfan, health and sleep; ownership rules may suppress fields that would fight an active thermostat. Flow group actions use the existing group controller and support power, house/heat/cool mode, auto/comfort/sleep/away and the existing custom group target.
|
||||
|
||||
## Compressor protection queue
|
||||
|
||||
Runtime settings expose `compressor_protection_enabled` and `compressor_protection_seconds` (30–1800; default 180). While enabled, thermostat starts and Heat/Cool reversals that fall inside the protection window are represented on the owning zone by `compressor_pending_action`, `compressor_pending_since`, and `compressor_pending_until`.
|
||||
@@ -1490,3 +1499,17 @@ Runtime settings expose `compressor_protection_enabled` and `compressor_protecti
|
||||
- `POST /api/compressor-queue/cancel-all` cancels all currently pending compressor-protection tasks.
|
||||
|
||||
Cancellation suppresses the same pending intent until a new explicit thermostat/group/house command re-arms it, a scheduled Temporary Quick Thermostat session takes ownership, or a different mode/target creates a new intent. Safety OFF commands are not delayed by compressor protection. Direct technical device commands remain immediate manual-control operations.
|
||||
|
||||
### Flow portability and diagnostics
|
||||
|
||||
`GET /api/flows/:id/export` returns a versioned `gree-controller-flow` JSON document containing only the source graph. Generated schedules/automations are not exported.
|
||||
|
||||
`POST /api/flows/import` accepts either that envelope or a direct Flow source payload, creates a new Flow ID/revision, validates it and atomically recompiles outputs.
|
||||
|
||||
`POST /api/flows/simulate` accepts `{ flow, flow_id?, at?, overrides?, log? }`. `at` is RFC3339. `overrides` maps Flow node IDs to simulated values. The endpoint validates and compiles the graph, evaluates every action and returns per-node traces plus `matched`, `would_execute` and `blocked_reason` (for example disabled zone/device, manual/local/temporary thermostat ownership, thermostat-output conflict or disabled Flow). It never mutates thermostat/device/group/schedule/automation state. Home Assistant read/attribute/parse failures evaluate safely as false and are visible in the trace instead of accidentally satisfying `NOT`/`neq` logic.
|
||||
|
||||
`GET /api/flows/:id/logs?limit=100` returns events associated with the Flow or its generated automations.
|
||||
|
||||
Existing Flow updates require `expected_revision`. A mismatched revision returns HTTP 409 to prevent stale editor tabs from overwriting newer graphs. Source Flow plus generated outputs are replaced atomically in one database transaction while configuration/automation/schedule/thermostat-cycle operations are serialized.
|
||||
|
||||
Additional Flow condition blocks are `house_mode`, `device_state`, `zone_state`, `group_state`, `night_mode`, `ha_attribute`, `ha_available` and `constant`, alongside weekday/time/date, temperature, Home Assistant state/numeric and AND/OR/NOT blocks. `device_state` can inspect enabled/online/power/mode/fan/swing/quiet/turbo/light/air/xfan/health/sleep state. The editor ships ten editable templates: workday comfort, weather comfort, smart demand, device resilience, night group, HA window guard, presence eco, frost guard, nested guard and night quiet.
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
# Visual Flow architecture
|
||||
|
||||
Flow is an authoring/orchestration layer. It does not replace the thermostat, schedule, group or device engines.
|
||||
|
||||
## Compilation
|
||||
|
||||
- `weekday + time_range -> zone_thermostat` with schedule-compatible settings compiles to a native `Schedule`.
|
||||
- Richer DAGs compile to native `Automation` rows with `trigger_kind = "flow"`.
|
||||
- Generated rows keep `flow_id` and `flow_node_id` and are read-only in the legacy editors.
|
||||
- The Flow source graph plus all of its generated schedule/automation rows are replaced in one SQLite transaction.
|
||||
- Flow updates require `expected_revision`; stale editor tabs receive HTTP 409.
|
||||
|
||||
## Existing control domains remain authoritative
|
||||
|
||||
- `zone_thermostat` writes the existing persistent Zone intent and wakes the normal thermostat cycle.
|
||||
- `group_action` calls the existing `control_group` path, including custom group targets.
|
||||
- `device_action` uses the existing `DeviceCommand` / automatic-device path.
|
||||
- Thermostat hysteresis, compressor protection, schedule hand-back, manual/local ownership and Temporary Quick Thermostat keep their existing priority.
|
||||
- GREE fan/quiet/sleep and dry/fan HVAC modes are suppressed on thermostat-assigned devices when they would fight the regulator. Device-only features such as light/turbo/swing/air/xfan/health remain available through the normal command path.
|
||||
|
||||
## Concurrency invariants
|
||||
|
||||
Structural Flow writes use the global order:
|
||||
|
||||
`configuration -> automation -> schedule -> thermostat-cycle`
|
||||
|
||||
Thermostat/device actions then use:
|
||||
|
||||
`automation -> schedule -> thermostat-cycle -> zone -> device`
|
||||
|
||||
Group actions use the existing group order:
|
||||
|
||||
`automation -> house -> thermostat-cycle -> group -> zone(s) -> device`
|
||||
|
||||
The control loop runs thermostat arbitration and automation arbitration sequentially. Automation execution reloads the row after acquiring the automation lock and skips it when `updated_at` changed. Same-cycle due automations deterministically claim target devices so two rules cannot issue conflicting commands to the same unit in one pass. Polling and physical commands share per-zone/per-device locks.
|
||||
|
||||
Holding the automation lock across the physical action is deliberate: Flow cannot be deleted/recompiled while an already-selected action is in flight. Do not shorten this ownership window without adding an explicit execution-generation/token mechanism.
|
||||
|
||||
External sensor values can naturally change between condition sampling and action execution. This is normal sampled-control semantics, not a persistent-state race; safety/ownership is rechecked at the action boundary.
|
||||
|
||||
## Home Assistant safety
|
||||
|
||||
`ha_state`, `ha_numeric`, `ha_attribute` and `ha_available` fail closed. Connection failures, missing attributes and non-numeric numeric states evaluate to `false` and appear as an error object in dry-run traces. This prevents `NOT` / `neq` branches from becoming true merely because Home Assistant is unavailable.
|
||||
|
||||
## Diagnostics
|
||||
|
||||
The Flow editor exposes:
|
||||
|
||||
- dry-run at an arbitrary date/time,
|
||||
- per-source overrides,
|
||||
- per-node trace,
|
||||
- `would_execute` and ownership/block reason,
|
||||
- Flow-scoped execution/dry-run logs,
|
||||
- import/export of versioned `.flow.json` source graphs.
|
||||
|
||||
Dry-run never mutates thermostats, devices, groups, schedules or automations.
|
||||
|
||||
## Blocks
|
||||
|
||||
Condition/source blocks currently include weekday, time range, date range, application Night mode, outdoor/device/zone temperature, house mode, device state, thermostat/zone state, group state, Home Assistant state/numeric/attribute/availability and a diagnostic constant. Logic blocks are AND, OR and NOT.
|
||||
|
||||
Actions include thermostat zone, GREE device and climate group. Direct GREE actions expose power, HVAC mode, target temperature, fan speed, vertical/horizontal swing, quiet, turbo, light, air, xfan, health and sleep.
|
||||
|
||||
## Built-in templates
|
||||
|
||||
The editor ships editable templates for:
|
||||
|
||||
- workday comfort,
|
||||
- weather-aware comfort,
|
||||
- smart AND/OR demand,
|
||||
- device resilience,
|
||||
- night group control,
|
||||
- Home Assistant window guard,
|
||||
- presence comfort/eco,
|
||||
- frost protection,
|
||||
- nested OR + NOT guard,
|
||||
- application Night-mode quiet profile.
|
||||
|
||||
## Good next stateful blocks
|
||||
|
||||
The next useful additions should be implemented with persisted runtime state rather than pretending they are stateless predicates:
|
||||
|
||||
- `for X minutes` / stable-for,
|
||||
- debounce,
|
||||
- hysteresis block,
|
||||
- rising/falling edge,
|
||||
- cooldown/rate limit independent of the action,
|
||||
- delay/timer,
|
||||
- retry/backoff,
|
||||
- variables/counters,
|
||||
- reusable subflows/macros,
|
||||
- explicit priority/mutex groups for actions,
|
||||
- trace replay from historical sensor samples.
|
||||
|
||||
These need durable state and restart semantics before they should be exposed in the editor.
|
||||
Reference in New Issue
Block a user