Add support for SPH inverters using V1 API

README.md

@@ -8,7 +8,7 @@ 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
 That project has since ben archived.
 
-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()`.
+This library supports both the classic password-based API and the token-based V1 API, officially supported by Growatt. Currently, the V1 API implementation supports MIN and SPH devices, where MIN broadly corresponds to classic TLX and SPH to classic MIX. If your inverter supports the V1 API, it is encouraged to use this over the classic API, as it offers better security, more features, and more relaxed rate limiting.
 
 ## Usage
 

docs/openapiv1.md

@@ -21,7 +21,9 @@ print(plants)
 
 ### Methods
 
-Any methods that may be useful.
+#### Generic Methods
+
+Methods that work across all device types.
 
 | Method | Arguments | Description |
 |:---|:---|:---|
@@ -30,15 +32,38 @@ Any methods that may be useful.
 | `api.plant_energy_overview(plant_id)` | plant_id: String | Get energy overview data for a plant. |
 | `api.plant_energy_history(plant_id, start_date, end_date, time_unit, page, perpage)` | plant_id: String, start_date: Date, end_date: Date, time_unit: String, page: Int, perpage: Int | Get historical energy data for a plant for multiple days/months/years. |
 | `api.device_list(plant_id)` | plant_id: String | Get a list of devices in specified plant. |
+
+#### MIN Methods
+
+Methods for MIN devices (type 7).
+
+| Method | Arguments | Description |
+|:---|:---|:---|
 | `api.min_energy(device_sn)` | device_sn: String | Get current energy data for a min inverter, including power and energy values. |
 | `api.min_detail(device_sn)` | device_sn: String | 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)` | device_sn: String, start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for a min inverter (7-day max range). |
 | `api.min_settings(device_sn)` | device_sn: String | Get all settings for a min inverter. |
 | `api.min_read_parameter(device_sn, parameter_id, start_address=None, end_address=None)` | device_sn: String, parameter_id: String, start_address: Int, end_address: Int | Read a specific setting for a min inverter. see: [details](./openapiv1/min_tlx_settings.md) |
 | `api.min_write_parameter(device_sn, parameter_id, parameter_values)` | device_sn: String, parameter_id: String, parameter_values: Dict/Array | Set parameters on a min inverter. Parameter values can be a single value, a list, or a dictionary. see: [details](./openapiv1/min_tlx_settings.md) |
-| `api.min_write_time_segment(device_sn, segment_id, batt_mode, start_time, end_time, enabled=True)` | device_sn: String, segment_id: Int, batt_mode: Int <0=load priority, 1=battery priority, 2=grid priority>, start_time: Time, end_time: Time, enabled: Bool | Update a specific time segment for a min inverter. see: [details](./openapiv1/min_tlx_settings.md) |
+| `api.min_write_time_segment(device_sn, segment_id, batt_mode, start_time, end_time, enabled=True)` | device_sn: String, segment_id: Int, batt_mode: Int <0=load priority, 1=battery priority, 2=grid priority>, start_time: datetime.time, end_time: datetime.time, enabled: Bool | Update a specific time segment for a min inverter. see: [details](./openapiv1/min_tlx_settings.md) |
 | `api.min_read_time_segments(device_sn, settings_data=None)` | device_sn: String, settings_data: Dict | Read all time segments from a MIN inverter. Optionally pass settings_data to avoid redundant API calls. see: [details](./openapiv1/min_tlx_settings.md) |
 
