Manual

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}/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  
  PVForecast_Perc decimal, optional  
  PVForecast_kWh decimal, optional  
  Loads_Perc decimal, optional  
  Loads_kWh decimal, optional with ExtraLoad
  GridCharge_Perc decimal, optional  
  GridCharge_kWh decimal, optional  
  Discharge_Perc decimal, optional  
  Discharge_kWh decimal, optional  
  EndBattery_Perc decimal  
  EndBattery_kWh decimal  
  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  

 

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} ] }

 

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
Error string(255) OK or error description
Data   Data from original request