meross-iot 0.1.0

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

@@ -0,0 +1,411 @@
+'use strict';
+
+const DiffuserLightState = require('../../model/states/diffuser-light-state');
+const DiffuserSprayState = require('../../model/states/diffuser-spray-state');
+const { DiffuserLightMode, DiffuserSprayMode } = require('../../model/enums');
+const { buildStateChanges } = require('../../utilities/state-changes');
+
+/**
+ * Diffuser feature module.
+ * Provides control over diffuser light and spray functionality for essential oil diffusers.
+ */
+module.exports = {
+    /**
+     * Controls the diffuser light settings.
+     *
+     * Automatically includes the device UUID in the light configuration object.
+     *
+     * @param {Object} options - Diffuser light options
+     * @param {Object} options.light - Light configuration object
+     * @param {number} [options.light.channel] - Channel to control (default: 0)
+     * @param {number} [options.light.onoff] - Turn light on (1) or off (0)
+     * @param {number} [options.light.mode] - Light mode (use DiffuserLightMode enum)
+     * @param {number} [options.light.luminance] - Brightness value
+     * @param {number} [options.light.rgb] - RGB color value
+     * @returns {Promise<Object>} Response from the device containing the updated light state
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async setDiffuserLight(options = {}) {
+        if (!options.light) {
+            throw new Error('light is required');
+        }
+        const light = { ...options.light };
+        light.uuid = this.uuid;
+        const payload = { 'light': [light] };
+        const response = await this.publishMessage('SET', 'Appliance.Control.Diffuser.Light', payload);
+
+        if (response && response.light) {
+            this._updateDiffuserLightState(response.light);
+            this._lastFullUpdateTimestamp = Date.now();
+        } else if (light) {
+            this._updateDiffuserLightState([light]);
+            this._lastFullUpdateTimestamp = Date.now();
+        }
+
+        return response;
+    },
+
+    /**
+     * Controls the diffuser spray mode.
+     *
+     * Automatically includes the device UUID in the spray configuration.
+     *
+     * @param {Object} options - Diffuser spray options
+     * @param {number} [options.channel=0] - Channel to control (default: 0)
+     * @param {number|import('../lib/enums').DiffuserSprayMode} options.mode - Spray mode value or DiffuserSprayMode enum
+     * @returns {Promise<Object>} Response from the device containing the updated spray state
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async setDiffuserSpray(options = {}) {
+        const { normalizeChannel } = require('../../utilities/options');
+        if (options.mode === undefined) {
+            throw new Error('mode is required');
+        }
+        const channel = normalizeChannel(options);
+        const payload = { 'spray': [{ channel, 'mode': options.mode || 0, 'uuid': this.uuid }] };
+        const response = await this.publishMessage('SET', 'Appliance.Control.Diffuser.Spray', payload);
+
+        if (response && response.spray) {
+            this._updateDiffuserSprayState(response.spray, 'response');
+            this._lastFullUpdateTimestamp = Date.now();
+        } else {
+            this._updateDiffuserSprayState([{ channel, mode: options.mode || 0 }], 'response');
+            this._lastFullUpdateTimestamp = Date.now();
+        }
+
+        return response;
+    },
+
+    /**
+     * Gets the current diffuser light state from the device.
+     *
+     * Use {@link getCachedDiffuserLightState} to get cached state without making a request.
+     * @param {Object} [options={}] - Get options
+     * @returns {Promise<Object>} Response containing light state with `light` array
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getDiffuserLightState(_options = {}) {
+        const response = await this.publishMessage('GET', 'Appliance.Control.Diffuser.Light', {});
+        if (response && response.light) {
+            this._updateDiffuserLightState(response.light, 'response');
+            this._lastFullUpdateTimestamp = Date.now();
+        }
+        return response;
+    },
+
+    /**
+     * Gets the current diffuser spray state from the device.
+     *
+     * Use {@link getCachedDiffuserSprayState} to get cached state without making a request.
+     * @param {Object} [options={}] - Get options
+     * @returns {Promise<Object>} Response containing spray state with `spray` array
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getDiffuserSprayState(_options = {}) {
+        const response = await this.publishMessage('GET', 'Appliance.Control.Diffuser.Spray', {});
+        if (response && response.spray) {
+            this._updateDiffuserSprayState(response.spray, 'response');
+            this._lastFullUpdateTimestamp = Date.now();
+        }
+        return response;
+    },
+
+    /**
+     * Gets the cached diffuser light state for the specified channel.
+     *
+     * Returns cached state without making a request. Use {@link getDiffuserLightState} to fetch
+     * fresh state from the device. State is automatically updated when commands are sent or
+     * push notifications are received.
+     *
+     * @param {number} [channel=0] - Channel to get state for (default: 0)
+     * @returns {import('../lib/model/states/diffuser-light-state').DiffuserLightState|undefined} Cached light state or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     */
+    getCachedDiffuserLightState(channel = 0) {
+        this.validateState();
+        return this._diffuserLightStateByChannel.get(channel);
+    },
+
+    /**
+     * Gets the diffuser light mode for the specified channel (cached).
+     *
+     * Returns the light mode enum from cached state. Use {@link getRawDiffuserLightMode} to get
+     * the raw numeric value.
+     *
+     * @param {number} [channel=0] - Channel to get mode for (default: 0)
+     * @returns {import('../lib/enums').DiffuserLightMode|undefined} DiffuserLightMode enum object (e.g., DiffuserLightMode.FIXED_RGB) or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     * @see getRawDiffuserLightMode
+     */
+    getDiffuserLightMode(channel = 0) {
+        this.validateState();
+        const lightState = this._diffuserLightStateByChannel.get(channel);
+        if (lightState && lightState.mode !== undefined && lightState.mode !== null) {
+            const enumKey = Object.keys(DiffuserLightMode).find(key => DiffuserLightMode[key] === lightState.mode);
+            return enumKey ? DiffuserLightMode[enumKey] : undefined;
+        }
+        return undefined;
+    },
+
+    /**
+     * Gets the raw numeric diffuser light mode value for the specified channel (cached).
+     *
+     * Returns the raw numeric mode value. For enum object, use {@link getDiffuserLightMode} instead.
+     *
+     * @param {number} [channel=0] - Channel to get mode for (default: 0)
+     * @returns {number|undefined} Raw numeric mode value or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     * @see getDiffuserLightMode
+     */
+    getRawDiffuserLightMode(channel = 0) {
+        this.validateState();
+        const lightState = this._diffuserLightStateByChannel.get(channel);
+        if (lightState) {
+            return lightState.mode;
+        }
+        return undefined;
+    },
+
+    /**
+     * Gets the diffuser light brightness for the specified channel (cached).
+     *
+     * @param {number} [channel=0] - Channel to get brightness for (default: 0)
+     * @returns {number|undefined} Brightness value (0-100) or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     */
+    getDiffuserLightBrightness(channel = 0) {
+        this.validateState();
+        const lightState = this._diffuserLightStateByChannel.get(channel);
+        if (lightState) {
+            return lightState.luminance;
+        }
+        return undefined;
+    },
+
+    /**
+     * Gets the diffuser light RGB color for the specified channel (cached).
+     *
+     * @param {number} [channel=0] - Channel to get color for (default: 0)
+     * @returns {Array<number>|undefined} RGB tuple [r, g, b] where each value is 0-255, or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     */
+    getDiffuserLightRgbColor(channel = 0) {
+        this.validateState();
+        const lightState = this._diffuserLightStateByChannel.get(channel);
+        if (lightState) {
+            return lightState.rgbTuple;
+        }
+        return undefined;
+    },
+
+    /**
+     * Checks if the diffuser light is on for the specified channel (cached).
+     *
+     * @param {number} [channel=0] - Channel to check (default: 0)
+     * @returns {boolean|undefined} True if on, false if off, undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     */
+    getDiffuserLightIsOn(channel = 0) {
+        this.validateState();
+        const lightState = this._diffuserLightStateByChannel.get(channel);
+        if (lightState) {
+            return lightState.isOn;
+        }
+        return undefined;
+    },
+
+    /**
+     * Gets the cached diffuser spray state for the specified channel.
+     *
+     * Returns cached state without making a request. Use {@link getDiffuserSprayState} to fetch
+     * fresh state from the device. State is automatically updated when commands are sent or
+     * push notifications are received.
+     *
+     * @param {number} [channel=0] - Channel to get state for (default: 0)
+     * @returns {import('../lib/model/states/diffuser-spray-state').DiffuserSprayState|undefined} Cached spray state or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     */
+    getCachedDiffuserSprayState(channel = 0) {
+        this.validateState();
+        return this._diffuserSprayStateByChannel.get(channel);
+    },
+
+    /**
+     * Gets the diffuser spray mode for the specified channel (cached).
+     *
+     * Returns the spray mode enum from cached state. Use {@link getRawDiffuserSprayMode} to get
+     * the raw numeric value.
+     *
+     * @param {number} [channel=0] - Channel to get mode for (default: 0)
+     * @returns {import('../lib/enums').DiffuserSprayMode|undefined} DiffuserSprayMode enum object (e.g., DiffuserSprayMode.LIGHT) or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     * @see getRawDiffuserSprayMode
+     */
+    getDiffuserSprayMode(channel = 0) {
+        this.validateState();
+        const sprayState = this._diffuserSprayStateByChannel.get(channel);
+        if (sprayState && sprayState.mode !== undefined && sprayState.mode !== null) {
+            const enumKey = Object.keys(DiffuserSprayMode).find(key => DiffuserSprayMode[key] === sprayState.mode);
+            return enumKey ? DiffuserSprayMode[enumKey] : undefined;
+        }
+        return undefined;
+    },
+
+    /**
+     * Gets the raw numeric diffuser spray mode value for the specified channel (cached).
+     *
+     * Returns the raw numeric mode value. For enum object, use {@link getDiffuserSprayMode} instead.
+     *
+     * @param {number} [channel=0] - Channel to get mode for (default: 0)
+     * @returns {number|undefined} Raw numeric mode value or undefined if not available
+     * @throws {Error} If state has not been initialized (call refreshState() first)
+     * @see getDiffuserSprayMode
+     */
+    getRawDiffuserSprayMode(channel = 0) {
+        this.validateState();
+        const sprayState = this._diffuserSprayStateByChannel.get(channel);
+        if (sprayState) {
+            return sprayState.mode;
+        }
+        return undefined;
+    },
+
+    /**
+     * Updates the cached diffuser light state from light data.
+     *
+     * Called automatically when diffuser light push notifications are received or commands complete.
+     * Handles both single objects and arrays of light data.
+     *
+     * @param {Object|Array} lightData - Light data (single object or array)
+     * @param {string} [source='response'] - Source of the update ('push' | 'poll' | 'response')
+     * @private
+     */
+    _updateDiffuserLightState(lightData, source = 'response') {
+        if (!lightData) {return;}
+
+        const lightArray = Array.isArray(lightData) ? lightData : [lightData];
+
+        for (const lightItem of lightArray) {
+            const channelIndex = lightItem.channel;
+            if (channelIndex === undefined || channelIndex === null) {continue;}
+
+            const oldState = this._diffuserLightStateByChannel.get(channelIndex);
+            const oldValue = oldState ? {
+                isOn: oldState.isOn,
+                brightness: oldState.luminance,
+                rgb: oldState.rgbTuple,
+                mode: oldState.mode
+            } : undefined;
+
+            let state = this._diffuserLightStateByChannel.get(channelIndex);
+            if (!state) {
+                state = new DiffuserLightState(lightItem);
+                this._diffuserLightStateByChannel.set(channelIndex, state);
+            } else {
+                state.update(lightItem);
+            }
+
+            const newValue = buildStateChanges(oldValue, {
+                isOn: state.isOn,
+                brightness: state.luminance,
+                rgb: state.rgbTuple,
+                mode: state.mode
+            }, ['rgb']);
+
+            if (Object.keys(newValue).length > 0) {
+                this.emit('stateChange', {
+                    type: 'diffuserLight',
+                    channel: channelIndex,
+                    value: newValue,
+                    oldValue,
+                    source,
+                    timestamp: Date.now()
+                });
+            }
+        }
+    },
+
+    /**
+     * Updates the cached diffuser spray state from spray data.
+     *
+     * Called automatically when diffuser spray push notifications are received or commands complete.
+     * Handles both single objects and arrays of spray data.
+     *
+     * @param {Object|Array} sprayData - Spray data (single object or array)
+     * @param {string} [source='response'] - Source of the update ('push' | 'poll' | 'response')
+     * @private
+     */
+    _updateDiffuserSprayState(sprayData, source = 'response') {
+        if (!sprayData) {return;}
+
+        const sprayArray = Array.isArray(sprayData) ? sprayData : [sprayData];
+
+        for (const sprayItem of sprayArray) {
+            const channelIndex = sprayItem.channel;
+            if (channelIndex === undefined || channelIndex === null) {continue;}
+
+            const oldState = this._diffuserSprayStateByChannel.get(channelIndex);
+            const oldValue = oldState ? {
+                mode: oldState.mode
+            } : undefined;
+
+            let state = this._diffuserSprayStateByChannel.get(channelIndex);
+            if (!state) {
+                state = new DiffuserSprayState(sprayItem);
+                this._diffuserSprayStateByChannel.set(channelIndex, state);
+            } else {
+                state.update(sprayItem);
+            }
+
+            const newValue = buildStateChanges(oldValue, {
+                mode: state.mode
+            });
+
+            if (Object.keys(newValue).length > 0) {
+                this.emit('stateChange', {
+                    type: 'diffuserSpray',
+                    channel: channelIndex,
+                    value: newValue,
+                    oldValue,
+                    source,
+                    timestamp: Date.now()
+                });
+            }
+        }
+    },
+
+    /**
+     * Gets the diffuser sensor data (humidity and temperature) from the device.
+     *
+     * @returns {Promise<Object>} Response containing sensor data with humidity and temperature
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getDiffuserSensor(_options = {}) {
+        return await this.publishMessage('GET', 'Appliance.Control.Diffuser.Sensor', {});
+    },
+
+    /**
+     * Controls the diffuser sensor configuration.
+     *
+     * Note: This namespace primarily supports GET and PUSH. SET may not be available for all devices.
+     *
+     * @param {Object} sensorData - Sensor data object
+     * @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 setDiffuserSensor(options = {}) {
+        if (!options.sensorData) {
+            throw new Error('sensorData is required');
+        }
+        const sensorData = options.sensorData;
+        const payload = sensorData;
+        return await this.publishMessage('SET', 'Appliance.Control.Diffuser.Sensor', payload);
+    }
+};
+

package/lib/controller/features/digest-timer-feature.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * Timer digest feature module.
+ * Provides access to timer summary information without fetching individual timer details.
+ */
+module.exports = {
+    /**
+     * Gets timer digest (summary) information.
+     *
+     * Returns a summary of all timers across all channels. Use this to check timer status
+     * without fetching detailed timer information. For detailed timer data, use {@link getTimerX}.
+     *
+     * @returns {Promise<Object>} Response containing timer digest data
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getTimerXDigest() {
+        return await this.publishMessage('GET', 'Appliance.Digest.TimerX', {});
+    }
+};
+

package/lib/controller/features/digest-trigger-feature.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * Trigger digest feature module.
+ * Provides access to trigger summary information without fetching individual trigger details.
+ */
+module.exports = {
+    /**
+     * Gets trigger digest (summary) information.
+     *
+     * Returns a summary of all triggers across all channels. Use this to check trigger status
+     * without fetching detailed trigger information. For detailed trigger data, use {@link getTriggerX}.
+     *
+     * @returns {Promise<Object>} Response containing trigger digest data
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getTriggerXDigest() {
+        return await this.publishMessage('GET', 'Appliance.Digest.TriggerX', {});
+    }
+};
+

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

@@ -0,0 +1,79 @@
+'use strict';
+
+const { DNDMode } = require('../../model/enums');
+
+/**
+ * Do-not-disturb feature module.
+ * Controls the device's do-not-disturb mode, which disables the ambient LED when enabled.
+ */
+module.exports = {
+    /**
+     * Gets the do-not-disturb mode from the device.
+     * @param {Object} [options={}] - Get options
+     * @returns {Promise<import('../lib/enums').DNDMode>} DNDMode enum object (DNDMode.DND_DISABLED or DNDMode.DND_ENABLED)
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getDNDMode(_options = {}) {
+        const result = await this.publishMessage('GET', 'Appliance.System.DNDMode', {});
+        if (result && result.DNDMode && result.DNDMode.mode !== undefined) {
+            const modeValue = result.DNDMode.mode;
+            const enumKey = Object.keys(DNDMode).find(key => DNDMode[key] === modeValue);
+            this._lastFullUpdateTimestamp = Date.now();
+            return enumKey ? DNDMode[enumKey] : DNDMode.DND_DISABLED;
+        }
+        this._lastFullUpdateTimestamp = Date.now();
+        return DNDMode.DND_DISABLED;
+    },
+
+    /**
+     * Gets the raw numeric DND mode value from the device.
+     *
+     * Returns the numeric value directly without converting to an enum. For enum object,
+     * use {@link getDNDMode} instead.
+     * @param {Object} [options={}] - Get options
+     * @returns {Promise<number>} Raw numeric DND mode value (0 = disabled, 1 = enabled)
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     * @see getDNDMode
+     */
+    async getRawDNDMode(_options = {}) {
+        const result = await this.publishMessage('GET', 'Appliance.System.DNDMode', {});
+        if (result && result.DNDMode && result.DNDMode.mode !== undefined) {
+            return result.DNDMode.mode;
+        }
+        return DNDMode.DND_DISABLED;
+    },
+
+    /**
+     * Controls the do-not-disturb mode setting.
+     *
+     * When enabled, the device turns off its ambient LED to reduce visual disturbance.
+     *
+     * @param {Object} options - DND mode options
+     * @param {boolean|import('../lib/enums').DNDMode} options.mode - DNDMode enum value or boolean (true = enabled, false = disabled)
+     * @returns {Promise<void>}
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     * @throws {import('../lib/errors/errors').CommandError} If mode value is invalid
+     */
+    async setDNDMode(options = {}) {
+        if (options.mode === undefined) {
+            const { CommandError } = require('../../model/exception');
+            throw new CommandError('mode is required', { options }, this.uuid);
+        }
+        let modeValue;
+        if (typeof options.mode === 'boolean') {
+            modeValue = options.mode ? DNDMode.DND_ENABLED : DNDMode.DND_DISABLED;
+        } else if (options.mode === DNDMode.DND_ENABLED || options.mode === DNDMode.DND_DISABLED) {
+            modeValue = options.mode;
+        } else {
+            const { CommandError } = require('../../model/exception');
+            throw new CommandError('Invalid DND mode. Expected boolean or DNDMode enum value.', { mode: options.mode }, this.uuid);
+        }
+
+        const payload = { 'DNDMode': { 'mode': modeValue } };
+        await this.publishMessage('SET', 'Appliance.System.DNDMode', payload);
+    }
+};
+

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

@@ -0,0 +1,144 @@
+'use strict';
+
+const { normalizeChannel } = require('../../utilities/options');
+const { buildStateChanges } = require('../../utilities/state-changes');
+
+/**
+ * Electricity feature module.
+ * Provides access to real-time power consumption metrics including voltage, current, and power.
+ */
+module.exports = {
+    /**
+     * Initializes electricity metrics cache.
+     *
+     * Called lazily when electricity data is first accessed to avoid unnecessary initialization.
+     *
+     * @private
+     */
+    _initializeElectricityCache() {
+        if (this._channelCachedSamples === undefined) {
+            this._channelCachedSamples = new Map();
+        }
+    },
+
+    /**
+     * Gets instant power consumption metrics from the device.
+     *
+     * Note that voltage and current values reported by most Meross devices may not be accurate.
+     * The power (wattage) value is typically more reliable. Use the power attribute directly
+     * rather than calculating it as voltage * current.
+     *
+     * To avoid excessive device polling, prefer using {@link getCachedElectricity} and only
+     * call this method when the cached value is null or the sampleTimestamp indicates stale data.
+     *
+     * @param {Object} [options={}] - Get options
+     * @param {number} [options.channel=0] - Channel to read metrics from (default: 0)
+     * @returns {Promise<{amperage: number, voltage: number, wattage: number, sampleTimestamp: Date}>} PowerInfo object with converted units
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getElectricity(options = {}) {
+        const channel = normalizeChannel(options);
+        this._initializeElectricityCache();
+
+        const result = await this.publishMessage('GET', 'Appliance.Control.Electricity', { channel });
+        const data = result && result.electricity ? result.electricity : {};
+
+        this._updateElectricityState({ channel, ...data }, 'response');
+
+        return this._channelCachedSamples.get(channel) || null;
+    },
+
+    /**
+     * Gets the cached power consumption metrics.
+     *
+     * Returns the most recently fetched power info without making a request. Use {@link getElectricity}
+     * to fetch fresh data from the device.
+     *
+     * @param {number} [channel=0] - Channel to get metrics for (default: 0)
+     * @returns {{amperage: number, voltage: number, wattage: number, sampleTimestamp: Date}|null} Cached PowerInfo object or null if not available
+     */
+    getCachedElectricity(channel = 0) {
+        this._initializeElectricityCache();
+        return this._channelCachedSamples.get(channel) || null;
+    },
+
+    /**
+     * Gets the raw electricity metrics response without parsing or unit conversion.
+     *
+     * Returns the raw API response with device-native units. For parsed data with standard
+     * unit conversions, use {@link getElectricity} instead.
+     *
+     * @param {Object} [options={}] - Get options
+     * @param {number} [options.channel=0] - Channel to read metrics from (default: 0)
+     * @returns {Promise<Object>} Raw API response containing electricity data
+     * @throws {import('../lib/errors/errors').UnconnectedError} If device is not connected
+     * @throws {import('../lib/errors/errors').CommandTimeoutError} If command times out
+     */
+    async getRawElectricity(options = {}) {
+        const channel = normalizeChannel(options);
+        return await this.publishMessage('GET', 'Appliance.Control.Electricity', { channel });
+    },
+
+    /**
+     * Updates the cached electricity state from electricity data.
+     *
+     * Called automatically when electricity data is received. Parses raw device data,
+     * converts units, and emits stateChange events when values change.
+     *
+     * @param {Object} electricityData - Raw electricity data from device
+     * @param {number} electricityData.channel - Channel index
+     * @param {number} [electricityData.current] - Current in device units (milliamps)
+     * @param {number} [electricityData.voltage] - Voltage in device units (tenths of volts)
+     * @param {number} [electricityData.power] - Power in device units (milliwatts)
+     * @param {string} [source='response'] - Source of the update ('push' | 'poll' | 'response')
+     * @private
+     */
+    _updateElectricityState(electricityData, source = 'response') {
+        if (!electricityData) {return;}
+
+        this._initializeElectricityCache();
+
+        const channelIndex = electricityData.channel;
+        if (channelIndex === undefined || channelIndex === null) {return;}
+
+        const current = parseFloat(electricityData.current || 0) / 1000;
+        const voltage = parseFloat(electricityData.voltage || 0) / 10;
+        const power = parseFloat(electricityData.power || 0) / 1000;
+
+        const powerInfo = {
+            amperage: current,
+            voltage,
+            wattage: power,
+            sampleTimestamp: new Date()
+        };
+
+        const oldPowerInfo = this._channelCachedSamples.get(channelIndex);
+        const oldValue = oldPowerInfo ? {
+            amperage: oldPowerInfo.amperage,
+            voltage: oldPowerInfo.voltage,
+            wattage: oldPowerInfo.wattage
+        } : undefined;
+
+        this._channelCachedSamples.set(channelIndex, powerInfo);
+
+        const newValue = buildStateChanges(oldValue, {
+            amperage: powerInfo.amperage,
+            voltage: powerInfo.voltage,
+            wattage: powerInfo.wattage
+        });
+
+        if (Object.keys(newValue).length > 0) {
+            const valueToEmit = oldValue === undefined ? powerInfo : { ...newValue, sampleTimestamp: powerInfo.sampleTimestamp };
+
+            this.emit('stateChange', {
+                type: 'electricity',
+                channel: channelIndex,
+                value: valueToEmit,
+                oldValue,
+                source,
+                timestamp: Date.now()
+            });
+        }
+    }
+};