first commit

2026-08-23 21:34:07 +02:00
commit 1d3dcba1a9
62 changed files with 12456 additions and 0 deletions
@@ -0,0 +1,67 @@
+# Home Assistant entity-ID migration
+
+## Goal
+
+Replace an existing GREE climate entity while preserving its `entity_id`.
+
+Example:
+
+```text
+Before: climate.klima_salon -> default GREE integration -> AC
+After:  climate.klima_salon -> GREE Controller integration -> Rust controller -> AC
+```
+
+Keeping the same entity ID allows existing dashboards, scripts, scenes and automations that reference the entity by ID to continue working.
+
+## Why a takeover step is required
+
+Home Assistant's entity registry reserves entity IDs. A second integration cannot create another active `climate.klima_salon` while the original entity still exists. The new integration therefore checks for conflicts and stops setup rather than allowing HA to generate a suffixed name such as `climate.klima_salon_2`.
+
+## Generate the mapping
+
+For one entity:
+
+```bash
+./scripts/generate_ha_migration.py \
+  --entity climate.klima_salon \
+  --device gree-aabbccddeeff
+```
+
+For several:
+
+```bash
+./scripts/generate_ha_migration.py \
+  --map climate.klima_salon=gree-aabbccddeeff \
+  --map climate.klima_sypialnia=gree-112233445566
+```
+
+Generated structure:
+
+```json
+{
+  "version": 1,
+  "entities": [
+    {
+      "entity_id": "climate.klima_salon",
+      "device_id": "gree-aabbccddeeff"
+    }
+  ]
+}
+```
+
+Copy it to `/config/gree_controller_entities.json` on the Home Assistant host.
+
+## Migration sequence
+
+1. Add the physical AC to the standalone Rust application.
+2. Test power, mode and target temperature from its web UI.
+3. Generate the HA entity mapping.
+4. Copy the custom component to `/config/custom_components/gree_controller/`.
+5. Disable/remove the previous GREE integration in HA so it no longer controls or publishes the old climate entity.
+6. Remove any stale entity registry entry only after the old integration is unloaded.
+7. Add the **GREE Controller** integration and provide its URL/token.
+8. Confirm the exact old entity ID is present again.
+9. Test `climate.set_temperature`, HVAC modes and power from HA.
+10. Verify automations and dashboards that use the preserved entity ID.
+
+The standalone controller remains available during the HA migration, so the AC can still be controlled from its own web UI if HA is restarting.