Mqtt

GbbOptimizer (ex. GbbVictronWeb) uses Mqtt protocol to receive requests from external program (e.g. Home Assistant).

External program should connect to Mqtt with:

• Address: see here
• Port: 8883
• User: {PlantId}
• Password: {PlantToken}
• UseTTL: true
• ClientID should end with: _{PlantId}

 

1. Signals send from mqtt to external program:

• Signals must be first enable in 'Discharge Plan' module.
• Data are calculated based on forecast for current hour.
• Signals are send every hour.
• Given signal is not send if "X" is not defined in "Discharge Plan" (field is empty in form)

External program can subscribe to following signals:

Topic	Payload
{PlantId}/signals/SOCHigherEqThanX	"1" if SOC >= x, otherwise "0"
{PlantId}/signals/SOCLowerEqThanX	"1" if SOC <= x, otherwise "0"
{PlantId}/signals/SellingPriceHigherEqThanX	"1" if SellingPrice >= x, otherwise "0"
{PlantId}/signals/SellingPriceLowerEqThanX	"1" if SellingPrice <= x, otherwise "0"
{PlantId}/signals/FromGridHigherEqThanX	"1" if FromGrid >= x, otherwise "0"
{PlantId}/signals/ToGridHigherEqThanX	"1" if ToGrid >= x, otherwise "0"

 

Program also send json data on topic: {PlantId}/signals/data

Key	Type	Value
SOC	int	SOC value (%) on start of hour
SellingPrice	decimal	Current SellingPrice (missing if no price)
PurchasePrice	decimal	Current PurchasePrice (missing if no price)
FromGrid_kWh	decimal	Forecasted FromGrid
ToGrid_kWh	decimal	Forecasted ToGrid_kWh

 

2. Requests to program by mqtt:

• Send requests to {PlantId}/ha_gbb/dataserver/serverrequest
• Listen for answers on {PlantId}/ha_gbb/dataserver/serverresponse

For compatible with previous versions program also support following (not recommended):

• Send requests to {PlantId}/dataserver/serverrequest
• Listen for answers on {PlantId}/dataserver/serverresponse

Response with error

For every request there can be response with error:

{"Operation": “xxx”, "Status": “ERROR”, "ErrDesc": “any description of error”}

Key	Type	Value
Operation	String	operation from request
Status	String	“ERROR”
ErrDesc	String	Any description of error for user.

 

Operation BatteryForecast_GetChartData

Return information about battery forecast.

 

Request from External Program:

{"Operation": "BatteryForecast_GetChartData"}

Key	Type	Value
Operation	String	“BatteryForecast_GetChartData”

 

Response from GbbOptimizer

{"Operation": "BatteryForecast_GetChartData", "Status": “OK”, "BatteryForecast_GetChartData": [ {"Hour": 7, "StartBattery_Perc": 13.5, ...}, ...]}

Key		Type	Value
Operation		String	“BatteryForecast_GetChartData”
Status		String	“OK”
BatteryForecast_GetChartData		Table
	Day	date
	Hour	Integer 0-23
	StartBattery_Perc	decimal
	StartBattery_kWh	decimal
	StartBattery_kWhAC	decimal
	PVForecast_Perc	decimal, optional
	PVForecast_kWh	decimal, optional
	PVForecast_kWhAC	decimal, optional
	Loads_Perc	decimal, optional
	Loads_kWh	decimal, optional	with ExtraLoad
	Loads_kWhAC	decimal, optional
	GridCharge_Perc	decimal, optional
	GridCharge_kWh	decimal, optional
	GridCharge_kWhAC	decimal, optional
	Discharge_Perc	decimal, optional
	Discharge_kWh	decimal, optional
	Discharge_kWhAC	decimal, optional
	EndBattery_Perc	decimal
	EndBattery_kWh	decimal
	EndBattery_kWhAC	decimal
	EndBattery_Price	decimal, optional
	Profit_Amount	decimal, optional
	FromGrid_kWh	decimal, optional
	Purchase_Price	decimal, optional
	Purchase_Amount	decimal, optional
	ToGrid_kWh	decimal, optional
	Sale_Price	decimal, optional
	Sale_Amount	decimal, optional
	Consumption_kWh	decimal, optional	the same as Loads_kWh
	Consumption_Price	decimal, optional
	Consumption_Amount	decimal, optional
	ExtraLoadsKW	decimal, optional
	ExtraLoadsKW_ElectricVehicle	decimal, optional
	ExtraLoadsKW_HeatingPump	decimal, optional
	ExtraLoadsKW_Generic1	decimal, optional
	ExtraLoadsKW_Generic2	decimal, optional
	ExtraLoadsKW_Generic3	decimal, optional
	ExtraLoadsKW_Generic4	decimal, optional
	ExtraLoadsKW_Generic5	decimal, optional
	ExtraLoadsKW_Generic6	decimal, optional

 

Operation History_GetHours

Returns information about hour history from Gain/Profits module.

 

Request from External Program:

{"Operation": "History_GetHours", "FromDate": "2024-01-01", "ToDate": "2024-01-01"}

Key	Type	Value	Remarks
Operation	String	“History_GetDays”
FromDate	Date, optional	"2024-01-01"	if omitted: today
ToDate	Date, optional	"2024-01-01"	if omitted: today

Second form:

Key	Type	Value	Remarks
Operation	String	“History_GetHours”
Period	String	"curr_day" or "prev_day" or "today_yesterday"
AddPeriodToProperty	int, optional	1	if 1 then in responce "History_Hours" will be sufixed with "_[Period]", eg. "History_Hour_curr_day"

 

Response from GbbOptimizer

{"Operation": "History_GetHours", "Status": “OK”, "History_Hours": [ {"Day": ...]}

Key		Type	Value
Operation		String	“History_GetDays”
Status		String	“OK”
Period	String, optional
FromDate	Date	"2024-01-01"
ToDate	Date	"2024-01-03"
History_Hours		Table
	Hour	decimal
	Day	date
	FromGrid_kWh	decimal, optional
	FromGrid2_kWh	decimal, optional
	PurchaseAmount	decimal, optional
	ToGrid_kWh	decimal, optional
	ToGrid2_kWh	decimal, optional
	SaleAmount	decimal, optional
	Consumption_kWh	decimal, optional
	ConsumptionAmount	decimal, optional
	ProfitAmount	decimal, optional
	Solar_kWh	decimal, optional
	ToBattery_kWh	decimal, optional
	SOC_Min	decimal, optional
	SOC_Max	decimal, optional
	SOC_Start	decimal, optional
	SOC_End	decimal, optional
	BattChange_kWh	decimal, optional
	LostPower_kWh	decimal, optional
	ChargeFromGrid_kWh	decimal, optional
	ChargeFromPV_kWh	decimal, optional
	DischargeToGrid_kWh	decimal, optional
	DischargeToLoads_kWh	decimal, optional
	Start_kWh	decimal, optional
	End_kWh	decimal, optional
	ValueStartAmount	decimal, optional
	ValueEndAmount	decimal, optional
	ValueChangeAmount	decimal, optional

 

Operation History_GetDays

Returns information about day history from Gain/Profits module.

 

Request from External Program:

{"Operation": "History_GetDays", "FromDate": "2024-01-01", "ToDate": "2024-01-03"}

Key	Type	Value	Remarks
Operation	String	“History_GetDays”
FromDate	Date, optional	"2024-01-01"	if omitted: today
ToDate	Date, optional	"2024-01-03"	if omitted: today

Second form:

Key	Type	Value	Remarks
Operation	String	“History_GetDays”
Period	String	"curr_month" or "prev_month" or "curr_year" or "prev_year"
AddPeriodToProperty	int, optional	1	if 1 then in responce "History_Days" will be sufixed with "_[Period]", eg. "History_Days_prev_month"

 

Response from GbbOptimizer

{"Operation": "History_GetDays", "Status": “OK”, "History_Days": [ {"Day": ...]}

Key		Type	Value
Operation		String	“History_GetDays”
Status		String	“OK”
Period	String, optional
FromDate	Date	"2024-01-01"
ToDate	Date	"2024-01-03"
History_Days		Table
	Day	date
	FromGrid_kWh	decimal, optional
	FromGrid2_kWh	decimal, optional
	PurchaseAmount	decimal, optional
	ToGrid_kWh	decimal, optional
	ToGrid2_kWh	decimal, optional
	SaleAmount	decimal, optional
	Consumption_kWh	decimal, optional
	ConsumptionAmount	decimal, optional
	ProfitAmount	decimal, optional
	Solar_kWh	decimal, optional
	ToBattery_kWh	decimal, optional
	SOC_Min	decimal, optional
	SOC_Max	decimal, optional
	SOC_Start	decimal, optional
	SOC_End	decimal, optional
	BattChange_kWh	decimal, optional
	LostPower_kWh	decimal, optional
	ChargeFromGrid_kWh	decimal, optional
	ChargeFromPV_kWh	decimal, optional
	DischargeToGrid_kWh	decimal, optional
	DischargeToLoads_kWh	decimal, optional
	Start_kWh	decimal, optional
	End_kWh	decimal, optional
	ValueStartAmount	decimal, optional
	ValueEndAmount	decimal, optional
	ValueChangeAmount	decimal, optional

 

Operation History_GetMonths

Returns information about month history from Gain/Profits module.

 

Request from External Program:

{"Operation": "History_GetMonths", "FromYear": 2024, "FromMonth": 1, "ToYear": 2024, "ToMonth": 2}

Key	Type	Value	Remarks
Operation	String	“History_GetMonths”
FromYear	int, optional	2024	if omitted: current year
FromMonth	int, optional	1	if omitted: current month
ToYear	int, optional	2024	if omitted: current year
ToMonth	int, optional	2	if omitted: current month

Second form:

Key	Type	Value	Remarks
Operation	String	“History_GetMonths”
Period	String	"curr_month" or "prev_month" or "curr_year" or "prev_year"
AddPeriodToProperty	int, optional	1	if 1 then in responce "History_Months" will be sufixed with "_[Period]", eg: "History_Months_prev_month"

 

Response from GbbOptimizer

{"Operation": "History_GetMonths", "Status": “OK”, "History_Months": [ {"Year": ...]}

Key		Type	Value
Operation		String	“History_GetMonths”
Status		String	“OK”
Period		String
FromYear		String	2024
FromMonth		int	1
ToYear		int	2024
ToMonth		int	2
History_Month		Table
	Day	date	First day of month
	Year	int
	Month	int
	FromGrid_kWh	decimal, optional
	FromGrid2_kWh	decimal, optional
	PurchaseAmount	decimal, optional
	ToGrid_kWh	decimal, optional
	ToGrid2_kWh	decimal, optional
	SaleAmount	decimal, optional
	Consumption_kWh	decimal, optional
	ConsumptionAmount	decimal, optional
	ProfitAmount	decimal, optional
	Solar_kWh	decimal, optional
	ToBattery_kWh	decimal, optional
	SOC_Min	decimal, optional
	SOC_Max	decimal, optional
	SOC_Start	decimal, optional
	SOC_End	decimal, optional
	BattChange_kWh	decimal, optional
	LostPower_kWh	decimal, optional
	ChargeFromGrid_kWh	decimal, optional
	ChargeFromPV_kWh	decimal, optional
	DischargeToGrid_kWh	decimal, optional
	DischargeToLoads_kWh	decimal, optional
	Start_kWh	decimal, optional
	End_kWh	decimal, optional
	ValueStartAmount	decimal, optional
	ValueEndAmount	decimal, optional
	ValueChangeAmount	decimal, optional

 

3. Changes data in program

Change manual prices

Topic with data send to program: {plantId}/ha_gbb/api/setmanualprices

Payload:

Key		type	remarks
OrderId		string(255), optional	Any text copied from request to answer
Data		table
	Date	Date, required	Date of price
	StartHour	int, hour (0-23), required	Start hour of price
	StartMinute	int, minute (0-59), optional	Start minute of hour, if missing then 0
	PurchasePrice	decimal, optional
	TransferPrice	decimal, optional
	SalePrice	decimal, optional

example:

{ "Data": [ {"Date": "2024-04-20", "StartHour": 20, "PurchasePrice": 0.23} ] }

 

Change extra loads

Topic with data send to program: {plantId}/ha_gbb/api/setextraloads

Payload:

Key		type	remarks
OrderId		string(255), optional	Any text copied from request to answer
Data		table
	Date	Date, required	Date of extra loads (today or tomorrow)
	StartHour	int, hour (0-23), required	Start hour of extra loads
	StartMinute	int, minute (0-59), optional	Start minute of hour, if missing then 0
	TypeNo	int, required	0 - EV, 1 - HeatPump, 2 - Other1, 3 - Other2, ..., 7 - Other6
	ExtraLoads_kWh	decimal, required	kWh

example:

{ "Data": [ {"Date": "2024-04-20", "StartHour": 20, "TypeNo": 1, "ExtraLoads": 1.23} ] }

 

Change real temperature

Topic with data send to program: {plantId}/ha_gbb/api/setrealtemperature

Payload:

Key		type	remarks
OrderId		string(255), optional	Any text copied from request to answer
Data		table
	Date	Date, required	Date of extra loads (yesterday, today or tomorrow) If Hour is not present than hour is taken from Date, otherwise time (hour and minutes) are ignored
	Hour	int, hour (0-23), optional	Hour of temperature
	RealTemperature	decimal, required	stC

example:

{ "Data": [ {"Date": "2024-04-20", "Hour": 20, "RealTemperature": 1.23} ] }

 

Set optimizer parameters

Topic with data send to program: {plantId}/ha_gbb/api/setoptimizer

Payload:

Key		type	remarks
OrderId		string(255), optional	Any text copied from request to answer
Data		object
	Opt2_3x100Request	int	0 or 1

example:

{ "Data": {"Opt2_3x100Request": 1} }

 

Set car parameters

Topic with data send to program: {plantId}/ha_gbb/api/setcar

Remark: 'HomeAssistant EV Car' must be added first (one)

Remark2: only given parameters are changed, so in different payload different parameters can be changes. But program required following information to be up to date: SOC, SOC_ChargeLimit, IsConnected, IsCharging, Position_Longitude, Position_Latitude

Payload:

Key		type	remarks
OrderId		string(255), optional	Any text copied from request to answer
Data		Table	More then one car can be update
	VIN	string, required	Key to search existing car. If new VIN than new car is added (up to 10 cars)
	BatteryKWh	decimal, optional	Car battery size
	ChargeA	decimal, optional	Default car charge A
	Phases	int, optional	1 or 3 phases of charge
	SOC	int, optional	Current SOC
	SOC_ChargeLimit	int, optional	Target SOC
	InService	bool, optional	is car in service?
	IsConnected	bool, optional	is car connected to charge?
	IsCharging	bool, optional	is car is cahrging now?
	Position_Longitude, Position_Latitude	double, optional	Current car position

 

example:

{ "Data": [ {"VIN":"vin1234", "SOC":40, "SOC_ChargeLimit": 90} ], [ {"VIN":"vin4321", "InService": true] }

 

Set HP parameters

Topic with data send to program: {plantId}/ha_gbb/api/sethp

Remark: only given parameters are changed.

Payload:

Key		type	remarks
OrderId		string(255), optional	Any text copied from request to answer
Data		object
	HPForecast_Break_On	bool, optional	HP doesn't work: on/off
	HPForecast_BreakFromDate	date, optional	Start Date
	HPForecast_BreakFromHour	int, optional	Start Hour (0-23)
	HPForecast_BreakToDate	date, optional	End Date (included)
	HPForecast_BreakToHour	int, optional	End Hour (included) (0-23)

 

example:

{ "Data": {"HPForecast_Break_On":true, "HPForecast_BreakToDate":"2026-01-30", "HPForecast_BreakToHour": 23} }

 

Result of changes

After every change in data (eg. {plantid}/ha_gbb/api/setmanualprices) program send info on this topic with OK or error description.

Topic with data send from program: {plantid}/ha_gbb/api/result

Payload:

Key	type	remarks
OrderId	string(255), optional	Any text copied from request to answer
Result	string(255)	OK or error description
Data		Data from original request