hoffmation-base 3.0.0-alpha.4 → 3.0.0-alpha.41

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

@@ -1,8 +1,30 @@
+/**
+ * The settings for the polly-service (if needed).
+ * This service is used to convert text to speech.
+ */
 export interface iPollySettings {
+    /**
+     * The path to store the mp3 files
+     */
     mp3Path: string;
+    /**
+     * The region to use for the Polly service
+     */
     region: string;
+    /**
+     * The signature version to use for the Polly service
+     */
     signatureVersion: string;
+    /**
+     * Your AWS access key id
+     */
     accessKeyId: string;
+    /**
+     * Your AWS secret access key
+     */
     secretAccessKey: string;
+    /**
+     * The voice id to use for the Polly service
+     */
     voiceID: string;
 }

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

@@ -1,4 +1,14 @@
+/**
+ * Interface for the REST settings.
+ * This is primarily used to configure the REST service within Hoffmation-Express.
+ */
 export interface iRestSettings {
+    /**
+     * Whether the REST service should be active.
+     */
     active: boolean;
+    /**
+     * The port the REST service should listen on.
+     */
     port?: number;
 }

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

@@ -1,4 +1,14 @@
+/**
+ * The settings for the Sonos-Service (if present).
+ */
 export interface iSonosSettings {
+    /**
+     * Whether the Sonos service should be active.
+     */
     active: boolean;
+    /**
+     * Whether Room Default Callbacks should be added to start Radio on Bottom Right long button press.
+     * @warning This can collide with AC-Control (@see {@link iDaikinSettings.buttonBotRightForAc})
+     */
     buttonBotRightForRadio?: boolean;
 }

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

@@ -1,7 +1,24 @@
 import { LogLevel } from '../../models';
+/**
+ * The settings for the telegram-service (if needed).
+ * Telegram can be used to have a communication channel to the house and to receive notifications.
+ */
 export interface iTelegramSettings {
+    /**
+     * The threshold for the log level to trigger a message to telegram
+     * TODO: Maybe migrate to {@link iLogSettings}
+     */
     logLevel: LogLevel;
+    /**
+     * The token for the telegram bot
+     */
     telegramToken: string;
+    /**
+     * The allowed IDs for clients interacting with the bot
+     */
     allowedIDs: number[];
+    /**
+     * The IDs that are subscribed to updates from us (e.g. for notifications)
+     */
     subscribedIDs: number[];
 }

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

@@ -1,4 +1,14 @@
+/**
+ * The settings for the Tibber-Service (if needed).
+ * Tibber is an energy provider which can be used to have hourly energy prices.
+ */
 export interface iTibberSettings {
+    /**
+     * The API key for Tibber-API-Authorization
+     */
     apiKey: string;
+    /**
+     * The home ID for this home within the Tibber Account
+     */
     homeId: string;
 }

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

@@ -1,4 +1,13 @@
+/**
+ * Interface representing a specific time of day defined by hours and minutes
+ */
 export interface iTimePair {
+    /**
+     * The hours of the time pair
+     */
     hours: number;
+    /**
+     * The minutes of the time pair
+     */
     minutes: number;
 }

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

@@ -1,5 +1,14 @@
 import { iTimePair } from './iTimePair';
+/**
+ * The settings for the time-service.
+ */
 export interface iTimeSettings {
+    /**
+     * The time which should be considered as the start of the night
+     */
     nightStart: iTimePair;
+    /**
+     * The time which should be considered as the end of the night
+     */
     nightEnd: iTimePair;
 }

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

@@ -1,3 +1,13 @@
+/**
+ * The settings for the translation-service.
+ * The translation-service is used to provide certain messages in the desired language.
+ * Currently only german and english are supported.
+ * @warning The translation-service is not yet fully implemented and only used in some cases.
+ */
 export interface iTranslationSettings {
+    /**
+     * The desired language for the translations
+     * @default 'en'
+     */
     language: string;
 }

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

@@ -1,11 +1,42 @@
+/**
+ * The options neded to connect to a Unifi controller
+ */
 export interface iUnifiConnectionOptions {
+    /**
+     * The host address of the Unifi controller (or its IP address)
+     */
     host?: string;
+    /**
+     * The port of the Unifi controller
+     */
     port?: number;
+    /**
+     * The username used to log in to the Unifi controller (if needed)
+     */
     username?: string;
+    /**
+     * The password used to log in to the Unifi controller (if needed)
+     */
     password?: string;
+    /**
+     * The 2FA token used to log in to the Unifi controller (if needed)
+     * @warning This is not recommended to be used, as after a reboot you would need a new token
+     */
     token2FA?: string;
+    /**
+     * The site of this house (if needed)
+     */
     site?: string;
+    /**
+     * Whether to verify the SSL certificate of the Unifi controller or connect anyway
+     */
     sslverify?: boolean;
+    /**
+     * The timeout for the connection to the Unifi controller
+     */
     timeout?: number;
+    /**
+     * Whether to stay logged in or to reauthenticate on each request
+     */
     rememberMe?: boolean;
 }

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

