Simplify the V1 methods by using single re-usable base methods

.gitignore

@@ -26,6 +26,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+*.json
 
 # Symlink
 examples/growattServer

.ruff.toml

@@ -0,0 +1,25 @@
+# The contents of this file is based on https://github.com/home-assistant/core/blob/dev/pyproject.toml
+
+target-version = "py313"
+
+[lint]
+select = [
+    "ALL",
+]
+
+ignore = [
+    "ANN401", # Dynamically typed expressions (typing.Any) are disallowed
+    "D203", # no-blank-line-before-class (incompatible with formatter)
+    "D212", # multi-line-summary-first-line (incompatible with formatter)
+    "COM812", # incompatible with formatter
+    "ISC001", # incompatible with formatter
+]
+
+[lint.flake8-pytest-style]
+fixture-parentheses = false
+
+[lint.pyupgrade]
+keep-runtime-typing = true
+
+[lint.mccabe]
+max-complexity = 25

docs/openapiv1/mix_sph_settings.md

@@ -0,0 +1,65 @@
+# MIX/SPH Inverter Settings
+
+This is part of the [OpenAPI V1 doc](../openapiv1.md).
+
+For MIX/SPH systems, the public V1 API provides a way to read and write inverter settings:
+
+* **Device Settings**
+  * function: `api.device_settings`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `device_type`: Use `DeviceType.MIX_SPH` for MIX/SPH inverters
+
+* **Read Parameter**
+  * function: `api.read_parameter`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `device_type`: Use `DeviceType.MIX_SPH` for MIX/SPH inverters
+    * `parameter_id`: Parameter ID to read (e.g., "ac_charge", "discharge_power")
+
+* **Time Segments**
+  * function: `api.read_time_segments`
+  * parameters:
+    * `device_sn`: The device serial number
+    * `device_type`: Use `DeviceType.MIX_SPH` for MIX/SPH inverters
+    * `settings_data`: Optional settings data to avoid redundant API calls
+
+  Returns:
+    ```python
+    [
+        {
+            'segment_id': int,  # Segment number (1-9)
+            'batt_mode': int,   # 0=Load First, 1=Battery First, 2=Grid First
+            'mode_name': str,   # String representation of the mode
+            'start_time': str,  # Start time in format "HH:MM"
+            'end_time': str,    # End time in format "HH:MM"
+            'enabled': bool     # Whether the segment is enabled
+        },
+        # ... (up to 9 segments)
+    ]
+    ```
+
+## Common Usage Examples
+
+### Reading Device Settings
+```python
+from growattServer import OpenApiV1, DeviceType
+
+api = OpenApiV1(token="your_api_token")
+settings = api.device_settings("DEVICE_SN", DeviceType.MIX_SPH)
+```
+
+### Reading Parameters
+```python
+# Read a specific parameter
+value = api.read_parameter("DEVICE_SN", DeviceType.MIX_SPH, "ac_charge")
+```
+
+### Reading Time Segments
+```python
+# Option 1: Single call
+segments = api.read_time_segments("DEVICE_SN", DeviceType.MIX_SPH)
+
+# Option 2: Reuse settings data to avoid multiple API calls
+settings = api.device_settings("DEVICE_SN", DeviceType.MIX_SPH)
+segments = api.read_time_segments("DEVICE_SN", DeviceType.MIX_SPH, settings)

examples/min_example.py

@@ -1,7 +1,8 @@
-import growattServer
+from . import growattServer
 import datetime
 import json
 import requests
+import os
 
 """
 # Example script controlling a MID/TLX Growatt (MID-30KTL3-XH + APX battery) system using the public growatt API 
@@ -27,43 +28,65 @@
     devices = api.device_list(plant_id)
 
     for device in devices['devices']:
-        if device['type'] == 7:  # (MIN/TLX)
+        print(device)
+        if device['device_type'] == growattServer.DeviceType.MIN_TLX:
             inverter_sn = device['device_sn']
-            print(f"Processing inverter: {inverter_sn}")
+            device_type = device['device_type']
+            print(f"Processing {device_type.name} inverter: {inverter_sn}")
 
             # Get device details
-            inverter_data = api.min_detail(inverter_sn)
+            inverter_data = api.device_details(
+                device_sn=inverter_sn, 
+                device_type=device_type
+            )
             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)
+            energy_data = api.device_energy(
+                device_sn=inverter_sn, 
+                device_type=device_type
+            )
             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)
+            energy_history_data = api.device_energy_history(
+                device_sn=inverter_sn,
+                device_type=device_type
+            )
             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)
+                json.dump(energy_history_data.get('datas', []), f, indent=4, sort_keys=True)
 
             # Get settings
-            settings_data = api.min_settings(device_sn=inverter_sn)
+            settings_data = api.device_settings(
+                 device_sn=inverter_sn, 
+                 device_type=device_type
+            )
             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))
+            tou = api.read_time_segments(
+                 device_sn=inverter_sn, 
+                 device_type=device_type, 
+                 settings_data=settings_data
+            )
+            print("Time-of-Use Segments:")
+            with open('tou_data.json', 'w') as f:
+                json.dump(tou, f, indent=4, sort_keys=True)
 
             # Read discharge power
-            discharge_power = api.min_read_parameter(
-                inverter_sn, 'discharge_power')
-            print("Current discharge power:", discharge_power, "%")
+            discharge_power = api.common_read_parameter(
+                device_sn=inverter_sn, 
+                device_type=device_type, 
+                parameter_id='discharge_power'
+            )
+            print(f"Current discharge power: {discharge_power}%")
 
             # Settings parameters - Uncomment to test
 

examples/min_example_dashboard.py

@@ -1,10 +1,32 @@
-import growattServer
+from . import growattServer
 import json
 import requests
+import datetime
+import os
+
+
+def safe_float(val, default=0.0):
+    try:
+        # If already a float, return as is
+        if isinstance(val, float):
+            return val
+        # If it's an int, convert to float
+        if isinstance(val, int):
+            return float(val)
+        # If it's a string, try to parse
+        if isinstance(val, str):
+            # Remove any commas, spaces, etc.
+            val = val.replace(',', '').strip()
+            return float(val)
+        # If it's a type that can be cast to float (e.g., numpy.float64)
+        return float(val)
+    except (TypeError, ValueError, KeyError, AttributeError):
+        return default
+
 
 """
-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.
+# Example script controlling a MIX/SPH Growatt (SPH3~6k TL BL UP + 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
@@ -17,23 +39,21 @@
     # Initialize the API with token
     api = growattServer.OpenApiV1(token=api_token)
 
-    # Get plant list using V1 API
+    # Plant info
     plants = api.plant_list()
+    print(f"Plants: Found {plants['count']} plants")
     plant_id = plants['plants'][0]['plant_id']
+    today = datetime.date.today()
+    devices = api.get_devices(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)
+    for device in devices:
+        # Works automatically for MIN, MIX, or any future device type!
+        energy_data = device.energy()
+        print(f"Energy: {energy_data}")
+
+    if energy_data is None:
+        raise Exception("No MIN_TLX device found to get energy data from.")
 
     # energy data does not contain epvToday for some reason, so we need to calculate it
     epv_today = energy_data["epv1Today"] + energy_data["epv2Today"]
@@ -92,4 +112,6 @@
 except requests.exceptions.RequestException as e:
     print(f"Network Error: {e}")
 except Exception as e:
+    import traceback
     print(f"Unexpected error: {e}")
+    traceback.print_exc()

examples/mix_example.py

@@ -1,7 +1,8 @@
-import growattServer
+from . import growattServer
 import datetime
 import getpass
 import pprint
+import json
 
 """
 This is a very trivial script that logs into a user's account and prints out useful data for a "Mix" system (Hybrid).
@@ -76,7 +77,16 @@ def indent_print(to_output, indent):
     #These two API calls return lots of duplicated information, but each also holds unique information as well
     mix_info = api.mix_info(device_sn, plant_id)
     pp.pprint(mix_info)
+
+    print("Saving inverter data to old_inverter_data.json")
+    with open('old_inverter_data.json', 'w') as f:
+      json.dump(mix_info, f, indent=4, sort_keys=True)
+
     mix_totals = api.mix_totals(device_sn, plant_id)
+    print("Saving energy data to old_energy_data.json")
+    with open('old_energy_data.json', 'w') as f:
+      json.dump(mix_totals, f, indent=4, sort_keys=True)
+
     #pp.pprint(mix_totals)
     indent_print("*TOTAL VALUES*", 4)
     indent_print("==Today Totals==", 4)
@@ -94,6 +104,10 @@ def indent_print(to_output, indent):
     print("")
 
     mix_detail = api.mix_detail(device_sn, plant_id)
+
+    print("Saving energy data to old_detail_data.json")
+    with open('old_detail_data.json', 'w') as f:
+      json.dump(mix_detail, f, indent=4, sort_keys=True)
     #pp.pprint(mix_detail)
 
     #Some of the 'totals' values that are returned by this function do not align to what we would expect, however the graph data always seems to be accurate.

examples/mix_v1_example.py

@@ -0,0 +1,51 @@
+from . import growattServer
+import datetime
+import json
+import requests
+import os
+
+"""
+# Example script controlling a MIX/SPH Growatt (SPH3~6k TL BL UP + 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']
+    today = datetime.date.today()
+    devices = api.get_devices(plant_id)
+
+    for device in devices:
+        # Works automatically for MIN, MIX, or any future device type!
+        device_type = device.device_type
+        device_sn = device.device_sn
+        print(f"Device: {device_type} SN: {device_sn}")
+        details = device.details()
+        energy = device.energy()
+        settings = device.settings()
+        history = device.energy_history(start_date=today)
+
+        print(f"Details: {details}")
+        print(f"Energy: {energy}")
+        print(f"Settings: {settings}")
+        print(f"History: {history}")
+
+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}")