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

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

@@ -2,18 +2,26 @@ import { iLamp } from './iLamp';
 import { DimmerSetLightCommand, DimmerSettings, LampToggleLightCommand } from '../../../models';
 /**
  * This interface represents a dimmable lamp device.
+ *
+ * For devices with {@link DeviceCapability.dimmablelamp} capability.
  */
 export interface iDimmableLamp extends iLamp {
+    /**
+     * The settings of the dimmer providing e.g. brightness settings for different times of the day.
+     */
     settings: DimmerSettings;
+    /**
+     * The current brightness of the light in percent.
+     */
     readonly brightness: number;
     /**
      * This function toggles the light on or off.
-     * @param {LampToggleLightCommand} command - The command to execute on the light device.
+     * @param command - The command to execute on the light device.
      */
     toggleLight(command: LampToggleLightCommand): void;
     /**
      * This function sets the light to a specific value.
-     * @param {DimmerSetLightCommand} command - The command to execute on the light device.
+     * @param command - The command to execute on the light device.
      */
     setLight(command: DimmerSetLightCommand): void;
 }

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

@@ -1,10 +1,29 @@
 import { iExcessEnergyConsumer } from './iExcessEnergyConsumer';
 import { iBaseDevice } from './iBaseDevice';
 import { iDisposable } from '../../services';
