Site: add returnEnergy to aggregated battery state (#33241)

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Michael Geers <michael@geers.tv>

assets/js/types/evcc.ts

@@ -1131,8 +1131,10 @@ export interface Battery {
   capacity: number;
   /** Charge level in %. Weighted by capacity across all batteries. */
   soc: number;
-  /** Total battery energy in kWh. */
+  /** Total discharged energy in kWh. */
   energy?: number;
+  /** Total charged energy in kWh. */
+  returnEnergy?: number;
   /** Measurement data per battery meter. */
   devices?: BatteryMeter[];
   /** Projected charge levels based on the solar and price forecast. */

core/site.go

@@ -867,6 +867,12 @@ func (site *Site) updateBatteryMeters() {
 		}
 		return *m.Energy
 	})
+	site.battery.ReturnEnergy = lo.SumBy(mm, func(m types.Measurement) float64 {
+		if m.ReturnEnergy == nil {
+			return 0
+		}
+		return *m.ReturnEnergy
+	})
 	site.battery.Devices = mm
 
 	battery := site.battery

core/types/types.go

@@ -56,10 +56,11 @@ func (m Measurement) GetTitle() string {
 }
 
 type BatteryState struct {
-	Power    float64          `json:"power"`
-	Energy   float64          `json:"energy,omitempty"`
-	Capacity float64          `json:"capacity,omitempty"`
-	Soc      float64          `json:"soc"`
-	Devices  []Measurement    `json:"devices,omitempty" influxdb:"battery"`
-	Forecast *BatteryForecast `json:"forecast,omitempty"`
+	Power        float64          `json:"power"`
+	Energy       float64          `json:"energy,omitempty"`
+	ReturnEnergy float64          `json:"returnEnergy,omitempty"`
+	Capacity     float64          `json:"capacity,omitempty"`
+	Soc          float64          `json:"soc"`
+	Devices      []Measurement    `json:"devices,omitempty" influxdb:"battery"`
+	Forecast     *BatteryForecast `json:"forecast,omitempty"`
 }

server/mcp/openapi.json

@@ -3843,7 +3843,11 @@
             "type": "number"
           },
           "energy": {
-            "description": "Total battery energy in kWh.",
+            "description": "Total discharged energy in kWh.",
+            "type": "number"
+          },
+          "returnEnergy": {
+            "description": "Total charged energy in kWh.",
             "type": "number"
           },
           "devices": {

server/mqtt_test.go

@@ -152,7 +152,7 @@ func (suite *mqttSuite) TestMeasurement() {
 
 func (suite *mqttSuite) TestBatteryState() {
 	topics := lo.Map([]string{
-		"power", "energy", "capacity", "soc",
+		"power", "energy", "returnEnergy", "capacity", "soc",
 		"devices", "devices/1/name", "devices/1/title", "devices/1/icon", "devices/1/power", "devices/1/energy", "devices/1/returnEnergy", "devices/1/powers", "devices/1/currents", "devices/1/excessDCPower", "devices/1/capacity", "devices/1/soc", "devices/1/controllable", "devices/1/suggestion",
 		"forecast",
 	}, func(s string, _ int) string {
@@ -169,5 +169,5 @@ func (suite *mqttSuite) TestBatteryState() {
 	})
 
 	suite.Equal(topics, suite.topics, "topics")
-	suite.Equal([]string{"2", "", "", "20", "1", "", "", "", "1", "", "", "", "", "", "", "10", "", "", ""}, suite.payloads, "payloads")
+	suite.Equal([]string{"2", "", "", "", "20", "1", "", "", "", "1", "", "", "", "", "", "", "10", "", "", ""}, suite.payloads, "payloads")
 }

server/openapi.state.yaml

@@ -302,7 +302,10 @@ components:
           description: Charge level in %. Weighted by capacity across all batteries.
           type: number
         energy:
-          description: Total battery energy in kWh.
+          description: Total discharged energy in kWh.
+          type: number
+        returnEnergy:
+          description: Total charged energy in kWh.
           type: number
         devices:
           description: Measurement data per battery meter.