Skip to content

Add support for SPH inverters using V1 API #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
johanzander wants to merge 5 commits into
base: master
Choose a base branch
from
+967 −46
Open

Add support for SPH inverters using V1 API #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ace52f3
Add V1 API support for SPH devices
johanzander Jan 8, 2026
f1c771c
Update README and OpenAPI documentation to clarify support for MIN an…
johanzander Jan 8, 2026
288e28c
Adress review comments
johanzander Jan 13, 2026
baace18
Enhance SPH read methods with global settings and optional device_sn
johanzander Jan 15, 2026
8b9a67c
docs and API: clarify SPH helper methods, harmonize with MIN V1, impr…
johanzander Jan 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
40 changes: 37 additions & 3 deletions docs/openapiv1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|:---|:---|:---|
Expand All @@ -30,16 +32,48 @@ 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) |

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.
#### 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. see: [details](./openapiv1/sph_settings.md) |
| `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=None, start_address=None, end_address=None)` | device_sn: String, parameter_id: String (optional), start_address: Int (optional), end_address: Int (optional) | Read a specific parameter (only pv_on_off supported). 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. see: [details](./openapiv1/sph_settings.md) |

#### SPH Helper Methods

Convenience methods that wrap the core SPH methods above for common use cases.

| Method | Arguments | Description |
|:---|:---|:---|
| `api.sph_write_ac_charge_times(...)` | device_sn, charge_power, charge_stop_soc, mains_enabled, periods | Helper: wraps `sph_write_parameter()` with type `mix_ac_charge_time_period`. see: [details](./openapiv1/sph_settings.md) |
| `api.sph_write_ac_discharge_times(...)` | device_sn, discharge_power, discharge_stop_soc, periods | Helper: wraps `sph_write_parameter()` with type `mix_ac_discharge_time_period`. see: [details](./openapiv1/sph_settings.md) |
| `api.sph_read_ac_charge_times(...)` | device_sn (optional), settings_data (optional) | Helper: parses charge config from `sph_detail()` response. see: [details](./openapiv1/sph_settings.md) |
| `api.sph_read_ac_discharge_times(...)` | device_sn (optional), settings_data (optional) | Helper: parses discharge config from `sph_detail()` response. see: [details](./openapiv1/sph_settings.md) |

#### Classic methods

Methods from [classic API](./shinephone.md#methods) should be available, but it's safer to rely on the functions described in this section where possible. There is no guarantee that the classic API methods will work, or remain stable through updates.

### Variables

Expand Down
211 changes: 211 additions & 0 deletions docs/openapiv1/sph_settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,211 @@
# 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.

**Source:** [Official Growatt API Documentation](https://www.showdoc.com.cn/262556420217021/6129763571291058)

## Read All Settings

* function: `api.sph_detail`
* parameters:
* `device_sn`: The device serial number
* returns: Dict containing all device data and settings

**Return parameter description:**

| Field | Type | Description |
|-------|------|-------------|
| serialNum | String | Serial Number |
| portName | String | Communication port information Communication port type and address |
| dataLogSn | String | DataLog serial number |
| groupId | int | Inverter group |
| alias | String | Alias |
| location | String | Location |
| addr | int | Inverter address |
| fwVersion | String | Firmware version |
| model | long | Model |
| innerVersion | String | Internal version number |
| lost | boolean | Whether communication is lost |
| status | int | Mix Status 0: waiting mode, 1: self-check mode, 3: failure mode, 4: upgrading, 5, 6, 7, 8: normal mode |
| tcpServerIp | String | TCP server IP address |
| lastUpdateTime | Date | Last update time |
| sysTime | Calendar | System Time |
| deviceType | int | 0: Mix6k, 1: Mix4-10k |
| communicationVersion | String | Communication version number |
| onOff | int | Switch machine |
| pmax | int | Rated power |
| vnormal | float | Rated PV voltage |
| lcdLanguage | int | LCD language |
| countrySelected | int | Country selection |
| wselectBaudrate | int | Baud rate selection |
| comAddress | int | Mailing address |
| manufacturer | String | Manufacturer Code |
| dtc | int | Device code |
| modbusVersion | int | MODBUS version |
| floatChargeCurrentLimit | float | Float charge current limit |
| vbatWarning | float | Low battery voltage alarm point |
| vbatWarnClr | float | Low battery voltage recovery point |
| vbatStopForDischarge | float | Battery discharge stop voltage |
| vbatStopForCharge | float | Battery charging stop voltage |
| vbatStartForDischarge | float | Lower limit of battery discharge voltage |
| vbatStartforCharge | float | Battery charging upper limit voltage |
| batTempLowerLimitD | float | Lower limit of battery discharge temperature |
| batTempUpperLimitD | float | Upper limit of battery discharge temperature |
| batTempLowerLimitC | float | Lower limit of battery charging temperature |
| batTempUpperLimitC | float | Upper limit of battery charging temperature |
| forcedDischargeTimeStart1 | String | Discharge 1 start time |
| forcedDischargeTimeStart2 | String | Discharge 2 start time |
| forcedDischargeTimeStart3 | String | Discharge 3 start time |
| forcedDischargeTimeStop1 | String | Discharge 1 stop time |
| forcedDischargeTimeStop2 | String | Discharge 2 stop time |
| forcedDischargeTimeStop3 | String | Discharge 3 stop time |
| forcedChargeTimeStart1 | String | Charge 1 start time |
| forcedChargeTimeStart2 | String | Charge 2 start time |
| forcedChargeTimeStart3 | String | Charge 3 start time |
| forcedChargeTimeStop1 | String | Charge 1 stop time |
| forcedChargeTimeStop2 | String | Charge 2 stop time |
| forcedChargeTimeStop3 | String | Charge 3 stop time |
| bctMode | int | Sensor type (2:METER;1:cWirelessCT;0:cWiredCT) |
| bctAdjust | int | Sensor adjustment enable |
| wdisChargeSOCLowLimit1 | int | Discharge in load priority mode |
| wdisChargeSOCLowLimit2 | int | Grid priority mode discharge |
| wchargeSOCLowLimit1 | int | Load priority mode charging |
| wchargeSOCLowLimit2 | int | Battery priority mode charging |
| acChargeEnable | int | AC charging enable |
| priorityChoose | int | Energy priority selection |
| chargePowerCommand | int | Charging power setting |
| disChargePowerCommand | int | Discharge power setting |
| bagingTestStep | int | Battery self-test |
| batteryType | int | Battery type selection |
| epsFunEn | int | Emergency power enable |
| epsVoltSet | int | Emergency power supply voltage |
| epsFreqSet | int | Emergency power frequency |
| forcedDischargeStopSwitch1 | int | Discharge 1 enable bit |
| forcedDischargeStopSwitch2 | int | Discharge 2 enable bit |
| forcedDischargeStopSwitch3 | int | Discharge 3 enable bit |
| forcedChargeStopSwitch1 | int | Charge 1 enable bit |
| forcedChargeStopSwitch2 | int | Charge 2 enable bit |
| forcedChargeStopSwitch3 | int | Charge 3 enable bit |
| voltageHighLimit | float | Mains voltage upper limit |
| voltageLowLimit | float | Mains voltage lower limit |
| buckUpsFunEn | int | Off-grid enable |
| uspFreqSet | int | Off-grid frequency |
| buckUPSVoltSet | int | Off-grid voltage |
| pvPfCmdMemoryState | int | Does the inverter store the following commands |
| activeRate | int | Active power |
| reactiveRate | int | Reactive power |
| underExcited | int | Capacitive or Perceptual |
| exportLimit | int | Backflow prevention enable |
| exportLimitPowerRate | float | Backflow prevention |
| powerFactor | float | PF value |
| pv_on_off | String | Switch |
| pf_sys_year | String | Set time |
| pv_grid_voltage_high | String | Mains voltage upper limit |
| pv_grid_voltage_low | String | Mains voltage lower limit |
| mix_off_grid_enable | String | Off-grid enable |
| mix_ac_discharge_frequency | String | Off-grid frequency |
| mix_ac_discharge_voltage | String | Off-grid voltage |
| pv_pf_cmd_memory_state | String | Set whether to store the following PF commands |
| pv_active_p_rate | String | Set active power |
| pv_reactive_p_rate | String | Set reactive power |
| pv_reactive_p_rate_two | String | No power capacity/inductive |
| backflow_setting | String | Backflow prevention setting |
| pv_power_factor | String | Set PF value |
| batSeriesNum | int | Number of cells in series |
| batParallelNum | int | Number of parallel cells |
| error_code | string | 0: normal return, 10001: system error |
| error_msg | string | Error message prompt |

## Read Parameter

* function: `api.sph_read_parameter`
* parameters:
* `device_sn`: The device serial number
* `parameter_id`: Parameter ID to read (optional)
* `start_address`, `end_address`: Optional, for reading registers by address

**Supported parameter types for reading:**

| parameter_id | Description | Return value |
|--------------|-------------|--------------|
| `pv_on_off` | Switch | 0 (off), 1 (on) |

## Write Parameter

* function: `api.sph_write_parameter`
* parameters:
* `device_sn`: The device serial number
* `parameter_id`: Parameter ID to write
* `parameter_values`: Value to set (single value, list, or dictionary)

**Supported parameter types for writing:**

| parameter_id | Description | Values |
|--------------|-------------|--------|
| **Device Control** |||
| `pv_on_off` | Switch | "0" (off), "1" (on) |
| `pf_sys_year` | Set time | hour:min format |
| **Charge Settings** |||
| `mix_ac_charge_time_period` | Charge time periods | charge power, stop SOC, mains enable, time periods... |
| **Discharge Settings** |||
| `mix_ac_discharge_time_period` | Discharge time periods | discharge power, stop SOC, time periods... |
| **Grid Settings** |||
| `pv_grid_voltage_high` | Mains voltage upper limit | e.g. "270" |
| `pv_grid_voltage_low` | Mains voltage lower limit | e.g. "180" |
| `pv_active_p_rate` | Set active power | 0-100 |
| `pv_reactive_p_rate` | Set reactive power | value |
| `pv_reactive_p_rate_two` | No power capacity/inductive | value |
| `pv_pf_cmd_memory_state` | Set whether to store PF commands | "0" (no), "1" (yes) |
| `pv_power_factor` | Set PF value | 0-100 |
| `backflow_setting` | Backflow prevention setting | "1" (on), "0" (off), power % |
| **Off-Grid/EPS Settings** |||
| `mix_off_grid_enable` | Off-grid enable | "1" (enabled), "0" (disabled) |
| `mix_ac_discharge_frequency` | Off-grid frequency | "0" (50Hz), "1" (60Hz) |
| `mix_ac_discharge_voltage` | Off-grid voltage | "0" (230V), "1" (208V), "2" (240V) |

> **Note:** For time period settings, it's recommended to use the dedicated helper functions `sph_write_ac_charge_times()` and `sph_write_ac_discharge_times()` instead of calling `sph_write_parameter()` directly.

## AC Charge Time Periods

### Write: `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

### Read: `api.sph_read_ac_charge_times`

* parameters:
* `device_sn`: The device serial number (not used if settings_data is provided)
* `settings_data`: Settings data from sph_detail() (not used if device_sn is provided)
* note: Either `device_sn` or `settings_data` must be provided
* returns: Dict with `charge_power`, `charge_stop_soc`, `mains_enabled`, and `periods` list

## AC Discharge Time Periods

### Write: `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: `api.sph_read_ac_discharge_times`

* parameters:
* `device_sn`: The device serial number (not used if settings_data is provided)
* `settings_data`: Settings data from sph_detail() (not used if device_sn is provided)
* note: Either `device_sn` or `settings_data` must be provided
* returns: Dict with `discharge_power`, `discharge_stop_soc`, and `periods` list
Loading