hoffmation-base 3.8.0 → 4.0.0

package/lib/devices/victron/victron-device.d.ts

@@ -1,9 +1,14 @@
-import { iBatteryDevice, iEnergyManager, iExcessEnergyConsumer, iJsonOmitKeys } from '../../interfaces';
+import { iBatteryDevice, iEnergyHistoryOutlook, iEnergyManager, iExcessEnergyConsumer, iJsonOmitKeys, iMorningReserveVerdict } from '../../interfaces';
 import { VictronDeviceSettings } from '../../settingsObjects';
 import { Battery } from '../sharedFunctions';
 import { VictronDeviceData, VictronMqttConnectionOptions, VictronMqttConsumer } from 'victron-mqtt-consumer';
 import { BaseDevice } from '../BaseDevice';
 export declare class VictronDevice extends BaseDevice implements iEnergyManager, iBatteryDevice, iJsonOmitKeys {
+    /**
+     * The shortest horizon the battery reservation is spread over, in hours. Not a setting: it is a bound on
+     * the arithmetic rather than a dial of the plant - see {@link VictronDevice.reserveHorizonHours}.
+     */
+    private static readonly minimumReserveHorizonHours;
     /** @inheritDoc */
     readonly settings: VictronDeviceSettings;
     /** @inheritDoc */
@@ -17,11 +22,28 @@ export declare class VictronDevice extends BaseDevice implements iEnergyManager,
     private _lastPersistenceCalculation;
     private _nextPersistEntry;
     private _excessEnergy;
+    /** The last reported release state, so the five second loop writes a line on change, not on every pass. */
+    private _lastReleaseLine;
     constructor(opts: VictronMqttConnectionOptions);
     /** @inheritDoc */
     get acBlocked(): boolean;
     /** @inheritDoc */
     get batteryLevel(): number;
+    /**
+     * Delegated rather than written here, exactly the way this device delegates its consumer switching to
+     * {@link EnergyManagerUtils.turnOnAdditionalConsumer}: the answer is about the **plant**, and every energy
+     * manager owes the same one - so it is written once and no manager is left with a copy or a stub. What this
+     * device keeps for itself is the policy: the rungs, the reservation and the ac block.
+     * @inheritDoc
+     */
+    get morningOutlook(): iEnergyHistoryOutlook | undefined;
+    /**
+     * Delegated for the same reason {@link morningOutlook} is: the judgement is about the plant's battery and
+     * every manager owes the same one. What this device keeps for itself is what it *does* with the verdict -
+     * the reservation and the ac block below.
+     * @inheritDoc
+     */
+    get morningReserveVerdict(): iMorningReserveVerdict | undefined;
     get victronConsumer(): VictronMqttConsumer;
     get data(): VictronDeviceData;
     get excessEnergy(): number;
@@ -33,6 +55,7 @@ export declare class VictronDevice extends BaseDevice implements iEnergyManager,
     addExcessConsumer(device: iExcessEnergyConsumer): void;
     /** @inheritDoc */
     dispose(): void;
+    /** @inheritDoc */
     getReport(): string;
     recalculatePowerSharing(): void;
     toJSON(): Partial<VictronDevice>;
@@ -42,6 +65,65 @@ export declare class VictronDevice extends BaseDevice implements iEnergyManager,
      */
     setGridSetPoint(setPoint: number): void;
     private calculateExcessEnergy;
+    /**
+     * Rung 1, the only rung of the recorded history that decides: if the state of charge carries past the
+     * coming morning low even when no further yield arrives, nothing has to be held back and no consumer has to
+     * be kept off.
+     *
+     * This manager's own policy and rightly here rather than in the shared utils: what a plant does with the
+     * outlook is the manager's judgement, and the reservation and ac block it feeds are this device's.
+     *
+     * Arithmetic over the plant's own measured consumption - no fit, no weights, no window length. That is what
+     * separates it from the rung below, which measures against the lower edge of the fitted band and therefore
+     * only records (see {@link EnergyManagerUtils.observeModelShadow}).
+     * @param outlook - What the plant said, or undefined while it cannot say anything - which includes the
+     * absent charge level, so the guard against it stays in the shared utils alone.
+     * @returns The release, or undefined while the measured consumption cannot carry it.
+     */
+    private morningRelease;
+    /**
+     * How much of the production is held back for the battery.
+     *
+     * With the release nothing is held back: the coming morning clears the reserve on measured consumption
+     * alone. Without it the calculation is the one that was here before - it aims at a full battery by sunset,
+     * which over-reserves, and that is what an installation without a usable recorded history keeps.
+     * @param released - Whether rung 1 carried the coming morning.
+     * @param hoursTilSunset - The horizon the shortfall is spread over.
+     * @returns The wattage to hold back.
+     */
+    private neededBatteryWattage;
+    /**
+     * The horizon the shortfall is actually spread over: the remaining sun hours, but never less than
+     * {@link VictronDevice.minimumReserveHorizonHours}.
+     *
+     * The raw horizon is a difference against the next sunset and runs to zero, while the part of day this
+     * calculation is entered under is derived separately from today's sunset plus its own offsets - so the two
+     * do not turn at the same instant. In the gap the divisor is first tiny and then negative: a shortfall of a
+     * few percent becomes a rate in the megawatt range, at exactly zero an `Infinity` that leaves the process
+     * through `toJSON`, and past the turn a *negative* reservation that is added to the excess and offers
+     * energy the plant does not have. Every five seconds, and since the horizon is counted in hours rather than
+     * minutes, sixty times as large as when this was harmless.
+     *
+     * The bound is a rate bound, not a schedule: below half an hour of daylight there is nothing left to charge
+     * in, so the quotient stops describing a charging rate and only its magnitude still moves. Half an hour
+     * caps the reservation at twice the battery capacity per hour - still above anything the plant can take in,
+     * therefore never loosening a reservation that was meaningful, while keeping the value finite and signed
+     * the way the rest of the calculation assumes.
+     * @param hoursTilSunset - The raw remaining sun hours, which may be zero or negative.
+     * @returns The horizon to divide by, at least the minimum.
+     */
+    private reserveHorizonHours;
+    /**
+     * Reports the release whenever it changes, and never otherwise: this runs every five seconds, and a line
+     * per pass would bury the change nobody must miss. The very first pass is remembered but not reported while
+     * there is no release, so an installation whose recorded history holds nothing stays silent instead of
+     * announcing its unchanged behaviour once per start.
+     *
+     * Named after the reserve rather than after the reservation, because the same release also answers the ac
+     * block - and it does so around the clock, while the reservation only applies in daylight.
+     * @param release - The release of this pass, or undefined while the measured consumption cannot carry one.
+     */
+    private logMorningRelease;
     private turnOnAdditionalConsumer;
     private turnOffAdditionalConsumer;
     private persist;

package/lib/devices/victron/victron-device.js

@@ -50,6 +50,16 @@ class VictronDevice extends BaseDevice_1.BaseDevice {
         if (!this.settings.hasBattery) {
             return false;
         }
+        if (this.morningRelease(this.morningOutlook) !== undefined) {
+            // Where the plant's measured consumption alone shows the coming morning clears the reserve, that
+            // statement decides and the clock does not. The ladder below is a stand-in for the same question, and
+            // its sunny morning branch cannot answer the case it was built for: it reads the day's mean cloud
+            // cover, which a day that is dull in the morning and clears up at noon never falls below.
+            //
+            // Only the release direction. Blocking on the model would mean acting on the fitted band, which is
+            // exactly what the shadow exists to defer.
+            return false;
+        }
         const hours = new Date().getHours();
         if (hours > 18) {
             return this.batteryLevel < this.settings.minimumNightTimeAcBatteryLevel;
@@ -81,6 +91,25 @@ class VictronDevice extends BaseDevice_1.BaseDevice {
         }
         return level;
     }
+    /**
+     * Delegated rather than written here, exactly the way this device delegates its consumer switching to
+     * {@link EnergyManagerUtils.turnOnAdditionalConsumer}: the answer is about the **plant**, and every energy
+     * manager owes the same one - so it is written once and no manager is left with a copy or a stub. What this
+     * device keeps for itself is the policy: the rungs, the reservation and the ac block.
+     * @inheritDoc
+     */
+    get morningOutlook() {
+        return utils_1.EnergyManagerUtils.morningOutlook(this);
+    }
+    /**
+     * Delegated for the same reason {@link morningOutlook} is: the judgement is about the plant's battery and
+     * every manager owes the same one. What this device keeps for itself is what it *does* with the verdict -
+     * the reservation and the ac block below.
+     * @inheritDoc
+     */
+    get morningReserveVerdict() {
+        return utils_1.EnergyManagerUtils.morningReserveVerdict(this, this.morningOutlook);
+    }
     get victronConsumer() {
         return this._victronConsumer;
     }
@@ -124,8 +153,16 @@ class VictronDevice extends BaseDevice_1.BaseDevice {
             this._iCalculationInterval = null;
         }
     }
+    /** @inheritDoc */
     getReport() {
-        return '';
+        var _a;
+        const response = [];
+        response.push(`Production: ${(_a = this.data.pvInverter.power) !== null && _a !== void 0 ? _a : 0}W`);
+        response.push(`Drawing Wattage: ${this.drawingWattage}W`);
+        response.push(`Injecting Wattage: ${this.injectingWattage}W`);
+        response.push(`Self Consuming Wattage: ${this.selfConsumingWattage}W`);
+        response.push(`Battery Level: ${this.batteryLevel}%`);
+        return response.join('\n');
     }
     recalculatePowerSharing() {
         this.calculateExcessEnergy();
@@ -167,6 +204,19 @@ class VictronDevice extends BaseDevice_1.BaseDevice {
             this.log(enums_1.LogLevel.Debug, 'No data available from Victron device.');
             return;
         }
+        // The manager's loop is what drives the plant's one reading, for every consumer of it. Asked, not
+        // scheduled: what it costs is decided by the data situation rather than by a setting, and each of the
+        // reads behind this throttles itself, so asking on every pass of the five second loop costs the same
+        // number of queries as asking once an hour.
+        utils_1.EnergyManagerUtils.refreshEnergyHistory(this);
+        // Read once and handed on, rather than each of the three asking again: the projection is arithmetic over
+        // one read, and three passes over it would still have to agree with each other.
+        const outlook = this.morningOutlook;
+        const release = this.morningRelease(outlook);
+        this.logMorningRelease(release);
+        // Fed from here and from nowhere else. `acBlocked` is a getter anyone may read at any rate, and a tally
+        // that counts reads rather than evaluations measures the callers instead of the model.
+        utils_1.EnergyManagerUtils.observeModelShadow(this, outlook, release !== undefined);
         // Step 1: Calculate battery need
         const hoursTilSunset = services_1.TimeCallbackService.hoursTilSunset();
         let neededBatteryWattage = 0;
@@ -176,7 +226,7 @@ class VictronDevice extends BaseDevice_1.BaseDevice {
                 this.log(enums_1.LogLevel.Debug, 'No battery data available from Victron device.');
                 return;
             }
-            neededBatteryWattage = ((1 - this.batteryLevel / 100.0) * this.settings.batteryCapacityWattage) / hoursTilSunset;
+            neededBatteryWattage = this.neededBatteryWattage(release !== undefined, hoursTilSunset);
             // Step 2: Calculate expected solar output
             const solarOutput = (_a = this.data.pvInverter.power) !== null && _a !== void 0 ? _a : 0;
             // Step 3: Calculate expected base consumption
@@ -205,6 +255,100 @@ class VictronDevice extends BaseDevice_1.BaseDevice {
         }
         this.calculatePersistenceValues();
     }
+    /**
+     * Rung 1, the only rung of the recorded history that decides: if the state of charge carries past the
+     * coming morning low even when no further yield arrives, nothing has to be held back and no consumer has to
+     * be kept off.
+     *
+     * This manager's own policy and rightly here rather than in the shared utils: what a plant does with the
+     * outlook is the manager's judgement, and the reservation and ac block it feeds are this device's.
+     *
+     * Arithmetic over the plant's own measured consumption - no fit, no weights, no window length. That is what
+     * separates it from the rung below, which measures against the lower edge of the fitted band and therefore
+     * only records (see {@link EnergyManagerUtils.observeModelShadow}).
+     * @param outlook - What the plant said, or undefined while it cannot say anything - which includes the
+     * absent charge level, so the guard against it stays in the shared utils alone.
+     * @returns The release, or undefined while the measured consumption cannot carry it.
+     */
+    morningRelease(outlook) {
+        if (outlook === undefined) {
+            // The fallback holds back more, not less.
+            return undefined;
+        }
+        const reserve = this.settings.minimumMorningSocReserve;
+        const worstCaseLowSoc = outlook.worstCaseLowSoc;
+        if (worstCaseLowSoc === undefined || worstCaseLowSoc < reserve) {
+            return undefined;
+        }
+        return {
+            reason: `worst case low ${utils_1.Utils.round(worstCaseLowSoc, 2)}% holds the reserve ${reserve}% ` +
+                'without any further yield',
+        };
+    }
+    /**
+     * How much of the production is held back for the battery.
+     *
+     * With the release nothing is held back: the coming morning clears the reserve on measured consumption
+     * alone. Without it the calculation is the one that was here before - it aims at a full battery by sunset,
+     * which over-reserves, and that is what an installation without a usable recorded history keeps.
+     * @param released - Whether rung 1 carried the coming morning.
+     * @param hoursTilSunset - The horizon the shortfall is spread over.
+     * @returns The wattage to hold back.
+     */
+    neededBatteryWattage(released, hoursTilSunset) {
+        if (released) {
+            return 0;
+        }
+        const missingShare = 1 - this.batteryLevel / 100.0;
+        return (missingShare * this.settings.batteryCapacityWattage) / this.reserveHorizonHours(hoursTilSunset);
+    }
+    /**
+     * The horizon the shortfall is actually spread over: the remaining sun hours, but never less than
+     * {@link VictronDevice.minimumReserveHorizonHours}.
+     *
+     * The raw horizon is a difference against the next sunset and runs to zero, while the part of day this
+     * calculation is entered under is derived separately from today's sunset plus its own offsets - so the two
+     * do not turn at the same instant. In the gap the divisor is first tiny and then negative: a shortfall of a
+     * few percent becomes a rate in the megawatt range, at exactly zero an `Infinity` that leaves the process
+     * through `toJSON`, and past the turn a *negative* reservation that is added to the excess and offers
+     * energy the plant does not have. Every five seconds, and since the horizon is counted in hours rather than
+     * minutes, sixty times as large as when this was harmless.
+     *
+     * The bound is a rate bound, not a schedule: below half an hour of daylight there is nothing left to charge
+     * in, so the quotient stops describing a charging rate and only its magnitude still moves. Half an hour
+     * caps the reservation at twice the battery capacity per hour - still above anything the plant can take in,
+     * therefore never loosening a reservation that was meaningful, while keeping the value finite and signed
+     * the way the rest of the calculation assumes.
+     * @param hoursTilSunset - The raw remaining sun hours, which may be zero or negative.
+     * @returns The horizon to divide by, at least the minimum.
+     */
+    reserveHorizonHours(hoursTilSunset) {
+        return Math.max(hoursTilSunset, VictronDevice.minimumReserveHorizonHours);
+    }
+    /**
+     * Reports the release whenever it changes, and never otherwise: this runs every five seconds, and a line
+     * per pass would bury the change nobody must miss. The very first pass is remembered but not reported while
+     * there is no release, so an installation whose recorded history holds nothing stays silent instead of
+     * announcing its unchanged behaviour once per start.
+     *
+     * Named after the reserve rather than after the reservation, because the same release also answers the ac
+     * block - and it does so around the clock, while the reservation only applies in daylight.
+     * @param release - The release of this pass, or undefined while the measured consumption cannot carry one.
+     */
+    logMorningRelease(release) {
+        const line = release === undefined
+            ? 'no model free release, aiming at a full battery by sunset'
+            : `released: ${release.reason}`;
+        if (line === this._lastReleaseLine) {
+            return;
+        }
+        const first = this._lastReleaseLine === undefined;
+        this._lastReleaseLine = line;
+        if (first && release === undefined) {
+            return;
+        }
+        this.log(enums_1.LogLevel.Info, `Morning reserve decision: ${line}`);
+    }
     turnOnAdditionalConsumer() {
         const result = utils_1.EnergyManagerUtils.turnOnAdditionalConsumer(this._excessEnergyConsumer, this._lastDeviceChange);
         if (result == undefined) {
@@ -249,3 +393,8 @@ class VictronDevice extends BaseDevice_1.BaseDevice {
     }
 }
 exports.VictronDevice = VictronDevice;
+/**
+ * The shortest horizon the battery reservation is spread over, in hours. Not a setting: it is a bound on
+ * the arithmetic rather than a dial of the plant - see {@link VictronDevice.reserveHorizonHours}.
+ */
+VictronDevice.minimumReserveHorizonHours = 0.5;

package/lib/devices/victron/victron-morning-release.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The one statement the plant's recorded history is allowed to act on in the victron manager: that the coming
+ * morning low clears the reserve on measured consumption alone, with no further yield assumed and no model
+ * involved.
+ *
+ * There is no counterpart for "the morning falls short". Saying so needs the fitted model, and the model runs
+ * in the shadow; the absent value therefore means the previous calculation applies, which needs nothing from
+ * the history.
+ *
+ * Not part of the published surface: it is how this manager carries its own decision from one private method
+ * to the next, not something a consumer of the library reads.
+ */
+export interface iVictronMorningRelease {
+    /** What an operator reads the release by. */
+    reason: string;
+}

package/lib/devices/victron/victron-morning-release.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/enums/DeviceCapability.d.ts

@@ -23,6 +23,7 @@ export declare enum DeviceCapability {
     garageDoorOpener = 21,
     magnetSensor = 22,
     airQualitySensor = 23,
+    fossilGenerator = 24,
     bluetoothDetector = 101,
     trackableDevice = 102,
     scene = 103,

package/lib/enums/DeviceCapability.js

@@ -27,6 +27,7 @@ var DeviceCapability;
     DeviceCapability[DeviceCapability["garageDoorOpener"] = 21] = "garageDoorOpener";
     DeviceCapability[DeviceCapability["magnetSensor"] = 22] = "magnetSensor";
     DeviceCapability[DeviceCapability["airQualitySensor"] = 23] = "airQualitySensor";
+    DeviceCapability[DeviceCapability["fossilGenerator"] = 24] = "fossilGenerator";
     DeviceCapability[DeviceCapability["bluetoothDetector"] = 101] = "bluetoothDetector";
     DeviceCapability[DeviceCapability["trackableDevice"] = 102] = "trackableDevice";
     DeviceCapability[DeviceCapability["scene"] = 103] = "scene";

package/lib/interfaces/baseDevices/iAirQualityCollector.d.ts

@@ -1,6 +1,7 @@
 import { iRoomDevice } from './iRoomDevice';
 import { AirQualitySensorChangeAction } from '../../action';
-import { iAirQualityReadings, iAirQualitySensor } from './iAirQualitySensor';
+import { iAirQualityReadings } from './iAirQualityReadings';
+import { iAirQualitySensor } from './iAirQualitySensor';
 /**
  * This interface represents a device measuring air quality.
  *

package/lib/interfaces/baseDevices/iAirQualityReadings.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The set of air quality metrics a sensor can report.
+ *
+ * Devices differ widely in what they measure, so every member is always present but defaults to
+ * `UNDEFINED_AIR_QUALITY_VALUE` until the device reports it. This mirrors the sentinel approach of
+ * `UNDEFINED_TEMP_VALUE` and spares consumers a null check on every metric; use
+ * {@link iAirQualitySensor.reports} to tell "not measured" apart from a measured zero.
+ */
+export interface iAirQualityReadings {
+    /**
+     * The air quality index as calculated by the device (lower is better)
+     */
+    aqi: number;
+    /**
+     * The carbon dioxide concentration in ppm
+     */
+    co2: number;
+    /**
+     * The nitrogen oxide index (1 equals background level)
+     */
+    nox: number;
+    /**
+     * Particulate matter up to 1.0 µm in µg/m³
+     */
+    pm1p0: number;
+    /**
+     * Particulate matter up to 2.5 µm in µg/m³
+     */
+    pm2p5: number;
+    /**
+     * Particulate matter up to 4.0 µm in µg/m³
+     */
+    pm4p0: number;
+    /**
+     * Particulate matter up to 10.0 µm in µg/m³
+     */
+    pm10p0: number;
+    /**
+     * The total volatile organic compounds in ppb
+     */
+    tvoc: number;
+    /**
+     * The vape detection reading of the device
+     */
+    vape: number;
+    /**
+     * The volatile organic compounds index (100 equals background level)
+     */
+    voc: number;
+}

package/lib/interfaces/baseDevices/iAirQualityReadings.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/interfaces/baseDevices/iAirQualitySensor.d.ts

@@ -1,59 +1,6 @@
 import { iJsonOmitKeys } from '../iJsonOmitKeys';
 import { AirQualitySensorChangeAction } from '../../action';
-/**
- * The value reported for a metric the sensor does not measure or has not reported yet.
- */
-export declare const UNDEFINED_AIR_QUALITY_VALUE = -1;
-/**
- * The set of air quality metrics a sensor can report.
- *
- * Devices differ widely in what they measure, so every member is always present but defaults to
- * {@link UNDEFINED_AIR_QUALITY_VALUE} until the device reports it. This mirrors the sentinel approach of
- * {@link UNDEFINED_TEMP_VALUE} and spares consumers a null check on every metric; use
- * {@link iAirQualitySensor.reports} to tell "not measured" apart from a measured zero.
- */
-export interface iAirQualityReadings {
-    /**
-     * The air quality index as calculated by the device (lower is better)
-     */
-    aqi: number;
-    /**
-     * The carbon dioxide concentration in ppm
-     */
-    co2: number;
-    /**
-     * The nitrogen oxide index (1 equals background level)
-     */
-    nox: number;
-    /**
-     * Particulate matter up to 1.0 µm in µg/m³
-     */
-    pm1p0: number;
-    /**
-     * Particulate matter up to 2.5 µm in µg/m³
-     */
-    pm2p5: number;
-    /**
-     * Particulate matter up to 4.0 µm in µg/m³
-     */
-    pm4p0: number;
-    /**
-     * Particulate matter up to 10.0 µm in µg/m³
-     */
-    pm10p0: number;
-    /**
-     * The total volatile organic compounds in ppb
-     */
-    tvoc: number;
-    /**
-     * The vape detection reading of the device
-     */
-    vape: number;
-    /**
-     * The volatile organic compounds index (100 equals background level)
-     */
-    voc: number;
-}
+import { iAirQualityReadings } from './iAirQualityReadings';
 /**
  * Common handling for a device measuring air quality.
  */

package/lib/interfaces/baseDevices/iAirQualitySensor.js

@@ -1,7 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UNDEFINED_AIR_QUALITY_VALUE = void 0;
-/**
- * The value reported for a metric the sensor does not measure or has not reported yet.
- */
-exports.UNDEFINED_AIR_QUALITY_VALUE = -1;

package/lib/interfaces/baseDevices/iEnergyManager.d.ts

@@ -1,6 +1,8 @@
 import { iBaseDevice } from './iBaseDevice';
 import { iDisposable } from '../iDisposeable';
+import { iEnergyHistoryOutlook } from '../iEnergyHistoryOutlook';
 import { iExcessEnergyConsumer } from './iExcessEnergyConsumer';
+import { iMorningReserveVerdict } from '../iMorningReserveVerdict';
 /**
  * Interface for devices that can manage energy consumption and production.
  *
@@ -17,6 +19,47 @@ export interface iEnergyManager extends iBaseDevice, iDisposable {
      * Whether the Energy Manager actively blocks AC
      */
     readonly acBlocked: boolean;
+    /**
+     * What the plant's own recorded history says about the coming morning low, or `undefined` while this
+     * manager cannot say anything about it - no battery, no stated capacity, or no charge level to project
+     * from.
+     *
+     * **Read, not asked with a charge level.** The level of the plant's battery is the manager's own, and a
+     * consumer that handed one in could hand in a different number than the manager itself reads. It is also
+     * why the guard against the "no reading" marker of {@link iBatteryDevice.batteryLevel} lives here, once,
+     * rather than in every consumer.
+     *
+     * **Free to read.** This getter must stay pure arithmetic over what was already read, so that a consumer
+     * asking on every one of its own decisions costs no query and no request quota. The reading itself is driven
+     * separately, from the manager's own loop.
+     *
+     * **Delegate, do not implement.** `EnergyManagerUtils.morningOutlook(this)` answers it for any manager, and
+     * `EnergyManagerUtils.refreshEnergyHistory(this)` in the manager's loop drives the reading - the same pair
+     * both managers in this repository use. There is one energy manager per installation, so the shared
+     * implementation keeps one reading and one shadow record; a manager that builds its own would pay the
+     * bounded weather backfill twice and split that record in half.
+     *
+     * The answer states facts about the plant and no arithmetic on them. The judgement that goes with it is
+     * {@link morningReserveVerdict}; read that one unless you genuinely need the raw quantities.
+     */
+    readonly morningOutlook: iEnergyHistoryOutlook | undefined;
+    /**
+     * Whether the plant expects the coming morning to hold the reserve its battery must not fall below, or
+     * `undefined` while it can say neither.
+     *
+     * **The judgement belongs here, not to the asking consumer.** How low the morning may get is a property of
+     * the battery, and how little sun still counts as none a property of the plant's photovoltaic - a fuel
+     * burning generator and an air conditioner do not want different answers to that. Where they differ is how
+     * sure they want to be before they act, and that is {@link iMorningReserveVerdict.measured}: the verdicts
+     * that need no fitted model may move something, the modelled ones are reported and left alone.
+     *
+     * **Free to read**, for the same reason {@link morningOutlook} is - pure arithmetic over what was already
+     * read.
+     *
+     * **Delegate, do not implement.** `EnergyManagerUtils.morningReserveVerdict(this, this.morningOutlook)`
+     * answers it for any manager.
+     */
+    readonly morningReserveVerdict: iMorningReserveVerdict | undefined;
     /**
      * The total wattaage being injected into the grid at the moment of last calculation.
      */

package/lib/interfaces/baseDevices/iHumidityCollector.d.ts

@@ -1,7 +1,6 @@
 import { iRoomDevice } from './iRoomDevice';
 import { HumiditySensorChangeAction } from '../../action';
 import { iHumiditySensor } from './iHumiditySensor';
-export declare const UNDEFINED_HUMIDITY_VALUE = -1;
 /**
  * This interface represents a humidity sensor device.
  *

package/lib/interfaces/baseDevices/iHumidityCollector.js

@@ -1,4 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UNDEFINED_HUMIDITY_VALUE = void 0;
-exports.UNDEFINED_HUMIDITY_VALUE = -1;

package/lib/interfaces/baseDevices/iTemperatureCollector.d.ts

@@ -1,7 +1,6 @@
 import { iRoomDevice } from './iRoomDevice';
 import { TemperatureSensorChangeAction } from '../../action';
 import { iTemperatureSensor } from './iTemperatureSensor';
-export declare const UNDEFINED_TEMP_VALUE = -99;
 /**
  * This interface represents a temperature sensor device.
  *

package/lib/interfaces/baseDevices/iTemperatureCollector.js

@@ -1,4 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UNDEFINED_TEMP_VALUE = void 0;
-exports.UNDEFINED_TEMP_VALUE = -99;

package/lib/interfaces/baseDevices/index.d.ts

@@ -13,7 +13,11 @@ export * from './iGarageDoorOpener';
 export * from './iHandle';
 export * from './iHeater';
 export * from './iAirQualityCollector';
+export * from './iAirQualityReadings';
 export * from './iAirQualitySensor';
+export * from './undefinedAirQualityValue';
+export * from './undefinedHumidityValue';
+export * from './undefinedTempValue';
 export * from './iHumidityCollector';
 export * from './iIlluminationSensor';
 export * from './iLamp';

package/lib/interfaces/baseDevices/index.js

@@ -28,7 +28,11 @@ __exportStar(require("./iGarageDoorOpener"), exports);
 __exportStar(require("./iHandle"), exports);
 __exportStar(require("./iHeater"), exports);
 __exportStar(require("./iAirQualityCollector"), exports);
+__exportStar(require("./iAirQualityReadings"), exports);
 __exportStar(require("./iAirQualitySensor"), exports);
+__exportStar(require("./undefinedAirQualityValue"), exports);
+__exportStar(require("./undefinedHumidityValue"), exports);
+__exportStar(require("./undefinedTempValue"), exports);
 __exportStar(require("./iHumidityCollector"), exports);
 __exportStar(require("./iIlluminationSensor"), exports);
 __exportStar(require("./iLamp"), exports);

package/lib/interfaces/baseDevices/undefinedAirQualityValue.d.ts

@@ -0,0 +1,4 @@
+/**
+ * The value reported for a metric the sensor does not measure or has not reported yet.
+ */
+export declare const UNDEFINED_AIR_QUALITY_VALUE = -1;

package/lib/interfaces/baseDevices/undefinedAirQualityValue.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNDEFINED_AIR_QUALITY_VALUE = void 0;
+/**
+ * The value reported for a metric the sensor does not measure or has not reported yet.
+ */
+exports.UNDEFINED_AIR_QUALITY_VALUE = -1;

package/lib/interfaces/baseDevices/undefinedHumidityValue.d.ts

@@ -0,0 +1,4 @@
+/**
+ * The value reported while a device has no humidity reading of its own yet.
+ */
+export declare const UNDEFINED_HUMIDITY_VALUE = -1;

package/lib/interfaces/baseDevices/undefinedHumidityValue.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNDEFINED_HUMIDITY_VALUE = void 0;
+/**
+ * The value reported while a device has no humidity reading of its own yet.
+ */
+exports.UNDEFINED_HUMIDITY_VALUE = -1;

package/lib/interfaces/baseDevices/undefinedTempValue.d.ts

@@ -0,0 +1,4 @@
+/**
+ * The value reported while a device has no temperature reading of its own yet.
+ */
+export declare const UNDEFINED_TEMP_VALUE = -99;

package/lib/interfaces/baseDevices/undefinedTempValue.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNDEFINED_TEMP_VALUE = void 0;
+/**
+ * The value reported while a device has no temperature reading of its own yet.
+ */
+exports.UNDEFINED_TEMP_VALUE = -99;