meross-iot 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.1] - 2026-01-22
+
+### Fixed
+- Improve heartbeat offline detection by using response silence (≥ heartbeat interval) instead of treating individual command errors/timeouts as offline signals
+
+## [0.9.0] - 2026-01-22
+
+### Added
+- Signal strength property (`device.signalStrength`) from Appliance.System.Runtime
+  - Provides signal strength percentage (1-100) on production firmware
+  - Automatically updated when runtime data is fetched
+  - Available in TypeScript definitions
+- Runtime polling support in ManagerSubscription
+  - Added `runtimeInterval` option (default: 60000ms) for periodic runtime data polling
+  - Runtime data (signal strength, network type, IoT status) requires polling as it doesn't support push notifications
+  - Respects smart caching configuration to reduce network traffic
+  - Polling automatically skips when device is offline
+
 ## [0.8.0] - 2026-01-22
 
 ### Added

package/README.md

@@ -26,7 +26,7 @@ The library can control devices locally via HTTP or via cloud MQTT server.
 npm install meross-iot@alpha
 
 # Or install specific version
-npm install meross-iot@0.7.1
+npm install meross-iot@0.9.1
 ```
 
 ## Usage & Documentation
@@ -177,6 +177,27 @@ Please create an issue on GitHub and include:
 
 ## Changelog
 
+### [0.9.1] - 2026-01-22
+
+#### Fixed
+- Improve heartbeat offline detection by using response silence (≥ heartbeat interval) instead of treating individual command errors/timeouts as offline signals
+
+<details>
+<summary>Older</summary>
+
+### [0.9.0] - 2026-01-22
+
+#### Added
+- Signal strength property (`device.signalStrength`) from Appliance.System.Runtime
+  - Provides signal strength percentage (1-100) on production firmware
+  - Automatically updated when runtime data is fetched
+  - Available in TypeScript definitions
+- Runtime polling support in ManagerSubscription
+  - Added `runtimeInterval` option (default: 60000ms) for periodic runtime data polling
+  - Runtime data (signal strength, network type, IoT status) requires polling as it doesn't support push notifications
+  - Respects smart caching configuration to reduce network traffic
+  - Polling automatically skips when device is offline
+
 ### [0.8.0] - 2026-01-22
 
 #### Added
@@ -212,9 +233,6 @@ Please create an issue on GitHub and include:
 - Prevent redundant ability updates when abilities haven't changed
 - Device initialization event now properly emitted by device itself after System.All is received
 
-<details>
-<summary>Older</summary>
-
 ### [0.7.2] - 2026-01-21
 
 #### Changed

package/index.d.ts

@@ -2854,6 +2854,8 @@ declare module 'meross-iot' {
         readonly lanIp: string | null
         readonly mqttHost: string | null
         readonly mqttPort: number | null
+        /** Signal strength percentage (1-100) from Appliance.System.Runtime. Available on production firmware. */
+        readonly signalStrength: number | null
         /** Device capabilities object containing supported features and namespaces */
         readonly abilities: Record<string, any> | null
         /** Normalized device capabilities map for easy feature discovery without namespace knowledge */

package/lib/controller/device.js

@@ -204,6 +204,7 @@ class MerossDevice extends EventEmitter {
         this.mqttPort = port;
         this.rssi = null;
         this.wifiSignal = null;
+        this.signalStrength = null;
         this.wifiSsid = null;
         this.wifiChannel = null;
         this.wifiSnr = null;
@@ -905,6 +906,7 @@ class MerossDevice extends EventEmitter {
                     firmwareVersion: this.firmwareVersion,
                     rssi: this.rssi,
                     wifiSignal: this.wifiSignal,
+                    signalStrength: this.signalStrength,
                     wifiSsid: this.wifiSsid,
                     wifiChannel: this.wifiChannel,
                     wifiSnr: this.wifiSnr,
@@ -1066,9 +1068,6 @@ class MerossDevice extends EventEmitter {
 
         if (message.header.method === 'ERROR') {
             const errorPayload = message.payload || {};
-            if (this._heartbeat) {
-                this._heartbeat.recordFailure();
-            }
             pending.reject(new MerossErrorCommand(
                 `Device returned error: ${JSON.stringify(errorPayload)}`,
                 errorPayload,
@@ -1318,9 +1317,6 @@ class MerossDevice extends EventEmitter {
                                 namespace,
                                 messageId
                             };
-                            if (this._heartbeat) {
-                                this._heartbeat.recordFailure();
-                            }
                             this.waitingMessageIds[messageId].reject(
                                 new MerossErrorCommandTimeout(
                                     `Command timed out after ${timeoutDuration}ms`,
@@ -1335,9 +1331,6 @@ class MerossDevice extends EventEmitter {
                 };
 
             } catch (error) {
-                if (this._heartbeat) {
-                    this._heartbeat.recordFailure();
-                }
                 reject(error);
             }
         });

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

@@ -31,6 +31,12 @@ function createRuntimeFeature(device) {
             const result = await device.publishMessage('GET', 'Appliance.System.Runtime', {});
             const data = result && result.runtime ? result.runtime : {};
             device._runtimeInfo = data;
+
+            // Update signalStrength property from runtime data (production firmware)
+            if (data.signal !== undefined) {
+                device.signalStrength = data.signal;
+            }
+
             return data;
         },
 

package/lib/device-factory.js

@@ -210,30 +210,30 @@ function getCachedDeviceClass(deviceType, hardwareVersion, firmwareVersion) {
 function _buildDynamicClass(typeKey, abilities, BaseClass) {
     const features = new Set();
 
-        features.add(require('./controller/features/system-feature'));
-
-        if (abilities && typeof abilities === 'object') {
-            const hasXVersion = new Set();
-            for (const namespace of Object.keys(abilities)) {
-                if (namespace.endsWith('X')) {
-                    const baseNamespace = namespace.slice(0, -1);
-                    hasXVersion.add(baseNamespace);
-                }
+    features.add(require('./controller/features/system-feature'));
+
+    if (abilities && typeof abilities === 'object') {
+        const hasXVersion = new Set();
+        for (const namespace of Object.keys(abilities)) {
+            if (namespace.endsWith('X')) {
+                const baseNamespace = namespace.slice(0, -1);
+                hasXVersion.add(baseNamespace);
             }
+        }
 
-            for (const [namespace] of Object.entries(abilities)) {
-                const feature = ABILITY_MATRIX[namespace];
-                if (feature) {
-                    if (namespace.endsWith('X')) {
+        for (const [namespace] of Object.entries(abilities)) {
+            const feature = ABILITY_MATRIX[namespace];
+            if (feature) {
+                if (namespace.endsWith('X')) {
+                    features.add(feature);
+                } else {
+                    if (!hasXVersion.has(namespace)) {
                         features.add(feature);
-                    } else {
-                        if (!hasXVersion.has(namespace)) {
-                            features.add(feature);
-                        }
                     }
                 }
             }
         }
+    }
 
     class DynamicDevice extends BaseClass {}
 

package/lib/managers/subscription.js

@@ -10,11 +10,11 @@ const { OnlineStatus } = require('../model/enums');
  * Coordinates push notifications and targeted polling to provide a single event stream for
  * device state changes. Device state is polled once on initial subscription to establish a
  * baseline for listeners, then typically relies on push notifications for ongoing updates.
- * Some features (electricity, consumption) require periodic polling because they do not
+ * Some features (electricity, consumption, runtime) require periodic polling because they do not
  * emit push notifications.
  *
  * Push notifications reduce latency and network traffic compared to frequent polling.
- * Periodic polling is intended for features without push support (electricity, consumption)
+ * Periodic polling is intended for features without push support (electricity, consumption, runtime)
  * or as an explicit fallback when a device is not producing push updates.
  *
  * @class
@@ -30,6 +30,7 @@ class ManagerSubscription extends EventEmitter {
      * @param {number} [options.deviceStateInterval=0] - Device state polling interval in milliseconds (0 to disable periodic polling, rely on push only after initial state)
      * @param {number} [options.electricityInterval=30000] - Electricity metrics polling interval in milliseconds (0 to disable)
      * @param {number} [options.consumptionInterval=60000] - Power consumption polling interval in milliseconds (0 to disable)
+     * @param {number} [options.runtimeInterval=60000] - Runtime information polling interval in milliseconds (0 to disable)
      * @param {number} [options.httpDeviceListInterval=120000] - HTTP device list polling interval in milliseconds
      * @param {boolean} [options.smartCaching=true] - Skip polling when cached data is fresh to reduce network traffic
      * @param {number} [options.cacheMaxAge=10000] - Maximum cache age in milliseconds before considering data stale
@@ -49,6 +50,7 @@ class ManagerSubscription extends EventEmitter {
             deviceStateInterval: options.deviceStateInterval !== undefined ? options.deviceStateInterval : 0,
             electricityInterval: options.electricityInterval !== undefined ? options.electricityInterval : 30000,
             consumptionInterval: options.consumptionInterval !== undefined ? options.consumptionInterval : 60000,
+            runtimeInterval: options.runtimeInterval !== undefined ? options.runtimeInterval : 60000,
             httpDeviceListInterval: options.httpDeviceListInterval || 120000,
             smartCaching: options.smartCaching !== false,
             cacheMaxAge: options.cacheMaxAge || 10000,
@@ -64,16 +66,17 @@ class ManagerSubscription extends EventEmitter {
      * Subscribe to device updates.
      *
      * Registers event listeners for push notifications and starts periodic polling
-     * based on configuration. For metrics (electricity/consumption), multiple calls merge by
-     * selecting the shortest interval so all listeners receive updates at the required frequency.
+     * based on configuration. Configuration is only applied on the first subscription
+     * call for a device; subsequent calls reuse the existing configuration.
      * Device state polling is configured explicitly via `deviceStateInterval` (with a baseline
      * state poll on initial subscription).
      *
      * @param {MerossDevice} device - Device to subscribe to
-     * @param {Object} [config={}] - Subscription configuration
+     * @param {Object} [config={}] - Subscription configuration (only applied on first subscription)
      * @param {number} [config.deviceStateInterval] - Device state polling interval in milliseconds (0 to disable periodic polling, rely on push only after initial state)
      * @param {number} [config.electricityInterval] - Electricity metrics polling interval in milliseconds (0 to disable)
      * @param {number} [config.consumptionInterval] - Power consumption polling interval in milliseconds (0 to disable)
+     * @param {number} [config.runtimeInterval] - Runtime information polling interval in milliseconds (0 to disable)
      * @param {boolean} [config.smartCaching] - Skip polling when cached data is fresh
      * @param {number} [config.cacheMaxAge] - Maximum cache age in milliseconds before refresh
      * @param {boolean} [config.pushOnly=false] - Prefer push-driven updates and emit cached state immediately when available
@@ -95,33 +98,24 @@ class ManagerSubscription extends EventEmitter {
         const subscription = this.subscriptions.get(deviceUuid);
         const isNewSubscription = !subscription.pollingIntervals || subscription.pollingIntervals.size === 0;
 
-        const existingConfig = subscription.config || { ...this.defaultConfig };
-        const pushOnly = config.pushOnly !== undefined ? config.pushOnly : (existingConfig.pushOnly || this.defaultConfig.pushOnly);
-
-        subscription.config = {
-            deviceStateInterval: config.deviceStateInterval !== undefined ? config.deviceStateInterval : (existingConfig.deviceStateInterval !== undefined ? existingConfig.deviceStateInterval : this.defaultConfig.deviceStateInterval),
-            electricityInterval: Math.min(
-                existingConfig.electricityInterval || this.defaultConfig.electricityInterval,
-                config.electricityInterval !== undefined ? config.electricityInterval : (existingConfig.electricityInterval || this.defaultConfig.electricityInterval)
-            ),
-            consumptionInterval: Math.min(
-                existingConfig.consumptionInterval || this.defaultConfig.consumptionInterval,
-                config.consumptionInterval !== undefined ? config.consumptionInterval : (existingConfig.consumptionInterval || this.defaultConfig.consumptionInterval)
-            ),
-            smartCaching: config.smartCaching !== undefined ? config.smartCaching : existingConfig.smartCaching,
-            cacheMaxAge: Math.min(
-                existingConfig.cacheMaxAge || this.defaultConfig.cacheMaxAge,
-                config.cacheMaxAge !== undefined ? config.cacheMaxAge : (existingConfig.cacheMaxAge || this.defaultConfig.cacheMaxAge)
-            ),
-            pushOnly
-        };
-
         if (isNewSubscription) {
+            const getConfigValue = (key) => config[key] !== undefined ? config[key] : this.defaultConfig[key];
+
+            subscription.config = {
+                deviceStateInterval: getConfigValue('deviceStateInterval'),
+                electricityInterval: getConfigValue('electricityInterval'),
+                consumptionInterval: getConfigValue('consumptionInterval'),
+                runtimeInterval: getConfigValue('runtimeInterval'),
+                smartCaching: getConfigValue('smartCaching'),
+                cacheMaxAge: getConfigValue('cacheMaxAge'),
+                pushOnly: getConfigValue('pushOnly')
+            };
+
             this._startPolling(device, subscription);
-        }
 
-        if (subscription.config.pushOnly && isNewSubscription) {
-            this._emitCachedState(device, subscription);
+            if (subscription.config.pushOnly) {
+                this._emitCachedState(device, subscription);
+            }
         }
 
         const listenerCount = this.listenerCount(eventName);
@@ -233,7 +227,7 @@ class ManagerSubscription extends EventEmitter {
     }
 
     /**
-     * Start polling for device state, electricity, and consumption data.
+     * Start polling for device state, electricity, consumption, and runtime data.
      *
      * Performs a one-time device state poll on initial subscription so consumers
      * can receive a current baseline state without waiting for the next push event.
@@ -272,6 +266,14 @@ class ManagerSubscription extends EventEmitter {
 
             subscription.pollingIntervals.set('consumption', interval);
         }
+
+        if (config.runtimeInterval > 0 && device.runtime && typeof device.runtime.get === 'function') {
+            const interval = setInterval(async () => {
+                await this._pollRuntime(device, subscription, config);
+            }, config.runtimeInterval);
+
+            subscription.pollingIntervals.set('runtime', interval);
+        }
     }
 
     /**
@@ -429,6 +431,46 @@ class ManagerSubscription extends EventEmitter {
         }
     }
 
+    /**
+     * Poll runtime information from the device.
+     *
+     * Runtime data (signal strength, network type, IoT status) requires polling as it
+     * doesn't support push notifications. Skips polling when cached runtime data is fresh
+     * (if smartCaching enabled) to reduce network traffic.
+     *
+     * @private
+     * @param {MerossDevice} device - Device to poll
+     * @param {Object} subscription - Subscription state object
+     * @param {Object} config - Configuration object with caching settings
+     */
+    async _pollRuntime(device, subscription, config) {
+        if (device.onlineStatus !== OnlineStatus.ONLINE) {
+            return;
+        }
+
+        const namespace = 'Appliance.System.Runtime';
+        if (this._hasRecentPush(subscription, namespace, 5000)) {
+            return;
+        }
+
+        try {
+            if (config.smartCaching && device._runtimeInfo) {
+                const cached = device.runtime.getCached();
+                if (cached && Object.keys(cached).length > 0) {
+                    const cacheAge = Date.now() - (subscription.lastPollTimes.get('runtime') || 0);
+                    if (cacheAge < config.cacheMaxAge) {
+                        return;
+                    }
+                }
+            }
+
+            await device.runtime.get();
+            subscription.lastPollTimes.set('runtime', Date.now());
+        } catch (error) {
+            this.logger(`Error polling runtime for ${device.uuid}: ${error.message}`);
+        }
+    }
+
     /**
      * Mark push notifications as active for a specific namespace.
      *

package/lib/model/exception.js

@@ -45,7 +45,7 @@ class MerossError extends Error {
         }
         if (this.isOperational !== undefined) {
             result.isOperational = this.isOperational;
-            }
+        }
         return result;
     }
 }

package/lib/utilities/heartbeat.js

@@ -3,11 +3,12 @@
 const { OnlineStatus } = require('../model/enums');
 
 /**
- * Manages device online/offline detection using multiple strategies.
+ * Manages device online/offline detection using time-based silence detection.
  *
- * Provides comprehensive connectivity monitoring through periodic heartbeat checks,
- * response tracking, failure counting, and System.All monitoring. Automatically
- * updates device online status when connectivity issues are detected.
+ * Tracks the last response time from the device and marks it offline when no
+ * response is received for the configured timeout period. Uses time-based detection
+ * rather than failure counting to avoid false offline states from transient network
+ * issues or temporary HTTP unavailability when MQTT is still functional.
  *
  * @class Heartbeat
  */
@@ -17,21 +18,18 @@ class Heartbeat {
      *
      * @param {Object} device - MerossDevice instance to monitor
      * @param {Object} [options={}] - Configuration options
-     * @param {number} [options.heartbeatInterval=120000] - Heartbeat interval in milliseconds (120 seconds)
-     * @param {number} [options.consecutiveFailureThreshold=1] - Number of consecutive failures before marking offline
+     * @param {number} [options.heartbeatInterval=295000] - Heartbeat interval in milliseconds (295 seconds)
      * @param {boolean} [options.enabled=true] - Whether heartbeat monitoring is enabled
      */
     constructor(device, options = {}) {
         this.device = device;
-        this.heartbeatInterval = options.heartbeatInterval || 120000;
-        this.consecutiveFailureThreshold = options.consecutiveFailureThreshold || 1;
+        this.heartbeatInterval = options.heartbeatInterval || 295000;
         this.enabled = options.enabled !== false;
 
         this._lastResponseTime = null;
-        this._consecutiveFailures = 0;
         this._heartbeatTimer = null;
         this._isRunning = false;
-        // Exponential backoff: starts at base delay, doubles when offline, capped at heartbeat interval
+        // Start with shorter delay to quickly detect when device comes back online
         this._pollingDelay = Math.floor(this.heartbeatInterval / 2);
     }
 
@@ -53,7 +51,7 @@ class Heartbeat {
     /**
      * Stops heartbeat monitoring and cleans up timers.
      *
-     * Should be called when device disconnects.
+     * Prevents memory leaks by clearing scheduled timers when device disconnects.
      */
     stop() {
         this._isRunning = false;
@@ -66,38 +64,26 @@ class Heartbeat {
     /**
      * Records a successful response from the device.
      *
-     * Updates last response time and resets consecutive failure counter.
-     * Resets polling delay to base interval when device comes back online.
-     * Called whenever any successful response is received.
+     * Updates the last response timestamp to reset the silence timer. Resets polling
+     * delay when device transitions from offline to online to quickly detect if it
+     * goes offline again.
      */
     recordResponse() {
         const wasOffline = this.device.onlineStatus === OnlineStatus.OFFLINE;
         this._lastResponseTime = Date.now();
-        this._consecutiveFailures = 0;
 
         if (wasOffline) {
             this._pollingDelay = Math.floor(this.heartbeatInterval / 2);
         }
-        
-        this._evaluateStatus();
-    }
 
-    /**
-     * Records a command failure or timeout.
-     *
-     * Increments consecutive failure counter and evaluates if device should
-     * be marked offline. Called when commands fail or timeout.
-     */
-    recordFailure() {
-        this._consecutiveFailures++;
         this._evaluateStatus();
     }
 
     /**
      * Records a System.All response.
      *
-     * System.All responses indicate device is active and responding.
-     * Updates last response time and resets failure counter.
+     * System.All responses are comprehensive state updates that confirm device
+     * connectivity, so they reset the silence timer.
      */
     recordSystemAll() {
         this.recordResponse();
@@ -106,9 +92,8 @@ class Heartbeat {
     /**
      * Evaluates device status and updates if necessary.
      *
-     * Checks multiple conditions to determine if device should be marked offline:
-     * - 1 consecutive failure
-     * - No response for > 2x heartbeat interval (240s) when device was online
+     * Only marks devices offline that are currently online to avoid redundant
+     * status updates and ensure we don't mark already-offline devices offline again.
      *
      * @private
      */
@@ -126,20 +111,18 @@ class Heartbeat {
     }
 
     /**
-     * Determines if device should be marked offline based on tracking data.
+     * Determines if device should be marked offline based on silence timeout.
+     *
+     * Requires device to be currently online to avoid marking already-offline devices.
+     * Requires at least one previous response to have a baseline for silence detection.
      *
      * @private
      * @returns {boolean} True if device should be marked offline
      */
     _shouldBeOffline() {
-        if (this._consecutiveFailures >= this.consecutiveFailureThreshold) {
-            return true;
-        }
-
         if (this._lastResponseTime && this.device.onlineStatus === OnlineStatus.ONLINE) {
             const timeSinceLastResponse = Date.now() - this._lastResponseTime;
-            const maxSilenceInterval = this.heartbeatInterval * 2;
-            if (timeSinceLastResponse > maxSilenceInterval) {
+            if (timeSinceLastResponse >= this.heartbeatInterval) {
                 return true;
             }
         }
@@ -150,8 +133,9 @@ class Heartbeat {
     /**
      * Schedules the next heartbeat check.
      *
-     * Uses exponential backoff delay when device is offline, otherwise uses
-     * heartbeat interval. Checks if heartbeat is needed (conditional triggering).
+     * Uses shorter polling delay when offline to quickly detect when device comes
+     * back online. Uses standard heartbeat interval when online to avoid unnecessary
+     * network traffic when device is actively responding.
      *
      * @private
      */
@@ -160,8 +144,8 @@ class Heartbeat {
             return;
         }
 
-        const delay = this.device.onlineStatus === OnlineStatus.OFFLINE 
-            ? this._pollingDelay 
+        const delay = this.device.onlineStatus === OnlineStatus.OFFLINE
+            ? this._pollingDelay
             : this.heartbeatInterval;
 
         this._heartbeatTimer = setTimeout(() => {
@@ -172,10 +156,9 @@ class Heartbeat {
     /**
      * Performs a heartbeat check by querying System.Online.
      *
-     * Only performs heartbeat if device has been silent for >= heartbeat interval
-     * (conditional triggering, like meross_lan). On success, the response will be
-     * handled by recordResponse() via the normal message handling flow. On failure,
-     * records a failure and applies exponential backoff when offline.
+     * Skips heartbeat if device responded recently to avoid redundant requests when
+     * device is actively communicating. On failure, increases polling delay when
+     * already offline to reduce network load while waiting for device recovery.
      *
      * @private
      */
@@ -184,7 +167,6 @@ class Heartbeat {
             return;
         }
 
-        // Only perform heartbeat if no response received for >= heartbeat interval
         if (this._lastResponseTime) {
             const timeSinceLastResponse = Date.now() - this._lastResponseTime;
             if (timeSinceLastResponse < this.heartbeatInterval) {
@@ -196,8 +178,8 @@ class Heartbeat {
         try {
             await this.device.system.getOnlineStatus();
         } catch (error) {
-            this.recordFailure();
-
+            // Single heartbeat failure doesn't mark device offline; only extended
+            // silence triggers offline detection to handle transient network issues
             if (this.device.onlineStatus === OnlineStatus.OFFLINE) {
                 this._pollingDelay = Math.min(
                     this._pollingDelay * 2,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meross-iot",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Control Meross cloud devices using nodejs",
   "author": "Abe Haverkamp",
   "contributors": [