hoffmation-base 3.8.0 → 4.0.0

package/lib/devices/dachs/dachs.d.ts

@@ -1,10 +1,10 @@
-import { iActuator, iBaseDevice, iDachsDeviceSettings, iDachsSettings } from '../../interfaces';
+import { iActuator, iBaseDevice, iDachsDeviceSettings, iDachsSettings, iFossilGeneratorSource } from '../../interfaces';
 import { DeviceCapability } from '../../enums';
 import { DachsTemperatureSensor } from './dachsTemperatureSensor';
 import { ActuatorSetStateCommand, ActuatorToggleCommand, ActuatorWriteStateToDeviceCommand, RestoreTargetAutomaticValueCommand } from '../../command';
 import { BlockAutomaticHandler } from '../../services';
 import { RoomBaseDevice } from '../RoomBaseDevice';
-export declare class Dachs extends RoomBaseDevice implements iBaseDevice, iActuator {
+export declare class Dachs extends RoomBaseDevice implements iBaseDevice, iActuator, iFossilGeneratorSource {
     /** @inheritDoc */
     settings: iDachsDeviceSettings;
     /** @inheritDoc */
@@ -47,10 +47,41 @@ export declare class Dachs extends RoomBaseDevice implements iBaseDevice, iActua
     private _tempHeatStorage;
     private fetchedData;
     private _blockStarted;
+    /** The decision of the last history gate evaluation; undefined out of season or without a charge level. */
+    private _historyGateResult;
+    private _historyGateEvaluations;
+    private _historyGateStatements;
+    private _lastGateDecision;
     /** @inheritDoc */
     get customName(): string;
     /** @inheritDoc */
     get actuatorOn(): boolean;
+    /**
+     * The unit persists its own state changes under {@link id}, so this is the id they are recorded under.
+     * @inheritDoc
+     */
+    get actuatorId(): string;
+    /**
+     * A live view of the setting rather than a copy: it is editable at runtime, and the correction of a
+     * historical day describes the unit as it is configured now.
+     * @inheritDoc
+     */
+    get ratedElectricalWattage(): number;
+    /**
+     * A live view of the setting, for the same reason as {@link ratedElectricalWattage}.
+     * @inheritDoc
+     */
+    get conversionFactor(): number;
+    /**
+     * The upper warm water temperature the Dachs is currently allowed to heat to.
+     *
+     * Only a stated warm season lowers the ceiling. The heating settings are optional and fall back to
+     * {@link HeatingMode.None}, so "not winter" covers the installation that states nothing at all - and
+     * reading that absence as summer takes the ceiling away from it the whole year round, without a switch
+     * anywhere to notice it by.
+     * @returns The applicable maximum warm water temperature in °C.
+     */
+    private get currentWarmWaterMaxTemp();
     constructor(options: iDachsSettings);
     /** @inheritDoc */
     get id(): string;
@@ -72,11 +103,57 @@ export declare class Dachs extends RoomBaseDevice implements iBaseDevice, iActua
      */
     private onBatteryLevelChange;
     private checkAllDesiredStates;
+    /**
+     * The state of charge of the plant's battery, as far as it is known.
+     * @returns The level in percent, or {@link NO_STATE_OF_CHARGE} while there is no energy manager or it
+     * carries no level - neither of which is a battery that is empty.
+     */
+    private static get currentStateOfCharge();
     private onHeatStorageTempChange;
     private onWarmWaterTempChange;
     private checkWwPumpDesiredState;
     private checkHeatingRod;
     private shouldDachsBeStarted;
+    /**
+     * What this unit makes of what the plant said about the coming morning.
+     *
+     * Its own question comes first and is the only one it answers itself: while the warm water sits below the
+     * minimum the unit is needed for heat, so energy does not decide and the plant's verdict is recorded without
+     * being acted on. Everything below that is translation - the plant judged whether the morning holds, this
+     * unit only says what it does about it.
+     *
+     * **A verdict the plant reached without its fitted model may move something, a modelled one may not.** The
+     * measured verdicts are arithmetic on the plant's own recorded consumption and carry no unmeasured
+     * assumption; the modelled one rests on a fit whose window length has never been checked against recorded
+     * data. Stage 4 therefore names which side of the reserve the band fell on and moves nothing - behaviourally
+     * the same as stage 5 and distinguishable from it only by the reason line. Whether the model beats the
+     * trivial rule is measured once, by the energy manager, over the plant's single shadow record.
+     *
+     * The stage numbers are this unit's log vocabulary rather than the plant's ladder: stage 1 is the warm water
+     * question nobody else has, stages 2 and 3 are the measured verdicts it acts on, stage 4 the modelled one it
+     * only reports, stage 5 no verdict at all.
+     * @returns The decision, or undefined while the heating mode is winter or the plant says nothing about the
+     * coming morning.
+     */
+    private evaluateHistoryGate;
+    /**
+     * Assembles a gate result and the reason line the operator reads it by.
+     * @param stage - The stage of this unit's own vocabulary that decided.
+     * @param suppress - Whether the electricity driven start is suppressed.
+     * @param request - Whether a start is asked for.
+     * @param detail - What the plant said, or what this unit answered instead.
+     * @param verdict - The plant's verdict, for the numbers the line is read by.
+     * @param lowerEdgeSoc - The projected morning charge level at the lower edge.
+     * @param upperEdgeSoc - The projected morning charge level at the upper edge.
+     * @returns The decision.
+     */
+    private static gateResult;
+    /**
+     * Writes the gate decision to the log - on info whenever the decision changed, on debug otherwise, as the
+     * evaluation runs on every battery and temperature update.
+     * @param result - The decision to log, if there is one.
+     */
+    private logHistoryGate;
     private checkAlternativeActuator;
     private onDachsRunningStateChange;
 }

package/lib/devices/dachs/dachs.js

@@ -19,6 +19,14 @@ const command_1 = require("../../command");
 const services_1 = require("../../services");
 const settings_service_1 = require("../../settings-service");
 const RoomBaseDevice_1 = require("../RoomBaseDevice");
+/**
+ * What an energy manager reports while its battery states no charge level at all - see the battery level of
+ * `victron-device.ts`, which answers with this instead of a level.
+ *
+ * A marker, not a low battery: read as a number it lands below every threshold of this unit, so whoever
+ * decides on it has to tell the two apart first.
+ */
+const NO_STATE_OF_CHARGE = -1;
 class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
     /** @inheritDoc */
     get customName() {
@@ -28,6 +36,43 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
     get actuatorOn() {
         return this._dachsOn;
     }
+    /**
+     * The unit persists its own state changes under {@link id}, so this is the id they are recorded under.
+     * @inheritDoc
+     */
+    get actuatorId() {
+        return this.id;
+    }
+    /**
+     * A live view of the setting rather than a copy: it is editable at runtime, and the correction of a
+     * historical day describes the unit as it is configured now.
+     * @inheritDoc
+     */
+    get ratedElectricalWattage() {
+        return this.settings.dachsRatedElectricalWattage;
+    }
+    /**
+     * A live view of the setting, for the same reason as {@link ratedElectricalWattage}.
+     * @inheritDoc
+     */
+    get conversionFactor() {
+        return this.settings.dachsConversionFactor;
+    }
+    /**
+     * The upper warm water temperature the Dachs is currently allowed to heat to.
+     *
+     * Only a stated warm season lowers the ceiling. The heating settings are optional and fall back to
+     * {@link HeatingMode.None}, so "not winter" covers the installation that states nothing at all - and
+     * reading that absence as summer takes the ceiling away from it the whole year round, without a switch
+     * anywhere to notice it by.
+     * @returns The applicable maximum warm water temperature in °C.
+     */
+    get currentWarmWaterMaxTemp() {
+        const mode = settings_service_1.SettingsService.heatMode;
+        return mode === enums_1.HeatingMode.Summer || mode === enums_1.HeatingMode.TransitionalSeason
+            ? this.settings.summerWarmWaterDesiredMaxTemp
+            : this.settings.warmWaterDesiredMaxTemp;
+    }
     constructor(options) {
         var _a, _b;
         const info = new DeviceInfo_1.DeviceInfo();
@@ -52,6 +97,8 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
          * The timestamp of the last time the Block was enforced.
          */
         this._blockStarted = 0;
+        this._historyGateEvaluations = 0;
+        this._historyGateStatements = 0;
         this.jsonOmitTopLevelKeys.push(...['warmWaterPump', 'heatingRod']);
         this.jsonOmitKeys.push(...[
             'client',
@@ -65,6 +112,9 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
         devices_1.Devices.alLDevices[allDevicesKey] = this;
         this.deviceCapabilities.push(enums_1.DeviceCapability.actuator);
         this.deviceCapabilities.push(enums_1.DeviceCapability.blockAutomatic);
+        // How the unit announces itself as one of the plant's fuel burning generators: whoever corrects a
+        // historical charge level for fuel burnt reads the device list, not a list handed to it by a caller.
+        this.deviceCapabilities.push(enums_1.DeviceCapability.fossilGenerator);
         if (options.influxDb) {
             this._influxClient = new lib_1.DachsInfluxClient(options.influxDb);
         }
@@ -149,7 +199,7 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
             this.settings.disableDachsOwnWW ||
             ((_a = this.warmWaterDachsAlternativeActuator) === null || _a === void 0 ? void 0 : _a.actuatorOn) ||
             this.heatStorageTempSensor.temperatureSensor.temperature < this.warmWaterSensor.temperatureSensor.temperature ||
-            this.warmWaterSensor.temperatureSensor.temperature > this.settings.warmWaterDesiredMaxTemp) {
+            this.warmWaterSensor.temperatureSensor.temperature > this.currentWarmWaterMaxTemp) {
             return;
         }
         const startPumpCommand = new command_1.ActuatorSetStateCommand(c, true, 'Dachs is starting/on');
@@ -200,6 +250,10 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
         if (this.blockAutomationHandler.automaticBlockActive) {
             return;
         }
+        // Read, not refreshed. The plant's history belongs to the energy manager, which keeps it up to date on a
+        // cadence of its own; asking here costs no query, so the decision may be taken as often as it likes.
+        this._historyGateResult = this.evaluateHistoryGate();
+        this.logHistoryGate(this._historyGateResult);
         const shouldDachsBeStarted = this.shouldDachsBeStarted(action, batteryLevel);
         this.checkHeatingRod(action, batteryLevel);
         this.checkAlternativeActuator(shouldDachsBeStarted, action);
@@ -211,13 +265,20 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
         setStateCommand.overrideCommandSource = enums_1.CommandSource.Automatic;
         this.setActuator(setStateCommand);
     }
-    onHeatStorageTempChange(action) {
+    /**
+     * The state of charge of the plant's battery, as far as it is known.
+     * @returns The level in percent, or {@link NO_STATE_OF_CHARGE} while there is no energy manager or it
+     * carries no level - neither of which is a battery that is empty.
+     */
+    static get currentStateOfCharge() {
         var _a, _b;
-        this.checkAllDesiredStates(action, (_b = (_a = devices_1.Devices.energymanager) === null || _a === void 0 ? void 0 : _a.batteryLevel) !== null && _b !== void 0 ? _b : 0);
+        return (_b = (_a = devices_1.Devices.energymanager) === null || _a === void 0 ? void 0 : _a.batteryLevel) !== null && _b !== void 0 ? _b : NO_STATE_OF_CHARGE;
+    }
+    onHeatStorageTempChange(action) {
+        this.checkAllDesiredStates(action, Dachs.currentStateOfCharge);
     }
     onWarmWaterTempChange(action) {
-        var _a, _b;
-        this.checkAllDesiredStates(action, (_b = (_a = devices_1.Devices.energymanager) === null || _a === void 0 ? void 0 : _a.batteryLevel) !== null && _b !== void 0 ? _b : 0);
+        this.checkAllDesiredStates(action, Dachs.currentStateOfCharge);
     }
     checkWwPumpDesiredState(action) {
         var _a, _b;
@@ -245,9 +306,9 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
             desiredWwPumpState = false;
             reason = `Temperature of warm water pump ${wwTemp}°C is higher than temperature of heat storage ${heatStorageTemp}°C`;
         }
-        else if (wwTemp > this.settings.warmWaterDesiredMaxTemp) {
+        else if (wwTemp > this.currentWarmWaterMaxTemp) {
             desiredWwPumpState = false;
-            reason = `Temperature of warm water pump ${wwTemp}°C is higher than the desired max value`;
+            reason = `Temperature of warm water pump ${wwTemp}°C is higher than the desired max value of ${this.currentWarmWaterMaxTemp}°C`;
         }
         else if (this._dachsOn) {
             desiredWwPumpState = true;
@@ -298,6 +359,12 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
     shouldDachsBeStarted(action, batteryLevel) {
         var _a, _b, _c;
         const dayType = services_1.TimeCallbackService.dayType(new models_1.SunTimeOffsets());
+        /**
+         * Set where the empty battery earns the release of the start block. Both the release and the block that
+         * may take its place are written further down, behind the heat driven branches - a decision taken before
+         * them could either swallow a heat driven start or leave the block standing while one happens.
+         */
+        let emptyBatteryEarnsRelease = false;
         if (this.blockDachsStart !== undefined) {
             if (this.settings.disableDachsTemporarily) {
                 const blockAction = new command_1.ActuatorSetStateCommand(action, true, `Dachs is disabled temporarily`, null);
@@ -322,10 +389,12 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
                 return false;
             }
             else if (batteryLevel < this.settings.batteryLevelAllowStartThreshold) {
-                const liftAction = new command_1.ActuatorSetStateCommand(action, false, `Battery reached ${batteryLevel}%, Dachs is now allowed to run if needed`, null);
-                this.blockDachsStart.setActuator(liftAction);
+                // The empty battery earns a release here, but nothing is written yet: whether the release happens
+                // or a block takes its place is decided behind the heat driven branches, so that neither outcome
+                // can reach around a heat driven start.
+                emptyBatteryEarnsRelease = true;
             }
-            else if (utils_1.Utils.nowMS() - this._blockStarted > 180 * 60 * 60 &&
+            else if (utils_1.Utils.nowMS() - this._blockStarted > 3 * 60 * 60 * 1000 &&
                 (((_a = settings_service_1.SettingsService.settings.heaterSettings) === null || _a === void 0 ? void 0 : _a.mode) === enums_1.HeatingMode.Winter ||
                     this.warmWaterDachsAlternativeActuator === undefined)) {
                 const liftAction = new command_1.ActuatorSetStateCommand(action, false, `Battery is at ${batteryLevel}%, but Dachs wasn't allowed to run for 3 hours, Dachs is now allowed to run if needed`, null);
@@ -342,17 +411,49 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
                 return false;
             }
         }
-        if (this._dachsOn) {
+        const alreadyRunning = this._dachsOn;
+        // The heat driven decision is taken but not returned yet, so that the block actuator below is written
+        // with it already known.
+        let heatDrivenStart = undefined;
+        if (!alreadyRunning) {
+            if (((_c = settings_service_1.SettingsService.settings.heaterSettings) === null || _c === void 0 ? void 0 : _c.mode) === enums_1.HeatingMode.Winter &&
+                this.heatStorageTempSensor.temperatureSensor.temperature < this.settings.winterMinimumHeatStorageTemp) {
+                // It is winter and heat storage is kinda cold --> Start
+                heatDrivenStart = true;
+            }
+            else if (this.heatStorageTempSensor.temperatureSensor.temperature > this.settings.heatStorageMaxStartTemp) {
+                // Heat Storage is already quite full, don't start
+                heatDrivenStart = false;
+            }
+        }
+        // Everything above is heat driven and stays untouched; from here on the decision is electricity driven,
+        // which is the only branch the history gate speaks about. The gate is read - and the block actuator
+        // written - only at this point, so neither of its two directions can reach around a heat driven decision.
+        const gate = this._historyGateResult;
+        const gateSuppresses = heatDrivenStart === undefined && (gate === null || gate === void 0 ? void 0 : gate.suppress) === true;
+        if (emptyBatteryEarnsRelease && this.blockDachsStart !== undefined) {
+            if (gateSuppresses) {
+                const gateBlockAction = new command_1.ActuatorSetStateCommand(action, true, `History gate suppresses the start - ${gate === null || gate === void 0 ? void 0 : gate.reason}`, null);
+                gateBlockAction.overrideCommandSource = enums_1.CommandSource.Force;
+                this.blockDachsStart.setActuator(gateBlockAction);
+                this._blockStarted = utils_1.Utils.nowMS();
+            }
+            else {
+                const liftAction = new command_1.ActuatorSetStateCommand(action, false, `Battery reached ${batteryLevel}%, Dachs is now allowed to run if needed`, null);
+                this.blockDachsStart.setActuator(liftAction);
+            }
+        }
+        if (alreadyRunning) {
             // We are already running
             return false;
         }
-        if (((_c = settings_service_1.SettingsService.settings.heaterSettings) === null || _c === void 0 ? void 0 : _c.mode) === enums_1.HeatingMode.Winter &&
-            this.heatStorageTempSensor.temperatureSensor.temperature < this.settings.winterMinimumHeatStorageTemp) {
-            // It is winter and heat storage is kinda cold --> Start
+        if (heatDrivenStart !== undefined) {
+            return heatDrivenStart;
+        }
+        if ((gate === null || gate === void 0 ? void 0 : gate.request) === true) {
             return true;
         }
-        else if (this.heatStorageTempSensor.temperatureSensor.temperature > this.settings.heatStorageMaxStartTemp) {
-            // Heat Storage is already quite full, don't start
+        if (gateSuppresses) {
             return false;
         }
         if ((dayType === enums_1.TimeOfDay.Daylight || dayType === enums_1.TimeOfDay.BeforeSunrise) &&
@@ -366,6 +467,102 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
         }
         return !this.settings.blockAutomaticSettings;
     }
+    /**
+     * What this unit makes of what the plant said about the coming morning.
+     *
+     * Its own question comes first and is the only one it answers itself: while the warm water sits below the
+     * minimum the unit is needed for heat, so energy does not decide and the plant's verdict is recorded without
+     * being acted on. Everything below that is translation - the plant judged whether the morning holds, this
+     * unit only says what it does about it.
+     *
+     * **A verdict the plant reached without its fitted model may move something, a modelled one may not.** The
+     * measured verdicts are arithmetic on the plant's own recorded consumption and carry no unmeasured
+     * assumption; the modelled one rests on a fit whose window length has never been checked against recorded
+     * data. Stage 4 therefore names which side of the reserve the band fell on and moves nothing - behaviourally
+     * the same as stage 5 and distinguishable from it only by the reason line. Whether the model beats the
+     * trivial rule is measured once, by the energy manager, over the plant's single shadow record.
+     *
+     * The stage numbers are this unit's log vocabulary rather than the plant's ladder: stage 1 is the warm water
+     * question nobody else has, stages 2 and 3 are the measured verdicts it acts on, stage 4 the modelled one it
+     * only reports, stage 5 no verdict at all.
+     * @returns The decision, or undefined while the heating mode is winter or the plant says nothing about the
+     * coming morning.
+     */
+    evaluateHistoryGate() {
+        var _a, _b;
+        if (((_a = settings_service_1.SettingsService.settings.heaterSettings) === null || _a === void 0 ? void 0 : _a.mode) === enums_1.HeatingMode.Winter) {
+            // During winter operation the heat demand decides when the unit runs, so the gate stays out of it.
+            return undefined;
+        }
+        // An absent verdict covers the installation without an energy manager, the one whose battery reports no
+        // charge level and the one whose manager states no reserve to judge against. The unit does not tell them
+        // apart: in none of them is there a judgement to act on, and the stock ladder below then decides as it did
+        // before the gate existed. Not logged here either - the plant already says why it stays silent, and this
+        // runs on every battery and temperature update.
+        const verdict = (_b = devices_1.Devices.energymanager) === null || _b === void 0 ? void 0 : _b.morningReserveVerdict;
+        if (verdict === undefined) {
+            return undefined;
+        }
+        this._historyGateEvaluations++;
+        if (verdict.modelFitted) {
+            this._historyGateStatements++;
+        }
+        const warmWater = this.warmWaterSensor.temperatureSensor.temperature;
+        if (warmWater < this.settings.warmWaterDesiredMinTemp) {
+            // The band of a verdict that was not acted on would read as though it had been; the line collapses onto
+            // the charge level instead, which is what "energy did not decide this" looks like in the log.
+            return Dachs.gateResult(1, false, false, `warm water ${warmWater}°C is below the minimum ${this.settings.warmWaterDesiredMinTemp}°C`, verdict, verdict.currentSoc, verdict.currentSoc);
+        }
+        if (verdict.holds === undefined) {
+            return Dachs.gateResult(5, false, false, verdict.reason, verdict, verdict.band.lower, verdict.band.upper);
+        }
+        if (!verdict.measured) {
+            return Dachs.gateResult(4, false, false, `${verdict.reason}, which this unit does not act on`, verdict, verdict.band.lower, verdict.band.upper);
+        }
+        return verdict.holds
+            ? Dachs.gateResult(2, true, false, verdict.reason, verdict, verdict.band.lower, verdict.band.upper)
+            : Dachs.gateResult(3, false, true, verdict.reason, verdict, verdict.band.lower, verdict.band.upper);
+    }
+    /**
+     * Assembles a gate result and the reason line the operator reads it by.
+     * @param stage - The stage of this unit's own vocabulary that decided.
+     * @param suppress - Whether the electricity driven start is suppressed.
+     * @param request - Whether a start is asked for.
+     * @param detail - What the plant said, or what this unit answered instead.
+     * @param verdict - The plant's verdict, for the numbers the line is read by.
+     * @param lowerEdgeSoc - The projected morning charge level at the lower edge.
+     * @param upperEdgeSoc - The projected morning charge level at the upper edge.
+     * @returns The decision.
+     */
+    static gateResult(stage, suppress, request, detail, verdict, lowerEdgeSoc, upperEdgeSoc) {
+        return {
+            suppress,
+            request,
+            reason: `Stage ${stage}: ${detail} (soc ${utils_1.Utils.round(verdict.currentSoc, 2)}%, band ` +
+                `${utils_1.Utils.round(lowerEdgeSoc, 2)}%..${utils_1.Utils.round(upperEdgeSoc, 2)}%, reserve ${verdict.reserve}%, ` +
+                `${verdict.sampleDays} days)`,
+            currentSoc: verdict.currentSoc,
+            lowerEdgeSoc,
+            upperEdgeSoc,
+            reserve: verdict.reserve,
+            sampleDays: verdict.sampleDays,
+        };
+    }
+    /**
+     * Writes the gate decision to the log - on info whenever the decision changed, on debug otherwise, as the
+     * evaluation runs on every battery and temperature update.
+     * @param result - The decision to log, if there is one.
+     */
+    logHistoryGate(result) {
+        if (result === undefined) {
+            return;
+        }
+        const decision = `${result.suppress}/${result.request}`;
+        const changed = decision !== this._lastGateDecision;
+        this._lastGateDecision = decision;
+        this.log(changed ? enums_1.LogLevel.Info : enums_1.LogLevel.Debug, `History gate: ${result.reason}; a statement was possible in ${this._historyGateStatements} of ` +
+            `${this._historyGateEvaluations} evaluations`);
+    }
     checkAlternativeActuator(shouldDachsBeStarted, action) {
         var _a, _b;
         if (!this.warmWaterDachsAlternativeActuator) {
@@ -397,8 +594,7 @@ class Dachs extends RoomBaseDevice_1.RoomBaseDevice {
         this.warmWaterDachsAlternativeActuator.setActuator(command);
     }
     onDachsRunningStateChange(runStateChange) {
-        var _a, _b;
-        this.checkAllDesiredStates(runStateChange, (_b = (_a = devices_1.Devices.energymanager) === null || _a === void 0 ? void 0 : _a.batteryLevel) !== null && _b !== void 0 ? _b : 0);
+        this.checkAllDesiredStates(runStateChange, Dachs.currentStateOfCharge);
     }
 }
 exports.Dachs = Dachs;

package/lib/devices/devices.d.ts

@@ -1,4 +1,4 @@
-import { iBaseDevice, iConfig, iDeviceConfig, iEnergyManager, iRoomImportEnforcer, iTemperatureCollector } from '../interfaces';
+import { iBaseDevice, iConfig, iDeviceConfig, iEnergyManager, iFossilGeneratorSource, iRoomImportEnforcer, iTemperatureCollector } from '../interfaces';
 import { Dachs } from './dachs';
 import { UnifiAccess, UnifiProtect } from './unifi';
 export declare class Devices {
@@ -67,9 +67,44 @@ export declare class Devices {
      * A reference to the Unifi Access device
      */
     static unifiAccess?: UnifiAccess;
+    /**
+     * The devices already reported as announcing a fuel burning generator without stating the fields of one,
+     * so the line is written on change instead of on every read of {@link fossilGenerators}.
+     */
+    private static readonly _incompleteGeneratorsReported;
     constructor(pDeviceData: {
         [id: string]: iDeviceConfig;
     }, pRoomImportEnforcer?: iRoomImportEnforcer, config?: iConfig);
+    /**
+     * The fuel burning generators of the plant - every device that announced itself as one by carrying
+     * {@link DeviceCapability.fossilGenerator}.
+     *
+     * Which generators a plant has is a property of the plant, not of whoever asks about it, so it is answered
+     * here rather than handed to a service by one of its callers. Reading the device list instead of keeping a
+     * list of registrations is what makes it independent of construction order: devices are built in the order
+     * the installation's configuration lists them, and a generator built before the reader would have to hope
+     * the reader existed already.
+     *
+     * Read anew on every use for the same reason - a generator added later is simply found the next time, and
+     * the two numbers of each entry are getters onto settings that are editable at runtime.
+     *
+     * The capability announces the intent, the three fields are what the correction actually works with, and
+     * both are checked. Cast into the role unchecked, a device that carries the capability without the fields
+     * hands over `undefined`, the correction turns into `NaN` and its entry is dropped without a word - the
+     * day is then under corrected, the photovoltaic looks better than it was, and the gate suppresses a start
+     * the house needed. That is the direction without a way back, so such a device is left out and named.
+     * @returns One entry per usable generator; empty while the plant has none.
+     */
+    static get fossilGenerators(): iFossilGeneratorSource[];
+    /**
+     * Names a device that announces itself as a fuel burning generator without stating what one has to state.
+     *
+     * Said once per device rather than once per read: this list is read on every history load, and a line per
+     * read would bury the change. The note is dropped again as soon as the device answers completely, so a
+     * field that only arrives later is not reported forever.
+     * @param key - The key the device is listed under.
+     */
+    private static reportIncompleteGenerator;
     static midnightReset(): void;
     static resetDetectionsToday(): void;
     static getBatteryInfo(): string;

package/lib/devices/devices.js

@@ -61,6 +61,65 @@ class Devices {
         shelly_1.ShellyDevice.checkMissing();
         tuya_1.TuyaDevice.checkMissing();
     }
+    /**
+     * The fuel burning generators of the plant - every device that announced itself as one by carrying
+     * {@link DeviceCapability.fossilGenerator}.
+     *
+     * Which generators a plant has is a property of the plant, not of whoever asks about it, so it is answered
+     * here rather than handed to a service by one of its callers. Reading the device list instead of keeping a
+     * list of registrations is what makes it independent of construction order: devices are built in the order
+     * the installation's configuration lists them, and a generator built before the reader would have to hope
+     * the reader existed already.
+     *
+     * Read anew on every use for the same reason - a generator added later is simply found the next time, and
+     * the two numbers of each entry are getters onto settings that are editable at runtime.
+     *
+     * The capability announces the intent, the three fields are what the correction actually works with, and
+     * both are checked. Cast into the role unchecked, a device that carries the capability without the fields
+     * hands over `undefined`, the correction turns into `NaN` and its entry is dropped without a word - the
+     * day is then under corrected, the photovoltaic looks better than it was, and the gate suppresses a start
+     * the house needed. That is the direction without a way back, so such a device is left out and named.
+     * @returns One entry per usable generator; empty while the plant has none.
+     */
+    static get fossilGenerators() {
+        const generators = [];
+        for (const key in Devices.alLDevices) {
+            const device = Devices.alLDevices[key];
+            if (!device.deviceCapabilities.includes(enums_1.DeviceCapability.fossilGenerator)) {
+                continue;
+            }
+            const candidate = device;
+            // Finiteness rather than a plausible range: a negative or zero rating over corrects, which only makes
+            // the photovoltaic look worse, while an absent one poisons the whole sum of the day.
+            if (typeof candidate.actuatorId !== 'string' ||
+                candidate.actuatorId === '' ||
+                !Number.isFinite(candidate.ratedElectricalWattage) ||
+                !Number.isFinite(candidate.conversionFactor)) {
+                Devices.reportIncompleteGenerator(key);
+                continue;
+            }
+            Devices._incompleteGeneratorsReported.delete(key);
+            generators.push(candidate);
+        }
+        return generators;
+    }
+    /**
+     * Names a device that announces itself as a fuel burning generator without stating what one has to state.
+     *
+     * Said once per device rather than once per read: this list is read on every history load, and a line per
+     * read would bury the change. The note is dropped again as soon as the device answers completely, so a
+     * field that only arrives later is not reported forever.
+     * @param key - The key the device is listed under.
+     */
+    static reportIncompleteGenerator(key) {
+        if (Devices._incompleteGeneratorsReported.has(key)) {
+            return;
+        }
+        Devices._incompleteGeneratorsReported.add(key);
+        logging_1.ServerLogService.writeLog(enums_1.LogLevel.Error, `Device '${key}' announces itself as a fuel burning generator but states no usable actuator id, rated ` +
+            'wattage and conversion factor, so nothing is subtracted for it and the photovoltaic looks better ' +
+            'than it was');
+    }
     static midnightReset() {
         // Nothing yet
     }
@@ -375,3 +434,8 @@ Devices.dachs = undefined;
  * @default undefined (no warm water temperature sensor)
  */
 Devices.temperatureWarmWater = undefined;
+/**
+ * The devices already reported as announcing a fuel burning generator without stating the fields of one,
+ * so the line is written on change instead of on every read of {@link fossilGenerators}.
+ */
+Devices._incompleteGeneratorsReported = new Set();

package/lib/devices/jsObject/jsObjectEnergyManager.d.ts

@@ -1,5 +1,5 @@
 import { IoBrokerBaseDevice } from '../IoBrokerBaseDevice';
-import { iDisposable, iEnergyManager, iExcessEnergyConsumer } from '../../interfaces';
+import { iDisposable, iEnergyHistoryOutlook, iEnergyManager, iExcessEnergyConsumer, iMorningReserveVerdict } from '../../interfaces';
 import { IoBrokerDeviceInfo } from '../IoBrokerDeviceInfo';
 import { PhaseState } from '../models';
 export declare class JsObjectEnergyManager extends IoBrokerBaseDevice implements iEnergyManager, iDisposable {
@@ -24,6 +24,21 @@ export declare class JsObjectEnergyManager extends IoBrokerBaseDevice implements
     get excessEnergy(): number;
     /** @inheritDoc */
     get acBlocked(): boolean;
+    /**
+     * The same shared implementation the other energy manager delegates to - not a stub, and not a copy. This
+     * manager measures three phases and carries neither a battery nor the dials that say how a history is read,
+     * so the shared code answers nothing for it and reads nothing for it either. That is the honest answer and
+     * the one an installation on this manager already got; it is reached by running the real path rather than
+     * by declaring it here.
+     * @inheritDoc
+     */
+    get morningOutlook(): iEnergyHistoryOutlook | undefined;
+    /**
+     * Delegated for the same reason {@link morningOutlook} is - and it answers nothing here for the same reason
+     * too: this manager states neither the reserve nor the sun threshold a verdict would be measured against.
+     * @inheritDoc
+     */
+    get morningReserveVerdict(): iMorningReserveVerdict | undefined;
     private _excessEnergyConsumerConsumption;
     /**
      * Example:

package/lib/devices/jsObject/jsObjectEnergyManager.js

@@ -62,6 +62,25 @@ class JsObjectEnergyManager extends IoBrokerBaseDevice_1.IoBrokerBaseDevice {
     get acBlocked() {
         return this.excessEnergy < 200;
     }
+    /**
+     * The same shared implementation the other energy manager delegates to - not a stub, and not a copy. This
+     * manager measures three phases and carries neither a battery nor the dials that say how a history is read,
+     * so the shared code answers nothing for it and reads nothing for it either. That is the honest answer and
+     * the one an installation on this manager already got; it is reached by running the real path rather than
+     * by declaring it here.
+     * @inheritDoc
+     */
+    get morningOutlook() {
+        return utils_1.EnergyManagerUtils.morningOutlook(this);
+    }
+    /**
+     * Delegated for the same reason {@link morningOutlook} is - and it answers nothing here for the same reason
+     * too: this manager states neither the reserve nor the sun threshold a verdict would be measured against.
+     * @inheritDoc
+     */
+    get morningReserveVerdict() {
+        return utils_1.EnergyManagerUtils.morningReserveVerdict(this, this.morningOutlook);
+    }
     /**
      * Example:
      * ________________________________________
@@ -137,6 +156,10 @@ class JsObjectEnergyManager extends IoBrokerBaseDevice_1.IoBrokerBaseDevice {
         }
     }
     calculateExcessEnergy() {
+        // The same call the other manager's loop makes, so whether anything is read is decided in one place
+        // rather than by which manager happens to ask. This one states no dials, so nothing is read and no
+        // request quota is spent.
+        utils_1.EnergyManagerUtils.refreshEnergyHistory(this);
         const phaseProduction = this._currentProduction / 3.0;
         this._phaseAState = new models_2.PhaseState(this._powerValuePhaseA, phaseProduction);
         this._phaseBState = new models_2.PhaseState(this._powerValuePhaseB, phaseProduction);