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

package/lib/models/rooms/RoomSettings/roomSettings.js

@@ -7,23 +7,78 @@ class RoomSettings extends objectSettings_1.ObjectSettings {
     constructor() {
         var _a;
         super(...arguments);
+        /**
+         * Whether this room should always have ambient light on after sunset (regardless of motion e.g. Gardenlights).
+         */
         this.ambientLightAfterSunset = server_1.SettingsService.settings.roomDefault.ambientLightAfterSunset;
+        /**
+         * Should lights be turned off after sunrise
+         */
         this.lichtSonnenAufgangAus = server_1.SettingsService.settings.roomDefault.lichtSonnenAufgangAus;
+        /**
+         * The default radio URL to use with speaker
+         */
         this.radioUrl = (_a = server_1.SettingsService.settings.roomDefault.radioUrl) !== null && _a !== void 0 ? _a : '';
+        /**
+         * Use shutter to reduce warming of rooms on hot days (detected by weather service)
+         */
         this.rolloHeatReduction = server_1.SettingsService.settings.roomDefault.rolloHeatReduction;
+        /**
+         * Should lights be turned on at Movement
+         */
         this.lampenBeiBewegung = server_1.SettingsService.settings.roomDefault.lampenBeiBewegung;
+        /**
+         * Should Light be turned on at day if there are no Windows configured for this room
+         */
         this.lightIfNoWindows = server_1.SettingsService.settings.roomDefault.lightIfNoWindows;
+        /**
+         * Time in seconds after which detected movement is reseted
+         */
         this.movementResetTimer = server_1.SettingsService.settings.roomDefault.movementResetTimer;
+        /**
+         * Indicates rooms, which are time independent always dark (like basement).
+         * This results in lamps beeing turned on at motion regardless of windows and time.
+         */
         this.roomIsAlwaysDark = server_1.SettingsService.settings.roomDefault.roomIsAlwaysDark;
+        /**
+         * +/- Offset for still turning on lamps at movement after/before sunrise
+         */
         this.sonnenAufgangLampenDelay = server_1.SettingsService.settings.roomDefault.sonnenAufgangLampenDelay;
+        /**
+         * +/- Default Offset for shutters opening on sunrise in minutes
+         */
         this.sonnenAufgangRolloDelay = server_1.SettingsService.settings.roomDefault.sonnenAufgangRolloDelay;
+        /**
+         * Should shutters be opened on sunrise
+         */
         this.sonnenAufgangRollos = server_1.SettingsService.settings.roomDefault.sonnenAufgangRollos;
+        /**
+         * !Needs Weather Data! Additional Offset in Minutes per % Cloudiness
+         */
         this.sonnenUntergangRolloAdditionalOffsetPerCloudiness = server_1.SettingsService.settings.roomDefault.sonnenUntergangRolloAdditionalOffsetPerCloudiness;
+        /**
+         * Latest time of shutter closing (regardless of geospecific sunset)
+         */
         this.sonnenUntergangRolloMaxTime = server_1.SettingsService.settings.roomDefault.sonnenUntergangRolloMaxTime;
+        /**
+         * Earliest time of shutter opening (regardless of geospecific sunset)
+         */
         this.sonnenAufgangRolloMinTime = server_1.SettingsService.settings.roomDefault.sonnenAufgangRolloMinTime;
+        /**
+         * +/- Offset for shutter closing on sunset in minutes
+         */
         this.sonnenUntergangRolloDelay = server_1.SettingsService.settings.roomDefault.sonnenUntergangRolloDelay;
+        /**
+         * +/- Offset for turning on lamps at movement after/before sunset
+         */
         this.sonnenUntergangLampenDelay = server_1.SettingsService.settings.roomDefault.sonnenUntergangLampenDelay;
+        /**
+         * Should shutters be closed on sunset (based on geolocation)
+         */
         this.sonnenUntergangRollos = server_1.SettingsService.settings.roomDefault.sonnenUntergangRollos;
+        /**
+         * Whether normal ceiling lights should also be turned on by movement, even if there are LEDs and outlets
+         */
         this.includeLampsInNormalMovementLightning = server_1.SettingsService.settings.roomDefault.includeLampsInNormalMovementLightning;
     }
     fromPartialObject(_obj) {

package/lib/models/rooms/iRoomBase.d.ts

@@ -1,11 +1,33 @@
 import { TimeCallback } from '../timeCallback';
 import { RoomSetLightTimeBasedCommand } from '../command';
+/**
+ * This interface represents a room with it's base functionality.
+ * Whilst accessing the custom rooms can be beneficial for direct device interaction, this provides interactions to e.g. device groups.
+ */
 export interface iRoomBase {
+    /**
+     * The time-callback for controlling shutters at sunrise
+     */
     sunriseShutterCallback: TimeCallback | undefined;
+    /**
+     * The time-callback for controlling shutters at sunset
+     */
     sunsetShutterCallback: TimeCallback | undefined;
+    /**
+     * The time-callback for controlling light at sunrise
+     */
     sonnenAufgangLichtCallback: TimeCallback | undefined;
+    /**
+     * The time-callback for controlling light at sunset
+     */
     sonnenUntergangLichtCallback: TimeCallback | undefined;
+    /**
+     * Whether the next sunset shutter-up should be skipped (afterwards this resets to false)
+     */
     skipNextRolloUp: boolean;
+    /**
+     * The name of the room
+     */
     roomName: string;
     /**
      * This function initializes the roomBase object of this room
@@ -21,12 +43,12 @@ export interface iRoomBase {
     recalcTimeCallbacks(): void;
     /**
      * This function sets the light in the room based on the command
-     * @param {RoomSetLightTimeBasedCommand} c - The command to execute
+     * @param c - The command to execute
      */
     setLightTimeBased(c: RoomSetLightTimeBasedCommand): void;
     /**
      * This function checks if it is now light time respecting the room settings, the current time and the daylight hours for this location.
-     * @returns {boolean}
+     * @returns
      */
     isNowLightTime(): boolean;
 }

package/lib/models/rooms/iRoomImportEnforcer.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Every Hoffmation Instance (e.g. using Hoffmation-Express) needs to enforce the Import of all house specific rooms.
+ * For Hoffmation-Base to be able to interact with this user-specific import enforcer this interface needs to be implemented.
+ */
 export interface iRoomImportEnforcer {
     /**
      * This function is called before initializing single devices,

package/lib/models/timeCallback.d.ts

@@ -21,7 +21,14 @@ export declare class TimeCallback {
     cloudOffset?: number | undefined;
     private _calculationSunrise?;
     get calculationSunrise(): Date;
+    /**
+     * The date this Callback was last fired
+     */
     lastDone: Date;
+    /**
+     * The calculated date when this callback should be fired next
+     * @warning This might have not yet been recalculated
+     */
     nextToDo?: Date;
     private _calculationSunset?;
     get calculationSunset(): Date;

package/lib/models/timeCallback.js

@@ -36,6 +36,9 @@ class TimeCallback {
         this.minutes = minutes;
         this.sunTimeOffset = sunTimeOffset;
         this.cloudOffset = cloudOffset;
+        /**
+         * The date this Callback was last fired
+         */
         this.lastDone = new Date(0);
     }
     recalcNextToDo(now) {
@@ -94,7 +97,7 @@ class TimeCallback {
                 break;
         }
         if (nextCalculatedTime < now && this.nextToDo && this.nextToDo > now) {
-            server_1.ServerLogService.writeLog(logLevel_1.LogLevel.Info, `Time Callback recalc results in the past, while previous target is still in future --> fire immediately.`);
+            server_1.ServerLogService.writeLog(logLevel_1.LogLevel.Info, 'Time Callback recalc results in the past, while previous target is still in future --> fire immediately.');
             this.perform(now);
             return;
         }

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

@@ -1,6 +1,21 @@
+/**
+ * The configuration needed to connect to an Asus Router
+ */
 export interface iAsusConfig {
+    /**
+     * The hostname of the Router (or it's IP-Address)
+     */
     address: string;
+    /**
+     * Whether to Ignore SSL warnings/error
+     */
     ignoreSSL?: boolean;
+    /**
+     * The password needed for authentication
+     */
     password: string;
+    /**
+     * The username to connect with.
+     */
     username: string;
 }

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

@@ -0,0 +1,23 @@
+import { CollisionSolving } from '../../models';
+/**
+ * These settings control the desired behaviour of {@link BlockAutomaticHandler}.
+ * Unless decided within a command this will determine the default behaviour.
+ *
+ * So this will e.g. be used when a Homebridge-Hoffmation instance
+ * e.g. issues a command to turn a light on as with this command no block
+ * duration or behaviour is specified.
+ */
+export interface iBlockAutomaticHandlerDefaults {
+    /**
+     * Whether at Block-Lift the desired automatic state should be restored.
+     */
+    revertToAutomaticAtBlockLift?: boolean;
+    /**
+     * The default duration in milliseconds for a block to be on any force action.
+     */
+    blockAutomaticDurationMS?: number;
+    /**
+     * The default collision solving strategy to use.
+     */
+    defaultCollisionSolving?: CollisionSolving;
+}

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

@@ -1,5 +1,19 @@
+/**
+ * The configuration for the Blue-Iris Instance (if present).
+ * Blue-Iris is a software to manage IP-Cameras
+ * Settings for {@link BlueIrisCoordinator} to connect to a Blue-Iris instance
+ */
 export interface iBlueIrisSettings {
+    /**
+     * The hostname of the Blue-Iris Instance
+     */
     serverAddress: string;
+    /**
+     * If needed, the username to authenticate with
+     */
     username?: string;
+    /**
+     * If needed, the password to authenticate with.
+     */
     password?: string;
 }

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

@@ -1,4 +1,13 @@
+/**
+ * Settings for tracking a bluetooth device using {@link iBluetoothDetector}
+ */
 export interface iBluetoothTrackingSettings {
+    /**
+     * The name of the device to track
+     */
     customName: string;
+    /**
+     * Whether to track the device
+     */
     activeTracking: boolean;
 }

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

@@ -15,38 +15,125 @@ import { iMuellSettings } from './iMuellSettings';
 import { iDaikinSettings } from './iDaikinSettings';
 import { iHeaterSettings } from './iHeaterSettings';
 import { iBlueIrisSettings } from './iBlueIrisSettings';
-import { iRestSettings } from './iRestSettings';
 import { iEspresenseSettings } from './iEspresenseSettings';
 import { iTibberSettings } from './iTibberSettings';
 import { iVictronSettings } from './iVictronSettings';
 import { iDachsSettings } from './iDachsSettings';
 import { iEnergyManagerSettings } from './iEnergyManagerSettings';
 import { iUnifiSettings } from './iUnifiSettings';
+import { iBlockAutomaticHandlerDefaults } from './iBlockAutomaticHandlerDefaults';
+import { iRestSettings } from './iRestSettings';
+/**
+ * The main configuration for Hoffmation normally stored in the `main-config.json` file.
+ */
 export interface iConfig {
+    /**
+     * @see iAsusConfig
+     */
     asusConfig?: iAsusConfig;
+    /**
+     * @see i
+     */
+    blockAutomaticHandlerDefaults?: iBlockAutomaticHandlerDefaults;
+    /**
+     * @see iBlueIrisSettings
+     */
     blueIris?: iBlueIrisSettings;
-    daikin?: iDaikinSettings;
+    /**
+     * @see iDachsSettings
+     */
     dachs?: iDachsSettings;
+    /**
+     * @see iDaikinSettings
+     */
+    daikin?: iDaikinSettings;
+    /**
+     * @see iEnergyManagerSettings
+     */
     energyManager?: iEnergyManagerSettings;
+    /**
+     * @see iEspresenseSettings
+     */
     espresense?: iEspresenseSettings;
-    ioBrokerUrl: string;
-    ioBroker?: iIobrokerSettigns;
+    /**
+     * Whether any Govee devices are present in the house and should be included in Hoffmation.
+     */
     goveeDevicesPresent?: boolean;
+    /**
+     * @see iHeaterSettings
+     */
     heaterSettings?: iHeaterSettings;
+    /**
+     * The URL to the ioBroker instance.
+     * @deprecated Please use the ioBroker property instead
+     */
+    ioBrokerUrl?: string;
+    /**
+     * @see iIobrokerSettigns
+     */
+    ioBroker?: iIobrokerSettigns;
+    /**
+     * @see iLogSettings
+     */
     logSettings?: iLogSettings;
+    /**
+     * @see iMp3Settings
+     */
     mp3Server?: iMp3Settings;
+    /**
+     * @see iMuellSettings
+     */
     muell?: iMuellSettings;
+    /**
+     * @see iNewsSettings
+     */
     news?: iNewsSettings;
+    /**
+     * @see iPersistenceSettings
+     */
     persistence?: iPersistenceSettings;
+    /**
+     * @see iPollySettings
+     */
     polly?: iPollySettings;
+    /**
+     * @see iRestSettings
+     */
     restServer?: iRestSettings;
+    /**
+     * @see iRoomDefaultSettings
+     */
     roomDefault: iRoomDefaultSettings;
+    /**
+     * @see iSonosSettings
+     */
     sonos?: iSonosSettings;
+    /**
+     * @see iTelegramSettings
+     */
     telegram?: iTelegramSettings;
+    /**
+     * @see iTibberSettings
+     */
     tibber?: iTibberSettings;
+    /**
+     * @see iTimeSettings
+     */
     timeSettings: iTimeSettings;
+    /**
+     * @see iTranslationSettings
+     */
     translationSettings: iTranslationSettings;
+    /**
+     * @see iUnifiSettings
+     */
     unifiSettings?: iUnifiSettings;
-    weather?: iWeatherSettings;
+    /**
+     * @see iVictronSettings
+     */
     victron?: iVictronSettings;
+    /**
+     * @see iWeatherSettings
+     */
+    weather?: iWeatherSettings;
 }

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

@@ -1,7 +1,23 @@
 import { DachsClientOptions, InfluxDbConnectionOptions } from '../devices/dachs';
+/**
+ * The configuration for the Dachs CHP (if present)
+ * CHP = Combined Heat and Power (in german Block-Heiz-Kraftwerk)
+ */
 export interface iDachsSettings {
+    /**
+     * The interval in milli-seconds in which the Dachs client should refresh its data.
+     */
     refreshInterval: number;
+    /**
+     * The connection options for the Dachs client.
+     */
     connectionOptions: DachsClientOptions;
+    /**
+     * If provided, the Dachs client will write data to this InfluxDB.
+     */
     influxDb?: InfluxDbConnectionOptions;
+    /**
+     * The room name the Dachs device is located in.
+     */
     roomName: string;
 }

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

@@ -1,6 +1,23 @@
+/**
+ * The configuration for Daikin Air-Conditioning devices (if present)
+ */
 export interface iDaikinSettings {
+    /**
+     * Whether the Daikin service should be active.
+     */
     active: boolean;
+    /**
+     * Enables further Logging for Daikin-device in case of akward issues.
+     * TODO: Move to Logservice Debugging Type
+     */
     activateTracingLogger?: boolean;
+    /**
+     * Whether all requests to the Daikin devices should be made using GET requests.
+     */
     useGetToPost?: boolean;
+    /**
+     * Whether Room Default Callbacks should be added to start ac on Bottom Right short and stop on long button press.
+     * @warning This can collide with Sonos-Control (@see {@link iSonosSettings.buttonBotRightForRadio})
+     */
     buttonBotRightForAc?: boolean;
 }

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

@@ -1,5 +1,18 @@
+/**
+ * The configuration for an Energy-Manager (if present).
+ * This can be used to make proper use of excess energy (e.g. from solar panels)
+ */
 export interface iEnergyManagerSettings {
+    /**
+     * Disable ioBroker JS-EnergyManager
+     */
     disableJsEnergyManager?: boolean;
+    /**
+     * The price per kWh injecting into the grid
+     */
     injectWattagePrice?: number;
+    /**
+     * The price per kWh from the grid
+     */
     wattagePrice?: number;
 }

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

@@ -1,6 +1,16 @@
 import { iBluetoothTrackingSettings } from './iBluetoothTrackingSettings';
+/**
+ * The configuration for Espresense devices (if present)
+ * This can be used to monitor/tack/locate the position of certain bluetooth devices within the house.
+ */
 export interface iEspresenseSettings {
+    /**
+     * The instance of the mqtt adapter providing the data for espresense devices within ioBroker.
+     */
     mqttInstance: number;
+    /**
+     * An map providing settings for some devices to be tracked.
+     */
     deviceMap: {
         [folderId: string]: iBluetoothTrackingSettings;
     };

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

@@ -1,9 +1,17 @@
 import { HeatingMode } from './heatingMode';
+/**
+ * Additional settings for the heating system (if present)
+ */
 export interface iHeaterSettings {
     /**
      * Whether heating with ac is allowed
      * This normally depends on the cost difference between ac heating and conventional heating
      */
     allowAcHeating?: boolean;
+    /**
+     * The desired Heating mode of the house.
+     * As of today you have to manually switch between summer and winter.
+     * TODO: Add heating Mode change to persisted settings and allow controlling it via the app
+     */
     mode?: HeatingMode;
 }

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

@@ -1,3 +1,7 @@
+/**
+ * The settings for the ioBroker instance
+ * Currently Hoffmation needs an ioBroker instance, but we might make it independent of it in the future.
+ */
 export interface iIobrokerSettigns {
     /**
      * Whether states should be initialized by processing each key on its own.
@@ -8,4 +12,8 @@ export interface iIobrokerSettigns {
      * Whether the new/advanced zigbee2mqtt adapter is used
      */
     useZigbee2mqtt?: boolean;
+    /**
+     * The URL to the ioBroker instance (or the IP-Address)
+     */
+    ioBrokerUrl: string;
 }

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

@@ -1,12 +1,47 @@
+import { LogLevel } from '../../models';
+/**
+ * The settings for the logging system.
+ * There are different log-levels which can be set and debug-logging can be granular enabled
+ */
 export interface iLogSettings {
-    logLevel: number;
+    /**
+     * The threshold level for logging (-1 = off)
+     */
+    logLevel: LogLevel | -1;
+    /**
+     * Whether to inlude the timestamp in the log messages
+     */
     useTimestamp: boolean;
+    /**
+     * Whether to log debug messages for movement state changes
+     */
     debugNewMovementState?: boolean;
+    /**
+     * Whether to log debug messages for shutter position changes
+     */
     debugShutterPositionChange?: boolean;
+    /**
+     * Whether to log debug messages for actuator change commands
+     */
     debugActuatorChange?: boolean;
+    /**
+     * Whether to log debug messages for shutter commands being blocked as it is already in the desired position
+     */
     debugUchangedShutterPosition?: boolean;
+    /**
+     * Whether to log debug messages for actuator commands being blocked as it is already in the desired state
+     */
     debugUnchangedActuator?: boolean;
+    /**
+     * Whether to log debug messages for daikin control commands
+     */
     debugDaikinSuccessfullControlInfo?: boolean;
+    /**
+     * Whether to log debug messages for euro heater valve position changes
+     */
     debugEuroHeaterValve?: boolean;
+    /**
+     * Whether to log debug messages for trilateration calculations
+     */
     debugTrilateration?: boolean;
 }

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

@@ -1,4 +1,14 @@
+/**
+ * The settings for the mp3-server (if needed).
+ * A mp3-server is mainly needed for playing text-to-speech messages on speakers (e.g. Sonos)
+ */
 export interface iMp3Settings {
+    /**
+     * local path for the mp3 files to store/load
+     */
     path: string;
+    /**
+     * external reachable adress to access those mp3 files
+     */
     serverAddress: string;
 }

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

@@ -1,3 +1,10 @@
+/**
+ * The settings for the Müll-Service (if needed).
+ * Müll-Service is a service to remind you of the different waste collections.
+ */
 export interface iMuellSettings {
+    /**
+     * URL to the calendar to fetch the events from
+     */
     calendarURL: string;
 }

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

@@ -1,5 +1,18 @@
+/**
+ * The settings for the news-service (if needed).
+ * The news-service is used to download news-podcasts and play them on speakers (e.g. Sonos)
+ */
 export interface iNewsSettings {
+    /**
+     * rss feed url that contains the news information and audio file
+     */
     rssUrl?: string;
+    /**
+     * request interval in minutes
+     */
     requestInterval?: number;
+    /**
+     * maximum age in minutes of files cached for playback before they get deleted
+     */
     keepMaxAge?: number;
 }

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

@@ -1,4 +1,14 @@
 import { PoolConfig } from 'pg';
+/**
+ * The settings for the persistence system.
+ * The persistence system is used mainly for following things:
+ * 1. To persists settings/configuration
+ * 2. To persists the state of devices (e.g. to remember the last state of a light)
+ * 3. To persists device data for Statistics
+ */
 export interface iPersistenceSettings {
+    /**
+     * PostgreSql configuration
+     */
     postgreSql?: PoolConfig;
 }

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

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

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

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