gree-controller/home-assistant/README.md

# Home Assistant integration

The project includes a custom Home Assistant integration under:

```text
home-assistant/custom_components/gree_controller/
```

It creates HA entities for physical units, thermostat zones, whole-house controls and climate groups, while sending every command to the standalone Rust controller. Home Assistant therefore remains a client and UDP/AES GREE communication stays outside HA.

The climate proxy supports power/turn on/off, HVAC modes, target temperature, fan mode, vertical swing and horizontal swing.

Version 0.5.0 additionally exposes the controller's automation plan:

- `sensor` for the whole-house plan (house mode, upcoming events and active rules),
- one `sensor` per thermostat zone with current demand, active preset/schedule and upcoming transitions,
- one writable `number` per zone for the controller target temperature (8-30°C, 0.5°C step),
- one `switch` per zone for enabling/disabling the thermostat directly from Home Assistant.

The plan entities can be placed on a normal Home Assistant dashboard; their `next_events` attributes contain the same schedule timeline shown as graphical blocks in the controller Web UI. Changing a zone target number calls the restricted controller zone API and creates the same temporary override as the Web UI. The zone switch uses the same API to enable or disable that thermostat.

## Install the custom integration

Copy the directory into your HA configuration:

```text
/config/custom_components/gree_controller/
```

Before adding the integration, open the standalone controller Web UI and go to **More -> Home Assistant / Sensors -> Create new token**. Copy the generated secret; it is shown only once.

Restart Home Assistant, then open **Settings -> Devices & services -> Add integration -> GREE Controller** and enter only:

- controller URL, for example `http://192.168.1.20:8787`,
- the generated controller access token.

The integration token is required even when the controller Web UI itself is left open on a trusted LAN. It is restricted to reading controller devices/control plans/groups and sending device, zone, whole-house or climate-group control commands.

## Preserve an existing entity ID

If existing automations and dashboards use an entity such as:

```text
climate.klima_salon
```

use the migration generator before switching integrations:

```bash
./scripts/generate_ha_migration.py \
  --entity climate.klima_salon \
  --device gree-aabbccddeeff
```

Copy the generated JSON file to:

```text
/config/gree_controller_entities.json
```

The custom integration reads this file and requests the exact same `climate.*` entity ID.

Home Assistant cannot have two active entities with the same `entity_id`. Therefore the old/default GREE entity must release `climate.klima_salon` before the new integration is loaded. Do not run both integrations against the same entity ID.

Safe order:

1. Configure and test the standalone Rust controller first.
2. Confirm the AC can be controlled from the GREE Controller web UI.
3. Generate and copy `gree_controller_entities.json`.
4. Disable or remove the old/default GREE integration entry in Home Assistant.
5. If its old entity registry record remains, remove that stale entity from HA after the old integration is unloaded.
6. Install/restart the `gree_controller` custom integration.
7. Verify that `climate.klima_salon` exists and controls the AC through the Rust service.
8. Check existing dashboards, scripts and automations. Because the entity ID is unchanged, references to `climate.klima_salon` do not need to be rewritten.

The integration deliberately fails setup on an entity-ID conflict instead of silently creating `climate.klima_salon_2`.

## Multiple devices

Use repeated mappings:

```bash
./scripts/generate_ha_migration.py \
  --map climate.klima_salon=gree-aabbccddeeff \
  --map climate.klima_sypialnia=gree-112233445566
```

## Optional validation

Validate the target controller device:

```bash
./scripts/generate_ha_migration.py \
  --entity climate.klima_salon \
  --controller-url http://192.168.1.20:8787 \
  --controller-token CONTROLLER_TOKEN
```

Validate that the source HA entity currently exists as well:

```bash
./scripts/generate_ha_migration.py \
  --entity climate.klima_salon \
  --device gree-aabbccddeeff \
  --ha-url http://homeassistant.local:8123 \
  --ha-token HOME_ASSISTANT_LONG_LIVED_TOKEN
```

Tokens are used only during validation and are not written to the mapping file.

## HA as an external temperature source

This is independent from the custom climate integration. Each Rust controller zone can assign its own HA room-temperature entity, for example:

```text
Living room -> GREE Living Room + sensor.living_room_temperature
Bedroom     -> GREE Bedroom + sensor.bedroom_temperature
```

The recommended `combined` strategy keeps the GREE sensor as the primary input and uses the room sensor as a configurable supporting measurement (40% weight by default). A zone may also select the room sensor as its preferred source. If HA or that entity becomes unavailable, the controller falls back to the corresponding GREE unit, so local control and schedules continue to run.
## Zone climate and optional unit features (0.5.4)

