Merge pull request #88 from longzheng/battery-charge-buffer

Implement battery charge buffer

Author: longzheng

config.schema.json

@@ -506,6 +506,20 @@
           },
           "additionalProperties": false,
           "description": "Publish active control limits"
+        },
+        "battery": {
+          "type": "object",
+          "properties": {
+            "chargeBufferWatts": {
+              "type": "number",
+              "description": "A minimum buffer to allow the battery to charge if export limit would otherwise have prevented the battery from charging"
+            }
+          },
+          "required": [
+            "chargeBufferWatts"
+          ],
+          "additionalProperties": false,
+          "description": "Battery configuration"
         }
       },
       "required": [

docs/.vitepress/config.ts

@@ -38,6 +38,7 @@ export default withMermaid(
                         { text: 'Site meter', link: '/configuration/meter' },
                         { text: 'Setpoints', link: '/configuration/setpoints' },
                         { text: 'Publish', link: '/configuration/publish' },
+                        { text: 'Battery', link: '/configuration/battery' },
                     ],
                 },
                 {

docs/configuration/battery.md

@@ -0,0 +1,27 @@
+# Battery
+
+An **optional** battery can be configured to adjust the controller behaviour.
+
+[[toc]]
+
+## Charge buffer
+
+In export limited scenarios, a "solar soaking" battery may not be able to charge correctly if the export limit is very low or zero. To allow the battery to charge, a minimum charge buffer can be configured which will override the export limit if it is below the configured watts.
+
+To configure a charge buffer, add the following property to `config.json`
+
+```js
+{
+    "battery": {
+        "chargeBufferWatts": 100 // (number) required: the minimum charge buffer in watts
+    }
+    ...
+}
+```
+
+> [!IMPORTANT]
+> Users on dynamic export connections MUST NOT set a high charge buffer which may violate your connection agreement for dynamic export limits.
+
+**Why doesn't the controller know if the battery is charged?**
+
+Since the controller does not have direct control of batteries (especially batteries without an API e.g. Tesla Powerwall), it is not possible to know if the battery is configured for charging. Even if the battery SOC is known, it is possible the battery may be configured with a lower SOC cap or VPP mode which overrides the charging behaviour.

src/coordinator/helpers/inverterController.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from 'vitest';
+import { type ActiveInverterControlLimit } from './inverterController.js';
 import {
+    adjustActiveInverterControlForBatteryCharging,
     calculateTargetSolarPowerRatio,
     calculateTargetSolarWatts,
     getActiveInverterControlLimit,
@@ -236,3 +238,88 @@ describe('getActiveInverterControlLimit', () => {
         } satisfies typeof inverterControlLimit);
     });
 });
+
+describe('adjustActiveInverterControlForBatteryCharging', () => {
+    it('should return the original limit if opModExpLimW is undefined', () => {
+        const activeInverterControlLimit: ActiveInverterControlLimit = {
+            opModEnergize: undefined,
+            opModConnect: undefined,
+            opModGenLimW: undefined,
+            opModExpLimW: undefined,
+            opModImpLimW: undefined,
+            opModLoadLimW: undefined,
+        };
+        const result = adjustActiveInverterControlForBatteryCharging({
+            activeInverterControlLimit,
+            batteryChargeBufferWatts: 100,
+        });
+        expect(result.opModExpLimW?.value).toEqual(undefined);
+    });
+
+    it('should return the original limit if opModExpLimW is greater than the buffer', () => {
+        const activeInverterControlLimit: ActiveInverterControlLimit = {
+            opModEnergize: undefined,
+            opModConnect: undefined,
+            opModGenLimW: undefined,
+            opModExpLimW: { source: 'fixed', value: 200 },
+            opModImpLimW: undefined,
+            opModLoadLimW: undefined,
+        };
+        const result = adjustActiveInverterControlForBatteryCharging({
+            activeInverterControlLimit,
+            batteryChargeBufferWatts: 100,
+        });
+        expect(result.opModExpLimW?.value).toEqual(200);
+    });
+
+    it('should return the original limit if opModExpLimW is equal to the buffer', () => {
+        const activeInverterControlLimit: ActiveInverterControlLimit = {
+            opModEnergize: undefined,
+            opModConnect: undefined,
+            opModGenLimW: undefined,
+            opModExpLimW: { source: 'fixed', value: 100 },
+            opModImpLimW: undefined,
+            opModLoadLimW: undefined,
+        };
+        const result = adjustActiveInverterControlForBatteryCharging({
+            activeInverterControlLimit,
+            batteryChargeBufferWatts: 100,
+        });
+        expect(result.opModExpLimW?.value).toEqual(100);
+    });
+
+    it('should adjust the limit if opModExpLimW is less than the buffer', () => {
+        const activeInverterControlLimit: ActiveInverterControlLimit = {
+            opModEnergize: undefined,
+            opModConnect: undefined,
+            opModGenLimW: undefined,
+            opModExpLimW: { source: 'batteryChargeBuffer', value: 0 },
+            opModImpLimW: undefined,
+            opModLoadLimW: undefined,
+        };
+        const result = adjustActiveInverterControlForBatteryCharging({
+            activeInverterControlLimit,
+            batteryChargeBufferWatts: 100,
+        });
+        expect(result.opModExpLimW?.value).toBe(100);
+    });
+
+    it('should not affect the other limits', () => {
+        const activeInverterControlLimit: ActiveInverterControlLimit = {
+            opModEnergize: { source: 'fixed', value: true },
+            opModConnect: { source: 'fixed', value: true },
+            opModGenLimW: { source: 'fixed', value: 1000 },
+            opModExpLimW: { source: 'fixed', value: 0 },
+            opModImpLimW: { source: 'fixed', value: 1000 },
+            opModLoadLimW: { source: 'fixed', value: 1000 },
+        };
+        const result = adjustActiveInverterControlForBatteryCharging({
+            activeInverterControlLimit,
+            batteryChargeBufferWatts: 100,
+        });
+        expect(result).toEqual({
+            ...activeInverterControlLimit,
+            opModExpLimW: { source: 'batteryChargeBuffer', value: 100 },
+        });
+    });
+});

