Add support for SPH inverters using V1 API #11

johanzander · 2026-01-08T21:51:01Z

Overview

Adds complete V1 API support for SPH (type 5) hybrid inverters

Design Rationale (per indykoning#125 discussion)

Zero breaking changes - all existing min_* methods unchanged, backward compatible
Follows the perfect PR recommendations
Follows existing architectural patterns - sph_* methods mirror min_* structure exactly
Potential improvements can be done in subsequent PRs

What's Included

10 new SPH methods:

  api.sph_detail(device_sn)                    # Device details
  api.sph_energy(device_sn)                    # Current energy
  api.sph_energy_history(...)                  # History (7-day max)
  api.sph_settings(device_sn)                  # All settings
  api.sph_read_parameter(...)                  # Read parameter
  api.sph_write_parameter(...)                 # Write parameter
  api.sph_write_ac_charge_time(...)            # AC charge periods (1-3)
  api.sph_write_ac_discharge_time(...)         # AC discharge periods (1-3)
  api.sph_read_ac_charge_times(...)            # Read charge periods
  api.sph_read_ac_discharge_times(...)         # Read discharge periods

  DeviceType enum:
  from growattServer import DeviceType  # SPH=5, MIN=7, etc.

Documentation:

README updates with all method signatures
Example script (examples/sph_example.py)

Technical Details

Endpoints: device/mix/*, mixSet, readMixParam (SPH uses MIX endpoints)
Time Periods: 3 AC charge + 3 AC discharge periods per API specification
Review: Parameter ranges match official Growatt V1 API docs

Testing

All methods verified against https://www.showdoc.com.cn/262556420217021
Parameter structures match API spec tables
Zero impact on existing MIN implementation
NO verification agains real hardware

Implements complete V1 API support for SPH (type 5) hybrid inverters, parallel to existing MIN device support. Changes: - Add DeviceType enum to distinguish device types - Implement 10 SPH methods in OpenApiV1: * sph_detail() - Get device details * sph_energy() - Get current energy data * sph_energy_history() - Get historical data (7-day max) * sph_settings() - Get all inverter settings * sph_read_parameter() - Read specific parameters * sph_write_parameter() - Write parameters * sph_write_ac_charge_time() - Configure AC charge periods (1-3) * sph_write_ac_discharge_time() - Configure AC discharge periods (1-3) * sph_read_ac_charge_times() - Read all charge periods * sph_read_ac_discharge_times() - Read all discharge periods - Add documentation to docs/openapiv1.md - Include working example script (examples/sph_example.py) Technical details: - SPH devices use 'mix' endpoints internally (device/mix/*) - AC charge/discharge periods support 3 time windows each - Methods follow same patterns as existing MIN implementation - All endpoints match official Growatt V1 API documentation

…d SPH devices with V1 API

johanzander · 2026-01-08T21:53:13Z

Hi @GraemeDBlue - please have a look at this and let me know what you think. I think this minimal approach as layed out in the design rationale would be approved quite easily by the maintainer.
Would be great if you could test it as I dont have an SPH device.

GraemeDBlue · 2026-01-09T08:53:05Z

Hi @GraemeDBlue - please have a look at this and let me know what you think. I think this minimal approach as layed out in the design rationale would be approved quite easily by the maintainer. Would be great if you could test it as I dont have an SPH device.

@johanzander right, so bit confused then as you said "Keep your internal implementation work (which is solid)" , but none of my work is retained at all anyway, are you only needing me as i have an SPH device?

johanzander · 2026-01-09T09:24:04Z

To be honest, I gave instructions to AI agent to align implementation to current python library architecture and keep changes to minimum in initial PR.

Doing large refactoring and feature development in same PR makes it very hard to review test and approve.

GraemeDBlue · 2026-01-09T09:29:00Z

To be honest, I gave instructions to AI agent to align implementation to current python library architecture and keep changes to minimum in initial PR.

Doing large refactoring and feature development in same PR makes it very hard to review test and approve.

How do you want to handle the conflicts then ?

johanzander · 2026-01-09T21:55:28Z

I follow the principles in the Perfect PR recommendation:

_Make your PRs as small as possible. A PR should only refactor one thing, fix one thing, add one feature, or adjust a single subject in the documentation. If you want to change multiple things, please create multiple PRs. Smaller PRs have a smaller scope, need less time to review, conflict less often, and generally need fewer review iterations.

Only change one thing at a time. This is the same as the previous point but a bit more specific. It is tempting to improve those one or two lines you've noticed nearby, but please don't. Put those in a separate PR. Unrelated changes in your PR are distracting and often lead to questions. In contrast, in an independent PR, it would be a quick and simple review and merge._

Hence, my recommendation is that you review/test this small PR, create a new PR to get this in. There shouldn't be any merge conflicts towards the master 1.7.1 version.

then for each improvement you want to commit to the library, you create a new PR, cherry picking the change from your own "upstream" version. This is exactly how I work with the Home Assistant integration, one small increment at a time, based on my now upstream version. This can be frustrating and I know the feeling when done a lot of work - my first PR to the HA Growatt integration was a huge refactoring and lots of features that got rejected immediately and I got asked to break it down into many smaller PRs.

GraemeDBlue · 2026-01-12T12:09:28Z

@johanzander

$ python3 -m examples.sph_example
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/home/graeme/web/PyPi_GrowattServer_johanzander/examples/sph_example.py", line 15, in <module>
    from . import growattServer
ImportError: cannot import name 'growattServer' from 'examples' (unknown location)

while

$ python3 -m examples.min_example
API Error: Error during getting plant list (Code: 10011, Message: error_permission_denied)

is as expected

GraemeDBlue

there are only 18 params , your requests are trying to do 19 , example scripts seem to work

growattServer/open_api_v1.py

Copilot

Pull request overview

This PR adds complete V1 API support for SPH (type 5) hybrid inverters to the growattServer library. The implementation mirrors the existing MIN inverter architecture and maintains full backward compatibility with zero breaking changes.

Changes:

Added DeviceType enum for type-safe device identification
Implemented 10 new SPH-specific API methods following the established MIN method patterns
Added comprehensive documentation and working example script

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
growattServer/open_api_v1.py	Added DeviceType enum and 10 SPH-specific methods (detail, energy, settings, parameters, AC charge/discharge configuration) using MIX API endpoints
growattServer/init.py	Exported DeviceType enum for public API access
examples/sph_example.py	Added comprehensive example demonstrating all SPH methods with commented write operations
docs/openapiv1/sph_settings.md	New documentation detailing SPH settings methods and parameters
docs/openapiv1.md	Updated main documentation with SPH methods table and reorganized method sections by device type
README.md	Updated library description to mention SPH support alongside MIN

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

growattServer/open_api_v1.py

Copilot · 2026-01-13T11:57:19Z

growattServer/open_api_v1.py

+    MAX = 4
+    SPH = 5  # (MIX)
+    SPA = 6
+    MIN = 7 


Trailing whitespace detected after the value 7. This should be removed to maintain code consistency.

Suggested change

MIN = 7

MIN = 7

Copilot · 2026-01-13T11:57:19Z

growattServer/open_api_v1.py

+    def sph_settings(self, device_sn):
+        """
+        Get settings for an SPH inverter.
+
+        Args:
+            device_sn (str): The serial number of the SPH inverter.
+
+        Returns:
+            dict: A dictionary containing the SPH inverter settings.
+
+        Raises:
+            GrowattV1ApiError: If the API returns an error response.
+            requests.exceptions.RequestException: If there is an issue with the HTTP request.
+        """
+
+        response = self.session.get(
+            self._get_url('device/mix/mix_data_info'),
+            params={
+                'device_sn': device_sn
+            }
+        )
+
+        return self._process_response(response.json(), "getting SPH inverter settings")


The sph_detail and sph_settings methods use the same endpoint ('device/mix/mix_data_info') and will return identical data. Consider either removing the duplicate method or adding a comment explaining why both methods exist if they serve different semantic purposes. For consistency with MIN methods where min_detail uses 'tlx_data_info' and min_settings uses 'tlx_set_info', these should ideally use different endpoints if such differentiation exists in the API.

Copilot · 2026-01-13T11:57:20Z

examples/sph_example.py

+
+import requests
+
+from . import growattServer


The import statement uses a relative import which is inconsistent with other example files in the repository. Other examples use 'import growattServer' as an absolute import. This should be changed to match the pattern used in min_example.py and other example scripts.

Suggested change

from . import growattServer

import growattServer

Copilot · 2026-01-13T11:57:20Z

examples/sph_example.py

+            with Path("inverter_data.json").open("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 Path("energy_data.json").open("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 Path("energy_history.json").open("w") as f:
+                json.dump(
+                    energy_history_data.get("datas", []),
+                    f,
+                    indent=4,
+                    sort_keys=True,
+                )
+
+            # Get settings
+            settings_data = api.sph_settings(
+                device_sn=inverter_sn,
+            )
+            print("Saving settings data to settings_data.json")  # noqa: T201
+            with Path("settings_data.json").open("w") as f:
+                json.dump(settings_data, f, indent=4, sort_keys=True)


Inconsistent use of Path.open() versus built-in open(). The min_example.py uses built-in open() while this example uses Path.open(). For consistency with other example files in the repository, consider using the built-in open() function instead.

Copilot · 2026-01-13T11:57:20Z

docs/openapiv1/sph_settings.md

+    * `start_time`: Datetime.time object for period start
+    * `end_time`: Datetime.time object for period end


Inconsistent capitalization: 'Datetime.time' should be 'datetime.time' (lowercase 'd'). The module name in Python is 'datetime', not 'Datetime'.

docs/openapiv1/sph_settings.md

Copilot · 2026-01-13T11:57:21Z

growattServer/open_api_v1.py

+        all_params["param1"] = str(charge_power)
+        all_params["param2"] = str(charge_stop_soc)
+        all_params["param3"] = "1" if mains_enabled else "0"
+        all_params[f"param{base_param + 4}"] = str(start_time.hour)
+        all_params[f"param{base_param + 5}"] = str(start_time.minute)
+        all_params[f"param{base_param + 6}"] = str(end_time.hour)
+        all_params[f"param{base_param + 7}"] = str(end_time.minute)
+        all_params[f"param{base_param + 8}"] = "1" if enabled else "0"


Potential parameter mapping issue: param1, param2, and param3 are set for every period, but these appear to be global parameters rather than period-specific. When configuring period 2 or 3, this may overwrite shared configuration values. If param1-3 are meant to be shared across all periods (not period-specific), consider documenting this behavior or implementing logic to preserve existing values for other periods. Verify this matches the API specification for mix_ac_charge_time_period.

there were wider issues with the method and how parameters were passed and used , so refactored it to reflect API endpoint

Copilot · 2026-01-13T11:57:21Z

growattServer/open_api_v1.py

+        all_params["param1"] = str(discharge_power)
+        all_params["param2"] = str(discharge_stop_soc)
+        all_params[f"param{base_param + 3}"] = str(start_time.hour)
+        all_params[f"param{base_param + 4}"] = str(start_time.minute)
+        all_params[f"param{base_param + 5}"] = str(end_time.hour)
+        all_params[f"param{base_param + 6}"] = str(end_time.minute)
+        all_params[f"param{base_param + 7}"] = "1" if enabled else "0"


Potential parameter mapping issue: param1 and param2 are set for every period, but these appear to be global parameters rather than period-specific. When configuring period 2 or 3, this may overwrite shared configuration values. If param1-2 are meant to be shared across all periods (not period-specific), consider documenting this behavior or implementing logic to preserve existing values for other periods. Verify this matches the API specification for mix_ac_discharge_time_period.

same comment as above, refactored

examples/sph_example.py

GraemeDBlue · 2026-01-13T13:17:23Z

@johanzander comments above

johanzander · 2026-01-13T20:16:10Z

Great! So I have Claude Code writing the code, and you have Copilot reviewing the changes , what a development :-).

Feel free to adress it yourself, otherwise I can fix it shortly, when I have credits again.

johanzander · 2026-01-13T21:31:09Z

all review comments adressed, please have a look.

GraemeDBlue · 2026-01-14T09:09:59Z

@johanzander could you not add https://github.com/indykoning/PyPi_GrowattServer/pull/125/files#diff-5461eaaa755cb6e17a88c081974c81b6a81e6b81d5f29015fb2ed33645732b59R148-R150 to the examples , having to keep editing the file to add my token is just annoying, and also encourages anyone else who uses this to use their own real token and not raise issues about it not working

GraemeDBlue

small fix for the sph examples to run "out the box"

GraemeDBlue · 2026-01-14T09:16:06Z

examples/sph_example.py

+                )
+
+            # Get details (includes settings data)
+            detail_data = api.sph_detail(


Why run this again ? it just causes this issue, remove it ?

Plants: Found 1 plants {'last_update_time': '2026-01-14 09:10:36', 'device_id': 0, 'device_sn': 'EGM2H4XXX', 'lost': False, 'model': 'A0B1D0T0PFU3M3S8', 'type': 5, 'datalogger_sn': 'KWK1CLXXXX', 'manufacturer': 'Growatt', 'status': 5} Processing SPH device: EGM2HXXX Saving inverter data to inverter_data.json Saving energy data to energy_data.json Saving energy history data to energy_history.json API Error: Error during getting SPH inverter details (Code: 10012, Message: error_frequently_access)

johanzander added 2 commits January 8, 2026 22:02

Update README and OpenAPI documentation to clarify support for MIN an…

f1c771c

…d SPH devices with V1 API

GraemeDBlue requested changes Jan 12, 2026

View reviewed changes

growattServer/open_api_v1.py Outdated Show resolved Hide resolved

growattServer/open_api_v1.py Outdated Show resolved Hide resolved

GraemeDBlue requested a review from Copilot January 13, 2026 11:50

Copilot started reviewing on behalf of GraemeDBlue January 13, 2026 11:50 View session

Copilot AI reviewed Jan 13, 2026

View reviewed changes

Adress review comments

288e28c

GraemeDBlue requested changes Jan 14, 2026

View reviewed changes

		* `start_time`: Datetime.time object for period start
		* `end_time`: Datetime.time object for period end

Add support for SPH inverters using V1 API #11

Are you sure you want to change the base?

Add support for SPH inverters using V1 API #11

Conversation

johanzander commented Jan 8, 2026

Overview

Design Rationale (per indykoning#125 discussion)

What's Included

Uh oh!

johanzander commented Jan 8, 2026

Uh oh!

GraemeDBlue commented Jan 9, 2026

Uh oh!

johanzander commented Jan 9, 2026

Uh oh!

GraemeDBlue commented Jan 9, 2026

Uh oh!

johanzander commented Jan 9, 2026

Uh oh!

GraemeDBlue commented Jan 12, 2026

Uh oh!

GraemeDBlue left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

johanzander Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

johanzander Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GraemeDBlue commented Jan 13, 2026

Uh oh!

johanzander commented Jan 13, 2026

Uh oh!

johanzander commented Jan 13, 2026

Uh oh!

GraemeDBlue commented Jan 14, 2026

Uh oh!

GraemeDBlue left a comment

Choose a reason for hiding this comment

Uh oh!

GraemeDBlue Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone