sph_settings.md

SPH Inverter Settings

This is part of the OpenAPI V1 doc.

For SPH (hybrid inverter) systems, the public V1 API provides methods to read and write inverter settings.

Source: Official Growatt API Documentation

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
  • 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