@@ -1,4 +1,12 @@
 import { iUnifiConnectionOptions } from './iUnifiConnectionOptions';
+/**
+ * The settings for the Unifi-Service (if needed).
+ * Unifi is a network management system which can be used to monitor and control the network and devices.
+ * Within Hoffmation it is mainly used to reconnect devices if they are not reachable.
+ */
 export interface iUnifiSettings {
+    /**
+     * The options for connecting to the Unifi controller
+     */
     loginOptions: iUnifiConnectionOptions;
 }

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

@@ -1,6 +1,20 @@
 import { InfluxDbConnectionOptions } from 'victron-mqtt-consumer/build/models/InfluxDbConnectionOptions';
+/**
+ * The settings for the Victron-Service (if present).
+ * Victron is a energy management system which provides solar or battery power.
+ */
 export interface iVictronSettings {
+    /**
+     * The address of the Victron GX device
+     */
     host: string;
+    /**
+     * The information to connect to the InfluxDB for storing the data
+     */
     influxDb: InfluxDbConnectionOptions;
+    /**
+     * Whether further information should be logged
+     * TODO: Move this to a respective {@link LogDebugType}
+     */
     debug: boolean;
 }

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

@@ -1,5 +1,18 @@
+/**
+ * The settings for the weather-service (if needed).
+ * The weather-service is used to get weather data for the house location.
+ */
 export interface iWeatherSettings {
+    /**
+     * The lattitude of the location
+     */
     lattitude: string;
+    /**
+     * The longitude of the location
+     */
     longitude: string;
+    /**
+     * App-ID from OpenWeatherMap
+     */
     appid?: string;
 }

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

@@ -25,3 +25,4 @@ export * from './iTimePair';
 export * from './iUnifiSettings';
 export * from './iUnifiConnectionOptions';
 export * from './iVictronSettings';
+export { iBlockAutomaticHandlerDefaults } from './iBlockAutomaticHandlerDefaults';

package/lib/server/devices/DeviceCapability.d.ts

