v0.9.6
This commit is contained in:
Mateusz Gruszczyński
@@ -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