v0.15.0

docs/API.md

@@ -1,6 +1,6 @@
 # GREE Controller API reference
 
-HTTP and WebSocket API for GREE Controller **0.14.24**.
+HTTP and WebSocket API for GREE Controller **0.15.0**.
 
 [← Main documentation](../README.md)
 
@@ -240,7 +240,7 @@ Response:
 {
   "status": "ok",
   "name": "gree-controller",
-  "version": "0.14.24",
+  "version": "0.15.0",
   "uptime_seconds": 1234,
   "control_ready": true,
   "time": "2026-08-30T06:54:00Z"
@@ -303,7 +303,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.24",
+    "version": "0.15.0",
     "uptime_seconds": 1234,
     "auth_required": false,
     "control_ready": true,
@@ -360,7 +360,8 @@ A device response contains:
 | `mode` | string | `auto`, `cool`, `dry`, `fan`, `heat`. |
 | `target_temperature` | number | Last known unit setpoint. |
 | `fan_speed` | integer | `0..5`; `0` is Auto. |
-| `swing_vertical`, `swing_horizontal` | boolean | Swing state. |
+| `swing_vertical` | integer | Vertical louver (`SwUpDn`): `0` off/default, `1` full range, `2..6` fixed positions, `7..11` partial swing ranges. |
+| `swing_horizontal` | integer | Horizontal louver (`SwingLfRig`): `0` off/default, `1` full range, `2..6` fixed positions. |
 | `quiet`, `turbo`, `light`, `air`, `xfan`, `health`, `sleep` | boolean | Optional GREE features. |
 | `supports_*` | boolean/null | Capability learned from device status. |
 | `current_temperature` | number/null | GREE indoor temperature. |
@@ -484,8 +485,8 @@ All fields optional; at least one meaningful field should be sent:
   "mode": "cool",
   "target_temperature": 22,
   "fan_speed": 3,
-  "swing_vertical": true,
-  "swing_horizontal": false,
+  "swing_vertical": 2,
+  "swing_horizontal": 1,
   "quiet": false,
   "turbo": false,
   "light": true,
@@ -496,6 +497,8 @@ All fields optional; at least one meaningful field should be sent:
 }
 ```
 
+Louver command values follow the raw GREE positions. For backward compatibility, legacy booleans are still accepted (`false` = `0`, `true` = `1`).
+
 Rules:
 
 - modes: `auto`, `cool`, `dry`, `fan`, `heat`,
@@ -1691,11 +1694,17 @@ Additional Flow condition blocks are `house_mode`, `device_state`, `zone_state`,
 
 
 
+## Granular louver positions — 0.15.0
+
+Vertical (`swing_vertical`) and horizontal (`swing_horizontal`) controls now carry the raw GREE louver position instead of only on/off. Vertical supports `0..11`; horizontal supports `0..6`. The first values map to Off, Full range (Auto) and the fixed positions shown by GREE remotes/apps; vertical `7..11` additionally represent partial swing ranges.
+
+Manual unit control and thermostat cards use position dropdowns. Legacy direct-device automations, `device_action` / `zone_thermostat` Flow actions and `device_state` conditions expose the same positions. The bundled Home Assistant direct and zone climate entities expose granular swing modes while retaining `off` and `on` as the first two modes for compatibility. Louver changes remain auxiliary one-shot commands and do not take thermostat ownership.
+
+The command API continues accepting legacy boolean swing payloads (`false` = `0`, `true` = `1`) so existing clients can migrate without an immediate break.
+
 ## Swing control across manual, thermostat and automation surfaces — 0.14.2
 
-Local device control exposes vertical (`swing_vertical`) and horizontal (`swing_horizontal`) swing independently. Thermostat zone UI and the bundled Home Assistant zone climate entity expose the same auxiliary controls when the assigned device reports support; changing swing does not hand thermostat ownership to manual control.
-
-Legacy direct-device automations accept optional `swing_vertical` and `swing_horizontal` action fields. Visual Flow exposes both axes in `device_action` and `zone_thermostat` actions and in device-state conditions. A `zone_thermostat` Flow using swing compiles to an automation rather than a native schedule so the auxiliary command is preserved. Swing remains outside the thermostat's continuously regulated fan/temperature outputs.
+Version 0.14.2 introduced independent vertical (`swing_vertical`) and horizontal (`swing_horizontal`) boolean swing controls across direct control, thermostat zones, legacy automations, Visual Flow and Home Assistant zone climates. Version 0.15.0 extends those fields to granular louver positions while preserving boolean command compatibility.
 
 ## Split/multisplit installations and energy comparison — 0.14.1
 

docs/FLOW.md

@@ -4,7 +4,7 @@ Flow is an authoring/orchestration layer. It does not replace the thermostat, sc
 
 ## Compilation
 
-- `weekday + time_range -> zone_thermostat` with schedule-compatible settings compiles to a native `Schedule`; selecting vertical or horizontal swing makes the action compile as an `Automation` so the swing command is not lost.
+- `weekday + time_range -> zone_thermostat` with schedule-compatible settings compiles to a native `Schedule`; selecting a vertical or horizontal louver position makes the action compile as an `Automation` so the louver command is not lost.
 - Richer DAGs compile to native `Automation` rows with `trigger_kind = "flow"`.
 - Generated rows keep `flow_id` and `flow_node_id`, use stable `flow-<stable-unique-id>` names, 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.
@@ -14,11 +14,11 @@ Flow is an authoring/orchestration layer. It does not replace the thermostat, sc
 
 ## Existing control domains remain authoritative
 
-- `zone_thermostat` writes the existing persistent Zone intent and wakes the normal thermostat cycle. It can also issue one-shot vertical/horizontal swing commands to the assigned unit; these auxiliary fields do not take over thermostat ownership.
+- `zone_thermostat` writes the existing persistent Zone intent and wakes the normal thermostat cycle. It can also issue one-shot granular vertical/horizontal louver commands to the assigned unit; these auxiliary fields do not take over thermostat ownership.
 - `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.
