hoffmation-base 3.7.3 → 4.0.0

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

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WeatherHistoryBackfill = void 0;
+const logging_1 = require("../../logging");
+const enums_1 = require("../../enums");
+const HTTPSOptions_1 = require("../HTTPSOptions");
+const https_service_1 = require("../https-service");
+const settings_service_1 = require("../../settings-service");
+const utils_1 = require("../../utils");
+/**
+ * Fills the gaps in the stored daily weather aggregates from the One Call 3.0 day summary endpoint.
+ *
+ * Its own service instead of a method on the weather service: that one serves the live forecast, while this
+ * one walks a window of past days and must stay bounded and throttled. The full recorded history is far larger
+ * than a day's request quota, so the fitting window is the hard limit and the throttle keeps an accidentally
+ * widened window from draining the quota in one burst.
+ */
+class WeatherHistoryBackfill {
+    /**
+     * Fetches the daily weather aggregates that are missing within the fitting window and stores them, plus the
+     * running day's aggregate on every run. Past days that are already stored are not fetched again, so a
+     * service restart does not cost quota; the running day always is, because it is a forecast that moves. A past
+     * day that was already fetched on the running day is not fetched again until the next calendar day.
+     * @param persist - The persistence to read the present days from and to write the fetched ones to
+     * @param referenceDate - The running day; the window ends on it, inclusive
+     * @param historyWindowDays - Length of the history window in days; calls are bounded by it plus one
+     * @param fetcher - The fetcher to use, defaults to the configured One Call 3.0 day summary endpoint
+     * @param throttleMs - Milliseconds to wait between two calls
+     * @returns - The number of days that were fetched and handed to the persistence. Not the number that
+     * arrived: `persistWeatherDaySummary` reports nothing back, so whether a row landed cannot be seen from
+     * here. Do not read this as a count of stored rows - look in the table for that.
+     */
+    static async run(persist, referenceDate, historyWindowDays, fetcher, throttleMs = WeatherHistoryBackfill.defaultThrottleMs) {
+        if (persist === undefined) {
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, 'WeatherHistoryBackfill: no persistence configured --> nothing to do');
+            return 0;
+        }
+        if (historyWindowDays < 1) {
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, `WeatherHistoryBackfill: window of ${historyWindowDays} days --> nothing to do`);
+            return 0;
+        }
+        const activeFetcher = fetcher !== null && fetcher !== void 0 ? fetcher : WeatherHistoryBackfill.createOpenWeatherFetcher();
+        if (activeFetcher === undefined) {
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, 'WeatherHistoryBackfill: no usable weather configuration --> skipped');
+            return 0;
+        }
+        const days = WeatherHistoryBackfill.windowDays(referenceDate, historyWindowDays);
+        const present = new Set((await persist.getWeatherDaySummaries(days[0], days[days.length - 1])).map((summary) => WeatherHistoryBackfill.dayKey(summary.date)));
+        // The last day of the window is the running one. Its aggregate is a forecast and moves through the day,
+        // so it is fetched on every run and the upsert overwrites it; a past day is archive and does not change,
+        // so a stored one is never paid for twice.
+        const runningDay = WeatherHistoryBackfill.dayKey(days[days.length - 1]);
+        if (WeatherHistoryBackfill.attemptedPastDaysRecordedOn !== runningDay) {
+            WeatherHistoryBackfill.resetAttemptedPastDays();
+            WeatherHistoryBackfill.attemptedPastDaysRecordedOn = runningDay;
+        }
+        let fetched = 0;
+        // Handed to the persistence, not confirmed as arrived - persistWeatherDaySummary reports nothing back.
+        let handedOver = 0;
+        let heldBack = 0;
+        for (const day of days) {
+            const key = WeatherHistoryBackfill.dayKey(day);
+            if (key !== runningDay && present.has(key)) {
+                continue;
+            }
+            if (key !== runningDay && WeatherHistoryBackfill.attemptedPastDays.has(key)) {
+                heldBack++;
+                continue;
+            }
+            if (fetched > 0 && throttleMs > 0) {
+                await utils_1.Utils.delay(throttleMs);
+            }
+            fetched++;
+            if (key !== runningDay) {
+                // Noted before the outcome is known, on purpose - see {@link attemptedPastDays}.
+                WeatherHistoryBackfill.attemptedPastDays.add(key);
+            }
+            const summary = await activeFetcher(day);
+            if (summary === undefined) {
+                continue;
+            }
+            persist.persistWeatherDaySummary(summary);
+            handedOver++;
+        }
+        logging_1.ServerLogService.writeLog(handedOver > 0 ? enums_1.LogLevel.Info : enums_1.LogLevel.Debug, `WeatherHistoryBackfill: handed ${handedOver} of ${fetched} fetched day(s) to the persistence within the last ` +
+            `${historyWindowDays} days plus today, ${heldBack} day(s) held back after an earlier fetch today`);
+        return handedOver;
+    }
+    /**
+     * Forgets which past days were already fetched, so the next run offers the whole window again. Called by
+     * `run` itself on a change of the running day; separate so a test can start from a known state.
+     */
+    static resetAttemptedPastDays() {
+        WeatherHistoryBackfill.attemptedPastDays.clear();
+        WeatherHistoryBackfill.attemptedPastDaysRecordedOn = undefined;
+    }
+    /**
+     * Builds the fetcher against the One Call 3.0 day summary endpoint.
+     * @param settings - The weather settings to use, defaults to the configured ones
+     * @returns - The fetcher, or `undefined` when there is no location or no key to work with
+     */
+    static createOpenWeatherFetcher(settings) {
+        var _a;
+        if (settings === void 0) { settings = (_a = settings_service_1.SettingsService.settings) === null || _a === void 0 ? void 0 : _a.weather; }
+        if (settings === undefined || !settings.appid || !settings.lattitude || !settings.longitude) {
+            return undefined;
+        }
+        const location = settings;
+        return (date) => WeatherHistoryBackfill.fetchDaySummary(location, date);
+    }
+    /**
+     * The days of the fitting window, oldest first, **including the running day**. The running day is in there
+     * on purpose: the gate reads today's cloud cover and maximum temperature out of the same table and through
+     * the same reader as the history, so that both sides of the fit are the same quantity from the same field.
+     * That is one extra call per run - the alternative was the gate deriving today's figures from a different
+     * product, which measurably is not the same number.
+     * @param referenceDate - The running day
+     * @param historyWindowDays - Length of the history window in days
+     * @returns - `historyWindowDays + 1` day starts, the last of which is the running day
+     */
+    static windowDays(referenceDate, historyWindowDays) {
+        const midnight = new Date(referenceDate);
+        midnight.setHours(0, 0, 0, 0);
+        const days = [];
+        for (let offset = historyWindowDays; offset >= 0; offset--) {
+            const day = new Date(midnight);
+            // Calendar arithmetic instead of subtracting milliseconds, so a daylight saving change does not shift
+            // every older day of the window by an hour.
+            day.setDate(day.getDate() - offset);
+            days.push(day);
+        }
+        return days;
+    }
+    static async fetchDaySummary(settings, date) {
+        const day = WeatherHistoryBackfill.dayKey(date);
+        return new Promise((resolve) => {
+            // HTTPSOptions logs the path it is constructed with, so it is constructed with a redacted one and the
+            // real query - which carries location and key - is set afterwards. The repository is public.
+            // Do NOT collapse these two into one constructor call: that puts the key into a log line. The guard is
+            // "keeps key and location out of the path HTTPSOptions is constructed with" in
+            // test/services/dachs-history-persistence.test.ts.
+            const options = new HTTPSOptions_1.HTTPSOptions(WeatherHistoryBackfill.host, `/data/3.0/onecall/day_summary (${day})`, {}, 'GET', 443);
+            options.path =
+                `/data/3.0/onecall/day_summary?lat=${settings.lattitude}&lon=${settings.longitude}` +
+                    `&date=${day}&appid=${settings.appid}&units=metric`;
+            // This promise settles because the callback always comes: `HTTPSService.request` reports every way a
+            // request can end - an answer, an exhausted retry chain, a failing socket, an endpoint that accepts the
+            // connection and then stays silent - to its callback exactly once, and bounds each attempt by its own
+            // time limit. A failure arrives as `HTTPSService.failureStatusCode`, which is not 200 and is discarded
+            // below like any other unusable answer. Nothing here has to watch the clock as well; a second deadline
+            // would only be able to fire before the retry does and throw away the answer it was about to bring.
+            https_service_1.HTTPSService.request(options, '', 1, (response, statusCode) => {
+                resolve(WeatherHistoryBackfill.parseDaySummary(response, statusCode, date, day));
+            });
+        });
+    }
+    static parseDaySummary(response, statusCode, date, day) {
+        var _a, _b, _c;
+        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}`);
+            return undefined;
+        }
+        const parsed = utils_1.Utils.guardedFunction(() => JSON.parse(response), undefined, `WeatherHistoryBackfill: unreadable day summary for ${day}`);
+        // Each leaf is established as a number in a plausible range here rather than trusted from the shape
+        // above. This is the boundary: what passes is written into the table the start decision is read from,
+        // and nothing between here and that decision looks at the values again.
+        const cloudCover = WeatherHistoryBackfill.plausibleReading((_a = parsed === null || parsed === void 0 ? void 0 : parsed.cloud_cover) === null || _a === void 0 ? void 0 : _a.afternoon, 0, 100);
+        const tempMin = WeatherHistoryBackfill.plausibleReading((_b = parsed === null || parsed === void 0 ? void 0 : parsed.temperature) === null || _b === void 0 ? void 0 : _b.min, WeatherHistoryBackfill.minTemperature, WeatherHistoryBackfill.maxTemperature);
+        const tempMax = WeatherHistoryBackfill.plausibleReading((_c = parsed === null || parsed === void 0 ? void 0 : parsed.temperature) === null || _c === void 0 ? void 0 : _c.max, WeatherHistoryBackfill.minTemperature, WeatherHistoryBackfill.maxTemperature);
+        if (cloudCover === undefined || tempMin === undefined || tempMax === undefined) {
+            // No substitute values: a made up cloud cover would be fitted as if it had been measured. A value
+            // outside its band is discarded exactly like a missing one, for the same reason.
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, `WeatherHistoryBackfill: incomplete day summary for ${day}`);
+            return undefined;
+        }
+        const dayStart = new Date(date);
+        dayStart.setHours(0, 0, 0, 0);
+        return { date: dayStart, cloudCover: cloudCover, tempMin: tempMin, tempMax: tempMax };
+    }
+    /**
+     * Establishes one field of the answer as a reading: a real number within the band its quantity can occupy.
+     *
+     * `typeof` rather than `Number(...)`: a value that has to be converted first is not a reading of the
+     * quantity, and converting would turn `null` into 0 and `""` into 0 - both of which pass every band. The
+     * band itself catches what is numeric but cannot be the quantity, `NaN` and the infinities included, since
+     * neither compares inside it.
+     * @param value - The field as it arrived
+     * @param min - Lowest value the quantity can take
+     * @param max - Highest value the quantity can take
+     * @returns - The reading, or undefined when the field is not one
+     */
+    static plausibleReading(value, min, max) {
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+            return undefined;
+        }
+        return value;
+    }
+    static dayKey(date) {
+        const month = `${date.getMonth() + 1}`.padStart(2, '0');
+        const day = `${date.getDate()}`.padStart(2, '0');
+        return `${date.getFullYear()}-${month}-${day}`;
+    }
+}
+exports.WeatherHistoryBackfill = WeatherHistoryBackfill;
+/** Milliseconds between two calls to the weather service. */
+WeatherHistoryBackfill.defaultThrottleMs = 1500;
+/**
+ * The band a daily air temperature in degrees Celsius can occupy. Wide on purpose - it is there to reject
+ * what cannot be a temperature at all, not to second guess the weather service on a hot afternoon. The
+ * bounds sit outside the coldest and the hottest reading ever recorded on the planet.
+ */
+WeatherHistoryBackfill.minTemperature = -95;
+WeatherHistoryBackfill.maxTemperature = 60;
+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
+ * recorded on.
+ *
+ * The attempt is remembered, not its outcome: a past day is archive, so a second fetch on the same calendar
+ * day cannot yield anything the first one did not, whatever became of the first. That also covers the fetch
+ * that succeeded while the write did not land - `persistWeatherDaySummary` reports nothing back, so a
+ * failing write is invisible from here and would otherwise cost the full window once per run, and the
+ * backfill runs far more often than once a day. The running day is remembered alongside, so a passing outage
+ * heals on the next calendar day instead of staying suppressed until a restart.
+ */
+WeatherHistoryBackfill.attemptedPastDays = new Set();
+WeatherHistoryBackfill.attemptedPastDaysRecordedOn = undefined;

package/lib/services/weather/weather-service.d.ts

@@ -18,6 +18,11 @@ export declare class WeatherService {
      * The sun horizontal degree (0 is North)
      */
     static sunDirection: number;
+    /**
+     * How many degrees a room has to exceed its desired temperature, before the sun shading
+     * triggers on the room temperature alone.
+     */
+    private static readonly roomOverheatOffset;
     private static _dataUpdateCbs;
     private static _refreshInterval;
     private static latitude;
@@ -48,6 +53,32 @@ export declare class WeatherService {
     static get currentTemp(): number;
     static willOutsideBeWarmer(referenceTemperature: number, logger: (level: LogLevel, message: string, debugType?: LogDebugType) => void): boolean;
     static weatherRolloPosition(normalPos: number, desiredTemperatur: number, currentTemperatur: number, logger: (level: LogLevel, message: string, debugType?: LogDebugType) => void, shutterSettings: ShutterSettings): number;
+    /**
+     * Determines whether the room is already warmer than wanted.
+     *
+     * The outside temperature alone cannot answer whether a room needs shading: a low autumn sun
+     * shines deep into a south facing room and heats it up considerably while it stays cool outside.
+     * The room's own temperature is the honest measure for that, so it may trigger the shading on its own.
+     * @param desiredTemperatur - The temperature the room is supposed to have
+     * @param currentTemperatur - The temperature the room currently has
+     * @returns True if both values are known and the room exceeds the desired temperature noticeably
+     */
+    private static isRoomOverheated;
+    /**
+     * Determines whether the sun currently shines onto this particular window,
+     * based on the angle between sun and window direction.
+     * @param shutterSettings - The settings of the shutter in question
+     * @param logger - The logging function to use
+     * @returns 1 while the sun faces the window, 0 otherwise
+     */
+    private static solarExposureShare;
+    /**
+     * Determines how much solar gain the current sky lets through, as an overcast sky provides
+     * too little of it to justify a darkened room.
+     * @param shutterSettings - The settings of the shutter in question
+     * @returns The share of clear sky, between 0 and 1
+     */
+    private static skyClearnessShare;
     static getCurrentCloudiness(): number;
     private static getRainNextMinutes;
     private static getActiveAlerts;

package/lib/services/weather/weather-service.js

@@ -168,37 +168,104 @@ class WeatherService {
         return referenceTemperature < wData.daily[0].temp.max;
     }
     static weatherRolloPosition(normalPos, desiredTemperatur, currentTemperatur, logger, shutterSettings) {
-        let result = normalPos;
+        const result = normalPos;
         if (currentTemperatur < desiredTemperatur && currentTemperatur < shutterSettings.heatReductionDirectionThreshold) {
             logger(enums_1.LogLevel.Trace, 'RolloWeatherPosition: Room needs to heat up anyways.');
             return result;
         }
-        else if (normalPos < shutterSettings.heatReductionPosition) {
+        if (normalPos < shutterSettings.heatReductionPosition) {
             logger(enums_1.LogLevel.Trace, 'RolloWeatherPosition: Shutter should be down anyways.');
             return result;
         }
-        else if (this.willOutsideBeWarmer(shutterSettings.heatReductionThreshold, logger)) {
-            result = shutterSettings.heatReductionPosition;
-        }
-        else if (this.hoursTilSunset() < 1) {
+        if (this.hoursTilSunset() < 1) {
             logger(enums_1.LogLevel.Trace, "RolloWeatherPosition: It's close to or after todays sunset");
             return result;
         }
-        else if (shutterSettings.direction !== undefined &&
-            !utils_1.Utils.degreeInBetween(shutterSettings.direction - 50, shutterSettings.direction + 50, this.sunDirection)) {
-            logger(enums_1.LogLevel.Trace, 'RolloWeatherPosition: Sun is facing a different direction');
+        // How much of the full reduction is warranted right now, between 0 (none) and 1 (full).
+        let reductionShare;
+        if (this.willOutsideBeWarmer(shutterSettings.heatReductionThreshold, logger)) {
+            // Insulation regime: at this point the ambient heat outweighs the solar gain, so the closed
+            // shutter is worth it as additional window insulation - no matter where the sun stands.
+            reductionShare = 1;
+        }
+        else if (this.willOutsideBeWarmer(shutterSettings.heatReductionDirectionThreshold, logger) ||
+            this.isRoomOverheated(desiredTemperatur, currentTemperatur)) {
+            // Sun shading regime: only the window the sun actually shines on is worth darkening.
+            reductionShare = this.solarExposureShare(shutterSettings, logger) * this.skyClearnessShare(shutterSettings);
+        }
+        else {
+            logger(enums_1.LogLevel.Trace, "RolloWeatherPosition: It won't get warm enough today.");
             return result;
         }
-        else if (this.getCurrentCloudiness() > 40) {
-            logger(enums_1.LogLevel.Trace, 'RolloWeatherPosition: It´s cloudy now.');
+        if (reductionShare <= 0) {
+            return result;
         }
-        else if (this.willOutsideBeWarmer(shutterSettings.heatReductionDirectionThreshold, logger)) {
-            result = shutterSettings.heatReductionPosition;
+        const span = normalPos - shutterSettings.heatReductionPosition;
+        // Quantized to 10% steps, so slight weather changes don't cause constant shutter movement.
+        // A full reduction keeps the configured position verbatim, as that one is a deliberate choice.
+        const target = reductionShare >= 1
+            ? shutterSettings.heatReductionPosition
+            : Math.min(normalPos, Math.max(shutterSettings.heatReductionPosition, Math.round((normalPos - span * reductionShare) / 10) * 10));
+        if (target !== normalPos) {
+            logger(enums_1.LogLevel.Info, `weatherRolloPosition(${normalPos}, ${desiredTemperatur}, ${currentTemperatur}) --> Target: ${target} ` +
+                `(share: ${utils_1.Utils.round(reductionShare, 2)}, cloudiness: ${this.getCurrentCloudiness()}%, ` +
+                `sunDirection: ${Math.round(this.sunDirection)}°, windowDirection: ${shutterSettings.direction}°)`);
         }
-        if (result !== normalPos) {
-            logger(enums_1.LogLevel.Info, `weatherRolloPosition(${normalPos}, ${desiredTemperatur}, ${currentTemperatur}) --> Target: ${result}`);
+        return target;
+    }
+    /**
+     * Determines whether the room is already warmer than wanted.
+     *
+     * The outside temperature alone cannot answer whether a room needs shading: a low autumn sun
+     * shines deep into a south facing room and heats it up considerably while it stays cool outside.
+     * The room's own temperature is the honest measure for that, so it may trigger the shading on its own.
+     * @param desiredTemperatur - The temperature the room is supposed to have
+     * @param currentTemperatur - The temperature the room currently has
+     * @returns True if both values are known and the room exceeds the desired temperature noticeably
+     */
+    static isRoomOverheated(desiredTemperatur, currentTemperatur) {
+        if (desiredTemperatur <= interfaces_1.UNDEFINED_TEMP_VALUE || currentTemperatur <= interfaces_1.UNDEFINED_TEMP_VALUE) {
+            // Without a heat group we have no room temperature to judge by.
+            return false;
         }
-        return result;
+        return currentTemperatur >= desiredTemperatur + WeatherService.roomOverheatOffset;
+    }
+    /**
+     * Determines whether the sun currently shines onto this particular window,
+     * based on the angle between sun and window direction.
+     * @param shutterSettings - The settings of the shutter in question
+     * @param logger - The logging function to use
+     * @returns 1 while the sun faces the window, 0 otherwise
+     */
+    static solarExposureShare(shutterSettings, logger) {
+        if (shutterSettings.direction === undefined) {
+            // Without a known direction we have to assume the worst case of a fully exposed window.
+            return 1;
+        }
+        const delta = utils_1.Utils.degreeDistance(shutterSettings.direction, this.sunDirection);
+        if (delta > shutterSettings.heatReductionDirectionTolerance) {
+            logger(enums_1.LogLevel.Trace, `RolloWeatherPosition: Sun is facing a different direction (${Math.round(delta)}° off).`);
+            return 0;
+        }
+        return 1;
+    }
+    /**
+     * Determines how much solar gain the current sky lets through, as an overcast sky provides
+     * too little of it to justify a darkened room.
+     * @param shutterSettings - The settings of the shutter in question
+     * @returns The share of clear sky, between 0 and 1
+     */
+    static skyClearnessShare(shutterSettings) {
+        const cloudiness = this.getCurrentCloudiness();
+        const fullReductionMax = shutterSettings.heatReductionCloudinessThreshold;
+        const noReductionMin = shutterSettings.heatReductionMaxCloudiness;
+        if (cloudiness <= fullReductionMax || noReductionMin <= fullReductionMax) {
+            return 1;
+        }
+        if (cloudiness >= noReductionMin) {
+            return 0;
+        }
+        return 1 - (cloudiness - fullReductionMax) / (noReductionMin - fullReductionMax);
     }
     static getCurrentCloudiness() {
         const wData = WeatherService.lastResponse;
@@ -247,18 +314,43 @@ class WeatherService {
             return;
         }
         const host = 'api.openweathermap.org';
-        const path = `/data/3.0/onecall?lat=${WeatherService.latitude}&lon=${WeatherService.longitude}&appid=${WeatherService.appID}&units=metric&lang=de`;
+        // HTTPSOptions logs the path it is constructed with, so it is constructed with a redacted one and the
+        // real query - which carries key and location - is set afterwards. The repository is public and an
+        // operator runs at Debug, which is the level that log line goes out on.
+        // Do NOT collapse these two into one constructor call: that puts the key into a log line. The guard is
+        // "carries key and location in the request and in no log line" in test/services/weather-service.test.ts.
+        const options = new HTTPSOptions_1.HTTPSOptions(host, '/data/3.0/onecall (forecast)', {}, 'GET', 443);
+        options.path =
+            `/data/3.0/onecall?lat=${WeatherService.latitude}&lon=${WeatherService.longitude}` +
+                `&appid=${WeatherService.appID}&units=metric&lang=de`;
         logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, 'Send WeatherAPi Request for data update.');
-        https_service_1.HTTPSService.request(new HTTPSOptions_1.HTTPSOptions(host, path, {}, 'GET', 443), '', 5, (response) => {
+        https_service_1.HTTPSService.request(options, '', 5, (response, statusCode) => {
+            if (statusCode < 200 || statusCode >= 300) {
+                // Everything outside the successful range ends the update here, and the last forecast stays in place:
+                // an old forecast is a worse answer than a fresh one, an error page is none at all.
+                // This covers both ways a request can miss its forecast. `HTTPSService.failureStatusCode` means there
+                // was no answer to begin with, and any other code means the endpoint answered something that is not
+                // one - a refused key answers 401, an exhausted quota 429. The body cannot be what decides that:
+                // those answers are readable JSON as well, so parsing them succeeds and yields a WeatherResponse
+                // whose every field is undefined.
+                // Only the code is named: the request carries the key and the answer mirrors the coordinate back.
+                logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, `WeatherAPi request answered ${statusCode} --> no forecast update`);
+                return;
+            }
             logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, 'WeatherAPi Response erhalten');
-            logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `WeatherAPi Response: ${response}`);
+            // The length rather than the body: the answer mirrors the coordinate of the request back, so a raw
+            // dump writes the location of the plant into the log even though it carries no key itself.
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `WeatherAPi Response of ${response.length} characters received`);
             utils_1.Utils.guardedFunction(() => {
                 const responseObj = JSON.parse(response);
                 WeatherService.processHourlyWeather(responseObj);
                 for (const dataUpdateCbsKey in this._dataUpdateCbs) {
                     this._dataUpdateCbs[dataUpdateCbsKey]();
                 }
-            }, this, `Response from Weather API call at https://${host}/${path}: ${response}`);
+            }, this, 
+            // Neither the request nor the answer is named here: the first carries the key, the second mirrors
+            // the location back. The status of the call is already reported by the two lines above.
+            'WeatherService: the answer of the weather API could not be processed');
         });
     }
     static recalcAzimuth() {
@@ -285,6 +377,11 @@ WeatherService.active = false;
  * The milliseconds of one day
  */
 WeatherService.oneDay = 1000 * 60 * 60 * 24;
+/**
+ * How many degrees a room has to exceed its desired temperature, before the sun shading
+ * triggers on the room temperature alone.
+ */
+WeatherService.roomOverheatOffset = 1;
 WeatherService._dataUpdateCbs = {};
 /**
  * The highest maximum temperature forecast for today (prevents oscillation)

package/lib/settings-service-instance.js

@@ -32,7 +32,9 @@ class SettingsServiceInstance {
                 return lat;
             }
         }
-        return 51.529556852253826;
+        // A coarse fallback so the sun times resolve at all when no location is configured. Deliberately not a
+        // site: one decimal is roughly city scale, and this default is public.
+        return 51.0;
     }
     get longitude() {
         var _a, _b;
@@ -42,7 +44,8 @@ class SettingsServiceInstance {
                 return longitude;
             }
         }
-        return 7.097266042276687;
+        // Coarse for the same reason as the latitude above.
+        return 7.0;
     }
     initialize(config) {
         this.settings = config;

package/lib/settingsObjects/deviceSettings/dachsSettings.d.ts

@@ -31,6 +31,12 @@ export declare class DachsDeviceSettings extends ActuatorSettings implements iDa
     winterMinimumHeatStorageTemp: number;
     /** @inheritDoc */
     winterMinimumPreNightHeatStorageTemp: number;
+    /** @inheritDoc */
+    summerWarmWaterDesiredMaxTemp: number;
+    /** @inheritDoc */
+    dachsRatedElectricalWattage: number;
+    /** @inheritDoc */
+    dachsConversionFactor: number;
     fromPartialObject(data: Partial<DachsDeviceSettings>): void;
     toJSON(): Partial<DachsDeviceSettings>;
 }

