meross-iot 0.1.0

package/lib/model/states/presence-sensor-state.js

@@ -0,0 +1,239 @@
+'use strict';
+
+const { PresenceState } = require('../enums');
+
+/**
+ * Represents the presence sensor state of a device channel.
+ *
+ * Encapsulates state information for presence sensor devices, including presence
+ * detection status, distance, and light/illuminance readings. State instances are
+ * managed by device controllers and updated automatically when device responses or
+ * push notifications are received.
+ *
+ * @class
+ * @example
+ * const presenceState = device.getCachedPresenceSensorState(0);
+ * if (presenceState) {
+ *     console.log('Is present:', presenceState.isPresent);
+ *     console.log('Distance:', presenceState.distanceMeters, 'm');
+ *     console.log('Light:', presenceState.lightLux, 'lux');
+ * }
+ */
+class PresenceSensorState {
+    /**
+     * Creates a new PresenceSensorState instance.
+     *
+     * @param {Object} [state=null] - Initial state object
+     * @param {Object} [state.presence] - Presence detection data
+     * @param {number} [state.presence.value] - Presence value (from PresenceState enum)
+     * @param {number} [state.presence.distance] - Distance in millimeters
+     * @param {number} [state.presence.timestamp] - Timestamp in seconds
+     * @param {number} [state.presence.times] - Times value
+     * @param {Object} [state.light] - Light/illuminance data
+     * @param {number} [state.light.value] - Light value in lux
+     * @param {number} [state.light.timestamp] - Timestamp in seconds
+     * @param {number} [state.channel] - Channel number
+     */
+    constructor(state = null) {
+        this._state = state || {};
+    }
+
+    /**
+     * Updates the state with new data.
+     *
+     * Merges new state data into the existing state. Presence and light objects are
+     * deep-merged using spread operators to preserve existing nested properties that
+     * aren't included in the update. Called automatically by device controllers when
+     * state updates are received from device responses or push notifications.
+     *
+     * @param {Object} state - New state data to merge
+     */
+    update(state) {
+        if (state) {
+            if (state.presence) {
+                this._state.presence = { ...(this._state.presence || {}), ...state.presence };
+            }
+            if (state.light) {
+                this._state.light = { ...(this._state.light || {}), ...state.light };
+            }
+            const { presence: _presence, light: _light, ...otherProps } = state;
+            Object.assign(this._state, otherProps);
+        }
+    }
+
+    /**
+     * Gets whether presence is currently detected.
+     *
+     * Converts the device's presence state enum value to a boolean for easier
+     * conditional logic in application code.
+     *
+     * @returns {boolean|undefined} True if presence detected, false if absence detected, undefined if no data
+     */
+    get isPresent() {
+        const { presence } = this._state;
+        if (!presence || presence.value === undefined || presence.value === null) {
+            return undefined;
+        }
+        return presence.value === PresenceState.PRESENCE;
+    }
+
+    /**
+     * Gets the presence state value.
+     *
+     * Returns the raw presence state value from the PresenceState enum. Use this
+     * when you need the exact enum value rather than a boolean conversion.
+     *
+     * @returns {number|undefined} PresenceState.PRESENCE (2) or PresenceState.ABSENCE (1), undefined if no data
+     */
+    get presenceValue() {
+        const { presence } = this._state;
+        if (!presence || presence.value === undefined || presence.value === null) {
+            return undefined;
+        }
+        return presence.value;
+    }
+
+    /**
+     * Gets the presence state as a string.
+     *
+     * Converts the boolean presence state to a human-readable string. Useful for
+     * logging and display purposes.
+     *
+     * @returns {string|undefined} 'presence' or 'absence', undefined if no data
+     */
+    get presenceState() {
+        const { isPresent } = this;
+        if (isPresent === undefined) {return undefined;}
+        return isPresent ? 'presence' : 'absence';
+    }
+
+    /**
+     * Gets the detected distance in meters.
+     *
+     * The device reports distance in millimeters. This getter converts to meters
+     * for more convenient use in applications that work with metric units.
+     *
+     * @returns {number|undefined} Distance in meters, undefined if no data
+     */
+    get distanceMeters() {
+        const { presence } = this._state;
+        if (!presence || presence.distance === undefined || presence.distance === null) {
+            return undefined;
+        }
+        return presence.distance / 1000;
+    }
+
+    /**
+     * Gets the detected distance in millimeters.
+     *
+     * Returns the raw distance value as reported by the device. Use this when
+     * you need the exact format used in device communication protocols.
+     *
+     * @returns {number|undefined} Distance in millimeters, undefined if no data
+     */
+    get distanceRaw() {
+        const { presence } = this._state;
+        if (!presence || presence.distance === undefined || presence.distance === null) {
+            return undefined;
+        }
+        return presence.distance;
+    }
+
+    /**
+     * Gets the timestamp when presence was detected.
+     *
+     * The device provides timestamps as Unix seconds. This getter converts to a
+     * JavaScript Date object for easier date manipulation and formatting.
+     *
+     * @returns {Date|undefined} Date object, undefined if no data
+     */
+    get presenceTimestamp() {
+        const { presence } = this._state;
+        if (!presence || presence.timestamp === undefined || presence.timestamp === null) {
+            return undefined;
+        }
+        return new Date(presence.timestamp * 1000);
+    }
+
+    /**
+     * Gets the times value from presence data.
+     *
+     * @returns {number|undefined} Times value, undefined if no data
+     */
+    get presenceTimes() {
+        const { presence } = this._state;
+        if (!presence || presence.times === undefined || presence.times === null) {
+            return undefined;
+        }
+        return presence.times;
+    }
+
+    /**
+     * Gets the light/illuminance value in lux.
+     *
+     * @returns {number|undefined} Light value in lux, undefined if no data
+     */
+    get lightLux() {
+        const { light } = this._state;
+        if (!light || light.value === undefined || light.value === null) {
+            return undefined;
+        }
+        return light.value;
+    }
+
+    /**
+     * Gets the timestamp when light was measured.
+     *
+     * The device provides timestamps as Unix seconds. This getter converts to a
+     * JavaScript Date object for easier date manipulation and formatting.
+     *
+     * @returns {Date|undefined} Date object, undefined if no data
+     */
+    get lightTimestamp() {
+        const { light } = this._state;
+        if (!light || light.timestamp === undefined || light.timestamp === null) {
+            return undefined;
+        }
+        return new Date(light.timestamp * 1000);
+    }
+
+    /**
+     * Gets the channel number.
+     *
+     * @returns {number|undefined} Channel number or undefined if not available
+     */
+    get channel() {
+        const { channel } = this._state;
+        if (channel === undefined || channel === null) {return undefined;}
+        return channel;
+    }
+
+    /**
+     * Gets the raw presence data object.
+     *
+     * Returns the complete presence data object as received from the device. Use
+     * this when you need access to all presence properties, including those not
+     * exposed by individual getters.
+     *
+     * @returns {Object|undefined} Raw presence data object, undefined if no data
+     */
+    get rawPresence() {
+        return this._state.presence;
+    }
+
+    /**
+     * Gets the raw light data object.
+     *
+     * Returns the complete light data object as received from the device. Use
+     * this when you need access to all light properties, including those not
+     * exposed by individual getters.
+     *
+     * @returns {Object|undefined} Raw light data object, undefined if no data
+     */
+    get rawLight() {
+        return this._state.light;
+    }
+}
+
+module.exports = PresenceSensorState;
+

