Added Growatt OpenAPI V1 Support (#100)

Co-authored-by: indykoning <[email protected]>

Author: johanzander

README.md

@@ -5,8 +5,14 @@ Package to retrieve PV information from the growatt server.
 Special thanks to [Sjoerd Langkemper](https://github.com/Sjord) who has provided a strong base to start off from https://github.com/Sjord/growatt_api_client
 These projects may merge in the future since they are simmilar in code and function.
 
+This library now supports both the legacy password-based authentication and the V1 API with token-based authentication for MIN systems (TLX are identified as MIN system in the public API). Certain endpoints are not supported anymore by openapi.growatt.com. For example `api.min_write_parameter()` should be used instead of old `api.update_tlx_inverter_setting()`.
+
 ## Usage
 
+### Legacy API
+
+Uses username/password basic authentication
+
 ```python
 import growattServer
 
@@ -16,16 +22,39 @@ login_response = api.login(<username>, <password>)
 print(api.plant_list(login_response['user']['id']))
 ```
 
+### V1 API
+
+The public v1 API requires token-based authentication
+
+```python
+import growattServer
+
+api = growattServer.OpenApiV1(token="YOUR_API_TOKEN")
+#Get a list of growatt plants.
+plants = api.plant_list_v1()
+print(plants)
+```
+
 ## Methods and Variables
 
 ### Methods
 
 Any methods that may be useful.
 
-`api.login(username, password)` Log into the growatt API. This must be done before making any request. After this you will be logged in. You will want to capture the response to get the `userId` variable.
+#### Legacy API Methods
+
+`api.login(username, password)` Log into the growatt API. This must be done before making any request. After this you will be logged in. You will want to capture the response to get the `userId` variable. Should not be used for public v1 APIs.
 
 `api.plant_list(user_id)` Get a list of plants registered to your account.
 
+`api.plant_list_v1()` Get a list of plants registered to your account, using public v1 API.
+
+`api.plant_details_v1(plant_id)` Get detailed information about a power station, using public v1 API.
+
+`api.plant_energy_overview_v1(plant_id)` Get energy overview data for a plant, using public v1 API.
+
+`api.plant_energy_history_v1(plant_id, start_date, end_date, time_unit, page, perpage)` Get historical energy data for a plant for multiple days/months/years, using public v1 API.
+
 `api.plant_info(plant_id)` Get info for specified plant.
 
 `api.plant_settings(plant_id)` Get the current settings for the specified plant
@@ -38,6 +67,8 @@ Any methods that may be useful.
 
 `api.device_list(plant_id)` Get a list of devices in specified plant.
 
+`api.device_list_v1(plant_id)` Get a list of devices in specified plant using the public v1 API.
+
 `api.inverter_data(inverter_id, date)` Get some basic data of a specific date for the inverter.
 
 `api.inverter_detail(inverter_id)` Get detailed data on inverter.
@@ -96,6 +127,34 @@ Any methods that may be useful.
 
 `api.update_noah_settings(serial_number, setting_type, parameters)` Applies the provided parameters (dictionary or array) for the specified setting on the specified noah device; see 'Noah settings' below for more information
 
+#### V1 API Methods
+
+`api.plant_list()` Get a list of plants registered to your account, using public v1 API.
+
+`api.plant_details(plant_id)` Get detailed information about a power station, using public v1 API.
+
+`api.plant_energy_overview(plant_id)` Get energy overview data for a plant, using public v1 API.
+
+`api.plant_energy_history(plant_id, start_date, end_date, time_unit, page, perpage)` Get historical energy data for a plant for multiple days/months/years, using public v1 API.
+
+`api.device_list(plant_id)` Get a list of devices in specified plant using the public v1 API.
+
+`api.min_energy(device_sn)` Get current energy data for a min inverter, including power and energy values.
+
+`api.min_detail(device_sn)` Get detailed data for a min inverter.
+
+`api.min_energy_history(device_sn, start_date=None, end_date=None, timezone=None, page=None, limit=None)` Get energy history data for a min inverter (7-day max range).
+
+`api.min_settings(device_sn)` Get all settings for a min inverter.
+
+`api.min_read_parameter(device_sn, parameter_id, start_address=None, end_address=None)` Read a specific setting for a min inverter.
+
+`api.min_write_parameter(device_sn, parameter_id, parameter_values)` Set parameters on a min inverter. Parameter values can be a single value, a list, or a dictionary.
+
+`api.min_write_time_segment(device_sn, segment_id, batt_mode, start_time, end_time, enabled=True)` Update a specific time segment for a min inverter.
+
+`api.min_read_time_segments(device_sn, settings_data=None)` Read all time segments from a MIN inverter. Optionally pass settings_data to avoid redundant API calls.
+
 ### Variables
 
 Some variables you may want to set.
@@ -118,6 +177,8 @@ The library can be initialised to introduce randomness into the User Agent field
 
 This has been added since the Growatt servers started checking for the presence of a `User-Agent` field in the headers that are sent.
 
+#### Legacy API Initialization
+
 By default the library will use a pre-set `User-Agent` value which identifies this library while also appearing like an Android device. However, it is also possible to pass in parameters to the intialisation of the library to override this entirely, or just add a random ID to the value. e.g.
 
 ```python
@@ -128,6 +189,12 @@ api = growattServer.GrowattApi(True) # Adds a randomly generated User ID to the
 api = growattServer.GrowattApi(False, "my_user_agent_value") # Overrides the default and uses "my_user_agent_value" in the User-Agent header
 ```
 
+#### V1 API Initialization
+
+```python
+api = growattServer.GrowattApiV1(token="YOUR_API_TOKEN") # Initialize with your API token
+```
+
 Please see the `user_agent_options.py` example in the `examples` directory if you wish to investigate further.
 
 ## Examples
@@ -240,6 +307,40 @@ The four functions `update_tlx_inverter_setting`, `update_mix_inverter_setting`,
 
 Only the settings described above have been tested with `update_tlx_inverter_setting` and they all take only one single parameter. It is very likely that the function works with all settings returned by `tlx_get_enabled_settings`, but this has not been tested. A helper function `update_tlx_inverter_time_segment` is provided for the settings that require more than one parameter.
 
+## MIN/TLX Inverter Settings Using V1 API
+
+For MIN/TLX systems, the public V1 API provides a more robust way to read and write inverter settings:
+
+* **Read Parameter**
+  * function: `api.min_read_parameter`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `parameter_id`: Parameter ID to read (e.g., "discharge_power")
+    * `start_address`, `end_address`: Optional, for reading registers by address
+
+* **Write Parameter**
+  * function: `api.min_write_parameter`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `parameter_id`: Parameter ID to write (e.g., "ac_charge")
+    * `parameter_values`: Value to set (single value, list, or dictionary)
+
+* **Time Segments**
+  * function: `api.min_write_time_segment`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `segment_id`: Segment number (1-9)
+    * `batt_mode`: Battery mode (0=Load First, 1=Battery First, 2=Grid First)
+    * `start_time`: Datetime.time object for segment start
+    * `end_time`: Datetime.time object for segment end
+    * `enabled`: Boolean to enable/disable segment
+
+* **Read Time Segments**
+  * function: `api.min_read_time_segments`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `settings_data`: Optional settings data to avoid redundant API calls
+
 ## Noah Settings
 The noah settings function allow you to change individual values on your noah system e.g. system default output power, battery management, operation mode and currency
 From what has been reverse engineered from the api, each setting has a `setting_type` and a set of `parameters` that are relevant to it.
@@ -287,4 +388,4 @@ The library contains functions that allow you to modify the configuration of you
 
 To the best of our knowledge only the `settings` functions perform modifications to your system and all other operations are read only. Regardless of the operation:
 
-***The library is used entirely at your own risk.***
+***The library is used entirely at your own risk.***

examples/min_example.py

@@ -0,0 +1,93 @@
+import growattServer
+import datetime
+import json
+import requests
+
+"""
+# Example script controlling a MID/TLX Growatt (MID-30KTL3-XH + APX battery) system using the public growatt API 
+# You can obtain an API token from the Growatt API documentation or developer portal.
+"""
+
+# Get the API token from user input or environment variable
+# api_token = os.environ.get("GROWATT_API_TOKEN") or input("Enter your Growatt API token: ")
+
+# test token from official API docs https://www.showdoc.com.cn/262556420217021/1494053950115877
+api_token = "6eb6f069523055a339d71e5b1f6c88cc"  # gitleaks:allow
+
+try:
+    # Initialize the API with token instead of using login
+    api = growattServer.OpenApiV1(token=api_token)
+
+    # Plant info
+    plants = api.plant_list()
+    print(f"Plants: Found {plants['count']} plants")
+    plant_id = plants['plants'][0]['plant_id']
+
+    # Devices
+    devices = api.device_list(plant_id)
+
+    for device in devices['devices']:
+        if device['type'] == 7:  # (MIN/TLX)
+            inverter_sn = device['device_sn']
+            print(f"Processing inverter: {inverter_sn}")
+
+            # Get device details
+            inverter_data = api.min_detail(inverter_sn)
+            print("Saving inverter data to inverter_data.json")
+            with open('inverter_data.json', 'w') as f:
+                json.dump(inverter_data, f, indent=4, sort_keys=True)
+
+            # Get energy data
+            energy_data = api.min_energy(device_sn=inverter_sn)
+            print("Saving energy data to energy_data.json")
+            with open('energy_data.json', 'w') as f:
+                json.dump(energy_data, f, indent=4, sort_keys=True)
+
+            # Get energy history
+            energy_history_data = api.min_energy_history(inverter_sn)
+            print("Saving energy history data to energy_history.json")
+            with open('energy_history.json', 'w') as f:
+                json.dump(energy_history_data['datas'],
+                          f, indent=4, sort_keys=True)
+
+            # Get settings
+            settings_data = api.min_settings(device_sn=inverter_sn)
+            print("Saving settings data to settings_data.json")
+            with open('settings_data.json', 'w') as f:
+                json.dump(settings_data, f, indent=4, sort_keys=True)
+
+            # Read time segments
+            tou = api.min_read_time_segments(inverter_sn, settings_data)
+            print(json.dumps(tou, indent=4))
+
+            # Read discharge power
+            discharge_power = api.min_read_parameter(
+                inverter_sn, 'discharge_power')
+            print("Current discharge power:", discharge_power, "%")
+
+            # Settings parameters - Uncomment to test
+
+            # Turn on AC charging
+#            api.min_write_parameter(inverter_sn, 'ac_charge', 1)
+#            print("AC charging enabled successfully")
+
+            # Enable Load First between 00:00 and 11:59 using time segment 1
+#            api.min_write_time_segment(
+#                device_sn=inverter_sn,
+#                segment_id=1,
+#                batt_mode=growattServer.BATT_MODE_BATTERY_FIRST,
+#                start_time=datetime.time(0, 0),
+#                end_time=datetime.time(00, 59),
+#                enabled=True
+#            )
+#            print("Time segment updated successfully")
+
+
+except growattServer.GrowattV1ApiError as e:
+    print(f"API Error: {e} (Code: {e.error_code}, Message: {e.error_msg})")
+except growattServer.GrowattParameterError as e:
+    print(f"Parameter Error: {e}")
+except requests.exceptions.RequestException as e:
+    print(f"Network Error: {e}")
+except Exception as e:
+    print(f"Unexpected error: {e}")

examples/min_example_dashboard.py

@@ -0,0 +1,95 @@
+import growattServer
+import json
+import requests
+
+"""
+Example script fetching key power and today+total energy metrics from a Growatt MID-30KTL3-XH (TLX) + APX battery hybrid system
+using the V1 API with token-based authentication.
+"""
+
+# Get the API token from user input or environment variable
+# api_token = os.environ.get("GROWATT_API_TOKEN") or input("Enter your Growatt API token: ")
+
+# test token from official API docs https://www.showdoc.com.cn/262556420217021/1494053950115877
+api_token = "6eb6f069523055a339d71e5b1f6c88cc"  # gitleaks:allow
+
+try:
+    # Initialize the API with token
+    api = growattServer.OpenApiV1(token=api_token)
+
+    # Get plant list using V1 API
+    plants = api.plant_list()
+    plant_id = plants['plants'][0]['plant_id']
+
+    # Get devices in plant
+    devices = api.device_list(plant_id)
+
+    # Iterate over all devices
+    energy_data = None
+    for device in devices['devices']:
+        if device['type'] == 7:  # (MIN/TLX)
+            inverter_sn = device['device_sn']
+
+            # Get energy data
+            energy_data = api.min_energy(device_sn=inverter_sn)
+            with open('energy_data.json', 'w') as f:
+                json.dump(energy_data, f, indent=4, sort_keys=True)
+
+    # energy data does not contain epvToday for some reason, so we need to calculate it
+    epv_today = energy_data["epv1Today"] + energy_data["epv2Today"]
+
+    solar_production = f'{float(epv_today):.1f}/{float(energy_data["epvTotal"]):.1f}'
+    solar_production_pv1 = f'{float(energy_data["epv1Today"]):.1f}/{float(energy_data["epv1Total"]):.1f}'
+    solar_production_pv2 = f'{float(energy_data["epv2Today"]):.1f}/{float(energy_data["epv2Total"]):.1f}'
+    energy_output = f'{float(energy_data["eacToday"]):.1f}/{float(energy_data["eacTotal"]):.1f}'
+    system_production = f'{float(energy_data["esystemToday"]):.1f}/{float(energy_data["esystemTotal"]):.1f}'
+    battery_charged = f'{float(energy_data["echargeToday"]):.1f}/{float(energy_data["echargeTotal"]):.1f}'
+    battery_grid_charge = f'{float(energy_data["eacChargeToday"]):.1f}/{float(energy_data["eacChargeTotal"]):.1f}'
+    battery_discharged = f'{float(energy_data["edischargeToday"]):.1f}/{float(energy_data["edischargeTotal"]):.1f}'
+    exported_to_grid = f'{float(energy_data["etoGridToday"]):.1f}/{float(energy_data["etoGridTotal"]):.1f}'
+    imported_from_grid = f'{float(energy_data["etoUserToday"]):.1f}/{float(energy_data["etoUserTotal"]):.1f}'
+    load_consumption = f'{float(energy_data["elocalLoadToday"]):.1f}/{float(energy_data["elocalLoadTotal"]):.1f}'
+    self_consumption = f'{float(energy_data["eselfToday"]):.1f}/{float(energy_data["eselfTotal"]):.1f}'
+    battery_charged = f'{float(energy_data["echargeToday"]):.1f}/{float(energy_data["echargeTotal"]):.1f}'
+
+    # Output the dashboard
+    print("\nGeneration overview             Today/Total(kWh)")
+    print(f'Solar production          {solar_production:>22}')
+    print(f' Solar production, PV1    {solar_production_pv1:>22}')
+    print(f' Solar production, PV2    {solar_production_pv2:>22}')
+    print(f'Energy Output             {energy_output:>22}')
+    print(f'System production         {system_production:>22}')
+    print(f'Self consumption          {self_consumption:>22}')
+    print(f'Load consumption          {load_consumption:>22}')
+    print(f'Battery Charged           {battery_charged:>22}')
+    print(f' Charged from grid        {battery_grid_charge:>22}')
+    print(f'Battery Discharged        {battery_discharged:>22}')
+    print(f'Import from grid          {imported_from_grid:>22}')
+    print(f'Export to grid            {exported_to_grid:>22}')
+
+    print("\nPower overview                          (Watts)")
+    print(f'AC Power                 {float(energy_data["pac"]):>22.1f}')
+    print(f'Self power               {float(energy_data["pself"]):>22.1f}')
+    print(
+        f'Export power             {float(energy_data["pacToGridTotal"]):>22.1f}')
+    print(
+        f'Import power             {float(energy_data["pacToUserTotal"]):>22.1f}')
+    print(
+        f'Local load power         {float(energy_data["pacToLocalLoad"]):>22.1f}')
+    print(f'PV power                 {float(energy_data["ppv"]):>22.1f}')
+    print(f'PV #1 power              {float(energy_data["ppv1"]):>22.1f}')
+    print(f'PV #2 power              {float(energy_data["ppv2"]):>22.1f}')
+    print(
+        f'Battery charge power     {float(energy_data["bdc1ChargePower"]):>22.1f}')
+    print(
+        f'Battery discharge power  {float(energy_data["bdc1DischargePower"]):>22.1f}')
+    print(f'Battery SOC              {int(energy_data["bdc1Soc"]):>21}%')
+
+except growattServer.GrowattV1ApiError as e:
+    print(f"API Error: {e} (Code: {e.error_code}, Message: {e.error_msg})")
+except growattServer.GrowattParameterError as e:
+    print(f"Parameter Error: {e}")
+except requests.exceptions.RequestException as e:
+    print(f"Network Error: {e}")
+except Exception as e:
+    print(f"Unexpected error: {e}")

examples/tlx_example_dashboard.py

@@ -108,7 +108,7 @@
 print(f'Export power             {float(inverter_detail["pacToGridTotal"]):>22.1f}')
 print(f'Import power             {float(inverter_detail["pacToUserTotal"]):>22.1f}')
 print(f'Local load power         {float(inverter_detail["pacToLocalLoad"]):>22.1f}')
-print(f'PV power                 {float(inverter_detail["psystem"]):>22.1f}')
+print(f'PV power                 {float(inverter_detail["ppv"]):>22.1f}')
 print(f'PV #1 power              {float(inverter_detail["ppv1"]):>22.1f}')
 print(f'PV #2 power              {float(inverter_detail["ppv2"]):>22.1f}')
 print(f'Battery charge power     {float(system_status["chargePower"])*1000:>22.1f}')