package/lib/settingsObjects/deviceSettings/dachsSettings.js

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DachsDeviceSettings = void 0;
 const utils_1 = require("../../utils");
 const actuatorSettings_1 = require("./actuatorSettings");
+// Shared with the energy manager's settings rather than copied: the two would otherwise drift apart on what
+// counts as an unusable share, and an installation would be answered differently depending on which device
+// happened to read the value.
+const victronDeviceSettings_1 = require("./victronDeviceSettings");
 class DachsDeviceSettings extends actuatorSettings_1.ActuatorSettings {
     constructor() {
         super(...arguments);
@@ -36,9 +40,15 @@ class DachsDeviceSettings extends actuatorSettings_1.ActuatorSettings {
         this.winterMinimumHeatStorageTemp = 55;
         /** @inheritDoc */
         this.winterMinimumPreNightHeatStorageTemp = 65;
+        /** @inheritDoc */
+        this.summerWarmWaterDesiredMaxTemp = 58;
+        /** @inheritDoc */
+        this.dachsRatedElectricalWattage = 5500;
+        /** @inheritDoc */
+        this.dachsConversionFactor = 0.8;
     }
     fromPartialObject(data) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
         this.disableHeatingRod = (_a = data.disableHeatingRod) !== null && _a !== void 0 ? _a : this.disableHeatingRod;
         this.disableDachsOwnWW = (_b = data.disableDachsOwnWW) !== null && _b !== void 0 ? _b : this.disableDachsOwnWW;
         this.disableDachsTemporarily = (_c = data.disableDachsTemporarily) !== null && _c !== void 0 ? _c : this.disableDachsTemporarily;
@@ -58,6 +68,9 @@ class DachsDeviceSettings extends actuatorSettings_1.ActuatorSettings {
         this.winterMinimumHeatStorageTemp = (_p = data.winterMinimumHeatStorageTemp) !== null && _p !== void 0 ? _p : this.winterMinimumHeatStorageTemp;
         this.winterMinimumPreNightHeatStorageTemp =
             (_q = data.winterMinimumPreNightHeatStorageTemp) !== null && _q !== void 0 ? _q : this.winterMinimumPreNightHeatStorageTemp;
+        this.summerWarmWaterDesiredMaxTemp = (_r = data.summerWarmWaterDesiredMaxTemp) !== null && _r !== void 0 ? _r : this.summerWarmWaterDesiredMaxTemp;
+        this.dachsRatedElectricalWattage = (_s = data.dachsRatedElectricalWattage) !== null && _s !== void 0 ? _s : this.dachsRatedElectricalWattage;
+        this.dachsConversionFactor = (0, victronDeviceSettings_1.acceptedShare)('dachsConversionFactor', data.dachsConversionFactor, this.dachsConversionFactor);
         super.fromPartialObject(data);
     }
     toJSON() {

package/lib/settingsObjects/deviceSettings/shutterSettings.d.ts

@@ -25,6 +25,12 @@ export declare class ShutterSettings extends DeviceSettings implements iShutterS
     heatReductionDirectionThreshold: number;
     /** @inheritDoc */
     heatReductionThreshold: number;
+    /** @inheritDoc */
+    heatReductionDirectionTolerance: number;
+    /** @inheritDoc */
+    heatReductionCloudinessThreshold: number;
+    /** @inheritDoc */
+    heatReductionMaxCloudiness: number;
     /**
      * Some shutter give no position feedback on their own, so by knowing the durations in either direction,
      * we can programmatically trigger the callbacks.

package/lib/settingsObjects/deviceSettings/shutterSettings.js

@@ -30,6 +30,12 @@ class ShutterSettings extends deviceSettings_1.DeviceSettings {
         this.heatReductionDirectionThreshold = 24;
         /** @inheritDoc */
         this.heatReductionThreshold = 27;
+        /** @inheritDoc */
+        this.heatReductionDirectionTolerance = 50;
+        /** @inheritDoc */
+        this.heatReductionCloudinessThreshold = 40;
+        /** @inheritDoc */
+        this.heatReductionMaxCloudiness = 80;
         /**
          * Some shutter give no position feedback on their own, so by knowing the durations in either direction,
          * we can programmatically trigger the callbacks.
@@ -38,14 +44,18 @@ class ShutterSettings extends deviceSettings_1.DeviceSettings {
         this.triggerPositionUpdateByTime = false;
     }
     fromPartialObject(data) {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         this.msTilTop = (_a = data.msTilTop) !== null && _a !== void 0 ? _a : this.msTilTop;
         this.msTilBot = (_b = data.msTilBot) !== null && _b !== void 0 ? _b : this.msTilBot;
         this.direction = (_c = data.direction) !== null && _c !== void 0 ? _c : this.direction;
         this.heatReductionPosition = (_d = data.heatReductionPosition) !== null && _d !== void 0 ? _d : this.heatReductionPosition;
         this.heatReductionThreshold = (_e = data.heatReductionThreshold) !== null && _e !== void 0 ? _e : this.heatReductionThreshold;
         this.heatReductionDirectionThreshold = (_f = data.heatReductionDirectionThreshold) !== null && _f !== void 0 ? _f : this.heatReductionDirectionThreshold;
-        this.triggerPositionUpdateByTime = (_g = data.triggerPositionUpdateByTime) !== null && _g !== void 0 ? _g : this.triggerPositionUpdateByTime;
+        this.heatReductionDirectionTolerance = (_g = data.heatReductionDirectionTolerance) !== null && _g !== void 0 ? _g : this.heatReductionDirectionTolerance;
+        this.heatReductionCloudinessThreshold =
+            (_h = data.heatReductionCloudinessThreshold) !== null && _h !== void 0 ? _h : this.heatReductionCloudinessThreshold;
+        this.heatReductionMaxCloudiness = (_j = data.heatReductionMaxCloudiness) !== null && _j !== void 0 ? _j : this.heatReductionMaxCloudiness;
+        this.triggerPositionUpdateByTime = (_k = data.triggerPositionUpdateByTime) !== null && _k !== void 0 ? _k : this.triggerPositionUpdateByTime;
         super.fromPartialObject(data);
     }
     toJSON() {