v0.14.0

README.md

@@ -2,13 +2,9 @@
 
 Self-hosted controller for GREE-compatible air conditioners with a local Web UI, thermostat zones, schedules, Home Assistant integration, history, notifications and a documented HTTP/WebSocket API.
 
-**Current release: 0.13.10**
+**Version: 0.14.0**
 
-Release 0.13.10 improves compatibility with GREE units that report optional feature fields as multi-state values instead of strict 0/1 flags. In particular, `Quiet=2` or `Quiet=3` no longer invalidates the whole status response, and the controller remembers the active Quiet encoding reported by the unit while keeping `Quiet=1` as the legacy default. Existing AES-ECB/AES-GCM behavior and API contracts remain unchanged.
-
-Release 0.13.9 fixes dashboard thermostat card sizing when local thermostat or manual device control is active. Cards now keep their intrinsic height instead of stretching every thermostat in the same grid row; API contracts are unchanged.
-
-Release 0.13.6 adds a dedicated notification toggle for GREE vs Home Assistant room-temperature discrepancies. Disabling this alert suppresses `zone.sensor_discrepancy` notifications only; sensor fallback and thermostat safety behavior are unchanged.
+Version 0.14.0 keeps the existing LAN/UDP 7000 transport unchanged and adds GREE Cloud as a separate first-class provider with encrypted REST discovery, persistent MQTT/TLS synchronization, Cloud commands, per-device capabilities, diagnostics and energy history. Local and Cloud entries are deliberately independent, even when they represent the same physical MAC.
 
 > [Full API reference](docs/API.md) — authentication, every endpoint, request bodies, response models, WebSocket events and examples.
 
@@ -143,6 +139,46 @@ Environment values explicitly supplied for supported runtime overrides win over
 
 Additional environment variables cover history retention, debug, night mode, Home Assistant and InfluxDB. See [`.env.example`](.env.example).
 
+## Local vs GREE Cloud
+
+Each device has an explicit `connection_type`:
+
+- **Local** uses the existing GREE LAN protocol over UDP/7000, including discovery, bind, status and commands. It never calls GREE Cloud.
+- **GREE Cloud** uses the configured account plus MQTT/TLS. It never performs UDP discovery, bind, probe or commands.
+
+The same physical air conditioner may intentionally be added twice, once as Local and once as GREE Cloud. The controller does not automatically fail over between transports, preventing duplicate commands.
+
+## GREE Cloud setup
+
+Open **Settings → GREE Cloud**, enable the provider, select the same region used by the official GREE app, enter the account login/email and password, then use **Test connection**. After a successful test, use **Refresh devices** and explicitly add the units you want to control through Cloud. Credentials are account-level settings; they are not copied into every device.
+
+The password field is write-only from the UI: a saved password is reported only as configured/not configured. The installation UUID used by the GREE Cloud User-Agent is generated once and persisted.
+
+## Cloud status
+
+Cloud devices distinguish `online`, `offline`, `cloud_disconnected`, `authentication_error` and `unknown`. Account/MQTT state is shown separately so an offline air conditioner is not confused with a broker, credential or internet failure. Device diagnostics include safe broker/topic/status information and decrypted/sanitized properties, never authentication tokens or cipher keys.
+
+## Cloud polling and synchronization
+
+MQTT push is the normal synchronization path. REST login is reused for the MQTT session and is not repeated for every status request. Polling is used for initial state, recovery, fallback and periodic verification; the configurable Cloud interval is clamped to at least 30 seconds. MQTT reconnect uses bounded backoff and restored subscriptions. A Cloud outage does not switch a device to LAN and does not block Local polling/control.
+
+## Energy
+
+Energy can come from either **GREE Cloud** or a cumulative Home Assistant energy sensor. Devices with both sources can select **Auto**, **GREE Cloud** or **Home Assistant**. Home Assistant candidates are limited to `device_class=energy`, `state_class=total|total_increasing` and `Wh`/`kWh` units.
+
+GREE `ElcAll` is a cumulative counter in tenths of a kWh and is normalized to kWh. Cumulative counters are converted to per-sample consumption deltas before history aggregation. The first sample establishes a baseline; duplicate samples consume zero; a falling/reset counter creates a new baseline; negative consumption is never stored. Energy history is separate from temperature history and can be aggregated hourly, daily, weekly or monthly, with Today, Yesterday, Current month, Previous month and Period total summaries. Older energy samples can be archived to InfluxDB using the same retention policy as other metrics.
+
+## GREE Cloud security
+
+Cloud REST and MQTT use TLS with certificate/hostname validation enabled. Passwords, REST tokens, MQTT credentials, Authorization headers and device cipher keys are excluded from normal API responses, Cloud diagnostics and logs. Network, connect and command operations have bounded timeouts; retries/reconnects are rate-limited rather than tight-looped.
+
+## Limitations
+
+- GREE Cloud availability and behavior depend on GREE's external services and the selected account region.
+- The Cloud status protocol does not expose a universal buzzer capability. When **suppress device beep** is enabled, Cloud commands follow `greeclimate` semantics and include `Buzzer_ON_OFF=1`; models that ignore this command-only field simply continue without a separately advertised buzzer capability.
+- Capability detection is based on discovery/model data plus properties actually returned by the device. Controls are hidden or rejected when support is known to be absent.
+- There is intentionally no automatic Local↔Cloud fallback.
+
 ## Connecting physical GREE units
 
 1. Place the controller host on a network that can reach the air-conditioner Wi-Fi modules by UDP.