hoffmation-base 3.0.0-alpha.9 → 3.0.0-alpha.90

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

@@ -1,64 +1,82 @@
 import { iRoomDevice } from './baseDeviceInterfaces';
 import { LogDebugType } from '../services';
-import { DeviceSettings, LogLevel, RoomBase, RoomDeviceAddingSettings } from '../../models';
+import { DeviceSettings, iJsonOmitKeys, LogLevel, RoomBase, RoomDeviceAddingSettings } from '../../models';
 import { IOBrokerConnection } from '../ioBroker';
 import { DeviceType } from './deviceType';
 import { IoBrokerDeviceInfo } from './IoBrokerDeviceInfo';
 import { DeviceCapability } from './DeviceCapability';
-export declare abstract class IoBrokerBaseDevice implements iRoomDevice {
+export declare abstract class IoBrokerBaseDevice implements iRoomDevice, iJsonOmitKeys {
     protected _info: IoBrokerDeviceInfo;
     deviceType: DeviceType;
-    settings: DeviceSettings | undefined;
+    /** @inheritDoc */
+    readonly jsonOmitKeys: string[];
+    /**
+     * 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,26 @@ class IoBrokerBaseDevice {
     constructor(_info, deviceType) {
         this._info = _info;
         this.deviceType = deviceType;
+        /** @inheritDoc */
+        this.jsonOmitKeys = ['individualStateCallbacks'];
+        /**
+         * @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 +48,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 +68,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 +90,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 +107,11 @@ class IoBrokerBaseDevice {
             debugType: logDebugType,
         });
     }
+    /** @inheritDoc */
     toJSON() {
-        return services_1.Utils.jsonFilter(this, ['individualStateCallbacks'], ['_room']);
+        return services_1.Utils.jsonFilter(this, this.jsonOmitKeys, ['_room']);
     }
+    /** @inheritDoc */
     persistDeviceInfo() {
         services_1.Utils.guardedTimeout(() => {
             var _a;
@@ -142,23 +149,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 +184,7 @@ class IoBrokerBaseDevice {
     }
 }
 exports.IoBrokerBaseDevice = IoBrokerBaseDevice;
+/**
+ * The settings for adding devices to Rooms
+ */
 IoBrokerBaseDevice.roomAddingSettings = {};

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

@@ -6,17 +6,19 @@ export declare class IoBrokerDeviceInfo extends DeviceInfo {
     deviceRoomIndex: number;
     type: 'device' | 'channel' | 'state';
     fullID: string;
-    channel?: number;
-    valueName?: string;
     devConf: deviceConfig;
     static idSplitter(id: string): string[];
     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,
-     * so we name the first child state for the object creation (e.g. javascript.0.00-EnergyManager.CurrentProduction)
+     * @param pDevConf - The device Config based on the extracted devices.json from ioBroker
+     * @param deviceId - The id of the device
+     * @param deviceType - The type of the device
+     * @param room - The room id of the device
+     * @param deviceRoomIndex - Index of this device in regards to the devicetype.
      */
-    constructor(pDevConf: deviceConfig, isJsStateChildObject?: boolean);
+    constructor(pDevConf: deviceConfig, deviceId: string, deviceType: string, room: string, deviceRoomIndex: number);
+    static byStateJsSplit(pDevConf: deviceConfig): IoBrokerDeviceInfo;
+    static byDeviceConfig(pDevConf: deviceConfig): IoBrokerDeviceInfo;
     toJSON(): Partial<IoBrokerDeviceInfo>;
 }

package/lib/server/devices/IoBrokerDeviceInfo.js

@@ -19,59 +19,63 @@ 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,
-     * so we name the first child state for the object creation (e.g. javascript.0.00-EnergyManager.CurrentProduction)
+     * @param pDevConf - The device Config based on the extracted devices.json from ioBroker
+     * @param deviceId - The id of the device
+     * @param deviceType - The type of the device
+     * @param room - The room id of the device
+     * @param deviceRoomIndex - Index of this device in regards to the devicetype.
      */
-    constructor(pDevConf, isJsStateChildObject = false) {
+    constructor(pDevConf, deviceId, deviceType, room, deviceRoomIndex) {
         super();
         this.devConf = pDevConf;
         this.type = pDevConf.type;
-        const idSplit = IoBrokerDeviceInfo.idSplitter(pDevConf._id);
         this.fullID = pDevConf._id;
-        this.devID = idSplit[2];
+        this.devID = deviceId;
         this.fullName = pDevConf.common.name;
+        this.deviceType = deviceType;
+        this.deviceRoomIndex = deviceRoomIndex;
+        this.room = room;
+    }
+    static byStateJsSplit(pDevConf) {
         const nameSplit = pDevConf.common.name.split('-');
-        if (!isJsStateChildObject) {
-            /**
-             * 0: hm-rpc
-             * 1: rcpInstance
-             * 2: Device ID
-             * 3?: Channel
-             * 4?: ValueName
-             */
-            if (idSplit.length > 3) {
-                this.channel = Number(idSplit[3]);
-            }
-            if (idSplit.length > 4) {
-                this.valueName = idSplit[4];
-            }
-            /** Name-Split
-             * 0: Indikator own "00"
-             * 1: "HmIP"
-             * 2: Raum
-             * 3: Was für ein Gerät
-             * 4: Index dieses Gerätes im Raum (ggf. + :Channel)
-             * 5?: Name des Wertes
-             */
-            this.room = nameSplit[2];
-            this.deviceType = nameSplit[3];
-            this.deviceRoomIndex = Number(nameSplit[4].split(':')[0]);
-            return;
-        }
-        else {
-            /** Name-Split
-             * 0: Indikator own "00"
-             * 1: "EnergyManager"
-             * 2: Raum
-             * 3: Was für ein Gerät
-             * 4: Index dieses Gerätes im Raum (ggf. + :Channel)
-             * 5?: Name des Wertes
-             */
-            this.deviceType = nameSplit[1];
-            this.room = nameSplit.length >= 3 ? nameSplit[2] : '';
-            this.deviceRoomIndex = nameSplit.length >= 4 ? Number(nameSplit[3]) : 0;
-        }
+        const idSplit = IoBrokerDeviceInfo.idSplitter(pDevConf._id);
+        /**
+         * Name-Split
+         * 0: Indikator own "00"
+         * 1: "EnergyManager"
+         * 2: Raum
+         * 3: Was für ein Gerät
+         * 4: Index dieses Gerätes im Raum (ggf. + :Channel)
+         * 5?: Name des Wertes
+         */
+        const deviceType = nameSplit[1];
+        const room = nameSplit.length >= 3 ? nameSplit[2] : '';
+        const deviceRoomIndex = nameSplit.length >= 4 ? Number(nameSplit[3]) : 0;
+        return new IoBrokerDeviceInfo(pDevConf, idSplit[2], deviceType, room, deviceRoomIndex);
+    }
+    static byDeviceConfig(pDevConf) {
+        const nameSplit = pDevConf.common.name.split('-');
+        const idSplit = IoBrokerDeviceInfo.idSplitter(pDevConf._id);
+        /**
+         * 0: hm-rpc
+         * 1: rcpInstance
+         * 2: Device ID
+         * 3?: Channel
+         * 4?: ValueName
+         */
+        /**
+         * Name-Split
+         * 0: Indikator own "00"
+         * 1: "HmIP"
+         * 2: Raum
+         * 3: Was für ein Gerät
+         * 4: Index dieses Gerätes im Raum (ggf. + : Channel)
+         * 5?: Name des Wertes
+         */
+        const room = nameSplit[2];
+        const deviceType = nameSplit[3];
+        const deviceRoomIndex = Number(nameSplit[4].split(':')[0]);
+        return new IoBrokerDeviceInfo(pDevConf, idSplit[2], deviceType, room, deviceRoomIndex);
     }
     toJSON() {
         return lodash_1.default.omit(this, ['devConf']);

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

@@ -1,18 +1,56 @@
 import { AcSettings } from '../../../models';
 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
+ */
 export interface iAcDevice extends iBaseDevice {
+    /**
+     * The settings of the air-conditioning device
+     */
     settings: AcSettings;
+    /**
+     * 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
+     */
     readonly temperature: number;
+    /**
+     * The current state of the air-conditioning device
+     */
     readonly mode: AcMode;
     /**
-     * Disable automatic Turn-On for given amount of ms and turn off immediately.
-     * @param {number} timeout
+     * This function should be called to inform the air-conditioning device about a change of the room temperature
+     * @param newTemperatur - The new temperature of the room in degrees Celsius
      */
-    deactivateAutomaticChange(timeout: number): void;
     onTemperaturChange(newTemperatur: number): void;
+    /**
+     * Updates the desired mode of the air-conditioning device and writes it to the device if desired
+     * @param mode - The new desired mode
+     * @param writeToDevice - Whether to write the new mode to the device
+     */
     setDesiredMode(mode: AcMode, writeToDevice: boolean): void;
+    /**
+     * Turns the air-conditioning device on without changing the settings
+     */
     turnOn(): void;
+    /**
+     * 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

@@ -1,11 +1,21 @@
 import { ActuatorSetStateCommand, ActuatorSettings, ActuatorToggleCommand, ActuatorWriteStateToDeviceCommand } from '../../../models';
 import { iRoomDevice } from './iRoomDevice';
 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 {
     /**
      * The settings for this Actuator primarily for controlling its automatic actions
      */
     settings: ActuatorSettings;
+    /**
+     * The target automatic state of the device.
+     * This is used to store the state the device should be in to fall back to it after automatic was blocked e.g. by a user.
+     */
     targetAutomaticState: boolean;
     /**
      * The state value of the device
@@ -25,6 +35,14 @@ export interface iActuator extends iRoomDevice, iTemporaryDisableAutomatic {
      * @param command
      */
     setActuator(command: ActuatorSetStateCommand): void;
+    /**
+     * Toggles the power state of this actuator
+     * @param command
+     */
     toggleActuator(command: ActuatorToggleCommand): boolean;
+    /**
+     * Writes the desired actuator state to the device
+     * @param command
+     */
     writeActuatorStateToDevice(command: ActuatorWriteStateToDeviceCommand): void;
 }

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

@@ -3,12 +3,37 @@ import { DeviceType } from '../deviceType';
 import { DeviceInfo } from '../DeviceInfo';
 import { DeviceCapability } from '../DeviceCapability';
 import { iIdHolder } from '../../../models/iIdHolder';
+/**
+ * This is the main interface for all devices as it ensures certain base functionality.
+ */
 export interface iBaseDevice extends iIdHolder {
+    /**
+     * The settings of the device which are overridden by the specific device implementation
+     */
     readonly settings: DeviceSettings | undefined;
+    /**
+     * The hardware-type of the device.
+     */
     deviceType: DeviceType;
-    info: DeviceInfo;
+    /**
+     * Some basic information about the device (mainly its name, id, room, etc.)
+     */
+    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.
+     */
     readonly deviceCapabilities: DeviceCapability[];
+    /**
+     * This method writes the device Info to the configured persistence layer, to ensure having foreign keys for all other persisted data.
+     */
     persistDeviceInfo(): void;
+    /**
+     * This method loads the device settings from the configured persistence layer.
+     * Whilst this is normally used during startup, it can be called at any time to refresh the settings in case of manual changes within the database.
+     */
     loadDeviceSettings(): void;
+    /**
+     * This mainly enforces all devices to have a toJSON method to ensure a consistent way of serializing devices.
+     */
     toJSON(): Partial<iBaseDevice>;
 }

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

@@ -1,10 +1,18 @@
-import { iRoomDevice } from './iRoomDevice';
-export interface iBatteryDevice extends iRoomDevice {
-    readonly lastBatteryPersist: number;
+import { iBaseDevice } from './iBaseDevice';
+import { Battery } from '../sharedFunctions';
+/**
+ * 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 iBaseDevice {
     /**
-     * The battery status of the device in percentage
-     * @type {number}
+     * Common battery handling like persisting
      */
-    readonly battery: number;
-    persistBatteryDevice(): void;
+    readonly battery: Battery;
+    /**
+     * The battery status of the device in percentage (0 empty - 100 full)
+     */
+    readonly batteryLevel: number;
 }

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,15 +1,57 @@
 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 buttonName - The name of the button
+     * @param pressType - The type of the button press
+     */
     persist(buttonName: string, pressType: ButtonPressType): void;
+    /**
+     * @returns An description of all configured assignments
+     */
     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 position - The position of the button
+     * @param pressType - The type of the button press
+     */
     pressButton(position: ButtonPosition, pressType: ButtonPressType): Error | null;
 }