@@ -21,6 +21,7 @@ export declare enum DeviceCapability {
     smokeSensor = 19,
     loadMetering = 20,
     garageDoorOpener = 21,
+    magnetSensor = 22,
     bluetoothDetector = 101,
     trackableDevice = 102,
     scene = 103,

package/lib/server/devices/DeviceCapability.js

@@ -25,6 +25,7 @@ var DeviceCapability;
     DeviceCapability[DeviceCapability["smokeSensor"] = 19] = "smokeSensor";
     DeviceCapability[DeviceCapability["loadMetering"] = 20] = "loadMetering";
     DeviceCapability[DeviceCapability["garageDoorOpener"] = 21] = "garageDoorOpener";
+    DeviceCapability[DeviceCapability["magnetSensor"] = 22] = "magnetSensor";
     DeviceCapability[DeviceCapability["bluetoothDetector"] = 101] = "bluetoothDetector";
     DeviceCapability[DeviceCapability["trackableDevice"] = 102] = "trackableDevice";
     DeviceCapability[DeviceCapability["scene"] = 103] = "scene";

package/lib/server/devices/DeviceInfo.d.ts

@@ -1,6 +1,15 @@
 export declare class DeviceInfo {
+    /**
+     * The complete name of the device in a human readable format
+     */
     fullName: string;
+    /**
+     * The roomname matching {@link iRoomBase.roomName}
+     */
     room: string;
+    /**
+     * If present the key to access this device in {@link Devices.alLDevices}
+     */
     allDevicesKey?: string;
     private _customName?;
     get customName(): string;

package/lib/server/devices/DeviceInfo.js

@@ -3,7 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeviceInfo = void 0;
 class DeviceInfo {
     constructor() {
+        /**
+         * The complete name of the device in a human readable format
+         */
         this.fullName = '';
+        /**
+         * The roomname matching {@link iRoomBase.roomName}
+         */
         this.room = '';
     }
     get customName() {

package/lib/server/devices/Griffe.js

@@ -8,10 +8,9 @@ class Griffe {
     static getGriffPosition() {
         const griffe = Griffe.getAllGriffe();
         griffe.sort((a, b) => {
-            a.position;
             return b.position - a.position;
         });
-        const response = [`These are the current handle positions:`];
+        const response = ['These are the current handle positions:'];
         for (const g of griffe) {
             response.push(`${models_1.WindowPosition[g.position]} Window: "${g.info.customName}"`);
         }

package/lib/server/devices/Heizgruppen.js

@@ -6,8 +6,8 @@ const devices_1 = require("./devices");
 class Heizgruppen {
     static getProblems() {
         const groups = this.getAllGruppen();
-        const response = [`Dies sind die bestehenden Differenzen:`];
-        response.push(`Raumname\t\tIst-Temperatur\t\tGerät`);
+        const response = ['Dies sind die bestehenden Differenzen:'];
+        response.push('Raumname\t\tIst-Temperatur\t\tGerät');
         for (const g of groups) {
             const heizungen = g.getBelongingHeizungen();
             const tempProblem = [`${g.info.room}\t\t${g.iTemperature}°C\t\t${g.info.customName}`];

package/lib/server/devices/IoBrokerBaseDevice.d.ts

@@ -8,57 +8,73 @@ import { DeviceCapability } from './DeviceCapability';
 export declare abstract class IoBrokerBaseDevice implements iRoomDevice {
     protected _info: IoBrokerDeviceInfo;
     deviceType: DeviceType;
-    settings: DeviceSettings | undefined;
+    /**
+     * The settings for adding devices to Rooms
+     */
     static roomAddingSettings: {
         [id: string]: RoomDeviceAddingSettings;
     };
+    /**
+     * @inheritDoc
+     * @default undefined (no Settings)
+     */
+    settings: DeviceSettings | undefined;
     private _room;
+    /** @inheritDoc */
     readonly deviceCapabilities: DeviceCapability[];
+    protected _debounceStateDelay: number;
+    protected _lastWrite: number;
+    protected stateMap: Map<string, ioBroker.State>;
+    /** @inheritDoc */
     get customName(): string;
+    /** @inheritDoc */
     get room(): RoomBase;
     protected readonly individualStateCallbacks: Map<string, Array<(val: ioBroker.StateValue) => void>>;
     protected constructor(_info: IoBrokerDeviceInfo, deviceType: DeviceType);
+    /** @inheritDoc */
     get id(): string;
     /**
      * Getter info
-     * @return {IoBrokerDeviceInfo}
+     * @returns The device info
      */
     get info(): IoBrokerDeviceInfo;
-    /**
-     * Setter info
-     * @param {IoBrokerDeviceInfo} value
-     */
-    set info(value: IoBrokerDeviceInfo);
-    /**
-     * Getter ioConn
-     * @return {IOBrokerConnection}
-     */
     get ioConn(): IOBrokerConnection | undefined;
     static addRoom(shortName: string, settings: RoomDeviceAddingSettings): void;
     static checkMissing(): void;
+    /** @inheritDoc */
     loadDeviceSettings(): void;
     /**
      * Allows to react on the state change of a given state with the passed cb
-     * @param {string} stateName Last part of the id e.g. "available" not "zigbee.0.00158d00053d3e4b.available"
-     * @param {(val: ioBroker.StateValue) => void} cb Desired Callback Action, with passed ioBroker.StateValue
+     * @param stateName - Last part of the id e.g. "available" not "zigbee.0.00158d00053d3e4b.available"
+     * @param cb - Desired Callback Action, with passed ioBroker.StateValue
      */
     addIndividualStateCallback(stateName: string, cb: (val: ioBroker.StateValue) => void): void;
     /**
      * Returns whether a connection to ioBroker is established or not
-     * @param showError If true, an error message will be written to the log if the connection is not established
+     * @param showError - If true, an error message will be written to the log if the connection is not established
+     * @returns Whether a connection exists
      */
     checkIoConnection(showError?: boolean): boolean;
+    /**
+     * Updates the state of a given data point
+     * @param {string[]} idSplit - ID of the data point
+     * @param {ioBroker.State} state - New state
+     * @param {boolean} initial - Whether this is during the initial update
+     * @param {boolean} pOverride - Whether the child class did override this method
+     */
     abstract update(idSplit: string[], state: ioBroker.State, initial: boolean, pOverride: boolean): void;
     log(level: LogLevel, message: string, logDebugType?: LogDebugType): void;
+    /** @inheritDoc */
     toJSON(): Partial<IoBrokerBaseDevice>;
+    /** @inheritDoc */
     persistDeviceInfo(): void;
     protected addToCorrectRoom(): void;
     /**
      * Sets the state of a given data point and returns true if that was successful.
-     * @param pointId Data point to write to
-     * @param state Data to write
-     * @param onSuccess Callback to run on successfully written data
-     * @param onError Callback to run if an error has occurred during writing the data
+     * @param pointId - Data point to write to
+     * @param state - Data to write
+     * @param onSuccess - Callback to run on successfully written data
+     * @param onError - Callback to run if an error has occurred during writing the data
      */
     protected setState(pointId: string, state: string | number | boolean | ioBroker.State | ioBroker.SettableState | null, onSuccess?: (() => void) | undefined, onError?: ((error: Error) => void) | undefined): void;
 }

package/lib/server/devices/IoBrokerBaseDevice.js

@@ -5,9 +5,11 @@ const services_1 = require("../services");
 const models_1 = require("../../models");
 const ioBroker_1 = require("../ioBroker");
 class IoBrokerBaseDevice {
+    /** @inheritDoc */
     get customName() {
         return this.info.customName;
     }
+    /** @inheritDoc */
     get room() {
         if (this._room === undefined) {
             this._room = services_1.Utils.guard(services_1.API.getRoom(this.info.room));
@@ -17,14 +19,24 @@ class IoBrokerBaseDevice {
     constructor(_info, deviceType) {
         this._info = _info;
         this.deviceType = deviceType;
+        /**
+         * @inheritDoc
+         * @default undefined (no Settings)
+         */
         this.settings = undefined;
         this._room = undefined;
+        /** @inheritDoc */
         this.deviceCapabilities = [];
+        // If configured > 0, this indicates the minimum time between state writes in ms
+        this._debounceStateDelay = 0;
+        this._lastWrite = 0;
+        this.stateMap = new Map();
         this.individualStateCallbacks = new Map();
         this.addToCorrectRoom();
         this.persistDeviceInfo();
         services_1.Utils.guardedTimeout(this.loadDeviceSettings, 300, this);
     }
+    /** @inheritDoc */
     get id() {
         const result = services_1.Utils.guard(this.info.allDevicesKey);
         if (result === '0' || result === '1') {
@@ -34,28 +46,17 @@ class IoBrokerBaseDevice {
     }
     /**
      * Getter info
-     * @return {IoBrokerDeviceInfo}
+     * @returns The device info
      */
     get info() {
         return this._info;
     }
-    /**
-     * Setter info
-     * @param {IoBrokerDeviceInfo} value
-     */
-    set info(value) {
-        this._info = value;
-    }
-    /**
-     * Getter ioConn
-     * @return {IOBrokerConnection}
-     */
     get ioConn() {
         return ioBroker_1.ioBrokerMain.iOConnection;
     }
     static addRoom(shortName, settings) {
         if (this.roomAddingSettings[shortName] !== undefined) {
-            services_1.ServerLogService.writeLog(models_1.LogLevel.Alert, `Es gibt bereits ein Registrat für HmIpRoomsettings für den Raumnamen "${shortName}"`);
+            services_1.ServerLogService.writeLog(models_1.LogLevel.Alert, `Es gibt bereits ein Registrat für Roomsetings für den Raumnamen "${shortName}"`);
             return;
         }
         this.roomAddingSettings[shortName] = settings;
@@ -65,14 +66,15 @@ class IoBrokerBaseDevice {
             this.roomAddingSettings[rName].checkMissing();
         }
     }
+    /** @inheritDoc */
     loadDeviceSettings() {
         var _a;
         (_a = this.settings) === null || _a === void 0 ? void 0 : _a.initializeFromDb(this);
     }
     /**
      * Allows to react on the state change of a given state with the passed cb
-     * @param {string} stateName Last part of the id e.g. "available" not "zigbee.0.00158d00053d3e4b.available"
-     * @param {(val: ioBroker.StateValue) => void} cb Desired Callback Action, with passed ioBroker.StateValue
+     * @param stateName - Last part of the id e.g. "available" not "zigbee.0.00158d00053d3e4b.available"
+     * @param cb - Desired Callback Action, with passed ioBroker.StateValue
      */
     addIndividualStateCallback(stateName, cb) {
         let arr = this.individualStateCallbacks.get(stateName);
@@ -86,7 +88,8 @@ class IoBrokerBaseDevice {
     }
     /**
      * Returns whether a connection to ioBroker is established or not
-     * @param showError If true, an error message will be written to the log if the connection is not established
+     * @param showError - If true, an error message will be written to the log if the connection is not established
+     * @returns Whether a connection exists
      */
     checkIoConnection(showError = false) {
         if (!this.ioConn && showError) {
@@ -102,9 +105,11 @@ class IoBrokerBaseDevice {
             debugType: logDebugType,
         });
     }
+    /** @inheritDoc */
     toJSON() {
         return services_1.Utils.jsonFilter(this, ['individualStateCallbacks'], ['_room']);
     }
+    /** @inheritDoc */
     persistDeviceInfo() {
         services_1.Utils.guardedTimeout(() => {
             var _a;
@@ -142,23 +147,31 @@ class IoBrokerBaseDevice {
     }
     /**
      * Sets the state of a given data point and returns true if that was successful.
-     * @param pointId Data point to write to
-     * @param state Data to write
-     * @param onSuccess Callback to run on successfully written data
-     * @param onError Callback to run if an error has occurred during writing the data
+     * @param pointId - Data point to write to
+     * @param state - Data to write
+     * @param onSuccess - Callback to run on successfully written data
+     * @param onError - Callback to run if an error has occurred during writing the data
      */
     setState(pointId, state, onSuccess = undefined, onError = undefined) {
         var _a;
         if (!this.checkIoConnection(true)) {
             return;
         }
+        if (this._debounceStateDelay > 0 && services_1.Utils.nowMS() - this._lastWrite < this._debounceStateDelay) {
+            services_1.Utils.guardedTimeout(() => {
+                this.log(models_1.LogLevel.Trace, `Debounced write for ${pointId} to ${state}`);
+                this.setState(pointId, state, onSuccess, onError);
+            }, this._debounceStateDelay, this);
+            return;
+        }
+        this._lastWrite = services_1.Utils.nowMS();
         (_a = this.ioConn) === null || _a === void 0 ? void 0 : _a.setState(pointId, state, (err) => {
             if (err) {
                 if (onError) {
                     onError(err);
                 }
                 else {
-                    console.log(`Error occured while setting state "${pointId}" to "${state}": ${err}`);
+                    this.log(models_1.LogLevel.Error, `Error occured while setting state "${pointId}" to "${state}": ${err}`);
                 }
                 return;
             }
@@ -169,4 +182,7 @@ class IoBrokerBaseDevice {
     }
 }
 exports.IoBrokerBaseDevice = IoBrokerBaseDevice;
+/**
+ * The settings for adding devices to Rooms
+ */
 IoBrokerBaseDevice.roomAddingSettings = {};

package/lib/server/devices/IoBrokerDeviceInfo.d.ts

@@ -13,8 +13,8 @@ export declare class IoBrokerDeviceInfo extends DeviceInfo {
     private static replaceInvalidIdChars;
     /**
      * Extracts the relevant infos from the passed deviceConfig and combines them in a new Info object
-     * @param {deviceConfig} pDevConf The device Config based on the extracted devices.json from ioBroker
-     * @param {boolean} isJsStateChildObject Within JS Objects, creating devices is limited,
+     * @param pDevConf - The device Config based on the extracted devices.json from ioBroker
+     * @param isJsStateChildObject - Within JS Objects, creating devices is limited,
      * so we name the first child state for the object creation (e.g. javascript.0.00-EnergyManager.CurrentProduction)
      */
     constructor(pDevConf: deviceConfig, isJsStateChildObject?: boolean);

package/lib/server/devices/IoBrokerDeviceInfo.js

@@ -19,8 +19,8 @@ class IoBrokerDeviceInfo extends DeviceInfo_1.DeviceInfo {
     }
     /**
      * Extracts the relevant infos from the passed deviceConfig and combines them in a new Info object
-     * @param {deviceConfig} pDevConf The device Config based on the extracted devices.json from ioBroker
-     * @param {boolean} isJsStateChildObject Within JS Objects, creating devices is limited,
+     * @param pDevConf - The device Config based on the extracted devices.json from ioBroker
+     * @param isJsStateChildObject - Within JS Objects, creating devices is limited,
      * so we name the first child state for the object creation (e.g. javascript.0.00-EnergyManager.CurrentProduction)
      */
     constructor(pDevConf, isJsStateChildObject = false) {
@@ -46,7 +46,8 @@ class IoBrokerDeviceInfo extends DeviceInfo_1.DeviceInfo {
             if (idSplit.length > 4) {
                 this.valueName = idSplit[4];
             }
-            /** Name-Split
+            /**
+             * Name-Split
              * 0: Indikator own "00"
              * 1: "HmIP"
              * 2: Raum
@@ -60,7 +61,8 @@ class IoBrokerDeviceInfo extends DeviceInfo_1.DeviceInfo {
             return;
         }
         else {
-            /** Name-Split
+            /**
+             * Name-Split
              * 0: Indikator own "00"
              * 1: "EnergyManager"
              * 2: Raum