meross-iot 0.1.0

package/lib/controller/features/alarm-feature.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { normalizeChannel } = require('../../utilities/options');
+
+const MAX_ALARM_EVENTS_MEMORY = 10;
+
+/**
+ * Alarm feature module.
+ * Handles alarm status queries and maintains a buffer of recent alarm events.
+ */
+module.exports = {
+    /**
+     * Initializes alarm events storage.
+     *
+     * Called lazily when the first alarm event is received to avoid unnecessary initialization.
+     *
+     * @private
+     */
+    _initializeAlarmEvents() {
+        if (!this._lastAlarmEvents) {
+            this._lastAlarmEvents = [];
+        }
+    },
+
+    /**
+     * Gets the current alarm status from the device.
+     *
+     * @param {Object} [options={}] - Get options
+     * @param {number} [options.channel=0] - Channel to get alarm status for (default: 0)
+     * @returns {Promise<Object>} Alarm status response with `alarm` array
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getAlarmStatus(options = {}) {
+        const channel = normalizeChannel(options);
+        const payload = { 'alarm': [{ channel }] };
+        return await this.publishMessage('GET', 'Appliance.Control.Alarm', payload);
+    },
+
+    /**
+     * Gets a copy of the most recent alarm events.
+     *
+     * Alarm events are automatically stored when push notifications are received.
+     * The library maintains up to MAX_ALARM_EVENTS_MEMORY most recent events.
+     *
+     * @returns {Array<Object>} Copy of the alarm events array (most recent first)
+     */
+    getLastAlarmEvents() {
+        this._initializeAlarmEvents();
+        return [...this._lastAlarmEvents];
+    },
+
+    /**
+     * Updates the alarm events buffer from push notification data.
+     *
+     * Called automatically when alarm push notifications are received. Maintains a rolling
+     * buffer of the most recent events, discarding older ones when the limit is exceeded.
+     *
+     * @param {Object|Array} alarmData - Alarm data (single object or array)
+     * @private
+     */
+    _updateAlarmEvents(alarmData, source = 'push') {
+        if (!alarmData) {return;}
+
+        this._initializeAlarmEvents();
+
+        const alarmArray = Array.isArray(alarmData) ? alarmData : [alarmData];
+
+        for (const alarmEvent of alarmArray) {
+            const oldEvents = [...this._lastAlarmEvents];
+            this._lastAlarmEvents.unshift(alarmEvent);
+
+            if (this._lastAlarmEvents.length > MAX_ALARM_EVENTS_MEMORY) {
+                this._lastAlarmEvents = this._lastAlarmEvents.slice(0, MAX_ALARM_EVENTS_MEMORY);
+            }
+
+            const channel = alarmEvent.channel !== undefined ? alarmEvent.channel : 0;
+            this.emit('stateChange', {
+                type: 'alarm',
+                channel,
+                value: alarmEvent,
+                oldValue: oldEvents.length > 0 ? oldEvents[0] : undefined,
+                source,
+                timestamp: Date.now()
+            });
+        }
+    }
+};
+

