hoffmation-base 3.0.0-alpha.8 → 3.0.0-alpha.81

package/lib/models/rooms/RoomSettings/iRoomInitializationSettings.d.ts

@@ -1,5 +1,14 @@
 import { RoomDeviceAddingSettings } from './roomDeviceAddingSettings';
+/**
+ * The settings for initializing a room (after Devices are generated) to add devices to the room
+ */
 export interface iRoomInitializationSettings {
-    deviceAddidngSettings?: RoomDeviceAddingSettings;
+    /**
+     * The settings for adding a device to the room
+     */
+    deviceAddingSettings?: RoomDeviceAddingSettings;
+    /**
+     * The short name of the room
+     */
     shortName: string;
 }

package/lib/models/rooms/RoomSettings/roomDeviceAddingSettings.d.ts

@@ -3,7 +3,10 @@ import { RoomAddDeviceItem } from './roomAddDeviceItem';
 import { RoomBase } from '../RoomBase';
 export declare class RoomDeviceAddingSettings {
     RoomName: string;
-    devices: Array<Array<RoomAddDeviceItem>>;
+    /**
+     * The devices that are to be added to the room
+     */
+    devices: RoomAddDeviceItem[][];
     constructor(RoomName: string);
     addDevice(deviceType: DeviceType, setID: (value: string) => RoomBase, index: number, customName?: string | undefined): void;
     checkMissing(): void;

package/lib/models/rooms/RoomSettings/roomDeviceAddingSettings.js

@@ -7,6 +7,9 @@ const logLevel_1 = require("../../logLevel");
 class RoomDeviceAddingSettings {
     constructor(RoomName) {
         this.RoomName = RoomName;
+        /**
+         * The devices that are to be added to the room
+         */
         this.devices = [];
     }
     addDevice(deviceType, setID, index, customName = undefined) {

package/lib/models/rooms/RoomSettings/roomSettings.d.ts

@@ -1,23 +1,78 @@
 import { ObjectSettings } from '../../objectSettings';
 import { iTimePair } from '../../../server';
 export declare class RoomSettings extends ObjectSettings {
+    /**
+     * Whether this room should always have ambient light on after sunset (regardless of motion e.g. Gardenlights).
+     */
     ambientLightAfterSunset: boolean;
+    /**
+     * Should lights be turned off after sunrise
+     */
     lichtSonnenAufgangAus: boolean;
+    /**
+     * The default radio URL to use with speaker
+     */
     radioUrl: string;
+    /**
+     * Use shutter to reduce warming of rooms on hot days (detected by weather service)
+     */
     rolloHeatReduction: boolean;
+    /**
+     * Should lights be turned on at Movement
+     */
     lampenBeiBewegung: boolean;
+    /**
+     * Should Light be turned on at day if there are no Windows configured for this room
+     */
     lightIfNoWindows: boolean;
+    /**
+     * Time in seconds after which detected movement is reseted
+     */
     movementResetTimer: number;
+    /**
+     * Indicates rooms, which are time independent always dark (like basement).
+     * This results in lamps beeing turned on at motion regardless of windows and time.
+     */
     roomIsAlwaysDark: boolean;
+    /**
+     * +/- Offset for still turning on lamps at movement after/before sunrise
+     */
     sonnenAufgangLampenDelay: number;
+    /**
+     * +/- Default Offset for shutters opening on sunrise in minutes
+     */
     sonnenAufgangRolloDelay: number;
+    /**
+     * Should shutters be opened on sunrise
+     */
     sonnenAufgangRollos: boolean;
+    /**
+     * !Needs Weather Data! Additional Offset in Minutes per % Cloudiness
+     */
     sonnenUntergangRolloAdditionalOffsetPerCloudiness: number;
+    /**
+     * Latest time of shutter closing (regardless of geospecific sunset)
+     */
     sonnenUntergangRolloMaxTime: iTimePair;
+    /**
+     * Earliest time of shutter opening (regardless of geospecific sunset)
+     */
     sonnenAufgangRolloMinTime: iTimePair;
+    /**
+     * +/- Offset for shutter closing on sunset in minutes
+     */
     sonnenUntergangRolloDelay: number;
+    /**
+     * +/- Offset for turning on lamps at movement after/before sunset
+     */
     sonnenUntergangLampenDelay: number;
+    /**
+     * Should shutters be closed on sunset (based on geolocation)
+     */
     sonnenUntergangRollos: boolean;
+    /**
+     * Whether normal ceiling lights should also be turned on by movement, even if there are LEDs and outlets
+     */
     includeLampsInNormalMovementLightning: boolean;
     fromPartialObject(_obj: Partial<RoomSettings>): void;
 }

package/lib/models/rooms/RoomSettings/roomSettings.js

@@ -7,23 +7,78 @@ class RoomSettings extends objectSettings_1.ObjectSettings {
     constructor() {
         var _a;
         super(...arguments);
+        /**
+         * Whether this room should always have ambient light on after sunset (regardless of motion e.g. Gardenlights).
+         */
         this.ambientLightAfterSunset = server_1.SettingsService.settings.roomDefault.ambientLightAfterSunset;
+        /**
+         * Should lights be turned off after sunrise
+         */
         this.lichtSonnenAufgangAus = server_1.SettingsService.settings.roomDefault.lichtSonnenAufgangAus;
+        /**
+         * The default radio URL to use with speaker
+         */
         this.radioUrl = (_a = server_1.SettingsService.settings.roomDefault.radioUrl) !== null && _a !== void 0 ? _a : '';
+        /**
+         * Use shutter to reduce warming of rooms on hot days (detected by weather service)
+         */
         this.rolloHeatReduction = server_1.SettingsService.settings.roomDefault.rolloHeatReduction;
+        /**
+         * Should lights be turned on at Movement
+         */
         this.lampenBeiBewegung = server_1.SettingsService.settings.roomDefault.lampenBeiBewegung;
+        /**
+         * Should Light be turned on at day if there are no Windows configured for this room
+         */
         this.lightIfNoWindows = server_1.SettingsService.settings.roomDefault.lightIfNoWindows;
+        /**
+         * Time in seconds after which detected movement is reseted
+         */
         this.movementResetTimer = server_1.SettingsService.settings.roomDefault.movementResetTimer;
+        /**
+         * Indicates rooms, which are time independent always dark (like basement).
+         * This results in lamps beeing turned on at motion regardless of windows and time.
+         */
         this.roomIsAlwaysDark = server_1.SettingsService.settings.roomDefault.roomIsAlwaysDark;
+        /**
+         * +/- Offset for still turning on lamps at movement after/before sunrise
+         */
         this.sonnenAufgangLampenDelay = server_1.SettingsService.settings.roomDefault.sonnenAufgangLampenDelay;
+        /**
+         * +/- Default Offset for shutters opening on sunrise in minutes
+         */
         this.sonnenAufgangRolloDelay = server_1.SettingsService.settings.roomDefault.sonnenAufgangRolloDelay;
+        /**
+         * Should shutters be opened on sunrise
+         */
         this.sonnenAufgangRollos = server_1.SettingsService.settings.roomDefault.sonnenAufgangRollos;
+        /**
+         * !Needs Weather Data! Additional Offset in Minutes per % Cloudiness
+         */
         this.sonnenUntergangRolloAdditionalOffsetPerCloudiness = server_1.SettingsService.settings.roomDefault.sonnenUntergangRolloAdditionalOffsetPerCloudiness;
+        /**
+         * Latest time of shutter closing (regardless of geospecific sunset)
+         */
         this.sonnenUntergangRolloMaxTime = server_1.SettingsService.settings.roomDefault.sonnenUntergangRolloMaxTime;
+        /**
+         * Earliest time of shutter opening (regardless of geospecific sunset)
+         */
         this.sonnenAufgangRolloMinTime = server_1.SettingsService.settings.roomDefault.sonnenAufgangRolloMinTime;
+        /**
+         * +/- Offset for shutter closing on sunset in minutes
+         */
         this.sonnenUntergangRolloDelay = server_1.SettingsService.settings.roomDefault.sonnenUntergangRolloDelay;
+        /**
+         * +/- Offset for turning on lamps at movement after/before sunset
+         */
         this.sonnenUntergangLampenDelay = server_1.SettingsService.settings.roomDefault.sonnenUntergangLampenDelay;
+        /**
+         * Should shutters be closed on sunset (based on geolocation)
+         */
         this.sonnenUntergangRollos = server_1.SettingsService.settings.roomDefault.sonnenUntergangRollos;
+        /**
+         * Whether normal ceiling lights should also be turned on by movement, even if there are LEDs and outlets
+         */
         this.includeLampsInNormalMovementLightning = server_1.SettingsService.settings.roomDefault.includeLampsInNormalMovementLightning;
     }
     fromPartialObject(_obj) {

package/lib/models/rooms/iRoomBase.d.ts

@@ -1,15 +1,54 @@
 import { TimeCallback } from '../timeCallback';
 import { RoomSetLightTimeBasedCommand } from '../command';
+/**
+ * This interface represents a room with it's base functionality.
+ * Whilst accessing the custom rooms can be beneficial for direct device interaction, this provides interactions to e.g. device groups.
+ */
 export interface iRoomBase {
+    /**
+     * The time-callback for controlling shutters at sunrise
+     */
     sunriseShutterCallback: TimeCallback | undefined;
+    /**
+     * The time-callback for controlling shutters at sunset
+     */
     sunsetShutterCallback: TimeCallback | undefined;
+    /**
+     * The time-callback for controlling light at sunrise
+     */
     sonnenAufgangLichtCallback: TimeCallback | undefined;
+    /**
+     * The time-callback for controlling light at sunset
+     */
     sonnenUntergangLichtCallback: TimeCallback | undefined;
+    /**
+     * Whether the next sunset shutter-up should be skipped (afterwards this resets to false)
+     */
     skipNextRolloUp: boolean;
+    /**
+     * The name of the room
+     */
     roomName: string;
+    /**
+     * This function initializes the roomBase object of this room
+     */
     initializeBase(): void;
+    /**
+     * This function stores the roominformation to the database
+     */
     persist(): void;
+    /**
+     * This function recalculates the timecallbacks (e.g. sunset, sunrise handling)
+     */
     recalcTimeCallbacks(): void;
+    /**
+     * This function sets the light in the room based on the command
+     * @param c - The command to execute
+     */
     setLightTimeBased(c: RoomSetLightTimeBasedCommand): void;
+    /**
+     * This function checks if it is now light time respecting the room settings, the current time and the daylight hours for this location.
+     * @returns
+     */
     isNowLightTime(): boolean;
 }

package/lib/models/rooms/iRoomImportEnforcer.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Every Hoffmation Instance (e.g. using Hoffmation-Express) needs to enforce the Import of all house specific rooms.
+ * For Hoffmation-Base to be able to interact with this user-specific import enforcer this interface needs to be implemented.
+ */
 export interface iRoomImportEnforcer {
+    /**
+     * This function is called before initializing single devices,
+     * to ensure they can be added to the respective room.
+     */
     addRoomConstructor(): void;
 }

package/lib/models/timeCallback.d.ts

@@ -21,7 +21,14 @@ export declare class TimeCallback {
     cloudOffset?: number | undefined;
     private _calculationSunrise?;
     get calculationSunrise(): Date;
+    /**
+     * The date this Callback was last fired
+     */
     lastDone: Date;
+    /**
+     * The calculated date when this callback should be fired next
+     * @warning This might have not yet been recalculated
+     */
     nextToDo?: Date;
     private _calculationSunset?;
     get calculationSunset(): Date;

package/lib/models/timeCallback.js

@@ -36,6 +36,9 @@ class TimeCallback {
         this.minutes = minutes;
         this.sunTimeOffset = sunTimeOffset;
         this.cloudOffset = cloudOffset;
+        /**
+         * The date this Callback was last fired
+         */
         this.lastDone = new Date(0);
     }
     recalcNextToDo(now) {
@@ -93,25 +96,32 @@ class TimeCallback {
                 }
                 break;
         }
-        if (nextCalculatedTime < now && this.nextToDo && this.nextToDo > now) {
-            server_1.ServerLogService.writeLog(logLevel_1.LogLevel.Info, `Time Callback recalc results in the past, while previous target is still in future --> fire immediately.`);
-            this.perform(now);
-            return;
-        }
         if (((_a = this.nextToDo) === null || _a === void 0 ? void 0 : _a.getTime()) == nextCalculatedTime.getTime()) {
             // No change
             return;
         }
+        if (this.nextToDo && this.nextToDo > this.lastDone) {
+            if (nextCalculatedTime < now) {
+                server_1.ServerLogService.writeLog(logLevel_1.LogLevel.Info, `Time Callback recalc results in the past, while previous target wasn't yet done --> fire immediately.`);
+                this.perform(now);
+                return;
+            }
+            else if (nextCalculatedTime.getDay() !== this.nextToDo.getDay() && this.type === TimeCallbackType.SunSet) {
+                // Recalculation between Sunset and delayed sunset action can result in the next day beeing calculated --> fire immediately
+                server_1.ServerLogService.writeLog(logLevel_1.LogLevel.Info, `Time Callback recalc results in the next day, while previous action wasn't yet fired --> fire immediately.`);
+                this.perform(now);
+            }
+        }
         this.nextToDo = nextCalculatedTime;
         server_1.ServerLogService.writeLog(logLevel_1.LogLevel.Debug, `Next Time event for "${this.name}" at ${this.nextToDo.toLocaleString('de-DE')}`);
     }
     perform(now = new Date()) {
         server_1.ServerLogService.writeLog(logLevel_1.LogLevel.Debug, `Timecallback '${this.name}' fired`);
-        this.cFunction();
         this.lastDone = now;
         this.nextToDo = undefined;
         this._calculationSunrise = undefined;
         this._calculationSunset = undefined;
+        this.cFunction();
     }
 }
 exports.TimeCallback = TimeCallback;

package/lib/server/config/heatingMode.d.ts

@@ -1,5 +1,6 @@
 export declare enum HeatingMode {
     None = 0,
     Winter = 1,
-    Sommer = 2
+    Summer = 2,
+    TransitionalSeason = 3
 }

package/lib/server/config/heatingMode.js

@@ -5,5 +5,6 @@ var HeatingMode;
 (function (HeatingMode) {
     HeatingMode[HeatingMode["None"] = 0] = "None";
     HeatingMode[HeatingMode["Winter"] = 1] = "Winter";
-    HeatingMode[HeatingMode["Sommer"] = 2] = "Sommer";
+    HeatingMode[HeatingMode["Summer"] = 2] = "Summer";
+    HeatingMode[HeatingMode["TransitionalSeason"] = 3] = "TransitionalSeason";
 })(HeatingMode || (exports.HeatingMode = HeatingMode = {}));

package/lib/server/config/iAsusConfig.d.ts

@@ -1,6 +1,21 @@
+/**
+ * The configuration needed to connect to an Asus Router
+ */
 export interface iAsusConfig {
+    /**
+     * The hostname of the Router (or it's IP-Address)
+     */
     address: string;
+    /**
+     * Whether to Ignore SSL warnings/error
+     */
     ignoreSSL?: boolean;
+    /**
+     * The password needed for authentication
+     */
     password: string;
+    /**
+     * The username to connect with.
+     */
     username: string;
 }

package/lib/server/config/iBlockAutomaticHandlerDefaults.d.ts

@@ -0,0 +1,23 @@
+import { CollisionSolving } from '../../models';
+/**
+ * These settings control the desired behaviour of {@link BlockAutomaticHandler}.
+ * Unless decided within a command this will determine the default behaviour.
+ *
+ * So this will e.g. be used when a Homebridge-Hoffmation instance
+ * e.g. issues a command to turn a light on as with this command no block
+ * duration or behaviour is specified.
+ */
+export interface iBlockAutomaticHandlerDefaults {
+    /**
+     * Whether at Block-Lift the desired automatic state should be restored.
+     */
+    revertToAutomaticAtBlockLift?: boolean;
+    /**
+     * The default duration in milliseconds for a block to be on any force action.
+     */
+    blockAutomaticDurationMS?: number;
+    /**
+     * The default collision solving strategy to use.
+     */
+    defaultCollisionSolving?: CollisionSolving;
+}

package/lib/server/config/iBlueIrisSettings.d.ts

@@ -1,5 +1,19 @@
+/**
+ * The configuration for the Blue-Iris Instance (if present).
+ * Blue-Iris is a software to manage IP-Cameras
+ * Settings for {@link BlueIrisCoordinator} to connect to a Blue-Iris instance
+ */
 export interface iBlueIrisSettings {
+    /**
+     * The hostname of the Blue-Iris Instance
+     */
     serverAddress: string;
+    /**
+     * If needed, the username to authenticate with
+     */
     username?: string;
+    /**
+     * If needed, the password to authenticate with.
+     */
     password?: string;
 }

package/lib/server/config/iBluetoothTrackingSettings.d.ts

@@ -1,4 +1,13 @@
+/**
+ * Settings for tracking a bluetooth device using {@link iBluetoothDetector}
+ */
 export interface iBluetoothTrackingSettings {
+    /**
+     * The name of the device to track
+     */
     customName: string;
+    /**
+     * Whether to track the device
+     */
     activeTracking: boolean;
 }

package/lib/server/config/iConfig.d.ts

@@ -15,38 +15,126 @@ import { iMuellSettings } from './iMuellSettings';
 import { iDaikinSettings } from './iDaikinSettings';
 import { iHeaterSettings } from './iHeaterSettings';
 import { iBlueIrisSettings } from './iBlueIrisSettings';
-import { iRestSettings } from './iRestSettings';
 import { iEspresenseSettings } from './iEspresenseSettings';
 import { iTibberSettings } from './iTibberSettings';
 import { iVictronSettings } from './iVictronSettings';
 import { iDachsSettings } from './iDachsSettings';
 import { iEnergyManagerSettings } from './iEnergyManagerSettings';
 import { iUnifiSettings } from './iUnifiSettings';
+import { iBlockAutomaticHandlerDefaults } from './iBlockAutomaticHandlerDefaults';
+import { iRestSettings } from './iRestSettings';
+import { iGoveeSettings } from './iGoveeSettings';
+/**
+ * The main configuration for Hoffmation normally stored in the `main-config.json` file.
+ */
 export interface iConfig {
+    /**
+     * @see iAsusConfig
+     */
     asusConfig?: iAsusConfig;
+    /**
+     * @see i
+     */
+    blockAutomaticHandlerDefaults?: iBlockAutomaticHandlerDefaults;
+    /**
+     * @see iBlueIrisSettings
+     */
     blueIris?: iBlueIrisSettings;
-    daikin?: iDaikinSettings;
+    /**
+     * @see iDachsSettings
+     */
     dachs?: iDachsSettings;
+    /**
+     * @see iDaikinSettings
+     */
+    daikin?: iDaikinSettings;
+    /**
+     * @see iEnergyManagerSettings
+     */
     energyManager?: iEnergyManagerSettings;
+    /**
+     * @see iEspresenseSettings
+     */
     espresense?: iEspresenseSettings;
-    ioBrokerUrl: string;
-    ioBroker?: iIobrokerSettigns;
-    goveeDevicesPresent?: boolean;
+    /**
+     * @see iGoveeSettings
+     */
+    goveeSettings?: iGoveeSettings;
+    /**
+     * @see iHeaterSettings
+     */
     heaterSettings?: iHeaterSettings;
+    /**
+     * The URL to the ioBroker instance.
+     * @deprecated Please use the ioBroker property instead
+     */
+    ioBrokerUrl?: string;
+    /**
+     * @see iIobrokerSettigns
+     */
+    ioBroker?: iIobrokerSettigns;
+    /**
+     * @see iLogSettings
+     */
     logSettings?: iLogSettings;
+    /**
+     * @see iMp3Settings
+     */
     mp3Server?: iMp3Settings;
+    /**
+     * @see iMuellSettings
+     */
     muell?: iMuellSettings;
+    /**
+     * @see iNewsSettings
+     */
     news?: iNewsSettings;
+    /**
+     * @see iPersistenceSettings
+     */
     persistence?: iPersistenceSettings;
+    /**
+     * @see iPollySettings
+     */
     polly?: iPollySettings;
+    /**
+     * @see iRestSettings
+     */
     restServer?: iRestSettings;
+    /**
+     * @see iRoomDefaultSettings
+     */
     roomDefault: iRoomDefaultSettings;
+    /**
+     * @see iSonosSettings
+     */
     sonos?: iSonosSettings;
+    /**
+     * @see iTelegramSettings
+     */
     telegram?: iTelegramSettings;
+    /**
+     * @see iTibberSettings
+     */
     tibber?: iTibberSettings;
+    /**
+     * @see iTimeSettings
+     */
     timeSettings: iTimeSettings;
+    /**
+     * @see iTranslationSettings
+     */
     translationSettings: iTranslationSettings;
+    /**
+     * @see iUnifiSettings
+     */
     unifiSettings?: iUnifiSettings;
-    weather?: iWeatherSettings;
+    /**
+     * @see iVictronSettings
+     */
     victron?: iVictronSettings;
+    /**
+     * @see iWeatherSettings
+     */
+    weather?: iWeatherSettings;
 }

package/lib/server/config/iDachsSettings.d.ts

@@ -1,7 +1,23 @@
 import { DachsClientOptions, InfluxDbConnectionOptions } from '../devices/dachs';
+/**
+ * The configuration for the Dachs CHP (if present)
+ * CHP = Combined Heat and Power (in german Block-Heiz-Kraftwerk)
+ */
 export interface iDachsSettings {
+    /**
+     * The interval in milli-seconds in which the Dachs client should refresh its data.
+     */
     refreshInterval: number;
+    /**
+     * The connection options for the Dachs client.
+     */
     connectionOptions: DachsClientOptions;
+    /**
+     * If provided, the Dachs client will write data to this InfluxDB.
+     */
     influxDb?: InfluxDbConnectionOptions;
+    /**
+     * The room name the Dachs device is located in.
+     */
     roomName: string;
 }

package/lib/server/config/iDaikinSettings.d.ts

@@ -1,6 +1,23 @@
+/**
+ * The configuration for Daikin Air-Conditioning devices (if present)
+ */
 export interface iDaikinSettings {
+    /**
+     * Whether the Daikin service should be active.
+     */
     active: boolean;
+    /**
+     * Enables further Logging for Daikin-device in case of akward issues.
+     * TODO: Move to Logservice Debugging Type
+     */
     activateTracingLogger?: boolean;
+    /**
+     * Whether all requests to the Daikin devices should be made using GET requests.
+     */
     useGetToPost?: boolean;
+    /**
+     * Whether Room Default Callbacks should be added to start ac on Bottom Right short and stop on long button press.
+     * @warning This can collide with Sonos-Control (@see {@link iSonosSettings.buttonBotRightForRadio})
+     */
     buttonBotRightForAc?: boolean;
 }

package/lib/server/config/iEnergyManagerSettings.d.ts

@@ -1,5 +1,18 @@
+/**
+ * The configuration for an Energy-Manager (if present).
+ * This can be used to make proper use of excess energy (e.g. from solar panels)
+ */
 export interface iEnergyManagerSettings {
+    /**
+     * Disable ioBroker JS-EnergyManager
+     */
     disableJsEnergyManager?: boolean;
+    /**
+     * The price per kWh injecting into the grid
+     */
     injectWattagePrice?: number;
+    /**
+     * The price per kWh from the grid
+     */
     wattagePrice?: number;
 }

package/lib/server/config/iEspresenseSettings.d.ts

@@ -1,6 +1,16 @@
 import { iBluetoothTrackingSettings } from './iBluetoothTrackingSettings';
+/**
+ * The configuration for Espresense devices (if present)
+ * This can be used to monitor/tack/locate the position of certain bluetooth devices within the house.
+ */
 export interface iEspresenseSettings {
+    /**
+     * The instance of the mqtt adapter providing the data for espresense devices within ioBroker.
+     */
     mqttInstance: number;
+    /**
+     * An map providing settings for some devices to be tracked.
+     */
     deviceMap: {
         [folderId: string]: iBluetoothTrackingSettings;
     };

package/lib/server/config/iGoveeSettings.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Settings to connect to an external GoveeApi
+ */
+export interface iGoveeSettings {
+    /**
+     * The url of the {@link https://github.com/theimo1221/govee-express-api GoveeApi}
+     */
+    url: string;
+}

package/lib/server/config/iGoveeSettings.js

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