Each controller zone is exposed as a full Home Assistant `climate` entity with current/target temperature and HVAC modes: Off, Auto (follow the controller house mode), Cool and Heat. For a **zone thermostat**, Auto does not mean the GREE unit's native automatic heat/cool algorithm: it means **inherit the whole-house Heating/Cooling selection from GREE Controller**. Direct physical-device climate entities still use the native GREE Auto mode. The target temperature remains published while a zone is Off, so Home Assistant can display the configured setpoint instead of `unknown`. The existing zone target `number` and enabled `switch` remain available for compatibility.

From version 0.7.9, each zone climate also supports preset modes `auto`, `comfort`, `sleep` and `away`, and the same choices are exposed as a separate **Work profile** `select` on the zone device. `auto` removes the temporary per-zone profile override and returns the zone to its schedule. The zone enable switch now reports the configured zone state independently from group power gates; `effective_enabled` remains available in attributes/sensors to show when an enabled zone is currently blocked by a disabled group. From version 0.7.10, climate entity ON/OFF controls local thermostat power rather than technically enabling/disabling the zone: local ON may run the zone while its group is off, with full thermostat logic intact. From 0.7.12, every local OFF creates a fresh backend-owned 15-minute hand-back deadline exposed as `local_thermostat_resume_at`. A direct/pilot takeover suspends expiry of that local timer; if the unit is returned to the previous OFF state, the backend re-arms a fresh 15-minute countdown from that moment. The separate zone Enabled switch remains the technical availability switch.

From version 0.6.4, zone climate entities use `climate.<zone_name>_thermostat`, for example `climate.igor_thermostat`. On integration reload, existing zone climate registry entries are migrated to this scheme using the zone's current name. If the target entity ID is already occupied, the old ID is retained and Home Assistant logs a warning.

When the controller detects optional GREE properties, the integration also creates switches for supported features such as panel light, Quiet, Turbo, X-FAN, Air, Health and native Sleep. Reload the integration (or restart Home Assistant) after upgrading so newly added entity types are created.

## Whole-house controls

The integration also exposes three controller-level entities on the **GREE Controller** device:

- **Thermostat mode** (`select`) — Cooling, Heating or **Do not control**. Do not control pauses house-level thermostat commands but leaves direct device control and explicit per-zone Heat/Cool overrides untouched.
- **Work profile** (`select`) — Auto schedule, Comfort, Sleep or Away. If zones have mixed manual profiles, the select has no single current option until a whole-house profile is chosen again.
- Choosing **Cooling/Heating** in the thermostat-mode select or any whole-house **Work profile** is treated as explicit whole-house activation: it switches **All air conditioners** back on. **Do not control** does not change master power.
- **All air conditioners** (`switch`) — separate master power. Turning it off powers every enabled unit down and prevents zones/controller automations from restarting them. Turning it on powers all enabled units on again without changing the selected thermostat mode or profile.

These controls use the Home Assistant integration token and the dedicated `/api/integrations/home-assistant/house/*` endpoints.


## Climate groups (0.7.3)

Every group configured in **GREE Controller -> Groups** is published as a separate Home Assistant device. A group does not receive a fake common target temperature because its member zones can legitimately use different profile temperatures. Instead, the group device exposes the controls that exactly match the controller model:

- **Power** (`switch`) — enables/disables only this group.
- **Thermostat mode** (`select`) — **Global**, Cooling or Heating. **Global** means all member zones inherit the controller-wide Heating/Cooling selection.
- **Work profile** (`select`) — Auto schedule, Comfort, Sleep or Away.
- **Control plan** (`sensor`) — group status plus member zone IDs/names, average current temperature, enabled/demanding zone counts, online unit count and upcoming member schedule events.

If member zones have been changed individually and no longer share one mode or profile, the matching select has no current common value instead of reporting a misleading state. Selecting a group mode/profile applies it to every member through the existing controller group logic.

After upgrading the custom integration, restart Home Assistant or reload **Settings -> Devices & services -> GREE Controller**. Also reload the integration after adding/removing/renaming groups so new group devices/entities are created.

## Command state stability (0.7.6)

Direct physical-unit commands use a short pending-state guard in the Home Assistant coordinator. Some GREE firmware acknowledges a command before its status endpoint stops returning the previous value; the guard prevents that transient stale read from rendering as an `ON -> OFF -> ON` (or reverse) bounce. From version 0.7.9 the same guard also covers per-zone enable, HVAC mode, profile and target-temperature commands. The standalone controller also retries post-command verification for a bounded settling window. Failed commands drop the guard immediately and refresh factual state.