hoffmation-base 3.0.0-alpha.23 → 3.0.0-alpha.25

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

@@ -10,7 +10,7 @@ class Griffe {
         griffe.sort((a, b) => {
             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,28 +8,40 @@ 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
      * @returns The device info
      */
     get info(): IoBrokerDeviceInfo;
-    set info(value: IoBrokerDeviceInfo);
     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
@@ -43,9 +55,18 @@ export declare abstract class IoBrokerBaseDevice implements iRoomDevice {
      * @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;
     /**

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,17 +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') {
@@ -42,15 +51,12 @@ class IoBrokerBaseDevice {
     get info() {
         return this._info;
     }
-    set info(value) {
-        this._info = value;
-    }
     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;
@@ -60,6 +66,7 @@ class IoBrokerBaseDevice {
             this.roomAddingSettings[rName].checkMissing();
         }
     }
+    /** @inheritDoc */
     loadDeviceSettings() {
         var _a;
         (_a = this.settings) === null || _a === void 0 ? void 0 : _a.initializeFromDb(this);
@@ -98,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;
@@ -173,4 +182,7 @@ class IoBrokerBaseDevice {
     }
 }
 exports.IoBrokerBaseDevice = IoBrokerBaseDevice;
+/**
+ * The settings for adding devices to Rooms
+ */
 IoBrokerBaseDevice.roomAddingSettings = {};

package/lib/server/devices/baseDeviceInterfaces/iAcDevice.d.ts

@@ -3,6 +3,8 @@ import { AcMode } from '../../services';
 import { iBaseDevice } from './iBaseDevice';
 /**
  * Interface for normal air-conditioning devices
+ *
+ * For devices with {@link DeviceCapability.ac} capability.
  * TODO: Migrate to new Command-Based System
  * TODO: Extend from iActuator
  */
@@ -15,6 +17,10 @@ export interface iAcDevice extends iBaseDevice {
      * Whether the air-conditioning device is currently on
      */
     readonly on: boolean;
+    /**
+     * The temperature of the room where this device is located
+     */
+    readonly roomTemperature: number;
     /**
      * The current temperature of the air-conditioning device in degrees Celsius
      */
@@ -25,13 +31,13 @@ export interface iAcDevice extends iBaseDevice {
     readonly mode: AcMode;
     /**
      * This function should be called to inform the air-conditioning device about a change of the room temperature
-     * @param {number} newTemperatur - The new temperature of the room in degrees Celsius
+     * @param newTemperatur - The new temperature of the room in degrees Celsius
      */
     onTemperaturChange(newTemperatur: number): void;
     /**
      * Updates the desired mode of the air-conditioning device and writes it to the device if desired
-     * @param {AcMode} mode - The new desired mode
-     * @param {boolean} writeToDevice - Whether to write the new mode to the device
+     * @param mode - The new desired mode
+     * @param writeToDevice - Whether to write the new mode to the device
      */
     setDesiredMode(mode: AcMode, writeToDevice: boolean): void;
     /**
@@ -42,4 +48,9 @@ export interface iAcDevice extends iBaseDevice {
      * Turns the air-conditioning device off
      */
     turnOff(): void;
+    /**
+     * Calculates the desired mode based on the current settings and the room temperature
+     * @returns The desired mode
+     */
+    calculateDesiredMode(): AcMode;
 }

package/lib/server/devices/baseDeviceInterfaces/iActuator.d.ts

@@ -4,6 +4,8 @@ import { iTemporaryDisableAutomatic } from './iTemporaryDisableAutomatic';
 /**
  * Interface for Actuators.
  * An actuator can be any device whos primary function is to be on or off e.g a light, an outlet, a fan, etc.
+ *
+ * For devices with {@link DeviceCapability.actuator} capability.
  */
 export interface iActuator extends iRoomDevice, iTemporaryDisableAutomatic {
     /**

package/lib/server/devices/baseDeviceInterfaces/iBaseDevice.d.ts

@@ -18,7 +18,7 @@ export interface iBaseDevice extends iIdHolder {
     /**
      * Some basic information about the device (mainly its name, id, room, etc.)
      */
-    info: DeviceInfo;
+    readonly info: DeviceInfo;
     /**
      * The capabilities of the device thus referencing other interfaces which then can be used to treat devices regardless of their hardware-type.
      */

package/lib/server/devices/baseDeviceInterfaces/iBatteryDevice.d.ts

@@ -2,6 +2,8 @@ import { iRoomDevice } from './iRoomDevice';
 /**
  * Interface for Battery Devices.
  * A battery device can be any device that is powered by a battery e.g. a remote, a sensor, etc.
+ *
+ * For devices with {@link DeviceCapability.battery} capability.
  */
 export interface iBatteryDevice extends iRoomDevice {
     /**

package/lib/server/devices/baseDeviceInterfaces/iBluetoothDetector.d.ts

@@ -1,6 +1,14 @@
 import { iRoomDevice } from './iRoomDevice';
 import { ProximityCallback, TrilaterationBasePoint } from '../espresense';
+/**
+ * Interface for Bluetooth detector devices, providing proximity information for tracked devices
+ *
+ * For devices with {@link DeviceCapability.bluetoothDetector} capability.
+ */
 export interface iBluetoothDetector extends iRoomDevice {
+    /**
+     * The position of the device to allow for trilateration-calculations
+     */
     position: TrilaterationBasePoint;
     /**
      * Add callback to react on a specified device entering/leaving a given zone
@@ -9,17 +17,17 @@ export interface iBluetoothDetector extends iRoomDevice {
     addProximityCallback(cb: ProximityCallback): void;
     /**
      * Gets the distance of a currently present device
-     * @param {string} deviceName - The mapped Device name
-     * @param {number} maxAge - The maximum age in seconds to still respect that device
-     * @returns {number | undefined} Distance in meters or undefined if currently not present
+     * @param deviceName - The mapped Device name
+     * @param maxAge - The maximum age in seconds to still respect that device
+     * @returns Distance in meters or undefined if currently not present
      */
     distanceOfDevice(deviceName: string, maxAge: number): number | undefined;
     /**
      * Check if a device is currently present and below the given Distance
-     * @param {string} deviceName - The mapped Device name
-     * @param {number} maxDistance - The maximum distance in meters
-     * @param {number} maxAge - The maximum age in seconds to still respect that device
-     * @returns {boolean}
+     * @param deviceName - The mapped Device name
+     * @param maxDistance - The maximum distance in meters
+     * @param maxAge - The maximum age in seconds to still respect that device
+     * @returns
      */
     isDevicePresent(deviceName: string, maxDistance: number, maxAge: number): boolean;
 }

package/lib/server/devices/baseDeviceInterfaces/iButtonSwitch.d.ts

@@ -1,18 +1,47 @@
 import { Button, ButtonPosition, ButtonPressType } from '../button';
 import { iRoomDevice } from './iRoomDevice';
+/**
+ * Interface for Button Switch devices, providing e.g. access to the buttons and their assignments.
+ *
+ * For devices with {@link DeviceCapability.buttonSwitch} capability.
+ */
 export interface iButtonSwitch extends iRoomDevice {
+    /**
+     * The Top-Left Button which can be found on normale 4-6 Button switches
+     */
     buttonTopLeft: Button | undefined;
+    /**
+     * The Top-Right Button which can be found on normale 4-6 Button switches
+     */
     buttonTopRight: Button | undefined;
+    /**
+     * The vertically Middle and horicontally Left Button which can be found on 6 Button switches
+     */
     buttonMidLeft: Button | undefined;
+    /**
+     * The vertically Middle and horicontally Right Button which can be found on 6 Button switches
+     */
     buttonMidRight: Button | undefined;
+    /**
+     * The Bottom-Left Button which can be found on normale 4-6 Button switches
+     */
     buttonBotLeft: Button | undefined;
+    /**
+     * The Bottom-Right Button which can be found on normale 4-6 Button switches
+     */
     buttonBotRight: Button | undefined;
+    /**
+     * The Bottom Button which can be found on vertical 2 Button switches
+     */
     buttonBot: Button | undefined;
+    /**
+     * The Top Button which can be found on vertical 2 Button switches
+     */
     buttonTop: Button | undefined;
     /**
      * Persist the button press to the persistent storage
-     * @param {string} buttonName - The name of the button
-     * @param {ButtonPressType} pressType - The type of the button press
+     * @param buttonName - The name of the button
+     * @param pressType - The type of the button press
      */
     persist(buttonName: string, pressType: ButtonPressType): void;
     /**
@@ -21,8 +50,8 @@ export interface iButtonSwitch extends iRoomDevice {
     getButtonAssignment(): string;
     /**
      * Method to simulate a button press (e.g. for testing or to use a specific logic which is bound to this button)
-     * @param {ButtonPosition} position - The position of the button
-     * @param {ButtonPressType} pressType - The type of the button press
+     * @param position - The position of the button
+     * @param pressType - The type of the button press
      */
     pressButton(position: ButtonPosition, pressType: ButtonPressType): Error | null;
 }

package/lib/server/devices/baseDeviceInterfaces/iCameraDevice.d.ts

@@ -1,19 +1,52 @@
 import { iMotionSensor } from './iMotionSensor';
 import { CameraSettings } from '../../../models';
+import { iBaseDevice } from './iBaseDevice';
+/**
+ * An interface for any device with {@link DeviceCapability.camera} capability
+ */
 export interface iCameraDevice extends iMotionSensor {
+    /**
+     * The settings of the camera device
+     */
     settings: CameraSettings;
+    /**
+     * The last image taken by the camera as a base64 encoded string
+     */
     readonly lastImage: string;
+    /**
+     * The link to access the mpeg stream of the camera
+     */
     readonly mpegStreamLink: string;
+    /**
+     * The link to access the h264 stream of the camera
+     */
     readonly h264IosStreamLink: string;
+    /**
+     * The link to access the rtsp stream of the camera
+     */
     readonly rtspStreamLink: string;
+    /**
+     * The link to obtain a fresh image from the camera
+     */
     readonly currentImageLink: string;
-    readonly alarmBlockedByGriff: boolean;
-    readonly alarmBlockedByGriffTimeStamp: number;
     /**
-     * Inform this camera of certain handles being opened/closed to allow it to react accordingly (e.g. don't send alarm, for owner going into the garden)
-     * @param {boolean} open - Whether the handle is open or closed
+     * Whether the alarm is currently blocked by a certain device (e.g. an open handle for house-to-garden door)
+     */
+    readonly alarmBlockedByDevices: boolean;
+    /**
+     * Whether the camera has currently detected a dog
+     */
+    readonly dogDetected: boolean;
+    /**
+     * Whether the camera has currently detected a human
+     */
+    readonly personDetected: boolean;
+    /**
+     * Inform this camera of a device, which blocks the alarm (or should unlift its block)
+     * @param device - The device to block/unblock the alarm for
+     * @param block - Whether to block the alarm for the device or lift the block
      */
-    onGriffUpdate(open: boolean): void;
+    blockForDevice(device: iBaseDevice, block: boolean): void;
     /**
      * Inform this camera of state updates within iOBroker
      * TODO: Make camera independent of iOBroker