+/**
+ * Interface for devices that can manage energy consumption and production.
+ *
+ * For devices with {@link DeviceCapability.energyManager} capability.
+ */
 export interface iEnergyManager extends iBaseDevice, iDisposable {
+    /**
+     * The total energy being excessive at the moment of last calculation.
+     *
+     * For devices with {@link DeviceCapability.energyManager} capability.
+     */
     excessEnergy: number;
+    /**
+     * The total wattaage being injected into the grid at the moment of last calculation.
+     */
     readonly injectingWattage: number;
+    /**
+     * The total wattage being drawn from the grid at the moment of last calculation.
+     */
     readonly drawingWattage: number;
+    /**
+     * The total wattage being consumed within the house at the moment of last calculation.
+     */
     readonly selfConsumingWattage: number;
     /**
      * Add a device that can consume excess energy

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

@@ -1,13 +1,27 @@
 import { ExcessEnergyConsumerSettings } from '../../../models';
 import { iBaseDevice } from './iBaseDevice';
+/**
+ * This interface represents a device that can consume excess energy.
+ *
+ * For devices with {@link DeviceCapability.excessEnergyConsumer} capability.
+ */
 export interface iExcessEnergyConsumer extends iBaseDevice {
+    /**
+     * The energy consuming settings for this device
+     */
     readonly energySettings: ExcessEnergyConsumerSettings;
+    /**
+     * Consumption in Watts, needed to manage the Excess consumer
+     */
     currentConsumption: number;
+    /**
+     * Whether this consumer is currently on or off
+     */
     on: boolean;
     /**
      * Check if this device is available to consume excess energy
      * --> Device might be unavailable due to a force action from the user or other circumstances
-     * @returns {boolean} Whether this device is available to be turned on to consume excess energy
+     * @returns Whether this device is available to be turned on to consume excess energy
      */
     isAvailableForExcessEnergy(): boolean;
     /**
@@ -20,7 +34,7 @@ export interface iExcessEnergyConsumer extends iBaseDevice {
     turnOffDueToMissingEnergy(): void;
     /**
      * Check if this device was activated by excess energy
-     * @returns {boolean} Whether this device was activated by excess energy
+     * @returns Whether this device was activated by excess energy
      */
     wasActivatedByExcessEnergy(): boolean;
 }

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

@@ -1,7 +1,18 @@
 import { GarageDoorOpenerSettings } from '../../../models';
 import { iRoomDevice } from './iRoomDevice';
+/**
+ * This interface represents a garage door opener device.
+ *
+ * For devices with {@link DeviceCapability.garageDoorOpener} capability.
+ */
 export interface iGarageDoorOpener extends iRoomDevice {
+    /**
+     * The settings of the garage door opener
+     */
     settings: GarageDoorOpenerSettings;
+    /**
+     * Whether the garage door is currently closed
+     */
     readonly isClosed: boolean;
     /**
      * Open the garage door

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

@@ -1,21 +1,33 @@
 import { WindowPosition } from '../models';
 import { iRoomDevice } from './iRoomDevice';
+/**
+ * Interface for Handle Sensors.
+ * A handle sensor can be any device that is capable of detecting the position of a window handle e.g. a sensor, a window handle, etc.
+ *
+ * For devices with {@link DeviceCapability.handleSensor} capability.
+ */
 export interface iHandleSensor extends iRoomDevice {
+    /**
+     * The current position of the handle
+     */
     position: WindowPosition;
+    /**
+     * The time the handle was open in minutes
+     */
     minutesOpen: number;
     /**
      * Add a callback that is called when the handle is change to open
-     * @param {(pValue: boolean) => void} pCallback - The callback to fire
+     * @param pCallback - The callback to fire
      */
     addOffenCallback(pCallback: (pValue: boolean) => void): void;
     /**
      * Add a callback that is called when the handle is changed to ajar
-     * @param {(pValue: boolean) => void} pCallback - The callback to fire
+     * @param pCallback - The callback to fire
      */
     addKippCallback(pCallback: (pValue: boolean) => void): void;
     /**
      * Add a callback that is called when the handle is changed to closed
-     * @param {(pValue: boolean) => void} pCallback - The callback to fire
+     * @param pCallback - The callback to fire
      */
     addClosedCallback(pCallback: (pValue: boolean) => void): void;
 }

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

@@ -2,14 +2,40 @@
 import { HeaterSettings } from '../../../models';
 import { iRoomDevice } from './iRoomDevice';
 import { iDisposable } from '../../services';
+/**
+ * This interface represents a heater device.
+ *
+ * For devices with {@link DeviceCapability.heater} capability.
+ */
 export interface iHeater extends iRoomDevice, iDisposable {
+    /**
+     * The settings of the heater
+     */
     settings: HeaterSettings;
+    /**
+     * The desired temperature in degree Celsius for this room.
+     */
     desiredTemperature: number;
-    readonly humidity: number;
+    /**
+     * The current valve position of the heater (between 0 and 1.0)
+     */
     readonly iLevel: number;
+    /**
+     * The current temperature in degree Celsius of the heater
+     */
     readonly iTemperature: number;
-    roomTemperature: number;
+    /**
+     * The current room temperature in degree Celsius
+     */
+    readonly roomTemperature: number;
+    /**
+     * The interval to persist the heater information
+     * This mainly enforces the interval to be implemented.
+     */
     readonly persistHeaterInterval: NodeJS.Timeout;
+    /**
+     * Whether the heater is currently in a season turnoff state (no heating in summer)
+     */
     seasonTurnOff: boolean;
     /**
      * Perform a check to calculate the new desired heater state

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

@@ -1,12 +1,24 @@
 /// <reference types="node" />
 import { iRoomDevice } from './iRoomDevice';
 export declare const UNDEFINED_HUMIDITY_VALUE = -1;
+/**
+ * This interface represents a humidity sensor device.
+ *
+ * For devices with {@link DeviceCapability.humiditySensor} capability.
+ */
 export interface iHumiditySensor extends iRoomDevice {
+    /**
+     * The interval to persist the humidity sensor information
+     * This mainly enforces the interval to be implemented.
+     */
     readonly persistHumiditySensorInterval: NodeJS.Timeout;
+    /**
+     * The current humidity in percent
+     */
     readonly humidity: number;
     /**
      * Add a callback that is called when the humidity changes
-     * @param {(pValue: number) => void} pCallback - The callback to fire
+     * @param pCallback - The callback to fire
      */
     addHumidityCallback(pCallback: (pValue: number) => void): void;
     /**

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

@@ -1,4 +1,15 @@
 import { iRoomDevice } from './iRoomDevice';
+/**
+ * This interface represents a illumination sensor device.
+ *
+ * For devices with {@link DeviceCapability.illuminationSensor} capability.
+ */
 export interface iIlluminationSensor extends iRoomDevice {
+    /**
+     * The current illumination level detected by the sensor
+     *
+     * For {@link DeviceType.ZigbeeAquaraMotion} devices, this is the current illuminance in lux.
+     * TODO: Add unit and make it comparable
+     */
     currentIllumination: number;
 }

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

@@ -1,5 +1,10 @@
 import { LampSetLightCommand, LampSetTimeBasedCommand, LampToggleLightCommand } from '../../../models';
 import { iActuator } from './iActuator';
+/**
+ * This interface represents a lamp device.
+ *
+ * For devices with {@link DeviceCapability.lamp} capability.
+ */
 export interface iLamp extends iActuator {
     /**
      * The state value of the device
@@ -7,7 +12,7 @@ export interface iLamp extends iActuator {
     readonly lightOn: boolean;
     /**
      * Changes the state of the lamp based on the time
-     * @param {LampSetTimeBasedCommand} command - The command to execute
+     * @param command - The command to execute
      */
     setTimeBased(command: LampSetTimeBasedCommand): void;
     /**

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

@@ -1,13 +1,28 @@
 import { LedSetLightCommand, LedSettings } from '../../../models';
 import { iDimmableLamp } from './iDimmableLamp';
+/**
+ * Interface for RGB-CCT LED-Devices.
+ * A RGB-CCT LED-Device is a LED-Device that is capable of emitting light in different colors and color temperatures.
+ *
+ * For devices with {@link DeviceCapability.ledLamp} capability.
+ */
 export interface iLedRgbCct extends iDimmableLamp {
+    /**
+     * The settings of the LED-Device (e.g. brightness, color, colortemp) for different times of the day
+     */
     settings: LedSettings;
+    /**
+     * The currently active color in HEX representation
+     */
     readonly color: string;
+    /**
+     * The currently active color temperature
+     */
     readonly colortemp: number;
     /**
      * This function sets the light to a specific value
      * Accessible in API
-     * @param {LedSetLightCommand} c - The command to execute
+     * @param c - The command to execute
      */
     setLight(c: LedSetLightCommand): void;
 }

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

@@ -1,3 +1,8 @@
+/**
+ * Interface for a device that can measure the load power in Watts
+ *
+ * For devices with {@link DeviceCapability.loadMetering} capability.
+ */
 export interface iLoadMeter {
     /**
      * The current load power in Watts

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

@@ -0,0 +1,31 @@
+import { iRoomDevice } from './iRoomDevice';
+import { MagnetPosition } from '../models';
+/**
+ * This interface represents a magnet sensor device.
+ *
+ * For devices with {@link DeviceCapability.magnetSensor} capability.
+ */
+export interface iMagnetSensor extends iRoomDevice {
+    /**
+     * The current state of the Magnet Contact
+     */
+    position: MagnetPosition;
+    /**
+     * Whether a telegram message should be sent when the magnet contact is opened
+     */
+    telegramOnOpen: boolean;
+    /**
+     * Whether to announce when the magnet contact is opened using {@link iSpeaker}
+     */
+    speakOnOpen: boolean;
+    /**
+     * Add a callback that is called when the magnet contact is opened
+     * @param pCallback - The callback to fire
+     */
+    addOpenCallback(pCallback: (pValue: boolean) => void): void;
+    /**
+     * Add a callback that is called when the magnet contact is closed
+     * @param pCallback - The callback to fire
+     */
+    addClosedCallback(pCallback: (pValue: boolean) => void): void;
+}

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

@@ -1,12 +1,26 @@
 import { MotionSensorSettings } from '../../../models';
 import { iRoomDevice } from './iRoomDevice';
+/**
+ * This interface represents a motion sensor device.
+ *
+ * For devices with {@link DeviceCapability.motionSensor} capability.
+ */
 export interface iMotionSensor extends iRoomDevice {
+    /**
+     * The settings of the MotionSensor
+     */
     settings: MotionSensorSettings;
+    /**
+     * Whether motion is currently detected
+     */
     readonly movementDetected: boolean;
     /**
      * Time since the last motion was detected in seconds
      */
     readonly timeSinceLastMotion: number;
+    /**
+     * The number of detections today so far
+     */
     detectionsToday: number;
     /**
      * Adds a callback for when a motion state has changed.

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

@@ -1,5 +1,11 @@
 import { RoomBase } from '../../../models';
 import { iBaseDevice } from './iBaseDevice';
+/**
+ * This interface represents a device that is located in a single room.
+ */
 export interface iRoomDevice extends iBaseDevice {
+    /**
+     * The room the device is in (this might be undefined if the device is not yet properly initialized)
+     */
     room: RoomBase | undefined;
 }

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

@@ -1,16 +1,39 @@
 /// <reference types="node" />
 import { iRoomDevice } from './index';
 import { SceneSettings } from '../../../models';
+/**
+ * This interface represents a scene which for simplification is considered as a device.
+ *
+ * For devices with {@link DeviceCapability.scene} capability.
+ */
 export interface iScene extends iRoomDevice {
+    /**
+     * The settings for the scene
+     */
+    settings: SceneSettings;
+    /**
+     * A description of the scene providing the user with information about what the scene does
+     */
     description: string;
+    /**
+     * Callback to be executed when the scene should be started
+     */
     readonly onSceneStart: () => void;
+    /**
+     * Callback to be executed when the scene should be ended
+     */
     readonly onSceneEnd: () => void;
+    /**
+     * Whether the scene is currently active
+     */
     readonly on: boolean;
+    /**
+     * The timeout for the automatic end of the scene
+     */
     readonly automaticEndTimeout: NodeJS.Timeout | null;
-    settings: SceneSettings;
     /**
      * Starts the scene for the given duration
-     * @param {number} timeout - If set, the scene will end after the given time in ms
+     * @param timeout - If set, the scene will end after the given time in ms
      */
     startScene(timeout?: number): void;
     /**

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

@@ -1,10 +1,27 @@
 import { Window } from '../groups';
 import { iRoomDevice } from './iRoomDevice';
 import { ShutterSetLevelCommand, ShutterSettings } from '../../../models';
+/**
+ * This interface represents a shutter device.
+ *
+ * For devices with {@link DeviceCapability.shutter} capability.
+ */
 export interface iShutter extends iRoomDevice {
+    /**
+     * The settings for the shutter
+     */
     settings: ShutterSettings;
+    /**
+     * The current level of the shutter (0 = closed, 100 = open)
+     */
     currentLevel: number;
+    /**
+     * The desired level of the shutter for this window (this might be different from the current level due to the desired level being set by the user)
+     */
     desiredWindowShutterLevel: number;
+    /**
+     * The window this shutter is located within
+     */
     window: Window | undefined;
     /**
      * Persists the current information of the shutter to the database
@@ -12,7 +29,7 @@ export interface iShutter extends iRoomDevice {
     persist(): void;
     /**
      * Sets the level of the shutter
-     * @param {ShutterSetLevelCommand} command - The command to execute
+     * @param command - The command to execute
      */
     setLevel(command: ShutterSetLevelCommand): void;
 }

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

@@ -1,4 +1,9 @@
 import { iRoomDevice } from './iRoomDevice';
+/**
+ * This interface represents a smoke detector device.
+ *
+ * For devices with {@link DeviceCapability.smokeSensor} capability.
+ */
 export interface iSmokeDetectorDevice extends iRoomDevice {
     /**
      * Indicates if the smoke detector is currently detecting smoke
@@ -6,7 +11,7 @@ export interface iSmokeDetectorDevice extends iRoomDevice {
     readonly smoke: boolean;
     /**
      * Stops the alarm of the smoke detector
-     * @param {boolean} quiet - If true, the alarm will be stopped without announcing alarm end.
+     * @param quiet - If true, the alarm will be stopped without announcing alarm end.
      */
     stopAlarm(quiet: boolean): void;
 }

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

@@ -1,12 +1,17 @@
 import { iRoomDevice } from './iRoomDevice';
+/**
+ * This interface represents a speaker device.
+ *
+ * For devices with {@link DeviceCapability.speaker} capability.
+ */
 export interface iSpeaker extends iRoomDevice {
     /**
      * Plays an mp3 file on the device
-     * @param {string} mp3Name - The name of the mp3 file to play
-     * @param {number} duration - The duration of the mp3 file in seconds
-     * @param {number} [volume] - The volume to play the mp3 file with
-     * @param {boolean} [onlyWhenPlaying] - If true, the mp3 file will only be played when the device is already playing something
-     * @param {boolean} [resolveAfterRevert] - If true, the promise will be resolved after the device has reverted to the previous state
+     * @param mp3Name - The name of the mp3 file to play
+     * @param duration - The duration of the mp3 file in seconds
+     * @param [volume] - The volume to play the mp3 file with
+     * @param [onlyWhenPlaying] - If true, the mp3 file will only be played when the device is already playing something
+     * @param [resolveAfterRevert] - If true, the promise will be resolved after the device has reverted to the previous state
      */
     playOnDevice(mp3Name: string, duration: number, volume?: number, onlyWhenPlaying?: boolean, resolveAfterRevert?: boolean): void;
     /**
@@ -15,7 +20,7 @@ export interface iSpeaker extends iRoomDevice {
     playTestMessage(): void;
     /**
      * Plays a file from an url on the device
-     * @param {string} url - The url to play
+     * @param url - The url to play
      */
     playUrl(url: string): void;
     /**
@@ -24,10 +29,10 @@ export interface iSpeaker extends iRoomDevice {
     stop(): void;
     /**
      * Speaks a message on the device using the text-to-speech engine
-     * @param {string} pMessage - The message to speak
-     * @param {number} [volume] - The volume to speak the message with
-     * @param {boolean} [onlyWhenPlaying] - If true, the message will only be spoken when the device is already playing something
-     * @param {boolean} [resolveAfterRevert] - If true, the promise will be resolved after the device has reverted to the previous state
+     * @param pMessage - The message to speak
+     * @param [volume] - The volume to speak the message with
+     * @param [onlyWhenPlaying] - If true, the message will only be spoken when the device is already playing something
+     * @param [resolveAfterRevert] - If true, the promise will be resolved after the device has reverted to the previous state
      */
     speakOnDevice(pMessage: string, volume?: number, onlyWhenPlaying?: boolean, resolveAfterRevert?: boolean): void;
 }

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

@@ -1,19 +1,37 @@
 /// <reference types="node" />
 import { iRoomDevice } from './iRoomDevice';
 export declare const UNDEFINED_TEMP_VALUE = -99;
+/**
+ * This interface represents a temperature sensor device.
+ *
+ * For devices with {@link DeviceCapability.temperatureSensor} capability.
+ */
 export interface iTemperatureSensor extends iRoomDevice {
+    /**
+     * The interval to persist the temperature sensor information
+     * Mainly used to enforce implementation
+     */
     readonly persistTemperatureSensorInterval: NodeJS.Timeout;
+    /**
+     * The current room temperature as a number in Celsius
+     */
     roomTemperature: number;
-    iTemperature: number;
+    /**
+     * The devices measured Temperature as a number in Celsius
+     */
+    readonly iTemperature: number;
+    /**
+     * Formatted Temperature as a string in Celsius
+     */
     sTemperature: string;
     /**
      * Adds a callback to be called when the temperature changes
-     * @param {(pValue: number) => void} pCallback - The callback to be called
+     * @param pCallback - The callback to be called
      */
     addTempChangeCallback(pCallback: (pValue: number) => void): void;
     /**
      * Inform the temperature sensor that the temperature in the room has changed
-     * @param {number} newTemperatur - The new temperature in the room in Celsius
+     * @param newTemperatur - The new temperature in the room in Celsius
      */
     onTemperaturChange(newTemperatur: number): void;
     /**

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

@@ -1,6 +1,12 @@
 import { BlockAutomaticHandler } from '../../services/blockAutomaticHandler';
 import { iBaseDevice } from './iBaseDevice';
 import { RestoreTargetAutomaticValueCommand } from '../../../models';
+/**
+ * This interface represents a device which automatic action can be temporarily disabled.
+ * E.g. Forcing a lamp to stay on, even if the automatic would turn it off.
+ *
+ * For devices with {@link DeviceCapability.blockAutomatic} capability.
+ */
 export interface iTemporaryDisableAutomatic extends iBaseDevice {
     /**
      * The block automation handler containing the current block state/time, etc.
@@ -8,7 +14,7 @@ export interface iTemporaryDisableAutomatic extends iBaseDevice {
     readonly blockAutomationHandler: BlockAutomaticHandler;
     /**
      * Restores the automatic value/state of the device
-     * @param {RestoreTargetAutomaticValueCommand} command - The command to restore the automatic value/state
+     * @param command - The command to restore the automatic value/state
      */
     restoreTargetAutomaticValue(command: RestoreTargetAutomaticValueCommand): void;
 }

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

@@ -1,5 +1,13 @@
 import { iRoomDevice } from './iRoomDevice';
+/**
+ * This interface represents a TV device.
+ *
+ * For devices with {@link DeviceCapability.tv} capability.
+ */
 export interface iTvDevice extends iRoomDevice {
+    /**
+     * Whether the TV is currently on
+     */
     readonly on: boolean;
     /**
      * Turns the TV on

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

@@ -1,8 +1,28 @@
 import { iRoomDevice } from './iRoomDevice';
+/**
+ * This interface represents a vibration sensor device.
+ *
+ * For devices with {@link DeviceCapability.vibrationSensor} capability.
+ */
 export interface iVibrationSensor extends iRoomDevice {
-    vibrationBlockedByGriff: boolean;
-    vibrationBlockedByGriffTimeStamp: number;
+    /**
+     * Whether the vibration sensor is currently blocked by a handle.
+     */
+    vibrationBlockedByHandle: boolean;
+    /**
+     * The timestamp when the vibration sensor was blocked by a handle.
+     */
+    readonly vibrationBlockedByHandleTimeStamp: number;
+    /**
+     * Whether the vibration sensor is currently blocked by a motion event.
+     */
     vibrationBlockedByMotion: boolean;
-    vibrationBlockedByMotionTimeStamp: number;
-    vibration: boolean;
+    /**
+     * The timestamp when the vibration sensor was last blocked by a motion event.
+     */
+    readonly vibrationBlockedByMotionTimeStamp: number;
+    /**
+     * Whether the vibration sensor is currently detecting a vibration.
+     */
+    readonly vibration: boolean;
 }

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

@@ -22,3 +22,4 @@ export * from './iTemperatureSensor';
 export * from './iTemporaryDisableAutomatic';
 export * from './iTvDevice';
 export * from './iVibrationSensor';
+export { iMagnetSensor } from './iMagnetSensor';