From 0e6c16706cd30205f671833958930d03c49ed777 Mon Sep 17 00:00:00 2001 From: Rob Hofmann Date: Wed, 23 Sep 2026 13:00:43 +0200 Subject: [PATCH] Docs: apply review feedback on the user documentation Drop the policy that closes every time out and cannot connect issue. The cloud route now hands out the encryption key, which removes the main cause behind that policy, and the troubleshooting page covers the network causes. Corrections from review: - Entity IDs are chosen by Home Assistant, not by the integration. Say so in entities.md, automation-examples.md and the Device Name option. - External temperature and humidity sensors only change what the climate entity shows. Say so in entities.md and the README, as configuration.md already did. - Explain in configuration.md that the cloud login token is stored in the entry and reused at every load, and that only a failing token triggers a new login through reauthentication. YAML entries reuse it too. Fix the troubleshooting entry that claimed a login happens at every setup. - Format the "devices you do not pick are removed" note as a warning block. - Tell users to open an issue when a device answers a property that has no entity yet. - Tone down "every feature the remote has" and drop the comparison with the Home Assistant 2026.8 core integration. --- README.md | 15 ++++----------- docs/automation-examples.md | 2 +- docs/configuration.md | 15 +++++++++++---- docs/entities.md | 6 +++--- docs/troubleshooting.md | 11 ++++------- 5 files changed, 23 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index b61832c..8bf356f 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,9 @@ Gree integration for Home Assistant. It controls Gree air conditioners, and the Home Assistant ships a `gree` integration that works on the local network only. This one goes further. - **Local first, cloud when you need it.** Devices are controlled over UDP on your own network. The Gree cloud is there for devices you cannot reach, and to fetch device names and encryption keys during setup. See [connection methods](docs/connection-methods.md). -- **Every feature the remote has.** X-Fan, Health, Sleep, 8ยฐC Smart Heat, Power Save, Anti Direct Blow, Fresh Air, Humidity Control, display light and brightness, beeper, Turbo and Quiet. Each one is a switch, select or fan mode. See [entities](docs/entities.md). -- **Swing positions.** Twelve vertical and seven horizontal modes: fixed positions and partial swing ranges, not just on and off. The built-in integration only gained these in Home Assistant 2026.8. -- **Sensors.** Indoor and outdoor temperature, humidity and fault detection, when the unit has them. An external sensor can replace the unit's own room sensor in the climate entity. +- **The features on the remote.** X-Fan, Health, Sleep, 8ยฐC Smart Heat, Power Save, Anti Direct Blow, Fresh Air, Humidity Control, display light and brightness, beeper, Turbo and Quiet. Each one is a switch, select or fan mode. See [entities](docs/entities.md). +- **Swing positions.** Twelve vertical and seven horizontal modes: fixed positions and partial swing ranges, not just on and off. +- **Sensors.** Indoor and outdoor temperature, humidity and fault detection, when the unit has them. An external sensor can replace the unit's own reading in the climate entity. That changes only what Home Assistant shows; the unit keeps using its own sensor. - **Works across VLANs.** Add networks or hosts to the discovery, and they are probed with unicast. See [local discovery](docs/configuration.md#local-discovery). - **VRF systems.** A controller with several indoor units is discovered and set up as separate devices. - **Built for real firmware.** Both encryption versions, detected by itself. The request limit of each firmware is measured at bind time, so units that choke on large requests still work. A changed IP is picked up from DHCP or by rediscovery. @@ -61,19 +61,12 @@ Your devices are under **Settings** > **Devices & Services** > **Gree Climate**. ๐Ÿ“– **[Full installation guide](docs/installation.md)** ยท **[Full configuration guide](docs/configuration.md)** -## โš ๏ธ Issues - -Due to the many issues being created revolving "TimeOut"/"Cannot connect" errors, I will be closing these. Feel free to make a PR fixing your TimeOut/Cannot connect error. -More information on the "why" can be found here: https://github.com/RobHofmann/HomeAssistant-GreeClimateComponent/issues/405#issuecomment-4300110823 - -Before you open any other issue, read [Troubleshooting](docs/troubleshooting.md). It says what to include. - ## โ“ Help and support - ๐Ÿ”ง **[Troubleshooting](docs/troubleshooting.md)**: debug logging, repair issues, common errors, and how to report a bug - ๐Ÿ”‘ **[Encryption key](docs/encryption-key.md)**: when the integration cannot get the device key by itself - ๐Ÿ“‹ **[Supported devices](supported-devices.md)**: units that are known to work, and how to add yours -- ๐Ÿ› **[Report an issue](https://github.com/RobHofmann/HomeAssistant-GreeClimateComponent/issues/new/choose)**: read the Issues section above first +- ๐Ÿ› **[Report an issue](https://github.com/RobHofmann/HomeAssistant-GreeClimateComponent/issues/new/choose)**: read [Troubleshooting](docs/troubleshooting.md) first, it says what to include ## ๐Ÿค Contributing diff --git a/docs/automation-examples.md b/docs/automation-examples.md index eb802ce..528171b 100644 --- a/docs/automation-examples.md +++ b/docs/automation-examples.md @@ -1,6 +1,6 @@ # Automation examples -Ideas for automations with the entities of this integration. The examples use a device named **Living Room AC** in an English Home Assistant, so the entity IDs start with `living_room_ac`. Home Assistant builds an entity ID from the device name and the translated entity name, so in another language the IDs differ. Copy them from the device page. See [entities.md](entities.md) for the full list. +Ideas for automations with the entities of this integration. The examples use a device named **Living Room AC** in an English Home Assistant, with the entity IDs Home Assistant gives by default. Your IDs can differ: Home Assistant builds them from the device name and your language, and you may have renamed them. Copy them from the device page. See [entities.md](entities.md) for the full list. All examples use the automation syntax of Home Assistant 2024.10 and later, which every supported version has. diff --git a/docs/configuration.md b/docs/configuration.md index ae3ac4f..b421821 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -22,7 +22,9 @@ Shown when you picked the cloud method. | Email, Password | Your Gree account. | | Region | The region of your account. The integration uses it to pick the right Gree server. | -Every login ends the other sessions of the account, so the Gree app on your phone logs out. The integration stores the session and does not log in again on every restart. +The login returns a session token. The integration stores the token in the config entry and uses it every time the entry loads. A restart or a reload does not log in again. Only when the stored token stops working does the entry ask for [reauthentication](#reauthentication), which logs in once more and stores the new token. + +This matters because Gree allows one session per account. Every login ends the other sessions, so the Gree app on your phone logs out at that moment. A YAML entry works the same way: a matching entry keeps its token, and a changed email, region or password triggers a new login. ### Local discovery @@ -41,7 +43,10 @@ The values you enter are remembered and offered again in the next setup flow. ### Discovered devices -The list holds every device that was found and is not configured yet. Pick the ones to add. When you are reconfiguring, the devices you do not pick are removed from the entry. +The list holds every device that was found and is not configured yet. Pick the ones to add. + +> [!WARNING] +> When you are reconfiguring, the devices you do not pick are removed from the entry. With a cloud account, the list holds the devices of the account. It shows whether each one was also found on the local network. @@ -80,7 +85,7 @@ One page per device. Gree devices do not report reliably which features they hav | Field | Default | Meaning | |---|---|---| -| Device Name | the name the unit reports | Used for the device and as the start of every entity ID. | +| Device Name | the name the unit reports | The name of the device in Home Assistant. By default Home Assistant also uses it in the entity IDs. | | HVAC Modes | all | The modes the climate entity offers: Auto, Cool, Dry, Fan only, Heat, Off. | | Fan Speeds | all the unit supports | Auto, Low, Medium-Low, Medium, Medium-High, High, and Turbo and Quiet when the unit has them. | | Vertical Swing Modes | all | The vertical positions and swing ranges. | @@ -99,7 +104,9 @@ Open the entry under **Settings** > **Devices & Services**, click the three dots - On the **Local-only Devices** entry the flow starts at local discovery. - On an account entry the flow first asks whether to also look for local devices. The account itself cannot be removed from the entry. To make a device local-only, remove it from the account entry and add it again with the local method. -- Devices you do not pick in the device list are removed from the entry. + +> [!WARNING] +> Devices you do not pick in the device list are removed from the entry. ## Removing a device diff --git a/docs/entities.md b/docs/entities.md index da4bf0f..751bd41 100644 --- a/docs/entities.md +++ b/docs/entities.md @@ -6,7 +6,7 @@ Every device gets one climate entity and a set of sensors, switches, selects and 2. **What you enabled.** The **Device Features and Modes** option decides which optional switches and selects are created. See [configuration.md](configuration.md#device-features). 3. **The current mode.** Some features only exist in some HVAC modes. The entity then shows as unavailable in the other modes. -Entity IDs start with the device name, followed by the entity name in the language of your Home Assistant. In English, a device named `Living Room AC` gets `climate.living_room_ac`, `sensor.living_room_ac_indoor_temperature`, `switch.living_room_ac_x_fan`, and so on. A Dutch Home Assistant gives `switch.living_room_ac_pieptoon` for the beeper. Copy the IDs from the device page. The examples below use `climate.your_ac`. +Home Assistant chooses the entity IDs, not the integration. By default it builds them from the device name and the translated entity name. A device named `Living Room AC` in an English Home Assistant then gets `climate.living_room_ac` and `switch.living_room_ac_x_fan`. That default depends on your language and on your Home Assistant version, and you can change any ID yourself. Copy the IDs from the device page instead of guessing them. The examples below use `climate.your_ac`. ## Climate @@ -16,8 +16,8 @@ The main entity. Its name is the device name. |---|---| | HVAC mode | Auto, Cool, Dry, Fan only, Heat, Off. You choose the list at setup. Off turns the unit off, every other mode turns it on. | | Target temperature | 16 to 30 degrees C, or 61 to 86 degrees F. Available when Heat, Cool or Auto is in the mode list. The step is the **Temperature Step** option. In Auto mode the unit uses its own factory setting, so a temperature sent with Auto is ignored and logged as a warning. | -| Current temperature | The unit's room sensor, converted to the unit's temperature scale. Replaced by the **External Temperature Sensor** when one is set. | -| Current humidity | The unit's humidity sensor, when it has one. Replaced by the **External Humidity Sensor** when one is set. | +| Current temperature | The unit's room sensor, converted to the unit's temperature scale. Replaced by the **External Temperature Sensor** when one is set. That changes only what Home Assistant shows; the unit keeps regulating on its own sensor. | +| Current humidity | The unit's humidity sensor, when it has one. Replaced by the **External Humidity Sensor** when one is set. Display only, like the temperature. | | Fan mode | Auto, Low, Medium-Low, Medium, Medium-High, High, plus Turbo and Quiet when the unit has them. See below. | | Swing mode | Vertical positions and swing ranges. | | Horizontal swing mode | Horizontal positions and swing ranges, when the unit has them. | diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 93a6024..6e0d35b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2,10 +2,7 @@ ## Time out and cannot connect errors -Due to the many issues being created revolving "TimeOut"/"Cannot connect" errors, I will be closing these. Feel free to make a PR fixing your TimeOut/Cannot connect error. -More information on the "why" can be found here: https://github.com/RobHofmann/HomeAssistant-GreeClimateComponent/issues/405#issuecomment-4300110823 - -In short: a time out means the device did not answer a UDP packet. In almost every case the cause is in the network or on the device, not in the integration. The checks below find most of them. +A time out means the device did not answer a UDP packet. In almost every case the cause is in the network or on the device, not in the integration. The checks below find most of them. 1. **Can Home Assistant reach the device?** Ping the IP from the Home Assistant host. A device that does not answer a ping is asleep, on another network, or has a new IP. 2. **Is UDP port 7000 open on the way?** Devices on another VLAN need a firewall rule that allows UDP 7000 from Home Assistant to the device. See [Local discovery](configuration.md#local-discovery). @@ -62,13 +59,13 @@ The integration raises repair issues under **Settings** > **System** > **Repairs **The unit ignores Turbo or Quiet.** The unit does that while Power Save or Smart Heat 8ยฐC is on. Turn those off first. -**A feature I expect is missing.** The device did not answer the property behind it at setup, or the feature is not enabled. Reconfigure the entry and check **Device Features and Modes**. Use the `get_prop_values` action to see what the device answers. See [actions.md](actions.md). +**A feature I expect is missing.** The device did not answer the property behind it at setup, or the feature is not enabled. Reconfigure the entry and check **Device Features and Modes**. Use the `get_prop_values` action to see what the device answers. See [actions.md](actions.md). If the device answers the property but the integration has no entity for it, open an issue. We may need to add it. **The unit shows only default values, or every entity has the same value after every restart.** Some firmwares refuse a status request with too many columns. The integration measures the limit right after it binds and stays below it, so this should not happen. If it does, run `tools/probe_status_limit.py --host ` from a checkout of the repo. Attach the output to an issue. See [development.md](development.md#tools). **Changes made in the UI are undone after a restart.** The entry is managed by the `gree_custom:` block in `configuration.yaml`. The YAML wins at every start. Change the YAML instead, or remove the block to manage the entry in the UI. See [YAML configuration](configuration.md#yaml-configuration). -**The Gree app logs me out.** Gree allows one session per account. Every login by the integration ends the app session. The integration logs in at setup, when the cloud block in the YAML changes, and when you reauthenticate. Not at every restart. +**The Gree app logs me out.** Gree allows one session per account, and every login by the integration ends the app session. The integration logs in only when it has no session token yet. That is at the first setup of an account, at a YAML import with new account details, and at reauthentication. Loading or reloading the entry uses the stored token. See [Gree account](configuration.md#gree-account). **The device is on another VLAN and is not found.** Broadcasts do not cross VLANs. Add the network or the IP under **Extra Networks** or **Extra Hosts**, and allow UDP 7000 in the firewall. @@ -76,7 +73,7 @@ The integration raises repair issues under **Settings** > **System** > **Repairs ## How to report a bug -Time out and cannot connect reports are closed, see the top of this page. For everything else, open an issue with: +Run the checks under [Time out and cannot connect errors](#time-out-and-cannot-connect-errors) first. Then open an issue with: 1. The device brand, model and firmware version. The firmware is on the device page in Home Assistant. 2. The Home Assistant version and the integration version, from HACS or `manifest.json`.