RobHofmann · p-monteiro · Sep 16, 2025 · Sep 16, 2025 · Sep 16, 2025 · Sep 17, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,41 @@
+# Contributing
+
+This integration follows the development guidelines for Home Assistant integrations, while keeping the repository compatible with HACS.
+
+## Development Environment
+
+Home Assistant provides [several guidelines](https://developers.home-assistant.io/docs/development_environment) regarding the setup of the development environment. Because we are not contributing to the official integrations, there is no need to fork the official [Home Assistant Core](https://github.com/home-assistant/core) repository. However, it is useful to use it as it provides a preconfigured VSCode development environment with the necessary tools.
+
+Here's a general guide to get it working with this integration repository:
+
+1. Create a folder for the development (for example `development/`)
+2. Clone [home-assistant/core ](https://github.com/home-assistant/core) inside of it (`development/core`)
+3. Follow the [guidelines](https://developers.home-assistant.io/docs/development_environment) on getting the devcontainer working
+4. Fork [this](https://github.com/RobHofmann/HomeAssistant-GreeClimateComponent) repository and clone your fork inside of the same folder (`development/YourForkName`)
+5. Create a branch for your changes in the cloned repo `git checkout -b my-branch-name`
+6. Create a mount point for this integration in the devcontainer
+    1. Open `development/core/devcontainer/devcontainer.json`
+    2. Add the mounting:
+	```json
+		"mounts": [
+			"source=${localWorkspaceFolder}/../YourForkName/custom_components/gree_custom,target=/workspaces/core/config/custom_components/gree_custom,type=bind"
+		],
+	```
+7. Open `development/core` with VSCode
+8. Use the command **"Dev Containers: Reopen in Container"**
+9. Once inside the container make sure the folder `config/custom_components/gree_custom` exists
+10. You should be now be able to edit the integration files from inside the devcontainer
+11. Make your changes
+12. Push to your fork, rebase with the latest upstream version and submit a pull request
+
+## Testing
+
+Use the **Run Home Assistant Core** Task to start Home Assistant.
+
+You should also be able to set and hit breakpoints in your code.
+
+If you change your code, you have to restart Home Assistant (rerun the Task)
+
+## Styling
+
+Please adhere to the recomended coding style: https://developers.home-assistant.io/docs/development_guidelines
diff --git a/LICENSE b/LICENSE
@@ -1,7 +1,7 @@
                     GNU GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 
- Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
@@ -645,7 +645,7 @@ the "copyright" line and a pointer to where the full notice is found.
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 Also add information on how to contact you by electronic and paper mail.
 
@@ -664,11 +664,11 @@ might be different; for a GUI interface, you would use an "about box".
   You should also get your employer (if you work as a programmer) or school,
 if any, to sign a "copyright disclaimer" for the program, if necessary.
 For more information on this, and how to apply and follow the GNU GPL, see
-<http://www.gnu.org/licenses/>.
+<https://www.gnu.org/licenses/>.
 
   The GNU General Public License does not permit incorporating your program
 into proprietary programs.  If your program is a subroutine library, you
 may consider it more useful to permit linking proprietary applications with
 the library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.  But first, please read
-<http://www.gnu.org/philosophy/why-not-lgpl.html>.
+<https://www.gnu.org/licenses/why-not-lgpl.html>.
diff --git a/README.md b/README.md
@@ -1,47 +1,59 @@
-[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg?style=for-the-badge)](https://github.com/hacs/integration)
+[![HACS](https://img.shields.io/badge/HACS-Default-orange.svg)](https://hacs.xyz)
+[![Home Assistant](https://img.shields.io/badge/Compatible-Home_Assistant_2025.9.4-blue.svg)](https://www.home-assistant.io)
 
 # HomeAssistant-GreeClimateComponent
-Custom Gree climate component written in Python3 for Home Assistant. Controls ACs supporting the Gree protocol.
 
-For a comprehensive list of tested devices, see [Supported Devices](supported-devices.md).
-
-Tested on Home Assistant 2025.6.3 
-
-**If you are experiencing issues please be sure to provide details about your device, Home Assistant version and what exactly went wrong.**
+Custom Gree inetgration for Home Assistant written in Python3. Controls ACs supporting the Gree protocol.
 
 This integration connects directly to your HVAC devices via their IP address on the local network, unlike the official mobile app, which establish a direct connection only during initial setup and subsequently operate through Gree’s servers.
+
 The integration attempts to obtain the encryption key by the initial setup protocol, which has been reverse-engineered.
 
+> [!WARNING]
+> If your HVAC device was previously set up for remote access using a mobile app, the integration may fail to retrieve the encryption key automatically. Find out more on methods of obtaining your device key bellow.
+
+
+For a comprehensive list of tested devices, see [Supported Devices](supported-devices.md).
+
+**If you are experiencing issues please read the [Debugging](#debugging) section**
+
+
 Official mobile applications:
 - [Gree+ Android App](https://play.google.com/store/apps/details?id=com.gree.greeplus)
 - [Gree+ iOS App](https://apps.apple.com/app/gree/id1167857672)
 - [EWPE Smart Android App](https://play.google.com/store/apps/details?id=com.gree.ewpesmart)
 - [EWPE Smart iOS App](https://apps.apple.com/app/ewpe-smart/id1189467454)
 
-If your HVAC device was previously set up for remote access using a mobile app, the integration may fail to retrieve the encryption key automatically.
+To configure HVAC wifi (without the mobile app): https://github.com/arthurkrupa/gree-hvac-mqtt-bridge#configuring-hvac-wifi
 
-To extract encryption keys from an account on Gree’s cloud server: https://github.com/luc10/gree-api-client
 
-To configure HVAC wifi (without the mobile app): https://github.com/arthurkrupa/gree-hvac-mqtt-bridge#configuring-hvac-wifi
+## Installation
+
+### HACS (recommended)
+
+This integration is added to HACS default repository list. Search for 'Gree' in the HACS dashboard to find and install it.
+
+### Manual
 
-## HACS
-This component is added to HACS default repository list.
+Copy the `custom_components` folder to your own hassio `/config` folder.
+
+
+## Configuration
+
+### UI Configuration - Config Flow (recommended)
 
-## Config Flow - UI Configuration (recommended)
 The integration can be added from the Home Assistant UI.
-1. Navigate to **Settings** > **Devices & Services** and click **Add Integration**.
-2. Search for **Gree Climate** and fill in the desired `name`, `host`, `port` and `MAC address`.
-3. After setup you can open the integration options to configure additional parameters.
-4. Saving any changes in the options dialog automatically reloads the
-   integration, so new settings take effect immediately without
-   restarting Home Assistant.
 
-## Manual Installation
+1. Navigate to **Settings** > **Devices & Services** and click **Add Integration**.
+2. Search for **Gree Climate**
+3. Choose automatic discovery or manual setup and fill in the desired `name`, `host` and `MAC address`.
+4. After a successfull connection with the device, you will be asked to configure the device options.
 
+Your can also **Reconfigure** a device by changing its options. Saving any changes in the options dialog automatically reloads the integration, so new settings take effect immediately without restarting Home Assistant.
 
-1. *(Skip if using HACS)* Copy the `custom_components` folder to your own hassio `/config` folder.
+### Manual - YAML Configuration
 
-2. **YAML Configuration:** See [`manual-configuration.yaml`](manual-configuration.yaml) for a complete configuration example with all available options and detailed comments.
+See [`manual-configuration.yaml`](manual-configuration.yaml) for a complete configuration example with all available options and detailed comments.
 
    Basic example:
    ```yaml
@@ -52,41 +64,49 @@ The integration can be added from the Home Assistant UI.
        encryption_version: 2
    ```
 
-3. In your configuration.yaml add the following:
+### Obtaining the Encryption Key
 
-   ```yaml
-   climate: !include your_configuration.yaml
-   ```
+The integration has the capability of automatically retrieve the encryption version and key of a device using the gree protocol which has been reverse-engineered.
 
-4. *(Optional)* Add info logging to this component (to see if/how it works)
+However, if your HVAC device was previously set up for remote access using a mobile app, the integration may fail to retrieve the encryption key automatically.
 
-   ```yaml
-   logger:
-     default: error
-     logs:
-       custom_components.gree: debug
-       custom_components.gree.climate: debug
-   ```
+#### Method 1: From Gree's cloud server
 
-5. *(Optional)* Provide encryption key if you have it or feel like extracting it.
+To extract encryption keys from an account on Gree’s cloud server, follow the instructions in https://github.com/luc10/gree-api-client
 
-   One way is to pull the sqlite db from android device like described here:
+#### Method 2: From the Android app
 
-   https://stackoverflow.com/questions/9997976/android-pulling-sqlite-database-android-device
+One way is to pull the sqlite db from android device like described here:
 
-   ```bash
-   adb backup -f ~/backup.ab -noapk com.gree.ewpesmart
-   dd if=data.ab bs=1 skip=24 | python -c "import zlib,sys;sys.stdout.write(zlib.decompress(sys.stdin.read()))" | tar -xvf -
-   sqlite3 data.ab 'select privateKey from db_device_20170503;' # but table name can differ a little bit.
-   ```
+https://stackoverflow.com/questions/9997976/android-pulling-sqlite-database-android-device
+
+```bash
+adb backup -f ~/backup.ab -noapk com.gree.ewpesmart
+dd if=data.ab bs=1 skip=24 | python -c "import zlib,sys;sys.stdout.write(zlib.decompress(sys.stdin.read()))" | tar -xvf -
+sqlite3 data.ab 'select privateKey from db_device_20170503;' # but table name can differ a little bit.
+```
+
+> [!TIP]
+> If you are getting an UTF-8  error (like: "UnicodeDecodeError: 'utf-8' codec can't decode byte 0xda in position 1: invalid continuation byte"), see https://github.com/RobHofmann/HomeAssistant-GreeClimateComponent/issues/318.
+
+Optionally, you can also sniff the `uid` parameter. This is not needed for all devices.
+
+### Icon configuration
+
+You can set custom icons for the climate enity by modifying the icon translation file `icons.json`. Refer to this documentation: https://developers.home-assistant.io/docs/core/integration-quality-scale/rules/icon-translations/
 
-   Write it down in `climate.yaml`: `encryption_key: <key>`.
+## Debugging
 
-   > If you are getting an UTF-8  error (like: "UnicodeDecodeError: 'utf-8' codec can't decode byte 0xda in position 1: invalid continuation byte"), see https://github.com/RobHofmann/HomeAssistant-GreeClimateComponent/issues/318.
+If you are having problems with your device, whenever you write a bug report, be sure to provide details about your device, Home Assistant version and what exactly went wrong.
 
-6. *(Optional)* Provide the `uid` parameter (can be sniffed). This is not needed for all devices.
+It also helps tremendously if you include debug logs directly in your issue (otherwise we will just ask for them and it will take longer). So please enable debug logs in the integration UI or like this:
 
-7. *(Optional)* You can set custom icons by modifying the icon translation file `icons.json`. Refer to this documentation: https://developers.home-assistant.io/docs/core/integration-quality-scale/rules/icon-translations/
+```yaml
+logger:
+   default: error
+   logs:
+      custom_components.gree_custom: debug
+```
 
 ## Additional Sensors
 

diff --git a/custom_components/gree/__init__.py b/custom_components/gree/__init__.py