package/lib/model/states/roller-shutter-state.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * Represents the state of a roller shutter device channel.
+ *
+ * Encapsulates state information for roller shutter devices, including position
+ * and movement status. State instances are managed by device controllers and
+ * updated automatically when device responses or push notifications are received.
+ *
+ * @class
+ * @example
+ * const rollerShutterState = device.getCachedRollerShutterState(0);
+ * if (rollerShutterState) {
+ *     console.log('Position:', rollerShutterState.position);
+ *     console.log('Status:', rollerShutterState.state);
+ * }
+ */
+class RollerShutterState {
+    /**
+     * Creates a new RollerShutterState instance.
+     *
+     * @param {Object} [state=null] - Initial state object
+     * @param {number} [state.state] - Movement status (from RollerShutterStatus enum: IDLE=0, OPENING=1, CLOSING=2, UNKNOWN=-1)
+     * @param {number} [state.position] - Position value (0-100, where 0=closed, 100=open)
+     * @param {number} [state.channel] - Channel number
+     */
+    constructor(state = null) {
+        this._state = state || {};
+    }
+
+    /**
+     * Updates the state with new data.
+     *
+     * Merges new state data into the existing state using Object.assign to preserve
+     * properties not included in the update. Called automatically by device controllers
+     * when state updates are received from device responses or push notifications.
+     *
+     * @param {Object} state - New state data to merge
+     */
+    update(state) {
+        if (state) {
+            Object.assign(this._state, state);
+        }
+    }
+
+    /**
+     * Gets the movement status.
+     *
+     * @returns {number|undefined} Status value (0=idle, 1=opening, 2=closing, -1=unknown) or undefined if not available
+     * @see {@link module:lib/enums.RollerShutterStatus} for status constants
+     */
+    get state() {
+        const { state } = this._state;
+        if (state === undefined || state === null) {return undefined;}
+        return state;
+    }
+
+    /**
+     * Gets the current position.
+     *
+     * @returns {number|undefined} Position value (0-100, where 0=fully closed, 100=fully open) or undefined if not available
+     */
+    get position() {
+        const { position } = this._state;
+        if (position === undefined || position === null) {return undefined;}
+        return position;
+    }
+
+    /**
+     * Gets the channel number.
+     *
+     * @returns {number|undefined} Channel number or undefined if not available
+     */
+    get channel() {
+        const { channel } = this._state;
+        if (channel === undefined || channel === null) {return undefined;}
+        return channel;
+    }
+}
+
+module.exports = RollerShutterState;
+