package/lib/controller/features/child-lock-feature.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { normalizeChannel } = require('../../utilities/options');
+
+/**
+ * Child lock feature module.
+ * Provides control over physical control lock functionality.
+ */
+module.exports = {
+    /**
+     * Gets the child lock status from the device.
+     *
+     * @param {Object} [options={}] - Get options
+     * @param {number} [options.channel=0] - Channel to get lock status for (default: 0)
+     * @param {string} [options.subId=null] - Optional subdevice ID
+     * @returns {Promise<Object>} Response containing lock status with `lock` array
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getChildLock(options = {}) {
+        const channel = normalizeChannel(options);
+        const payload = {
+            lock: [{
+                channel
+            }]
+        };
+        if (options.subId) {
+            payload.lock[0].subId = options.subId;
+        }
+        return await this.publishMessage('GET', 'Appliance.Control.PhysicalLock', payload);
+    },
+
+    /**
+     * Controls the child lock status.
+     *
+     * @param {Object} options - Child lock options
+     * @param {Object|Array<Object>} [options.lockData] - Lock data object or array of lock items (if provided, used directly)
+     * @param {number} [options.channel] - Channel to control
+     * @param {string} [options.subId] - Optional subdevice ID
+     * @param {number} [options.onoff] - Lock on (1) or off (0)
+     * @returns {Promise<Object>} Response from the device
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async setChildLock(options = {}) {
+        let lockData;
+        if (options.lockData) {
+            lockData = Array.isArray(options.lockData) ? options.lockData : [options.lockData];
+        } else {
+            const channel = normalizeChannel(options);
+            lockData = [{
+                channel,
+                subId: options.subId,
+                onoff: options.onoff
+            }];
+        }
+        const payload = { lock: lockData };
+        return await this.publishMessage('SET', 'Appliance.Control.PhysicalLock', payload);
+    }
+};
+

package/lib/controller/features/config-feature.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * Configuration feature module.
+ * Provides access to device configuration settings such as over-temperature protection.
+ */
+module.exports = {
+    /**
+     * Gets the over-temperature protection configuration from the device.
+     * @param {Object} [options={}] - Get options
+     * @returns {Promise<Object>} Response containing over-temperature protection config
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getConfigOverTemp(_options = {}) {
+        return await this.publishMessage('GET', 'Appliance.Config.OverTemp', {});
+    },
+
+    /**
+     * Controls the over-temperature protection configuration.
+     *
+     * @param {Object} options - Over-temperature config options
+     * @param {boolean} options.enable - Enable state (true = on, false = off)
+     * @param {number} [options.type] - Protection type (1 = early warning, 2 = early warning and shutdown). If not provided, preserves current type
+     * @returns {Promise<Object>} Response from the device
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async setConfigOverTemp(options = {}) {
+        if (options.enable === undefined) {
+            const { CommandError } = require('../../model/exception');
+            throw new CommandError('enable is required', { options }, this.uuid);
+        }
+
+        const enableValue = options.enable ? 1 : 2;
+        let overTempData;
+
+        if (options.type !== undefined) {
+            overTempData = { enable: enableValue, type: options.type };
+        } else {
+            try {
+                const currentConfig = await this.getConfigOverTemp();
+                const currentType = currentConfig?.overTemp?.type;
+                overTempData = { enable: enableValue, type: currentType !== undefined ? currentType : 1 };
+            } catch (e) {
+                overTempData = { enable: enableValue, type: 1 };
+            }
+        }
+
+        const payload = { overTemp: overTempData };
+        return await this.publishMessage('SET', 'Appliance.Config.OverTemp', payload);
+    }
+};
+

package/lib/controller/features/consumption-feature.js

@@ -0,0 +1,210 @@
+'use strict';
+
+const { normalizeChannel } = require('../../utilities/options');
+
+/**
+ * Consumption feature module.
+ * Provides access to historical power consumption data and consumption configuration settings.
+ */
+module.exports = {
+    /**
+     * Initializes consumption cache.
+     *
+     * Called lazily when consumption data is first accessed to avoid unnecessary initialization.
+     *
+     * @private
+     */
+    _initializeConsumptionCache() {
+        if (this._channelCachedConsumption === undefined) {
+            this._channelCachedConsumption = new Map();
+        }
+    },
+
+    /**
+     * Gets daily power consumption data from the device.
+     *
+     * Returns parsed consumption data with Date objects and converted units (kWh). Date strings
+     * are parsed from YYYY-MM-DD format or standard Date string format. Use {@link getRawPowerConsumption}
+     * to get the raw API response without parsing.
+     *
+     * @param {Object} [options={}] - Get options
+     * @param {number} [options.channel=0] - Channel to read data from (default: 0)
+     * @returns {Promise<Array<{date: Date, totalConsumptionKwh: number}>>} Historical consumption data with date and totalConsumptionKwh
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getPowerConsumption(options = {}) {
+        const channel = normalizeChannel(options);
+        this._initializeConsumptionCache();
+
+        const result = await this.publishMessage('GET', 'Appliance.Control.Consumption', { channel });
+        const data = result && result.consumption ? result.consumption : [];
+
+        this._updateConsumptionState({ channel, consumption: data }, 'response');
+
+        return this._channelCachedConsumption.get(channel) || null;
+    },
+
+    /**
+     * Gets daily power consumption data from the device (X version).
+     *
+     * Returns parsed consumption data with Date objects and converted units (kWh). This is an
+     * alternative consumption endpoint that may provide different data or formatting. Use
+     * {@link getRawPowerConsumptionX} to get the raw API response without parsing.
+     *
+     * @param {Object} [options={}] - Get options
+     * @param {number} [options.channel=0] - Channel to read data from (default: 0)
+     * @returns {Promise<Array<{date: Date, totalConsumptionKwh: number}>>} Historical consumption data with date and totalConsumptionKwh
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getPowerConsumptionX(options = {}) {
+        const channel = normalizeChannel(options);
+        const result = await this.publishMessage('GET', 'Appliance.Control.ConsumptionX', { channel });
+        const data = result && result.consumptionx ? result.consumptionx : [];
+
+        const DATE_FORMAT = /^(\d{4})-(\d{2})-(\d{2})$/;
+        return data.map(x => {
+            const dateStr = x.date;
+            let date;
+            if (DATE_FORMAT.test(dateStr)) {
+                const [, year, month, day] = dateStr.match(DATE_FORMAT);
+                date = new Date(parseInt(year), parseInt(month) - 1, parseInt(day));
+            } else {
+                date = new Date(dateStr);
+            }
+
+            return {
+                date,
+                totalConsumptionKwh: parseFloat(x.value) / 1000
+            };
+        });
+    },
+
+    /**
+     * Gets cached consumption data
+     *
+     * Returns the most recently fetched consumption data without making a request.
+     * Use {@link getPowerConsumption} to fetch fresh data from the device.
+     *
+     * @param {number} [channel=0] - Channel to get data for (default: 0)
+     * @returns {Array<{date: Date, totalConsumptionKwh: number}>|null} Cached consumption data or null if not available
+     */
+    getCachedConsumption(channel = 0) {
+        this._initializeConsumptionCache();
+        return this._channelCachedConsumption.get(channel) || null;
+    },
+
+    /**
+     * Gets the raw power consumption response from the device without parsing or unit conversion.
+     *
+     * For parsed data with Date objects and converted units, use {@link getPowerConsumption} instead.
+     *
+     * @param {Object} [options={}] - Get options
+     * @param {number} [options.channel=0] - Channel to read data from (default: 0)
+     * @returns {Promise<Object>} Raw API response containing consumption data
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getRawPowerConsumption(options = {}) {
+        const channel = normalizeChannel(options);
+        return await this.publishMessage('GET', 'Appliance.Control.Consumption', { channel });
+    },
+
+    /**
+     * Gets the raw power consumption X response from the device without parsing or unit conversion.
+     *
+     * For parsed data with Date objects and converted units, use {@link getPowerConsumptionX} instead.
+     *
+     * @param {Object} [options={}] - Get options
+     * @param {number} [options.channel=0] - Channel to read data from (default: 0)
+     * @returns {Promise<Object>} Raw API response containing consumption X data
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getRawPowerConsumptionX(options = {}) {
+        const channel = normalizeChannel(options);
+        return await this.publishMessage('GET', 'Appliance.Control.ConsumptionX', { channel });
+    },
+
+    /**
+     * Gets the consumption configuration from the device.
+     *
+     * Returns voltage and current calibration coefficients used for power consumption calculations.
+     *
+     * @returns {Promise<Object>} Response containing consumption configuration
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getConsumptionConfig() {
+        return await this.publishMessage('GET', 'Appliance.Control.ConsumptionConfig', {});
+    },
+
+    /**
+     * Updates the cached consumption state from consumption data.
+     *
+     * Called automatically when consumption data is received. Parses raw device data,
+     * converts dates and units, and emits stateChange events when data changes.
+     *
+     * @param {Object} consumptionData - Raw consumption data from device
+     * @param {number} consumptionData.channel - Channel index
+     * @param {Array} consumptionData.consumption - Array of consumption entries with date and value
+     * @param {string} [source='response'] - Source of the update ('push' | 'poll' | 'response')
+     * @private
+     */
+    _updateConsumptionState(consumptionData, source = 'response') {
+        if (!consumptionData) {return;}
+
+        this._initializeConsumptionCache();
+
+        const channelIndex = consumptionData.channel;
+        if (channelIndex === undefined || channelIndex === null) {return;}
+
+        const data = consumptionData.consumption || [];
+
+        const DATE_FORMAT = /^(\d{4})-(\d{2})-(\d{2})$/;
+        const parsedData = data.map(x => {
+            const dateStr = x.date;
+            let date;
+            if (DATE_FORMAT.test(dateStr)) {
+                const [, year, month, day] = dateStr.match(DATE_FORMAT);
+                date = new Date(parseInt(year), parseInt(month) - 1, parseInt(day));
+            } else {
+                date = new Date(dateStr);
+            }
+
+            return {
+                date,
+                totalConsumptionKwh: parseFloat(x.value) / 1000
+            };
+        });
+
+        const oldData = this._channelCachedConsumption.get(channelIndex);
+        this._channelCachedConsumption.set(channelIndex, parsedData);
+
+        let hasChanges = false;
+        if (!oldData || oldData.length !== parsedData.length) {
+            hasChanges = true;
+        } else {
+            for (let i = 0; i < parsedData.length; i++) {
+                if (!oldData[i] ||
+                    oldData[i].totalConsumptionKwh !== parsedData[i].totalConsumptionKwh ||
+                    oldData[i].date.getTime() !== parsedData[i].date.getTime()) {
+                    hasChanges = true;
+                    break;
+                }
+            }
+        }
+
+        if (hasChanges) {
+            this.emit('stateChange', {
+                type: 'consumption',
+                channel: channelIndex,
+                value: parsedData,
+                oldValue: oldData || undefined,
+                source,
+                timestamp: Date.now()
+            });
+        }
+    }
+};

package/lib/controller/features/control-feature.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * Control feature module.
+ * Provides advanced control capabilities including batch commands, event acknowledgments, and firmware upgrades.
+ */
+module.exports = {
+    /**
+     * Executes multiple commands simultaneously.
+     *
+     * Allows sending multiple commands in a single request to reduce network overhead and improve
+     * efficiency when controlling multiple aspects of a device at once.
+     *
+     * @param {Array<Object>} commands - Array of command objects
+     * @param {string} commands[].namespace - Namespace for the command (e.g., "Appliance.Control.ToggleX")
+     * @param {string} commands[].method - Method for the command (e.g., "SET", "GET")
+     * @param {Object} commands[].payload - Payload for the command
+     * @returns {Promise<Object>} Response containing results for each command
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async setMultiple(commands) {
+        const payload = {
+            multiple: commands.map(cmd => ({
+                header: {
+                    namespace: cmd.namespace,
+                    method: cmd.method
+                },
+                payload: cmd.payload
+            }))
+        };
+        return await this.publishMessage('SET', 'Appliance.Control.Multiple', payload);
+    },
+
+    /**
+     * Acknowledges an over-temperature event.
+     *
+     * Over-temperature events are typically initiated by the device via SET. This method sends
+     * a SETACK response to acknowledge receipt of the event.
+     *
+     * @returns {Promise<Object>} Response from the device
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async acknowledgeControlOverTemp() {
+        return await this.publishMessage('SETACK', 'Appliance.Control.OverTemp', {});
+    },
+
+    /**
+     * Initiates a device firmware upgrade.
+     *
+     * @param {Object} upgradeData - Upgrade data object containing upgrade parameters
+     * @returns {Promise<Object>} Response from the device
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async setUpgrade(upgradeData) {
+        const payload = { upgrade: upgradeData };
+        return await this.publishMessage('SET', 'Appliance.Control.Upgrade', payload);
+    }
+};
+