From b78b0407a067f60ed978b6a1089847063554fc33 Mon Sep 17 00:00:00 2001 From: Johan Zander Date: Fri, 7 Nov 2025 15:57:31 +0100 Subject: [PATCH 1/3] Improve Growatt Server documentation for bronze tier compliance - Add removal instructions section (required for bronze tier) - Add troubleshooting section with common issues and solutions - Account lockout and terms acceptance in ShinePhone app - Rate limiting workarounds - HA restart prevention tips - Add known limitations section documenting rate limiting - Improve clarity: change "sensor logs into" to "integration connects to" - Use "entities" instead of just "sensors" for better accuracy - Fix markdown linter warnings by wrapping bare URLs in backticks --- source/_integrations/growatt_server.markdown | 41 +++++++++++++++++--- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/source/_integrations/growatt_server.markdown b/source/_integrations/growatt_server.markdown index 85798f4e9a17..8a56066edd93 100644 --- a/source/_integrations/growatt_server.markdown +++ b/source/_integrations/growatt_server.markdown @@ -19,14 +19,14 @@ ha_codeowners: The Growatt integration allows you to retrieve data from Growatt inverters. During setup, you can choose from various regional endpoint servers: -- For users in China: https://openapi-cn.growatt.com/ -- For users in North America: https://openapi-us.growatt.com/ -- For users in other regions: https://openapi.growatt.com/ -- SMTEN server: http://server.smten.com/ +- For users in China: `https://openapi-cn.growatt.com/` +- For users in North America: `https://openapi-us.growatt.com/` +- For users in other regions: `https://openapi.growatt.com/` +- SMTEN server: `http://server.smten.com/` Selecting the appropriate server for your region improves the reliability and performance of data collection. -Once integrated, the sensor logs into your Growatt account and retrieves your plants. If you have multiple plants, you can select which one to integrate. The integration then retrieves the inverters associated with the selected plant and generates sensors for these inverters, as well as overall plant sensors. +Once configured, the integration connects to your Growatt account. If you have multiple plants, you can select which one to integrate. It will then create entities for your plant and inverters, allowing you to monitor energy production and control settings in Home Assistant. ## Authentication @@ -53,6 +53,15 @@ Using an API token is recommended for MIN/TLX inverters as it uses the official {% include integrations/config_flow.md %} +## Known limitations + +### Rate limiting with username/password authentication + +The classic API (username/password authentication) has strict rate limits that can result in your account being locked out for up to 24 hours if exceeded. To avoid this issue: + +- **For MIN/TLX inverter users**: Use API token authentication instead, which uses the official Growatt V1 API that does not have this limitation. +- **For all other users**: Avoid all unnecessary integration reloads, as a reload triggers re-login via Growatt classic API. + ## Inverter controls When using API token authentication with MIN/TLX inverters, the integration provides additional control entities: @@ -76,3 +85,25 @@ These controls directly modify your inverter's operational settings. Only change - **AC charge** - **Description**: Enable or disable AC charging + +## Troubleshooting + +### Account locked or authentication failing + +If you're experiencing authentication failures or account lockouts: + +1. **Accept new terms and conditions**: Open the ShinePhone mobile app and log in with your Growatt account. You may need to accept updated terms and conditions before the integration can access your account successfully. + +2. **Account locked due to rate limiting**: If you're using username/password authentication and your account has been locked due to rate limiting: + - Wait for the lockout period to expire (up to 24 hours). + - Consider switching to API token authentication if you have a MIN/TLX inverter. + - Avoid frequent integration reloads, which can trigger rate limits. + +3. **Prevent lockouts during Home Assistant restarts**: + - If you experience frequent lockouts, temporarily disable the integration before restarting Home Assistant. + - To disable: Go to {% my integrations title="**Settings** > **Devices & services**" %}, select the Growatt integration, click the three dots {% icon "mdi:dots-vertical" %} menu, and select **Disable**. + - Re-enable after Home Assistant has fully restarted. + +## Removing the integration + +{% include integrations/remove_device_service.md %} From 8d0ef2d72aad227614141642ad5bbc4b26e64182 Mon Sep 17 00:00:00 2001 From: Johan Zander Date: Fri, 7 Nov 2025 16:15:15 +0100 Subject: [PATCH 2/3] small fix to documentation for Growatt integration --- source/_integrations/growatt_server.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/growatt_server.markdown b/source/_integrations/growatt_server.markdown index 8a56066edd93..13aa20dc7484 100644 --- a/source/_integrations/growatt_server.markdown +++ b/source/_integrations/growatt_server.markdown @@ -17,7 +17,7 @@ ha_codeowners: - '@johanzander' --- -The Growatt integration allows you to retrieve data from Growatt inverters. During setup, you can choose from various regional endpoint servers: +The Growatt integration enables you to retrieve data from Growatt inverters. During setup, you can choose from various regional endpoint servers: - For users in China: `https://openapi-cn.growatt.com/` - For users in North America: `https://openapi-us.growatt.com/` @@ -44,7 +44,7 @@ To obtain an API token for your Growatt account: 3. Generate or retrieve your API token. 4. Use this token during the integration setup in Home Assistant. -Using an API token is recommended for MIN/TLX inverters as it uses the official Growatt V1 API, which offers better stability, support and feature growth. +Using an API token is recommended for MIN/TLX inverters as it uses the official Growatt API, which offers better stability, support and feature growth. ## Prerequisites From a3698f4a89c321337419586555f8d2f454f57cef Mon Sep 17 00:00:00 2001 From: Johan Zander Date: Sat, 8 Nov 2025 00:15:35 +0100 Subject: [PATCH 3/3] Format regional endpoint server URLs in Growatt integration documentation --- source/_integrations/growatt_server.markdown | 27 +++++++++++++++++--- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/source/_integrations/growatt_server.markdown b/source/_integrations/growatt_server.markdown index 13aa20dc7484..1235d991c46b 100644 --- a/source/_integrations/growatt_server.markdown +++ b/source/_integrations/growatt_server.markdown @@ -19,10 +19,29 @@ ha_codeowners: The Growatt integration enables you to retrieve data from Growatt inverters. During setup, you can choose from various regional endpoint servers: -- For users in China: `https://openapi-cn.growatt.com/` -- For users in North America: `https://openapi-us.growatt.com/` -- For users in other regions: `https://openapi.growatt.com/` -- SMTEN server: `http://server.smten.com/` +- For users in China: + + ```text + https://openapi-cn.growatt.com/ + ``` + +- For users in North America: + + ```text + https://openapi-us.growatt.com/ + ``` + +- For users in other regions: + + ```text + https://openapi.growatt.com/ + ``` + +- SMTEN server: + + ```text + http://server.smten.com/ + ``` Selecting the appropriate server for your region improves the reliability and performance of data collection.