hoffmation-base 4.0.0 → 4.1.0

package/lib/interfaces/iPersist.d.ts

@@ -1,4 +1,5 @@
-import { iAcDevice, iActuator, iAirQualityCollector, iBaseDevice, iBatteryDevice, iButtonSwitch, iHandle, iHeater, iHumidityCollector, iIlluminationSensor, iMotionSensor, iShutter, iTemperatureCollector, iZigbeeDevice } from './baseDevices';
+import { iAcDevice, iActuator, iAirQualityCollector, iBaseDevice, iBatteryDevice, iButtonSwitch, iHandle, iHeater, iHumidityCollector, iIlluminationSensor, iMotionSensor, iShutter, iSoilCollector, iTemperatureCollector, iZigbeeDevice } from './baseDevices';
+import { iSoilMoistureSample } from './iSoilMoistureSample';
 import { iTemperatureMeasurement } from './iTemperatureMeasurement';
 import { iRoomBase } from './iRoomBase';
 import { ButtonPressType } from '../enums';
@@ -169,6 +170,22 @@ export interface iPersist {
      * @param device - The device to persist data for
      */
     persistAirQualitySensor(device: iAirQualityCollector): void;
+    /**
+     * Persists data of a soil sensor
+     * @param device - The device to persist data for
+     */
+    persistSoilSensor(device: iSoilCollector): void;
+    /**
+     * Gets the recorded soil moisture readings of one sensor within the given window, in percent.
+     * An absent, unreachable or empty persistence is a defined state, not a failure: the answer is then an
+     * empty list. Readings without a usable value are dropped rather than replaced by a substitute value - a
+     * missing reading completed with 0 would read as bone dry soil and could ask for water that is not needed.
+     * @param deviceId - The ID of the device to load the readings for
+     * @param startDate - Start of the window (inclusive)
+     * @param endDate - End of the window (inclusive)
+     * @returns - The readings, newest first
+     */
+    getSoilMoistureHistory(deviceId: string, startDate: Date, endDate: Date): Promise<iSoilMoistureSample[]>;
     /**
      * Persists data of a handle sensor
      * @param device - The device to persist data for

package/lib/interfaces/iSoilMoistureSample.d.ts

@@ -0,0 +1,13 @@
+/**
+ * One recorded soil moisture reading in the persistence layer.
+ */
+export interface iSoilMoistureSample {
+    /**
+     * The measured soil moisture in percent
+     */
+    soilMoisture: number;
+    /**
+     * The date of the measurement
+     */
+    date: Date;
+}

package/lib/interfaces/iSoilMoistureSample.js

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

package/lib/interfaces/iWeatherDaySummary.d.ts

@@ -18,4 +18,16 @@ export interface iWeatherDaySummary {
      * The day's maximum temperature in degrees celsius
      */
     tempMax: number;
+    /**
+     * Total precipitation of the day in millimetres, or `undefined` when the day carries no reading for it.
+     *
+     * Optional on purpose, in two directions. Towards implementers: this aggregate is produced by whoever calls
+     * `persistWeatherDaySummary`, and a required field would stop existing code from compiling for a quantity
+     * the previous three consumers never asked for. Towards the record itself: the three fields above decide
+     * whether a day counts at all - a day whose cloud cover is missing is discarded, because a substitute would
+     * be fitted as if measured. Precipitation must not join that rule. A day without it is still a perfectly
+     * good day for the decisions that read cloud cover and temperature, and discarding it would tear holes into
+     * a history those decisions already depend on.
+     */
+    precipitation?: number;
 }

package/lib/interfaces/index.d.ts

@@ -58,6 +58,7 @@ export * from './iProjectedSocBand';
 export * from './iMorningReserveVerdict';
 export * from './iDachsHistoryGateResult';
 export * from './iBatteryLevelSample';
+export * from './iSoilMoistureSample';
 export * from './iActuatorStateSample';
 export * from './iWeatherDaySummary';
 export { iShutterCalibration } from './iShutterCalibration';

package/lib/interfaces/index.js

@@ -71,5 +71,6 @@ __exportStar(require("./iProjectedSocBand"), exports);
 __exportStar(require("./iMorningReserveVerdict"), exports);
 __exportStar(require("./iDachsHistoryGateResult"), exports);
 __exportStar(require("./iBatteryLevelSample"), exports);
+__exportStar(require("./iSoilMoistureSample"), exports);
 __exportStar(require("./iActuatorStateSample"), exports);
 __exportStar(require("./iWeatherDaySummary"), exports);

package/lib/services/dbo/postgreSqlPersist.d.ts

@@ -1,5 +1,5 @@
 import { PoolConfig } from 'pg';
-import { iAcDevice, iActuator, iActuatorStateSample, iBaseDevice, iBatteryDevice, iBatteryLevelSample, iButtonSwitch, iConsumptionWindowSample, iDesiredShutterPosition, iHandle, iHeater, iAirQualityCollector, iHumidityCollector, iIlluminationSensor, iMotionSensor, iPersist, iRoomBase, iShutter, iShutterCalibration, iTemperatureCollector, iTemperatureMeasurement, iWeatherDaySummary, iZigbeeDevice } from '../../interfaces';
+import { iAcDevice, iActuator, iActuatorStateSample, iBaseDevice, iBatteryDevice, iBatteryLevelSample, iButtonSwitch, iConsumptionWindowSample, iDesiredShutterPosition, iHandle, iHeater, iAirQualityCollector, iHumidityCollector, iIlluminationSensor, iMotionSensor, iPersist, iRoomBase, iShutter, iShutterCalibration, iSoilCollector, iSoilMoistureSample, iTemperatureCollector, iTemperatureMeasurement, iWeatherDaySummary, iZigbeeDevice } from '../../interfaces';
 import { CountToday, EnergyCalculation } from '../../models';
 import { ButtonPressType } from '../../enums';
 export declare class PostgreSqlPersist implements iPersist {
@@ -54,6 +54,10 @@ export declare class PostgreSqlPersist implements iPersist {
     /** @inheritDoc */
     persistAirQualitySensor(device: iAirQualityCollector): void;
     /** @inheritDoc */
+    persistSoilSensor(device: iSoilCollector): void;
+    /** @inheritDoc */
+    getSoilMoistureHistory(deviceId: string, startDate: Date, endDate: Date): Promise<iSoilMoistureSample[]>;
+    /** @inheritDoc */
     persistBatteryDevice(device: iBatteryDevice): void;
     /** @inheritDoc */
     persistZigbeeDevice(device: iZigbeeDevice): void;

package/lib/services/dbo/postgreSqlPersist.js

@@ -246,7 +246,7 @@ class PostgreSqlPersist {
     }
     /** @inheritDoc */
     async getWeatherDaySummaries(startDate, endDate) {
-        const dbResult = await this.query(`SELECT date, "cloudCover", "tempMin", "tempMax"
+        const dbResult = await this.query(`SELECT date, "cloudCover", "tempMin", "tempMax", "precipitation"
        from hoffmation_schema."WeatherDaySummary"
        WHERE date >= '${startDate.toISOString()}'
          AND date <= '${endDate.toISOString()}'
@@ -268,13 +268,24 @@ class PostgreSqlPersist {
                 dropped++;
                 continue;
             }
-            result.push({ date: date, cloudCover: cloudCover, tempMin: tempMin, tempMax: tempMax });
+            // Read after the completeness check and deliberately outside it, mirroring the write path: every row
+            // stored before this column existed carries a null here, and none of them may be dropped for it. An
+            // absent value stays absent rather than becoming a 0, which would read as a dry day.
+            const precipitation = PostgreSqlPersist.toFiniteNumber(entry.precipitation);
+            result.push({
+                date: date,
+                cloudCover: cloudCover,
+                tempMin: tempMin,
+                tempMax: tempMax,
+                precipitation: precipitation,
+            });
         }
         PostgreSqlPersist.logDroppedRows('getWeatherDaySummaries', dropped);
         return result;
     }
     /** @inheritDoc */
     persistWeatherDaySummary(summary) {
+        var _a;
         // The values are bound, not written into the statement. Every other write in this file carries figures
         // this process produced itself; these come from the weather service, and they are read back out of this
         // table by a decision that switches an appliance. The fetcher already refuses what is not a number, but
@@ -282,15 +293,26 @@ class PostgreSqlPersist {
         // aggregate is data. The update half binds the same three placeholders: it is the one an interpolation
         // is most easily left behind in.
         this.query(`
-      insert into hoffmation_schema."WeatherDaySummary" ("date", "cloudCover", "tempMin", "tempMax")
-      values ($1, $2, $3, $4) ON CONFLICT ("date")
+      insert into hoffmation_schema."WeatherDaySummary" ("date", "cloudCover", "tempMin", "tempMax", "precipitation")
+      values ($1, $2, $3, $4, $5) ON CONFLICT ("date")
     DO
       UPDATE SET
         "cloudCover" = $2,
         "tempMin" = $3,
-        "tempMax" = $4
+        "tempMax" = $4,
+        "precipitation" = COALESCE($5, hoffmation_schema."WeatherDaySummary"."precipitation")
       ;
-    `, [summary.date.toISOString(), summary.cloudCover, summary.tempMin, summary.tempMax]);
+    `, [
+            summary.date.toISOString(),
+            summary.cloudCover,
+            summary.tempMin,
+            summary.tempMax,
+            // Undefined is bound as null on purpose - the column has to be able to say "not recorded", and a 0
+            // would say "it did not rain". The three columns above are overwritten unconditionally because the
+            // running day's forecast moves; this one keeps what is already stored when nothing new arrived, so a
+            // refetch that comes back without the field cannot erase a figure an earlier one delivered.
+            (_a = summary.precipitation) !== null && _a !== void 0 ? _a : null,
+        ]);
     }
     /** @inheritDoc */
     async initialize() {
@@ -506,6 +528,21 @@ BEGIN
 
   END IF;
 
+  IF (SELECT to_regclass('hoffmation_schema."SoilSensorDeviceData"') IS NULL) Then
+    -- Deliberately without a foreign key on "DeviceInfo", for the same reason as the air quality table above:
+    -- creating one needs the REFERENCES privilege on that table, which an existing installation whose tables
+    -- were created by another role may not grant.
+    create table if not exists hoffmation_schema."SoilSensorDeviceData"
+    (
+        "deviceID"        varchar(60) not null,
+        "soilMoisture"    double precision,
+        date              timestamp   not null,
+        constraint soilsensordevicedata_pk
+            primary key ("deviceID", date)
+    );
+
+  END IF;
+
   IF (SELECT to_regclass('hoffmation_schema."BatteryDeviceData"') IS NULL) Then  
     create table if not exists hoffmation_schema."BatteryDeviceData"
     (
@@ -578,11 +615,22 @@ BEGIN
                 primary key,
         "cloudCover" double precision,
         "tempMin"    double precision,
-        "tempMax"    double precision
+        "tempMax"    double precision,
+        "precipitation" double precision
     );
 
   END IF;
 
+  IF (SELECT COUNT(column_name) = 0
+    FROM information_schema.columns
+    WHERE table_name = 'WeatherDaySummary'
+      and column_name = 'precipitation') Then
+    -- The table predates this column, so an existing installation gets it added rather than created. Existing
+    -- rows keep a null, which is the honest answer: nothing was recorded for those days.
+    alter table hoffmation_schema."WeatherDaySummary"
+      add "precipitation" double precision;
+  END IF;
+
   IF (SELECT COUNT(column_name) = 0
     FROM information_schema.columns
     WHERE table_name = 'EnergyCalculation'
@@ -715,6 +763,53 @@ $$;`);
     `);
     }
     /** @inheritDoc */
+    persistSoilSensor(device) {
+        this.query(`
+      insert into hoffmation_schema."SoilSensorDeviceData" ("deviceID", "soilMoisture", "date")
+      values ('${device.id}', ${device.soilMoisture}, '${new Date().toISOString()}');
+    `);
+    }
+    /** @inheritDoc */
+    async getSoilMoistureHistory(deviceId, startDate, endDate) {
+        // The device id is bound rather than pasted in: it is a string this reader is handed, and a string inside
+        // quotes can close them. The dates travel the same way for consistency - bound as ISO text, which is what
+        // the naive column stores and hence the same comparison the statement makes with a literal.
+        const dbResult = await this.query(`SELECT "soilMoisture", date
+       from hoffmation_schema."SoilSensorDeviceData"
+       WHERE "deviceID" = $1
+         and date >= $2
+         AND date <= $3
+       ORDER BY DATE DESC`, [deviceId, startDate.toISOString(), endDate.toISOString()]);
+        if (dbResult === null || dbResult.length === 0) {
+            PostgreSqlPersist.logEmptyAnswer('getSoilMoistureHistory', dbResult, startDate, endDate);
+            return [];
+        }
+        const result = [];
+        let dropped = 0;
+        for (const entry of dbResult) {
+            // An absent value read as 0 would read as bone dry soil - the one reading that makes a watering
+            // decision act. A genuine 0 % survives; only an absent or unreadable one is dropped.
+            const soilMoisture = PostgreSqlPersist.toFiniteNumber(entry.soilMoisture);
+            // A reading without a timestamp cannot be placed: read as a Date an absent one lands on 1970-01-01,
+            // which looks like a reading at the far edge of the window rather than like a missing one.
+            const date = PostgreSqlPersist.fromNaiveTimestamp(entry.date);
+            if (soilMoisture === undefined || date === undefined) {
+                dropped++;
+                continue;
+            }
+            // Outside 0..100 this is not a soil moisture. The sentinel the sensor carries before its first reading
+            // is -1, and the write path already refuses to store it - this is the second line of defence, for rows
+            // an older version may have written.
+            if (soilMoisture < 0 || soilMoisture > 100) {
+                dropped++;
+                continue;
+            }
+            result.push({ soilMoisture: soilMoisture, date: date });
+        }
+        PostgreSqlPersist.logDroppedRows('getSoilMoistureHistory', dropped);
+        return result;
+    }
+    /** @inheritDoc */
     persistBatteryDevice(device) {
         this.query(`
       insert into hoffmation_schema."BatteryDeviceData" ("deviceID", "battery", "date")

package/lib/services/dbo/soil-moisture-row.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The raw shape the driver hands back for one stored soil moisture reading.
+ *
+ * Same conversion rules as {@link BatteryLevelRow}: the numeric column may arrive as a string, and the date is
+ * a Date built from naive components because the column carries no zone.
+ *
+ * Not part of the published surface - a database row shape is not an interface anyone implements.
+ */
+export type SoilMoistureRow = {
+    /** The stored soil moisture in percent, as the driver hands it back */
+    soilMoisture: string | number | null;
+    /** When the reading was taken, built from naive components */
+    date: Date | null;
+};

package/lib/services/dbo/soil-moisture-row.js

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

package/lib/services/dbo/weather-day-summary-row.d.ts

@@ -15,4 +15,6 @@ export type WeatherDaySummaryRow = {
     tempMin: string | number | null;
     /** Highest air temperature of that day in degrees celsius */
     tempMax: string | number | null;
+    /** Total precipitation of that day in millimetres. Null for every row written before the column existed */
+    precipitation: string | number | null;
 };

package/lib/services/weather/open-weather-day-summary.d.ts

@@ -18,4 +18,8 @@ export type OpenWeatherDaySummary = {
         min?: unknown;
         max?: unknown;
     };
+    /** Precipitation of the day, as the endpoint reports it. Absent on an endpoint that does not send it */
+    precipitation?: {
+        total?: unknown;
+    };
 };

package/lib/services/weather/weather-history-backfill.d.ts

@@ -18,6 +18,12 @@ export declare class WeatherHistoryBackfill {
      */
     private static readonly minTemperature;
     private static readonly maxTemperature;
+    /**
+     * The most millimetres of precipitation a single day can carry. Wide on purpose, like the temperature band:
+     * it rejects what cannot be a daily rainfall at all, it does not second guess the weather service on a
+     * thunderstorm. The bound sits above the highest daily total ever recorded on the planet.
+     */
+    private static readonly maxPrecipitation;
     private static readonly host;
     /**
      * The past days of the window that were already fetched on the running day, and the running day that was

package/lib/services/weather/weather-history-backfill.js

@@ -155,7 +155,7 @@ class WeatherHistoryBackfill {
         });
     }
     static parseDaySummary(response, statusCode, date, day) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         if (statusCode !== 200) {
             // Neither the answer nor the request is logged: both carry the key and the location.
             logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, `WeatherHistoryBackfill: day summary for ${day} answered ${statusCode}`);
@@ -174,9 +174,22 @@ class WeatherHistoryBackfill {
             logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, `WeatherHistoryBackfill: incomplete day summary for ${day}`);
             return undefined;
         }
+        // Read AFTER the completeness check and deliberately outside it. The three fields above decide whether the
+        // day counts; precipitation must never be able to discard one. An endpoint that does not send the field,
+        // or a dry day it chooses to omit, would otherwise tear a hole into the history the start decision reads -
+        // a defect that would only show up as a gradually thinning window, weeks later. Absent stays absent all
+        // the way into the column; it is not filled with a 0, which would be an ordinary reading rather than a
+        // visibly missing one.
+        const precipitation = WeatherHistoryBackfill.plausibleReading((_d = parsed === null || parsed === void 0 ? void 0 : parsed.precipitation) === null || _d === void 0 ? void 0 : _d.total, 0, WeatherHistoryBackfill.maxPrecipitation);
         const dayStart = new Date(date);
         dayStart.setHours(0, 0, 0, 0);
-        return { date: dayStart, cloudCover: cloudCover, tempMin: tempMin, tempMax: tempMax };
+        return {
+            date: dayStart,
+            cloudCover: cloudCover,
+            tempMin: tempMin,
+            tempMax: tempMax,
+            precipitation: precipitation,
+        };
     }
     /**
      * Establishes one field of the answer as a reading: a real number within the band its quantity can occupy.
@@ -212,6 +225,12 @@ WeatherHistoryBackfill.defaultThrottleMs = 1500;
  */
 WeatherHistoryBackfill.minTemperature = -95;
 WeatherHistoryBackfill.maxTemperature = 60;
+/**
+ * The most millimetres of precipitation a single day can carry. Wide on purpose, like the temperature band:
+ * it rejects what cannot be a daily rainfall at all, it does not second guess the weather service on a
+ * thunderstorm. The bound sits above the highest daily total ever recorded on the planet.
+ */
+WeatherHistoryBackfill.maxPrecipitation = 2000;
 WeatherHistoryBackfill.host = 'api.openweathermap.org';
 /**
  * The past days of the window that were already fetched on the running day, and the running day that was