package/lib/model/states/spray-state.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * Represents the spray state of a spray/humidifier device channel.
+ *
+ * Encapsulates state information for spray/humidifier devices. State instances are
+ * managed by device controllers and updated automatically when device responses or
+ * push notifications are received.
+ *
+ * @class
+ * @example
+ * const sprayState = device.getCachedSprayState(0);
+ * if (sprayState) {
+ *     console.log('Spray mode:', sprayState.mode);
+ * }
+ */
+class SprayState {
+    /**
+     * Creates a new SprayState instance.
+     *
+     * @param {Object} [state=null] - Initial state object
+     * @param {number} [state.mode] - Spray mode (from SprayMode enum: OFF=0, CONTINUOUS=1, INTERMITTENT=2)
+     * @param {number} [state.channel] - Channel number
+     */
+    constructor(state = null) {
+        this._state = state || {};
+    }
+
+    /**
+     * Updates the state with new data.
+     *
+     * Merges new state data into the existing state using Object.assign to preserve
+     * properties not included in the update. Called automatically by device controllers
+     * when state updates are received from device responses or push notifications.
+     *
+     * @param {Object} state - New state data to merge
+     */
+    update(state) {
+        if (state) {
+            Object.assign(this._state, state);
+        }
+    }
+
+    /**
+     * Gets the spray mode.
+     *
+     * @returns {number|undefined} Spray mode value (0=off, 1=continuous, 2=intermittent) or undefined if not available
+     * @see {@link module:lib/enums.SprayMode} for mode constants
+     */
+    get mode() {
+        const { mode } = this._state;
+        if (mode === undefined || mode === null) {return undefined;}
+        return mode;
+    }
+}
+
+module.exports = SprayState;
+

package/lib/model/states/thermostat-state.js