+- 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/louver/air/xfan/health remain available through the normal command path.
 
 ## Concurrency invariants
 
@@ -61,7 +61,7 @@ Dry-run never mutates thermostats, devices, groups, schedules or automations. Fo
 
 Condition/source blocks include weekday, time range, date range, optional 5-field CRON triggers, application Night mode, outdoor/device/zone temperature, house mode, device state, thermostat/zone state, group state, Home Assistant state/numeric/attribute/availability, rolling mean/median windows, numeric oscillation detection, a diagnostic constant, and `shared_input`. Stateful gates include `stable_for`, bounded `state_duration`, `on_change` (condition-result or raw-value edge), `rate_limit` (maximum successful executions in a rolling period), and `delay`. Their runtime state, together with rolling statistics and oscillation samples, is persisted in the generated automation payload so restarts do not silently reset timing/history. Editing a stateful block resets only that block's incompatible runtime state. Flow state continues to be observed while the action itself is in cooldown, preventing stale continuity/change state. A `rate_limit` block must be placed directly before an action and consumes quota only after a successful execution; suppressed or failed actions do not consume it. Shared inputs are configured centrally in Home Assistant / Sensors and referenced by ID. Shared inputs store reusable value sources only; operators and comparison values are configured exclusively in each Flow reference. Logic blocks are AND, OR and NOT.
 
-Actions include thermostat zone, GREE device, climate group, and generic Home Assistant service calls (`domain`, `service`, optional `entity_id`, JSON service data). Direct GREE actions expose power, HVAC mode, target temperature, fan speed, vertical/horizontal swing, quiet, turbo, light, air, xfan, health and sleep.
+Actions include thermostat zone, GREE device, climate group, and generic Home Assistant service calls (`domain`, `service`, optional `entity_id`, JSON service data). Direct GREE actions expose power, HVAC mode, target temperature, fan speed, vertical/horizontal louver position, quiet, turbo, light, air, xfan, health and sleep.
 
 ## Built-in presets