+#### SPH Methods
+
+Methods for SPH devices (type 5).
+
+| Method | Arguments | Description |
+|:---|:---|:---|
+| `api.sph_detail(device_sn)` | device_sn: String | Get detailed data and settings for an SPH hybrid inverter. |
+| `api.sph_energy(device_sn)` | device_sn: String | Get current energy data for an SPH inverter, including power and energy values. |
+| `api.sph_energy_history(device_sn, start_date=None, end_date=None, timezone=None, page=None, limit=None)` | device_sn: String, start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for an SPH inverter (7-day max range). |
+| `api.sph_read_parameter(device_sn, parameter_id, start_address=None, end_address=None)` | device_sn: String, parameter_id: String, start_address: Int, end_address: Int | Read a specific setting for an SPH inverter. see: [details](./openapiv1/sph_settings.md) |
+| `api.sph_write_parameter(device_sn, parameter_id, parameter_values)` | device_sn: String, parameter_id: String, parameter_values: Dict/Array | Set parameters on an SPH inverter. Parameter values can be a single value, a list, or a dictionary. see: [details](./openapiv1/sph_settings.md) |
+| `api.sph_write_ac_charge_times(device_sn, charge_power, charge_stop_soc, mains_enabled, periods)` | device_sn: String, charge_power: Int (0-100), charge_stop_soc: Int (0-100), mains_enabled: Bool, periods: List of 3 dicts with start_time, end_time, enabled | Configure AC charge time periods for an SPH inverter. see: [details](./openapiv1/sph_settings.md) |
+| `api.sph_write_ac_discharge_times(device_sn, discharge_power, discharge_stop_soc, periods)` | device_sn: String, discharge_power: Int (0-100), discharge_stop_soc: Int (0-100), periods: List of 3 dicts with start_time, end_time, enabled | Configure AC discharge time periods for an SPH inverter. see: [details](./openapiv1/sph_settings.md) |
+| `api.sph_read_ac_charge_times(device_sn, settings_data=None)` | device_sn: String, settings_data: Dict | Read all AC charge time periods from an SPH inverter. Optionally pass settings_data from sph_detail() to avoid redundant API calls. see: [details](./openapiv1/sph_settings.md) |
+| `api.sph_read_ac_discharge_times(device_sn, settings_data=None)` | device_sn: String, settings_data: Dict | Read all AC discharge time periods from an SPH inverter. Optionally pass settings_data from sph_detail() to avoid redundant API calls. see: [details](./openapiv1/sph_settings.md) |
+
 Methods from [here](./shinephone.md#methods) should be available, but it's safer to rely on the functions described in this file where possible. There is no guarantee those methods will work, or remain stable through updates.
 
 ### Variables

docs/openapiv1/sph_settings.md

@@ -0,0 +1,54 @@
+# SPH Inverter Settings
+
+This is part of the [OpenAPI V1 doc](../openapiv1.md).
+
+For SPH (hybrid inverter) systems, the public V1 API provides methods to read and write inverter settings. SPH inverters have different time period configurations compared to MIN inverters:
+
+* **Read Parameter**
+  * function: `api.sph_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.sph_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)
+
+* **AC Charge Time Periods**
+  * function: `api.sph_write_ac_charge_times`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `charge_power`: Charging power percentage (0-100)
+    * `charge_stop_soc`: Stop charging at this SOC percentage (0-100)
+    * `mains_enabled`: Boolean to enable/disable grid charging
+    * `periods`: List of 3 period dicts, each with:
+      * `start_time`: datetime.time object for period start
+      * `end_time`: datetime.time object for period end
+      * `enabled`: Boolean to enable/disable period
+
+* **AC Discharge Time Periods**
+  * function: `api.sph_write_ac_discharge_times`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `discharge_power`: Discharge power percentage (0-100)
+    * `discharge_stop_soc`: Stop discharging at this SOC percentage (0-100)
+    * `periods`: List of 3 period dicts, each with:
+      * `start_time`: datetime.time object for period start
+      * `end_time`: datetime.time object for period end
+      * `enabled`: Boolean to enable/disable period
+
+* **Read AC Charge Time Periods**
+  * function: `api.sph_read_ac_charge_times`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `settings_data`: Optional settings data to avoid redundant API calls
+
+* **Read AC Discharge Time Periods**
+  * function: `api.sph_read_ac_discharge_times`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `settings_data`: Optional settings data to avoid redundant API calls

examples/sph_example.py

@@ -0,0 +1,135 @@
+"""
+Example script for SPH devices using the OpenAPI V1.
+
+This script demonstrates controlling SPH interface devices (device type 5)
+such as hybrid inverter systems.
+You can obtain an API token from the Growatt API documentation or developer portal.
+"""
+
+import json
+
+import requests
+
+import growattServer
+
+# 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"  # noqa: S105
+
+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")  # noqa: T201
+    plant_id = plants["plants"][0]["plant_id"]
+
+    # Devices
+    devices = api.device_list(plant_id)
+
+    for device in devices["devices"]:
+        print(device)  # noqa: T201
+        if device["type"] == growattServer.DeviceType.SPH.value:
+            inverter_sn = device["device_sn"]
+            print(f"Processing SPH device: {inverter_sn}")  # noqa: T201
+
+            # Get device details
+            inverter_data = api.sph_detail(
+                device_sn=inverter_sn,
+            )
+            print("Saving inverter data to inverter_data.json")  # noqa: T201
+            with open("inverter_data.json", "w") as f:
+                json.dump(inverter_data, f, indent=4, sort_keys=True)
+
+            # Get energy data
+            energy_data = api.sph_energy(
+                device_sn=inverter_sn,
+            )
+            print("Saving energy data to energy_data.json")  # noqa: T201
+            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.sph_energy_history(
+                device_sn=inverter_sn,
+            )
+            print("Saving energy history data to energy_history.json")  # noqa: T201
+            with open("energy_history.json", "w") as f:
+                json.dump(
+                    energy_history_data.get("datas", []),
+                    f,
+                    indent=4,
+                    sort_keys=True,
+                )
+
+            # Get details (includes settings data)
+            detail_data = api.sph_detail(
+                device_sn=inverter_sn,
+            )
+            print("Saving detail data to settings_data.json")  # noqa: T201
+            with open("settings_data.json", "w") as f:
+                json.dump(detail_data, f, indent=4, sort_keys=True)
+
+            # Read AC charge time periods
+            charge_times = api.sph_read_ac_charge_times(
+                device_sn=inverter_sn,
+                settings_data=detail_data,
+            )
+            print("AC Charge Time Periods:")  # noqa: T201
+            print(json.dumps(charge_times, indent=4))  # noqa: T201
+
+            # Read AC discharge time periods
+            discharge_times = api.sph_read_ac_discharge_times(
+                device_sn=inverter_sn,
+                settings_data=detail_data,
+            )
+            print("AC Discharge Time Periods:")  # noqa: T201
+            print(json.dumps(discharge_times, indent=4))  # noqa: T201
+
+            # Read discharge power
+            discharge_power = api.sph_read_parameter(
+                device_sn=inverter_sn,
+                parameter_id="discharge_power",
+            )
+            print(f"Current discharge power: {discharge_power}%")  # noqa: T201
+
+            # Write examples - Uncomment to test
+
+            # Set AC charge time periods: charge at 50% power to 95% SOC
+            # api.sph_write_ac_charge_times(
+            #     device_sn=inverter_sn,
+            #     charge_power=50,  # 50% charging power
+            #     charge_stop_soc=95,  # Stop at 95% SOC
+            #     mains_enabled=True,  # Enable grid charging
+            #     periods=[
+            #         {"start_time": datetime.time(0, 0), "end_time": datetime.time(6, 0), "enabled": True},
+            #         {"start_time": datetime.time(0, 0), "end_time": datetime.time(0, 0), "enabled": False},
+            #         {"start_time": datetime.time(0, 0), "end_time": datetime.time(0, 0), "enabled": False},
+            #     ]
+            # )
+            # print("AC charge periods updated successfully")
+
+            # Set AC discharge time periods: discharge at 100% power to 20% SOC
+            # api.sph_write_ac_discharge_times(
+            #     device_sn=inverter_sn,
+            #     discharge_power=100,  # 100% discharge power
+            #     discharge_stop_soc=20,  # Stop at 20% SOC
+            #     periods=[
+            #         {"start_time": datetime.time(17, 0), "end_time": datetime.time(22, 0), "enabled": True},
+            #         {"start_time": datetime.time(0, 0), "end_time": datetime.time(0, 0), "enabled": False},
+            #         {"start_time": datetime.time(0, 0), "end_time": datetime.time(0, 0), "enabled": False},
+            #     ]
+            # )
+            # print("AC discharge periods updated successfully")
+
+except growattServer.GrowattV1ApiError as e:
+    print(f"API Error: {e} (Code: {e.error_code}, Message: {e.error_msg})")  # noqa: T201
+except growattServer.GrowattParameterError as e:
+    print(f"Parameter Error: {e}")  # noqa: T201
+except requests.exceptions.RequestException as e:
+    print(f"Network Error: {e}")  # noqa: T201
+except Exception as e:  # noqa: BLE001
+    print(f"Unexpected error: {e}")  # noqa: T201

growattServer/__init__.py

@@ -1,7 +1,7 @@
 # Import everything from base_api to ensure backward compatibility
 from .base_api import *
-# Import the V1 API class
-from .open_api_v1 import OpenApiV1
+# Import the V1 API class and DeviceType enum
+from .open_api_v1 import OpenApiV1, DeviceType
 # Import exceptions
 from .exceptions import GrowattError, GrowattParameterError, GrowattV1ApiError