hoffmation-base 3.7.3 → 3.8.0

package/lib/interfaces/settings/iShutterSettings.d.ts

@@ -26,11 +26,32 @@ export interface iShutterSettings extends iDeviceSettings {
      */
     heatReductionDirectionThreshold: number;
     /**
-     * The minimum temperature in degree celsius, to trigger heat reduction regardless of direction
+     * The minimum temperature in degree celsius, from which on the shutter is closed purely as window insulation,
+     * regardless of sun direction and cloudiness. At this point the ambient heat outweighs the solar gain.
      * @type {number}
      * @default 27
      */
     heatReductionThreshold: number;
+    /**
+     * The maximum angle in degrees between sun and window direction, for the sun to count as shining onto the window.
+     * @type {number}
+     * @default 50
+     */
+    heatReductionDirectionTolerance: number;
+    /**
+     * The cloudiness in percent up to which the full {@link heatReductionPosition} is used.
+     * Above this value the target position is faded back towards the normal position.
+     * @type {number}
+     * @default 40
+     */
+    heatReductionCloudinessThreshold: number;
+    /**
+     * The cloudiness in percent from which on no heat reduction takes place at all,
+     * as an overcast sky provides too little solar gain to justify a darkened room.
+     * @type {number}
+     * @default 80
+     */
+    heatReductionMaxCloudiness: number;
     /**
      *
      */

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;
@@ -285,6 +352,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/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() {