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

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,21 @@
 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 {
+    /**
+     * The last time the battery was persisted (in milliseconds since 1970)
+     */
     readonly lastBatteryPersist: number;
     /**
      * The battery status of the device in percentage
-     * @type {number}
      */
     readonly battery: number;
+    /**
+     * Method to persist the battery status of the device to the persistence layer
+     */
     persistBatteryDevice(): void;
 }

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;
 }

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

@@ -1,14 +1,57 @@
 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;
-    onGriffUpdate(open: boolean): void;
+    /**
+     * 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
+     */
+    blockForDevice(device: iBaseDevice, block: boolean): void;
+    /**
+     * Inform this camera of state updates within iOBroker
+     * TODO: Make camera independent of iOBroker
+     * @param idSplit - The id split of the state
+     * @param state - The state that has been updated
+     */
     update(idSplit: string[], state: ioBroker.State): void;
 }

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

@@ -1,12 +1,27 @@
 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 command - The command to execute on the light device.
+     */
     toggleLight(command: LampToggleLightCommand): void;
     /**
-     * This function sets the light to a specific value
-     * Accessible in API
+     * This function sets the light to a specific value.
+     * @param command - The command to execute on the light device.
      */
     setLight(command: DimmerSetLightCommand): void;
 }

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

@@ -1,12 +1,42 @@
 import { iExcessEnergyConsumer } from './iExcessEnergyConsumer';
 import { iBaseDevice } from './iBaseDevice';
-export interface iEnergyManager extends 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
+     * @param device - The device that can consume excess energy
+     */
     addExcessConsumer(device: iExcessEnergyConsumer): void;
+    /**
+     * Recalculates power-sharing between devices.
+     */
     recalculatePowerSharing(): void;
-    cleanup(): void;
+    /**
+     * Generates a report stating used energy and devices that consumed it
+     * @returns The report
+     */
     getReport(): string;
 }

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

@@ -1,12 +1,40 @@
-import { ExcessEnergyConsumerSettings, LogLevel } from '../../../models';
+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 Whether this device is available to be turned on to consume excess energy
+     */
     isAvailableForExcessEnergy(): boolean;
-    log(level: LogLevel, message: string): void;
+    /**
+     * Turn on this device to consume excess energy
+     */
     turnOnForExcessEnergy(): void;
+    /**
+     * Turn off this device as we don't have enough excess energy to power it
+     */
     turnOffDueToMissingEnergy(): void;
+    /**
+     * Check if 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,9 +1,30 @@
 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
+     */
     open(): void;
+    /**
+     * Close the garage door
+     */
     close(): void;
+    /**
+     * Trigger the garage door.
+     * This mostly results in driving the door to the opposite state, but if fired rapidly, it might stop the door in the middle.
+     */
     trigger(): void;
 }

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

@@ -1,9 +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 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 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 pCallback - The callback to fire
+     */
     addClosedCallback(pCallback: (pValue: boolean) => void): void;
 }

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

@@ -1,17 +1,53 @@
 /// <reference types="node" />
 import { HeaterSettings } from '../../../models';
 import { iRoomDevice } from './iRoomDevice';
-export interface iHeater extends 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;
-    stopAutomaticCheck(): void;
+    /**
+     * Perform a check to calculate the new desired heater state
+     */
     checkAutomaticChange(): void;
+    /**
+     * Informs the heater that the temperature of the room has changed
+     * @param newTemperatur - The new temperature in degree Celsius.
+     */
     onTemperaturChange(newTemperatur: number): void;
+    /**
+     * Persists the current heater information to the database
+     */
     persistHeater(): void;
 }

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

@@ -1,9 +1,29 @@
 /// <reference types="node" />
 import { iRoomDevice } from './iRoomDevice';
+import { HumiditySensorChangeAction } from '../../../models';
 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;
-    addHumidityCallback(pCallback: (pValue: number) => void): void;
+    /**
+     * Add a callback that is called when the humidity changes
+     * @param pCallback - The callback to fire
+     */
+    addHumidityCallback(pCallback: (action: HumiditySensorChangeAction) => void): void;
+    /**
+     * Persists the current humidity information to the database
+     */
     persistHumiditySensor(): 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,10 +1,15 @@
 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
+     * Changes the state of the lamp based on the time
+     * @param command - The command to execute
      */
-    readonly lightOn: boolean;
     setTimeBased(command: LampSetTimeBasedCommand): void;
     /**
      * Toggles the state of the lamp

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

@@ -1,8 +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 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