@@ -0,0 +1,297 @@
+'use strict';
+
+const { ThermostatMode, ThermostatWorkingMode, ThermostatModeBState } = require('../enums');
+
+/**
+ * Represents the thermostat state of a device channel.
+ *
+ * Encapsulates state information for thermostat devices, including mode, target
+ * temperature, current temperature, and working mode. State instances are managed
+ * by device controllers and updated automatically when device responses or push
+ * notifications are received.
+ *
+ * @class
+ * @example
+ * const thermostatState = device.getCachedThermostatState(0);
+ * if (thermostatState) {
+ *     console.log('Mode:', thermostatState.mode);
+ *     console.log('Target temp:', thermostatState.targetTemp);
+ *     console.log('Current temp:', thermostatState.currentTemp);
+ * }
+ */
+class ThermostatState {
+    /**
+     * Creates a new ThermostatState instance.
+     *
+     * @param {Object} [state=null] - Initial state object
+     * @param {number} [state.onoff] - On/off state (0=off, 1=on)
+     * @param {number} [state.channel] - Channel number
+     * @param {number} [state.mode] - Thermostat mode (from ThermostatMode enum)
+     * @param {number} [state.targetTemp] - Target temperature
+     * @param {number} [state.currentTemp] - Current temperature
+     * @param {number} [state.working] - Working mode (from ThermostatWorkingMode enum)
+     * @param {number} [state.state] - Mode B state (from ThermostatModeBState enum)
+     */
+    constructor(state = null) {
+        this._state = state || {};
+    }
+
+    /**
+     * Updates the state with new data.
+     *
+     * Merges new state data into the existing state using Object.assign to preserve
+     * properties not included in the update. Called automatically by device controllers
+     * when state updates are received from device responses or push notifications.
+     *
+     * @param {Object} state - New state data to merge
+     */
+    update(state) {
+        if (state) {
+            Object.assign(this._state, state);
+        }
+    }
+
+    /**
+     * Gets whether the thermostat is on.
+     *
+     * Converts the device's numeric on/off state (0 or 1) to a boolean for easier
+     * conditional logic in application code.
+     *
+     * @returns {boolean|undefined} True if on, false if off, undefined if state not available
+     */
+    get isOn() {
+        const { onoff } = this._state;
+        if (onoff === undefined || onoff === null) {return undefined;}
+        return onoff === 1;
+    }
+
+    /**
+     * Gets the thermostat mode.
+     *
+     * Normalizes the mode value against the ThermostatMode enum. Returns the enum value
+     * if found, or the raw value if it's in the valid range (0-4) but not in the enum.
+     * This normalization allows handling of future enum values without breaking existing
+     * code while still providing enum constants when available.
+     *
+     * @returns {number|undefined} ThermostatMode enum value, raw value if valid but not in enum, or undefined if invalid
+     * @see {@link module:lib/enums.ThermostatMode} for mode constants
+     */
+    get mode() {
+        const { mode } = this._state;
+        if (mode === undefined || mode === null) {return undefined;}
+        if (mode >= 0 && mode <= 4) {
+            const enumKey = Object.keys(ThermostatMode).find(key => ThermostatMode[key] === mode);
+            if (enumKey) {
+                return ThermostatMode[enumKey];
+            }
+            return mode;
+        }
+        return undefined;
+    }
+
+    /**
+     * Gets the raw thermostat mode value.
+     *
+     * Returns the unvalidated mode value directly from state. Use this when you need
+     * the exact value without enum normalization, such as when debugging or working
+     * with device protocols directly.
+     *
+     * @returns {number|undefined} Raw mode value or undefined if not available
+     */
+    get rawMode() {
+        return this._state.mode;
+    }
+
+    /**
+     * Gets the working mode.
+     *
+     * Normalizes the working mode value against the ThermostatWorkingMode enum.
+     * Returns undefined if the value doesn't match any enum constant.
+     *
+     * @returns {number|undefined} ThermostatWorkingMode enum value or undefined if not available
+     * @see {@link module:lib/enums.ThermostatWorkingMode} for mode constants
+     */
+    get workingMode() {
+        const { working } = this._state;
+        if (working === undefined || working === null) {return undefined;}
+        const enumKey = Object.keys(ThermostatWorkingMode).find(key => ThermostatWorkingMode[key] === working);
+        return enumKey ? ThermostatWorkingMode[enumKey] : undefined;
+    }
+
+    /**
+     * Gets the raw working mode value.
+     *
+     * Returns the unvalidated working mode value directly from state. Use this when
+     * you need the exact value without enum normalization.
+     *
+     * @returns {number|undefined} Raw working mode value or undefined if not available
+     */
+    get rawWorkingMode() {
+        return this._state.working;
+    }
+
+    /**
+     * Gets the mode B state.
+     *
+     * Normalizes the mode B state value against the ThermostatModeBState enum.
+     * Returns undefined if the value doesn't match any enum constant.
+     *
+     * @returns {number|undefined} ThermostatModeBState enum value or undefined if not available
+     * @see {@link module:lib/enums.ThermostatModeBState} for state constants
+     */
+    get state() {
+        const { state } = this._state;
+        if (state === undefined || state === null) {return undefined;}
+        const enumKey = Object.keys(ThermostatModeBState).find(key => ThermostatModeBState[key] === state);
+        return enumKey ? ThermostatModeBState[enumKey] : undefined;
+    }
+
+    /**
+     * Gets the raw mode B state value.
+     *
+     * Returns the unvalidated mode B state value directly from state. Use this when
+     * you need the exact value without enum normalization.
+     *
+     * @returns {number|undefined} Raw mode B state value or undefined if not available
+     */
+    get rawState() {
+        return this._state.state;
+    }
+
+    /**
+     * Gets whether a warning condition is active.
+     *
+     * Converts the device's numeric warning state (0 or 1) to a boolean for easier
+     * conditional logic in application code.
+     *
+     * @returns {boolean|undefined} True if warning is active, false otherwise, undefined if state not available
+     */
+    get warning() {
+        const { warning } = this._state;
+        if (warning === undefined || warning === null) {return undefined;}
+        return warning === 1;
+    }
+
+    /**
+     * Gets the target temperature in Celsius.
+     *
+     * The device stores temperature values as integers in tenths of a degree (e.g., 250 = 25.0°C).
+     * This getter converts to decimal Celsius for easier use in applications that work
+     * with standard temperature units.
+     *
+     * @returns {number|undefined} Target temperature in Celsius or undefined if not available
+     */
+    get targetTemperatureCelsius() {
+        const temp = this._state.targetTemp;
+        if (temp === undefined || temp === null) {return undefined;}
+        return temp / 10.0;
+    }
+
+    /**
+     * Gets the current temperature in Celsius.
+     *
+     * The device stores temperature values as integers in tenths of a degree (e.g., 250 = 25.0°C).
+     * This getter converts to decimal Celsius for easier use in applications that work
+     * with standard temperature units.
+     *
+     * @returns {number|undefined} Current temperature in Celsius or undefined if not available
+     */
+    get currentTemperatureCelsius() {
+        const temp = this._state.currentTemp;
+        if (temp === undefined || temp === null) {return undefined;}
+        return temp / 10.0;
+    }
+
+    /**
+     * Gets the minimum temperature setting in Celsius.
+     *
+     * The device stores temperature values as integers in tenths of a degree (e.g., 250 = 25.0°C).
+     * This getter converts to decimal Celsius for easier use in applications that work
+     * with standard temperature units.
+     *
+     * @returns {number|undefined} Minimum temperature in Celsius or undefined if not available
+     */
+    get minTemperatureCelsius() {
+        const temp = this._state.min;
+        if (temp === undefined || temp === null) {return undefined;}
+        return temp / 10.0;
+    }
+
+    /**
+     * Gets the maximum temperature setting in Celsius.
+     *
+     * The device stores temperature values as integers in tenths of a degree (e.g., 250 = 25.0°C).
+     * This getter converts to decimal Celsius for easier use in applications that work
+     * with standard temperature units.
+     *
+     * @returns {number|undefined} Maximum temperature in Celsius or undefined if not available
+     */
+    get maxTemperatureCelsius() {
+        const temp = this._state.max;
+        if (temp === undefined || temp === null) {return undefined;}
+        return temp / 10.0;
+    }
+
+    /**
+     * Gets the heat mode temperature setting in Celsius.
+     *
+     * The device stores temperature values as integers in tenths of a degree (e.g., 250 = 25.0°C).
+     * This getter converts to decimal Celsius for easier use in applications that work
+     * with standard temperature units.
+     *
+     * @returns {number|undefined} Heat mode temperature in Celsius or undefined if not available
+     */
+    get heatTemperatureCelsius() {
+        const temp = this._state.heatTemp;
+        if (temp === undefined || temp === null) {return undefined;}
+        return temp / 10.0;
+    }
+
+    /**
+     * Gets the cool mode temperature setting in Celsius.
+     *
+     * The device stores temperature values as integers in tenths of a degree (e.g., 250 = 25.0°C).
+     * This getter converts to decimal Celsius for easier use in applications that work
+     * with standard temperature units.
+     *
+     * @returns {number|undefined} Cool mode temperature in Celsius or undefined if not available
+     */
+    get coolTemperatureCelsius() {
+        const temp = this._state.coolTemp;
+        if (temp === undefined || temp === null) {return undefined;}
+        return temp / 10.0;
+    }
+
+    /**
+     * Gets the eco mode temperature setting in Celsius.
+     *
+     * The device stores temperature values as integers in tenths of a degree (e.g., 250 = 25.0°C).
+     * This getter converts to decimal Celsius for easier use in applications that work
+     * with standard temperature units.
+     *
+     * @returns {number|undefined} Eco mode temperature in Celsius or undefined if not available
+     */
+    get ecoTemperatureCelsius() {
+        const temp = this._state.ecoTemp;
+        if (temp === undefined || temp === null) {return undefined;}
+        return temp / 10.0;
+    }
+
+    /**
+     * Gets the manual mode temperature setting in Celsius.
+     *
+     * The device stores temperature values as integers in tenths of a degree (e.g., 250 = 25.0°C).
+     * This getter converts to decimal Celsius for easier use in applications that work
+     * with standard temperature units.
+     *
+     * @returns {number|undefined} Manual mode temperature in Celsius or undefined if not available
+     */
+    get manualTemperatureCelsius() {
+        const temp = this._state.manualTemp;
+        if (temp === undefined || temp === null) {return undefined;}
+        return temp / 10.0;
+    }
+}
+
+module.exports = ThermostatState;
+