112 lines
4.1 KiB
Markdown
112 lines
4.1 KiB
Markdown
# Home Assistant integration
|
|
|
|
The project includes a custom Home Assistant integration under:
|
|
|
|
```text
|
|
home-assistant/custom_components/gree_controller/
|
|
```
|
|
|
|
It creates HA `climate` entities but sends every command to the standalone Rust controller. Home Assistant therefore becomes a client, while UDP/AES GREE communication remains outside HA.
|
|
|
|
The climate proxy supports power/turn on/off, HVAC modes, target temperature, fan mode, vertical swing and horizontal swing.
|
|
|
|
## 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 **Settings -> Home Assistant integration access -> 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 and sending climate 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.
|