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

examples/sph_example.py

docs/openapiv1/sph_settings.md

growattServer/open_api_v1.py

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"

examples/sph_example.py

- sph_read_ac_charge_times now returns dict with charge_power, charge_stop_soc, mains_enabled, and periods - sph_read_ac_discharge_times now returns dict with discharge_power, discharge_stop_soc, and periods - Made device_sn optional when settings_data is provided (avoids redundant API calls) - Updated example to demonstrate new return structure - Updated documentation with new signatures and return types

GraemeDBlue · 2026-01-16T09:05:33Z

@johanzander

python3 -m examples.sph_example
Plants: Found 1 plants
{'last_update_time': '2026-01-16 09:00:12', 'device_id': 0, 'device_sn': 'EGM2HXXX', 'lost': False, 'model': 'A0B1D0T0XXXX', 'type': 5, 'datalogger_sn': 'KWK1CXXXXX', 'manufacturer': 'Growatt', 'status': 5}
Processing SPH device: EGM2HXXXXX
Saving inverter data to inverter_data.json
Saving energy data to energy_data.json
Saving energy history data to energy_history.json
AC Charge Configuration:
  Charge Power: 100%
  Stop SOC: 100%
  Mains Enabled: True
  Periods: [
    {
        "period_id": 1,
        "start_time": "00:00",
        "end_time": "00:00",
        "enabled": false
    },
    {
        "period_id": 2,
        "start_time": "00:00",
        "end_time": "00:00",
        "enabled": false
    },
    {
        "period_id": 3,
        "start_time": "00:00",
        "end_time": "00:00",
        "enabled": false
    }
]
AC Discharge Configuration:
  Discharge Power: 100%
  Stop SOC: 10%
  Periods: [
    {
        "period_id": 1,
        "start_time": "00:00",
        "end_time": "00:00",
        "enabled": false
    },
    {
        "period_id": 2,
        "start_time": "00:00",
        "end_time": "00:00",
        "enabled": false
    },
    {
        "period_id": 3,
        "start_time": "00:00",
        "end_time": "00:00",
        "enabled": false
    }
]
Network Error: 400 Client Error:  for url: https://openapi.growatt.com/v1/readMixParam

GraemeDBlue · 2026-01-16T09:10:38Z

discharge_power is not a valid parameter for readMixParam https://www.showdoc.com.cn/262556420217021/6129766954561259

GraemeDBlue

invalid params for readMixParam https://www.showdoc.com.cn/262556420217021/6129766954561259

GraemeDBlue · 2026-01-16T09:12:37Z

@johanzander thanks for adding token as env variable , but some bad params now for some reason that were not a problem before

GraemeDBlue · 2026-01-16T09:30:23Z

discharge power read seems to be /v1/device/mix/mix_data_info https://www.showdoc.com.cn/262556420217021/6129763571291058 for key disChargePowerCommand

…ove docs and examples

johanzander · 2026-01-17T10:58:58Z

pls. have a look @GraemeDBlue and see if everything works correctly

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

examples/sph_example.py Outdated Show resolved Hide resolved

GraemeDBlue requested changes Jan 16, 2026

View reviewed changes

docs and API: clarify SPH helper methods, harmonize with MIN V1, impr…

8b9a67c

…ove docs and examples

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

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

GraemeDBlue commented Jan 16, 2026

Uh oh!

GraemeDBlue commented Jan 16, 2026

Uh oh!

GraemeDBlue left a comment

Choose a reason for hiding this comment

Uh oh!

GraemeDBlue commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GraemeDBlue commented Jan 16, 2026

Uh oh!

johanzander commented Jan 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

GraemeDBlue commented Jan 16, 2026 •

edited

Loading