src/coordinator/helpers/inverterController.ts

@@ -39,7 +39,8 @@ export type InverterControlTypes =
     | 'mqtt'
     | 'csipAus'
     | 'twoWayTariff'
-    | 'negativeFeedIn';
+    | 'negativeFeedIn'
+    | 'batteryChargeBuffer';
 
 export type InverterControlLimit = {
     source: InverterControlTypes;
@@ -98,6 +99,7 @@ export class InverterController {
     private controlLimitsLoopTimer: NodeJS.Timeout | null = null;
     private applyControlLoopTimer: NodeJS.Timeout | null = null;
     private abortController: AbortController;
+    private batteryChargeBufferWatts: number | null = null;
 
     constructor({
         config,
@@ -113,6 +115,8 @@ export class InverterController {
         this.publish = new Publish({ config });
         this.secondsToSample = config.inverterControl.sampleSeconds;
         this.intervalSeconds = config.inverterControl.intervalSeconds;
+        this.batteryChargeBufferWatts =
+            config.battery?.chargeBufferWatts ?? null;
         this.setpoints = setpoints;
         this.logger = pinoLogger.child({ module: 'InverterController' });
         this.abortController = new AbortController();
@@ -305,10 +309,36 @@ export class InverterController {
             ...recentDerSamples.map((sample) => sample.invertersCount),
         );
 
+        const batteryAdjustedInverterControlLimit = (() => {
+            const batteryChargeBufferWatts = this.batteryChargeBufferWatts;
+
+            if (batteryChargeBufferWatts === null) {
+                return this.controlLimitsCache.activeInverterControlLimit;
+            }
+
+            const adjustedInverterControlLimit =
+                adjustActiveInverterControlForBatteryCharging({
+                    activeInverterControlLimit:
+                        this.controlLimitsCache.activeInverterControlLimit,
+                    batteryChargeBufferWatts,
+                });
+
+            this.logger.info(
+                {
+                    activeInverterControlLimit:
+                        this.controlLimitsCache.activeInverterControlLimit,
+                    batteryChargeBufferWatts,
+                    adjustedInverterControlLimit,
+                },
+                'Adjusted active inverter control limit for battery charging',
+            );
+
+            return adjustedInverterControlLimit;
+        })();
+
         const rampedInverterConfiguration = ((): InverterConfiguration => {
             const configuration = calculateInverterConfiguration({
-                activeInverterControlLimit:
-                    this.controlLimitsCache.activeInverterControlLimit,
+                activeInverterControlLimit: batteryAdjustedInverterControlLimit,
                 nameplateMaxW: averagedNameplateMaxW,
                 siteWatts: averagedSiteWatts,
                 solarWatts: averagedSolarWatts,
@@ -688,3 +718,27 @@ export function getActiveInverterControlLimit(
         opModLoadLimW,
     };
 }
+
+export function adjustActiveInverterControlForBatteryCharging({
+    activeInverterControlLimit,
+    batteryChargeBufferWatts,
+}: {
+    activeInverterControlLimit: ActiveInverterControlLimit;
+    batteryChargeBufferWatts: number;
+}): ActiveInverterControlLimit {
+    if (
+        activeInverterControlLimit.opModExpLimW !== undefined &&
+        activeInverterControlLimit.opModExpLimW.value < batteryChargeBufferWatts
+    ) {
+        // adjust the export limit value to the battery charge buffer watts
+        return {
+            ...activeInverterControlLimit,
+            opModExpLimW: {
+                source: 'batteryChargeBuffer',
+                value: batteryChargeBufferWatts,
+            },
+        };
+    }
+
+    return activeInverterControlLimit;
+}

src/helpers/config.ts

@@ -313,6 +313,16 @@ A longer time will smooth out load changes but may result in overshoot.`,
         })
         .describe('Publish active control limits')
         .optional(),
+    battery: z
+        .object({
+            chargeBufferWatts: z
+                .number()
+                .describe(
+                    'A minimum buffer to allow the battery to charge if export limit would otherwise have prevented the battery from charging',
+                ),
+        })
+        .describe('Battery configuration')
+        .optional(),
 });
 
 export type Config = z.infer<typeof configSchema>;

src/ui/gen/api.d.ts

@@ -2005,7 +2005,7 @@ export interface components {
             date: string;
         };
         /** @enum {string} */
-        InverterControlTypes: "fixed" | "mqtt" | "csipAus" | "twoWayTariff" | "negativeFeedIn";
+        InverterControlTypes: "fixed" | "mqtt" | "csipAus" | "twoWayTariff" | "negativeFeedIn" | "batteryChargeBuffer";
         InverterControlLimit: {
             /** Format: double */
             opModLoadLimW?: number;

src/ui/routes/index.lazy.tsx

@@ -726,6 +726,8 @@ function LimitCard({
                                 return 'Utility dynamic connection';
                             case 'twoWayTariff':
                                 return 'Two-way tariff';
+                            case 'batteryChargeBuffer':
+                                return 'Battery charge buffer';
                             case undefined:
                                 return '';
                         }