v0.15.0
This commit is contained in:
Mateusz Gruszczyński committed
1 parent
32f8a32bd2
commit
df10ead47e
38 files changed
+655
-210
No files matched your search
+18
-9
@@ -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
|
||||
|
||||
|
||||
+4
-4
@@ -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
|
||||
|
||||
|
||||
+71
-21
@@ -2,9 +2,9 @@
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "GREE Controller API",
|
||||
"version": "0.14.24",
|
||||
"version": "0.15.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\nAdministrator endpoints accept `Authorization: Bearer <APP_TOKEN>` or `x-api-token: <APP_TOKEN>` when configured. Restricted Home Assistant control endpoints also accept generated integration tokens.\n\n### Local and GREE Cloud\nDevices use one API model and one command surface. `connection_type=local` is dispatched only to the existing LAN/UDP provider; `connection_type=gree_cloud` is dispatched only to the GREE Cloud provider. No automatic transport fallback is performed.\n\n### GREE Cloud security\nCloud passwords, REST/MQTT tokens, Authorization values and device cipher keys are never returned in normal API responses or Cloud diagnostics. MQTT uses TLS with certificate and hostname validation.\n\n### Energy\nGREE Cloud `ElcAll` and selected Home Assistant cumulative energy sensors are normalized to kWh and converted to consumption deltas before aggregation. Raw cumulative values are retained only as meter samples/baselines.\n\n### 0.14.24\nPublic Custom Charts now fetch chart metadata before language assets, use English for missing-chart errors, support pinch-to-zoom/panning and clickable metric legends, and include the related missing-ID, favicon and Access Token UX fixes.\n\n### 0.14.23\nCode cleanup and small UX changes.\n\n### 0.14.22\nCode cleanup and small UX changes.\n\n### 0.14.21\nCode cleanup and small UX changes.\n\n### 0.14.20\nFixes the ARM cross-build bootstrap by removing the invalid xx-cargo version probe, prepares the target Rust standard library in a cacheable pre-source layer, shares dependency fetching across target architectures, and isolates compiled target caches per architecture while preserving DISTRO-selected Alpine/musl and Debian Trixie/glibc runtimes.\n\n### 0.14.19\nHome Assistant OCI builds now compile Rust for amd64/arm64 on the native build platform through xx cross-compilation, keep Cargo registry/target caches between builds, and send a smaller Docker context while preserving the selected Alpine (musl) or Debian Trixie (glibc) runtime. The Web UI also deduplicates the initial GREE Cloud runtime-status GET across the HTTP and WebSocket bootstrap renders.\n\n### 0.14.18\nShared Web UI CSS now uses generic reusable class names for segmented tabs, configuration layouts, chart cards, enable toggles, diagram primitives and Flow block categories; behavior and visual styling are unchanged.\n\n### 0.14.17\nHistory navigation now reuses the same segmented tab component as Flow / Schedules / Automations, with redundant History-specific tab CSS removed.\n\n### 0.14.16\nCustom Charts now expose saved-chart editing in the Web UI, public chart pages can switch history range through an optional hours override, and the standalone chart layout fits the viewport without vertical page scrolling.\n\n### 0.14.15\nHome Assistant add-on Custom Chart links now resolve the primary HA host IPv4 through Supervisor, support an explicit public_chart_base_url override, and enforce the fixed 8787 ingress/application port contract at startup and build time. Standalone bind/port behavior remains configurable.\n\n### 0.14.14\nShared Flow input Home Assistant sources now expose a dedicated entity search box separate from the selected entity_id, making large live entity catalogs easy to filter by name, ID and state.\n\n### 0.14.13\nHome Assistant add-on authentication is now hidden behind an automatic Supervisor status, manual URL/token fallback is unlocked only after a failed HA test, connection tests return a live sample entity reading, and Shared Flow input HA sources include searchable live entity suggestions.\n\n### 0.14.12\nThe Home Assistant add-on now uses the Supervisor Core API proxy and runtime SUPERVISOR_TOKEN automatically; standalone Home Assistant URL/token configuration is unchanged.\n\n### 0.14.11\nWeb UI icons now use a shared inline SVG set instead of font-dependent Unicode glyphs across navigation, dialogs, Flow, charts, controls and event categories for consistent cross-platform rendering.\n\n\n### 0.14.10\nNight mode and Home Assistant / Sensors standalone settings now use the full available page width, matching the other Web UI sections.\n\n### 0.14.9\nPower controls use an embedded SVG icon instead of a font-dependent Unicode glyph. Home Assistant room-sensor stale/error events identify the affected entity and zone, and historical event rows can recover that context from metadata.\n\n### 0.14.8\nRemaining Home Assistant and notification diagnostic errors no longer use device-transport 502 responses. Missing/invalid integration configuration returns 400, configured external dependency failures return 424, and 502 is reserved for Local/LAN GREE device communication.\n\n### 0.14.7\nHome Assistant energy-sensor discovery now returns an empty optional result when HA is not configured, uses 424 for configured external-dependency failures, and custom select popoveLine truncated
|
||||
"description": "Self-hosted API used by the GREE Controller Web UI and Home Assistant integration.\n\n### Authentication\nAdministrator endpoints accept `Authorization: Bearer <APP_TOKEN>` or `x-api-token: <APP_TOKEN>` when configured. Restricted Home Assistant control endpoints also accept generated integration tokens.\n\n### Local and GREE Cloud\nDevices use one API model and one command surface. `connection_type=local` is dispatched only to the existing LAN/UDP provider; `connection_type=gree_cloud` is dispatched only to the GREE Cloud provider. No automatic transport fallback is performed.\n\n### GREE Cloud security\nCloud passwords, REST/MQTT tokens, Authorization values and device cipher keys are never returned in normal API responses or Cloud diagnostics. MQTT uses TLS with certificate and hostname validation.\n\n### Energy\nGREE Cloud `ElcAll` and selected Home Assistant cumulative energy sensors are normalized to kWh and converted to consumption deltas before aggregation. Raw cumulative values are retained only as meter samples/baselines.\n\n### 0.15.0\nAdds granular vertical/horizontal louver positions across direct control, thermostat views, legacy automations, Visual Flow and the bundled Home Assistant integration. Legacy boolean swing command payloads remain accepted. Direct add-on access now shows an invalid-token error only after an explicit token submission.\n\n### 0.14.24\nPublic Custom Charts now fetch chart metadata before language assets, use English for missing-chart errors, support pinch-to-zoom/panning and clickable metric legends, and include the related missing-ID, favicon and Access Token UX fixes.\n\n### 0.14.23\nCode cleanup and small UX changes.\n\n### 0.14.22\nCode cleanup and small UX changes.\n\n### 0.14.21\nCode cleanup and small UX changes.\n\n### 0.14.20\nFixes the ARM cross-build bootstrap by removing the invalid xx-cargo version probe, prepares the target Rust standard library in a cacheable pre-source layer, shares dependency fetching across target architectures, and isolates compiled target caches per architecture while preserving DISTRO-selected Alpine/musl and Debian Trixie/glibc runtimes.\n\n### 0.14.19\nHome Assistant OCI builds now compile Rust for amd64/arm64 on the native build platform through xx cross-compilation, keep Cargo registry/target caches between builds, and send a smaller Docker context while preserving the selected Alpine (musl) or Debian Trixie (glibc) runtime. The Web UI also deduplicates the initial GREE Cloud runtime-status GET across the HTTP and WebSocket bootstrap renders.\n\n### 0.14.18\nShared Web UI CSS now uses generic reusable class names for segmented tabs, configuration layouts, chart cards, enable toggles, diagram primitives and Flow block categories; behavior and visual styling are unchanged.\n\n### 0.14.17\nHistory navigation now reuses the same segmented tab component as Flow / Schedules / Automations, with redundant History-specific tab CSS removed.\n\n### 0.14.16\nCustom Charts now expose saved-chart editing in the Web UI, public chart pages can switch history range through an optional hours override, and the standalone chart layout fits the viewport without vertical page scrolling.\n\n### 0.14.15\nHome Assistant add-on Custom Chart links now resolve the primary HA host IPv4 through Supervisor, support an explicit public_chart_base_url override, and enforce the fixed 8787 ingress/application port contract at startup and build time. Standalone bind/port behavior remains configurable.\n\n### 0.14.14\nShared Flow input Home Assistant sources now expose a dedicated entity search box separate from the selected entity_id, making large live entity catalogs easy to filter by name, ID and state.\n\n### 0.14.13\nHome Assistant add-on authentication is now hidden behind an automatic Supervisor status, manual URL/token fallback is unlocked only after a failed HA test, connection tests return a live sample entity reading, and Shared Flow input HA sources include searchable live entity suggestions.\n\n### 0.14.12\nThe Home Assistant add-on now uses the Supervisor Core API proxy and runtime SUPERVISOR_TOKEN automatically; standalone Home Assistant URL/token configuration is unchanged.\n\n### 0.14.11\nWeb UI icons now use a shared inline SVG set instead of font-dependent Unicode glyphs across navigation, dialogs, Flow, charts, controls and event categories for consistent cross-platform rendering.\n\n\n### 0.14.10\nNight mode and Home Assistant / Sensors standalone settings now use the full available page width, matching the other Web UI sections.\n\n### 0.14.9\nPower controls use an embedded SVG icon instead of a font-dependent Unicode glyph. Home Assistant room-sensor stale/error events identify the affected entity and zone, and historical event rows can recover that context from metadata.\n\n### 0.14.8\nRemaining Home Assistant and notification diagnostic errors no longer use device-transport 502 responses. Missing/invalid integration conLine truncated
|
||||
"license": {
|
||||
"name": "MIT"
|
||||
}
|
||||
@@ -5900,7 +5900,7 @@
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"example": "0.14.24"
|
||||
"example": "0.15.0"
|
||||
},
|
||||
"uptime_seconds": {
|
||||
"type": "integer",
|
||||
@@ -5973,16 +5973,38 @@
|
||||
"maximum": 5
|
||||
},
|
||||
"swing_vertical": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 11
|
||||
},
|
||||
{
|
||||
"type": "boolean",
|
||||
"deprecated": true
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "Optional raw GREE SwUpDn louver position. Legacy booleans are accepted for compatibility (false=0, true=1)."
|
||||
},
|
||||
"swing_horizontal": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 6
|
||||
},
|
||||
{
|
||||
"type": "boolean",
|
||||
"deprecated": true
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "Optional raw GREE SwingLfRig louver position. Legacy booleans are accepted for compatibility (false=0, true=1)."
|
||||
},
|
||||
"quiet": {
|
||||
"type": [
|
||||
@@ -6073,16 +6095,38 @@
|
||||
"maximum": 5
|
||||
},
|
||||
"swing_vertical": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 11
|
||||
},
|
||||
{
|
||||
"type": "boolean",
|
||||
"deprecated": true
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "Optional raw GREE SwUpDn louver position. Legacy booleans are accepted for compatibility (false=0, true=1)."
|
||||
},
|
||||
"swing_horizontal": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 6
|
||||
},
|
||||
{
|
||||
"type": "boolean",
|
||||
"deprecated": true
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "Optional raw GREE SwingLfRig louver position. Legacy booleans are accepted for compatibility (false=0, true=1)."
|
||||
},
|
||||
"quiet": {
|
||||
"type": [
|
||||
@@ -6303,10 +6347,16 @@
|
||||
"maximum": 5
|
||||
},
|
||||
"swing_vertical": {
|
||||
"type": "boolean"
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 11,
|
||||
"description": "Raw GREE SwUpDn louver position. 0=off/default, 1=full swing; fixed positions use 2..6, and vertical partial swing ranges use 7..11."
|
||||
},
|
||||
"swing_horizontal": {
|
||||
"type": "boolean"
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 6,
|
||||
"description": "Raw GREE SwingLfRig louver position. 0=off/default, 1=full swing; fixed positions use 2..6."
|
||||
},
|
||||
"quiet": {
|
||||
"type": "boolean"
|
||||
|
||||
Reference in new issue
Block a user