@espressif/rainmaker-neo-base-sdk 1.0.0 → 1.2.0

package/dist/cjs/services/ESPTransport/ESPLocalControlTransport.js.map

@@ -1 +1 @@
-{"version":3,"file":"ESPLocalControlTransport.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"ESPLocalControlTransport.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/services/ESPTransport/LocalControlSession.js

@@ -0,0 +1,62 @@
+'use strict';
+
+var ESPRMNeoBase = require('../../ESPRMNeoBase.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Attempts made before a local-control handshake is reported as failed. */
+const DEFAULT_CONNECT_RETRIES = 3;
+/**
+ * Returns the app-supplied local control adapter.
+ *
+ * @throws {Error} When no adapter was registered on {@link ESPRMNeoBase}.
+ */
+function getLocalControlAdapter() {
+    const adapter = ESPRMNeoBase.ESPRMNeoBase.getLocalControlAdapter();
+    if (!adapter) {
+        throw new Error("Local control adapter is not configured");
+    }
+    return adapter;
+}
+/**
+ * Ensures a usable local-control session for `nodeId`, connecting (with
+ * retries) when the adapter reports none.
+ *
+ * The adapter resolves on a successful handshake and rejects otherwise, so a
+ * resolved `connect` is treated as connected.
+ *
+ * @param adapter - Adapter to drive.
+ * @param nodeId - Node to connect to.
+ * @param metadata - Local transport metadata (`baseUrl`, `securityType`, `pop`,
+ *   `username`).
+ * @param options - Session endpoints for the protocol in use; omitted for the
+ *   adapter's built-in default paths.
+ * @param maxRetries - Connection attempts before failing.
+ * @throws {Error} When every connection attempt fails.
+ */
+async function ensureLocalControlSession(adapter, nodeId, metadata, options, maxRetries = DEFAULT_CONNECT_RETRIES) {
+    if (await adapter.isConnected(nodeId)) {
+        return;
+    }
+    let attempt = 0;
+    let lastError;
+    while (attempt < maxRetries) {
+        try {
+            await adapter.connect(nodeId, metadata.baseUrl, metadata.securityType ?? 0, metadata.pop, metadata.username, options);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            attempt += 1;
+        }
+    }
+    const message = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new Error(`Failed to connect after ${maxRetries} attempts: ${message}`);
+}
+
+exports.ensureLocalControlSession = ensureLocalControlSession;
+exports.getLocalControlAdapter = getLocalControlAdapter;
+//# sourceMappingURL=LocalControlSession.js.map

package/dist/cjs/services/ESPTransport/LocalControlSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalControlSession.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/services/NodeMQTTOrchestrator.js

@@ -141,8 +141,8 @@ class NodeMQTTOrchestrator {
     /**
      * Registers a node with the orchestrator.
      * Must be called before subscribeToNode, getParams, getShadow, etc.
-     * On shadow rename: clears the old binding; ignores shorter/incomplete names.
-     * Shrink membership via {@link unregisterNode} first.
+     * On shadow rename: clears the old binding, then installs the new name
+     * (including shrinks to a shorter membership shadow).
      *
      * @param nodeId - The device/node identifier.
      * @param shadowName - The named shadow (e.g. `params-groupId-subgroupId`).
@@ -151,9 +151,6 @@ class NodeMQTTOrchestrator {
         const instance = NodeMQTTOrchestrator.getInstance();
         const existing = instance.nodeMap.get(nodeId);
         if (existing && existing.shadowName !== shadowName) {
-            if (shadowName.split("-").length < existing.shadowName.split("-").length) {
-                return;
-            }
             NodeMQTTOrchestrator.unregisterNode(nodeId);
         }
         instance.nodeMap.set(nodeId, { shadowName });

package/dist/cjs/services/NodeMQTTOrchestrator.js.map

@@ -1 +1 @@
-{"version":3,"file":"NodeMQTTOrchestrator.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"NodeMQTTOrchestrator.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/types/transport.js

@@ -19,6 +19,29 @@ exports.ESPTransportMode = void 0;
     /** Communication is routed through MQTT (RainMaker Neo cloud: AWS shadow). */
     ESPTransportMode["mqtt"] = "mqtt";
 })(exports.ESPTransportMode || (exports.ESPTransportMode = {}));
+/**
+ * Wire protocol spoken by the `local` transport. Both protocols run over a
+ * protocomm session on the node's LAN HTTP server; they differ in endpoint
+ * names and message encoding.
+ *
+ * Carried on the local transport config's `metadata.protocol`, set by local
+ * discovery from the mDNS service type that produced the hit.
+ */
+exports.ESPLocalControlProtocol = void 0;
+(function (ESPLocalControlProtocol) {
+    /**
+     * RainMaker Neo protocol (`rmaker_local_ctrl/*` session plus
+     * `get_params`/`set_params`/`get_config`), advertised as
+     * `_esp_rmaker_ctrl._tcp`. Default for this SDK.
+     */
+    ESPLocalControlProtocol["rmakerLocalCtrl"] = "rmaker_local_ctrl";
+})(exports.ESPLocalControlProtocol || (exports.ESPLocalControlProtocol = {}));
+/**
+ * Protocol assumed when a local transport config carries no explicit
+ * `metadata.protocol` — for example a LAN transport restored from a client-side
+ * registry rather than a fresh discovery hit.
+ */
+const DEFAULT_LOCAL_CONTROL_PROTOCOL = exports.ESPLocalControlProtocol.rmakerLocalCtrl;
 /**
  * Default transport priority order used when neither the node nor the SDK base
  * has an explicit order configured: local control first, MQTT (cloud) fallback.
@@ -28,5 +51,6 @@ const DEFAULT_TRANSPORT_ORDER = [
     exports.ESPTransportMode.mqtt,
 ];
 
+exports.DEFAULT_LOCAL_CONTROL_PROTOCOL = DEFAULT_LOCAL_CONTROL_PROTOCOL;
 exports.DEFAULT_TRANSPORT_ORDER = DEFAULT_TRANSPORT_ORDER;
 //# sourceMappingURL=transport.js.map

package/dist/cjs/types/transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"transport.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/utils/constants.js

@@ -393,6 +393,15 @@ const TriggerErrorMessages = {
     /** Logged when retrieving triggers for a node fails. */
     GET_FAILED: "getTriggers failed",
 };
+/**
+ * Error messages for assumeRole (POST /v1/assumed-roles).
+ */
+const AssumeRoleErrorMessages = {
+    /** Thrown when `services` is provided without a `nodeId`. */
+    NODE_ID_REQUIRED: "assumeRole: nodeId is required when services is provided",
+    /** Thrown when the assume-role response is missing required credential fields. */
+    INVALID_RESPONSE: "Invalid assume role response: missing required credential fields",
+};
 /**
  * Error / log messages for temporary AWS credentials (POST /v1/user/credentials).
  */
@@ -466,8 +475,6 @@ const ProvisionType = {
  * An object containing endpoint paths.
  */
 const Endpoint = {
-    /** The endpoint for local control. */
-    LOCAL_CTRL: "esp_local_ctrl/control",
     /** The endpoint for cloud user association. */
     CLOUD_USER_ASSOCIATION: "cloud_user_assoc",
     /** The endpoint for challenge-response and get-node-id protocol with the device. */
@@ -475,6 +482,64 @@ const Endpoint = {
     /** The endpoint for assisted claiming. */
     RM_CLAIM: "rmaker_claim",
 };
+/**
+ * Endpoint paths of the `rmaker_local_ctrl` protocol served by RainMaker Neo
+ * firmware (see the firmware's local-control endpoint protocol spec).
+ *
+ * All data endpoints inherit the security of the session established on
+ * {@link RMakerLocalCtrlEndpoint.SESSION}.
+ */
+const RMakerLocalCtrlEndpoint = {
+    /** Protocomm session-security endpoint (SEC1 with/without PoP, or SEC2). */
+    SESSION: "rmaker_local_ctrl/session",
+    /** POST any payload; responds with the service info JSON (`sec_ver`, `cap`, …). */
+    VERSION: "rmaker_local_ctrl/version",
+    /** Reads the params JSON — protobuf `CmdGetData`, fragmented response. */
+    GET_PARAMS: "get_params",
+    /** Reads the node config JSON — protobuf `CmdGetData`, fragmented response. */
+    GET_CONFIG: "get_config",
+    /** Writes params — raw JSON request and response (no protobuf). */
+    SET_PARAMS: "set_params",
+};
+/**
+ * Root key of the JSON served by {@link RMakerLocalCtrlEndpoint.VERSION}, i.e.
+ * `{"rmaker_local_ctrl": {"ver": …, "sec_ver": …, "cap": [...]}}`. Passed to the
+ * local-control adapter so the native layer probes the right scheme version.
+ */
+const RMAKER_LOCAL_CTRL_VERSION_KEY = "rmaker_local_ctrl";
+/**
+ * Maximum fragment size (bytes) the firmware serves per `RespGetData`. Reads
+ * loop with `Offset += Payload.length` until `TotalLen` is reached; this value
+ * is informational (the device dictates the actual fragment length).
+ */
+const RMAKER_LOCAL_CTRL_FRAGMENT_SIZE = 200;
+/**
+ * `status` values in a `set_params` raw-JSON response.
+ */
+const RMakerLocalCtrlSetParamsStatus = {
+    SUCCESS: "success",
+    FAIL: "fail",
+};
+/**
+ * mDNS TXT record keys advertised by the `_esp_rmaker_ctrl._tcp` service.
+ */
+const RMakerLocalCtrlTxtKey = {
+    /** Node ID (also the service instance name and hostname). */
+    NODE_ID: "node_id",
+    /** Comma-separated active capabilities — see {@link RMakerLocalCtrlCapability}. */
+    CAP: "cap",
+};
+/**
+ * Capability tokens found in the `cap` TXT record. A node advertising only
+ * `ch_resp` is reachable for on-network user-node association but *not* for
+ * param control, so it must not be registered as a local control transport.
+ */
+const RMakerLocalCtrlCapability = {
+    /** Params/config endpoints are registered. */
+    LOCAL_CTRL: "local_ctrl",
+    /** Challenge-response (on-network user-node association) is registered. */
+    CH_RESP: "ch_resp",
+};
 /**
  * Assisted-claiming REST paths, on the deployment's main API and SigV4-signed
  * like every other `/v1/*` route.
@@ -632,8 +697,12 @@ const ProvErrorCodes = {
  * @enum {string}
  */
 const ServiceType = {
-    /** Represents the ESP local control TCP service type. */
-    ESP_LOCAL_CTRL_TCP: "_esp_local_ctrl._tcp.",
+    /**
+     * Service type advertised by RainMaker Neo firmware. A single instance serves
+     * the `rmaker_local_ctrl` endpoints; the `cap` TXT record says which endpoint
+     * sets are active. This is the default for local discovery in this SDK.
+     */
+    ESP_RMAKER_LOCAL_CTRL_TCP: "_esp_rmaker_ctrl._tcp.",
 };
 /**
  * An object containing protocol types.
@@ -847,6 +916,7 @@ exports.APIEndpoints = APIEndpoints;
 exports.APIOperations = APIOperations;
 exports.APIPathV1 = APIPathV1;
 exports.AWSCredentialsErrorMessages = AWSCredentialsErrorMessages;
+exports.AssumeRoleErrorMessages = AssumeRoleErrorMessages;
 exports.AuthErrorCodes = AuthErrorCodes;
 exports.AuthSuccessMessages = AuthSuccessMessages;
 exports.AutomationStatusValues = AutomationStatusValues;
@@ -877,6 +947,12 @@ exports.NodeWarnMessages = NodeWarnMessages;
 exports.ProtocolType = ProtocolType;
 exports.ProvErrorCodes = ProvErrorCodes;
 exports.ProvisionType = ProvisionType;
+exports.RMAKER_LOCAL_CTRL_FRAGMENT_SIZE = RMAKER_LOCAL_CTRL_FRAGMENT_SIZE;
+exports.RMAKER_LOCAL_CTRL_VERSION_KEY = RMAKER_LOCAL_CTRL_VERSION_KEY;
+exports.RMakerLocalCtrlCapability = RMakerLocalCtrlCapability;
+exports.RMakerLocalCtrlEndpoint = RMakerLocalCtrlEndpoint;
+exports.RMakerLocalCtrlSetParamsStatus = RMakerLocalCtrlSetParamsStatus;
+exports.RMakerLocalCtrlTxtKey = RMakerLocalCtrlTxtKey;
 exports.SDK_VERSION = SDK_VERSION;
 exports.ScheduleErrorMessages = ScheduleErrorMessages;
 exports.ScheduleSuccessMessages = ScheduleSuccessMessages;

package/dist/cjs/utils/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"constants.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/utils/eventSubscriptionUtils.js

@@ -3,26 +3,70 @@
 var ESPDiscoveryManager = require('../services/ESPTransport/ESPDiscovery/ESPDiscoveryManager.js');
 var NodeUpdatesBus = require('../services/NodeUpdatesBus.js');
 var transport = require('../types/transport.js');
+var constants = require('./constants.js');
 
 /*
  * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-/** Maps a default local-discovery hit into the client-facing payload shape. */
+/**
+ * Splits the mDNS `cap` TXT record (`"local_ctrl,ch_resp"`) into tokens.
+ * Returns `undefined` when the record is absent, which older firmware omits.
+ */
+function parseCapabilities(txt) {
+    const raw = txt?.[constants.RMakerLocalCtrlTxtKey.CAP];
+    if (typeof raw !== "string")
+        return undefined;
+    const capabilities = raw
+        .split(",")
+        .map((capability) => capability.trim())
+        .filter(Boolean);
+    return capabilities.length ? capabilities : undefined;
+}
+/**
+ * Maps a default local-discovery hit into the client-facing payload shape.
+ *
+ * The `_esp_rmaker_ctrl._tcp` instance is also advertised by nodes that
+ * only serve challenge-response (on-network user-node association). Those are
+ * not reachable for param control, so a hit whose `cap` TXT record excludes
+ * `local_ctrl` maps to `undefined` and is dropped rather than registered as a
+ * local transport. A hit with no `cap` record is treated as control-capable.
+ *
+ * @param info - Raw adapter result (`nodeId`, `baseUrl`, and `txt` when the
+ *   platform resolved TXT records).
+ * @returns The payload to deliver, or `undefined` to skip this hit.
+ */
 function toDiscoveredNodeData(info) {
+    const capabilities = parseCapabilities(info.txt);
+    if (capabilities &&
+        !capabilities.includes(constants.RMakerLocalCtrlCapability.LOCAL_CTRL)) {
+        return undefined;
+    }
     return {
         nodeId: info.nodeId,
         transportDetails: {
             type: transport.ESPTransportMode.local,
-            metadata: { baseUrl: info.baseUrl },
+            metadata: {
+                baseUrl: info.baseUrl,
+                protocol: transport.ESPLocalControlProtocol.rmakerLocalCtrl,
+                ...(capabilities && { capabilities }),
+            },
         },
     };
 }
-/** Starts LAN discovery; each hit is mapped then passed to `onDiscovered`. */
+/**
+ * Starts LAN discovery; each hit is mapped then passed to `onDiscovered`.
+ * Hits that are not control-capable (see {@link toDiscoveredNodeData}) are
+ * skipped.
+ */
 function startLocalDiscovery(onDiscovered) {
     const manager = new ESPDiscoveryManager.ESPDiscoveryManager();
-    manager.startDiscovery((info) => onDiscovered(toDiscoveredNodeData(info)));
+    manager.startDiscovery((info) => {
+        const data = toDiscoveredNodeData(info);
+        if (data)
+            onDiscovered(data);
+    });
     return { stop: () => manager.stopDiscovery() };
 }
 /** Forwards process-wide node param updates to `onUpdate`. */

package/dist/cjs/utils/eventSubscriptionUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"eventSubscriptionUtils.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"eventSubscriptionUtils.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/utils/nodeUtils.js

@@ -28,7 +28,18 @@ async function readLocalNodeConfig(nodeId) {
 /** Best-effort persist of node config to local storage. */
 async function writeLocalNodeConfig(nodeId, config) {
     try {
-        await ESPRMNeoStorage.ESPRMNeoStorage.setNodeConfig(nodeId, config);
+        let toStore = config;
+        // Cloud config omits connectivity — keep the last cached status when writing.
+        if (!config.connectivity_status) {
+            const prev = await ESPRMNeoStorage.ESPRMNeoStorage.getNodeConfig(nodeId);
+            if (prev?.connectivity_status) {
+                toStore = {
+                    ...config,
+                    connectivity_status: prev.connectivity_status,
+                };
+            }
+        }
+        await ESPRMNeoStorage.ESPRMNeoStorage.setNodeConfig(nodeId, toStore);
     }
     catch (error) {
         logger.warn(`Cache write failed for ${nodeId}`, error);

package/dist/cjs/utils/nodeUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"nodeUtils.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"nodeUtils.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/utils/waitForNodeOnline.js

@@ -65,11 +65,12 @@ function isNodeOnlineFromShadowPayload(payload) {
  * @throws {ESPProvError} If `timeoutMs` elapses without the node reporting online.
  * @throws {Error} If MQTT connection or subscription fails.
  */
-async function waitForNodeOnline({ nodeId, groupId, user, timeoutMs = DEFAULT_NODE_ONLINE_TIMEOUT_MS, pollIntervalMs = DEFAULT_NODE_ONLINE_POLL_INTERVAL_MS, }) {
-    const shadowName = shadowUtils.constructShadowName(groupId);
+async function waitForNodeOnline({ nodeId, groupId, subgroupIds, user, timeoutMs = DEFAULT_NODE_ONLINE_TIMEOUT_MS, pollIntervalMs = DEFAULT_NODE_ONLINE_POLL_INTERVAL_MS, }) {
+    const shadowName = shadowUtils.constructShadowName(groupId, subgroupIds ?? []);
     logger.info("Waiting for node to come online", {
         nodeId,
         groupId,
+        subgroupIds: subgroupIds ?? [],
         shadowName,
         timeoutMs,
         pollIntervalMs,
@@ -149,10 +150,10 @@ async function waitForNodeOnline({ nodeId, groupId, user, timeoutMs = DEFAULT_NO
             });
             await user.connectMQTT();
         }
-        // 2. Register (if needed) and subscribe before the shadow may exist
-        if (!alreadyRegistered) {
-            NodeMQTTOrchestrator.NodeMQTTOrchestrator.registerNode(nodeId, shadowName);
-        }
+        // 2. Bind to the membership shadow and subscribe before the shadow may exist.
+        // Always registerNode so a leftover longer/stale binding for the same nodeId
+        // is rebound to constructShadowName(groupId, subgroupIds).
+        NodeMQTTOrchestrator.NodeMQTTOrchestrator.registerNode(nodeId, shadowName);
         await NodeMQTTOrchestrator.NodeMQTTOrchestrator.subscribeToNode(nodeId, onUpdate);
         logger.debug("Subscribed to node shadow for online wait", {
             nodeId,

package/dist/cjs/utils/waitForNodeOnline.js.map

@@ -1 +1 @@
-{"version":3,"file":"waitForNodeOnline.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"waitForNodeOnline.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/ESPDevice.js

@@ -22,6 +22,12 @@ class ESPDevice {
     name;
     transport;
     security;
+    /**
+     * What a completed association produced, kept so `retryNetworkCredentials`
+     * can resume the flow instead of repeating it. Set once verification
+     * succeeds; `undefined` until then.
+     */
+    provisionResumeState;
     constructor(deviceConfig) {
         this.name = deviceConfig.name;
         this.transport = deviceConfig.transport;

package/dist/esm/ESPDevice.js.map

@@ -1 +1 @@
-{"version":3,"file":"ESPDevice.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"ESPDevice.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/ESPRMNeoBase.js

@@ -183,7 +183,7 @@ class ESPRMNeoBase {
     }
     /**
      * Sets the local control adapter used to talk to nodes over the LAN via
-     * the `esp_local_ctrl` protocol.
+     * the `rmaker_local_ctrl` protocol.
      *
      * @param adapter - Adapter implementing {@link ESPLocalControlAdapterInterface}.
      * @throws {Error} If the SDK is not initialized or the adapter is invalid.

package/dist/esm/ESPRMNeoNode.js

@@ -38,14 +38,19 @@ class ESPRMNeoNode {
     subgroupIds = [];
     devices = [];
     services = [];
+    /**
+     * Last-known connectivity. Seeded from cached `connectivity_status` when
+     * present (cloud config does not provide it); otherwise starts offline until
+     * an MQTT shadow `online` update arrives.
+     */
     connectivityStatus = {
         isConnected: false,
         lastConnectionTimestamp: 0,
     };
     /**
      * Transports currently usable for this node, keyed by mode.
-     * - `mqtt` (cloud) is added when the node reports online and removed when
-     *   it goes offline (via shadow updates or seeded `connectivity_status`).
+     * - `mqtt` (cloud) is added when the node is connected and removed when it
+     *   goes offline (from cached `connectivity_status` or shadow updates).
      * - `local` is added/removed at runtime by a `localDiscovery` subscriber as the
      *   node appears/disappears on the LAN (via {@link addTransport}/{@link removeTransport}).
      * Apps may also add custom string-keyed entries (pair with
@@ -78,16 +83,11 @@ class ESPRMNeoNode {
         this.subgroupIds = asStringArray(subgroupIdOrIds);
         this.transportOrder = ESPRMNeoBase.getTransportOrder();
         this.availableTransports = {};
-        this.applyNodeConfig(config);
         if (config.connectivity_status) {
             this.connectivityStatus = config.connectivity_status;
         }
-        if (this.connectivityStatus.isConnected) {
-            this.addTransport(ESPTransportMode.mqtt, {
-                type: ESPTransportMode.mqtt,
-                metadata: {},
-            });
-        }
+        this.applyNodeConfig(config);
+        this.syncMqttTransportAvailability();
         this.subscribeToMqttUpdates();
     }
     /**
@@ -167,11 +167,14 @@ class ESPRMNeoNode {
         this.devices = deviceRecords.map((d) => new ESPRMNeoDevice(transformNodeDevice(d), nodeRef));
         this.services = serviceRecords.map((s) => new ESPRMNeoService(transformNodeService(s), nodeRef));
         // Keep wire records for cache writes (never persist live class instances).
+        // Preserve last-known connectivity when the incoming config omits it
+        // (cloud node config does not include connectivity_status).
         this.wireConfig = {
             ...config,
             info,
             devices: deviceRecords,
             services: serviceRecords,
+            connectivity_status: config.connectivity_status ?? this.connectivityStatus,
         };
         this.config = {
             ...config,
@@ -241,19 +244,27 @@ class ESPRMNeoNode {
             this.wireConfig.params = this.config.params;
         }
         this.applyConnectivityStatus(shadow, connectivityStatus);
-        ESPRMNeoStorage.setItem(StorageKeys.NODE_CONFIG_PREFIX + this.nodeId, JSON.stringify({ ...this.wireConfig, node_id: this.nodeId }));
+        this.persistWireConfig();
         this.refreshConfigIfNcfgChanged(shadow);
     }
     /**
-     * Updates {@link connectivityStatus} and MQTT transport availability when the
-     * shadow reports `online`. Partial updates without `online` are ignored so
-     * an existing status is not cleared.
+     * Updates {@link connectivityStatus} when the shadow reports `online`, then
+     * syncs MQTT transport availability. Partial updates without `online` are
+     * ignored so an existing status is not cleared.
      */
     applyConnectivityStatus(shadow, connectivityStatus) {
         if (shadow.state?.reported?.online === undefined)
             return;
         this.connectivityStatus = connectivityStatus;
-        if (connectivityStatus.isConnected) {
+        this.wireConfig.connectivity_status = connectivityStatus;
+        this.syncMqttTransportAvailability();
+    }
+    /**
+     * Registers the MQTT transport only while {@link connectivityStatus} reports
+     * the node as connected; removes it when offline.
+     */
+    syncMqttTransportAvailability() {
+        if (this.connectivityStatus.isConnected) {
             this.addTransport(ESPTransportMode.mqtt, {
                 type: ESPTransportMode.mqtt,
                 metadata: {},
@@ -263,6 +274,14 @@ class ESPRMNeoNode {
             this.removeTransport(ESPTransportMode.mqtt);
         }
     }
+    /** Persists {@link wireConfig} (including last-known connectivity) to storage. */
+    persistWireConfig() {
+        ESPRMNeoStorage.setItem(StorageKeys.NODE_CONFIG_PREFIX + this.nodeId, JSON.stringify({
+            ...this.wireConfig,
+            node_id: this.nodeId,
+            connectivity_status: this.connectivityStatus,
+        }));
+    }
     /** When cloud `ncfg_ver` changes, refetch config and persist the new marker. */
     async refreshConfigIfNcfgChanged(shadow) {
         try {

package/dist/esm/ESPRMNeoNode.js.map

@@ -1 +1 @@
-{"version":3,"file":"ESPRMNeoNode.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"ESPRMNeoNode.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/index.js

@@ -15,7 +15,7 @@ export { ESPDevice } from './ESPDevice.js';
 export { ESPDiscoveryProtocol, ESPRMNeoEventType } from './types/discovery.js';
 export { ESPClaimStatus, ESPConnectStatus, ESPProvResponseStatus, ESPProvisionStatus, ESPSecurity, ESPTransport } from './types/provision.js';
 export { resolveNodeId } from './types/subscription.js';
-export { DEFAULT_TRANSPORT_ORDER, ESPTransportMode } from './types/transport.js';
+export { DEFAULT_LOCAL_CONTROL_PROTOCOL, DEFAULT_TRANSPORT_ORDER, ESPLocalControlProtocol, ESPTransportMode } from './types/transport.js';
 import './methods/ESPRMNeoAuth/ChangePassword.js';
 import './methods/ESPRMNeoAuth/ConfirmSignUp.js';
 import './methods/ESPRMNeoAuth/ForgotPassword.js';
@@ -102,6 +102,8 @@ import './methods/ESPDevice/SetProofOfPossession.js';
 import './methods/ESPDevice/SendData.js';
 import './methods/ESPDevice/InitializeSession.js';
 import './methods/ESPDevice/SetNetworkCredentials.js';
+import './methods/ESPDevice/ResetWifiStatus.js';
+import './methods/ESPDevice/RetryNetworkCredentials.js';
 import './methods/ESPDevice/InitiateUserNodeMapping.js';
 import './methods/ESPDevice/VerifyUserNodeMapping.js';
 import './methods/ESPDevice/StartAssistedClaiming.js';
@@ -109,7 +111,7 @@ export { buildGroupControlParamsTopic, buildRainMakerUserParamsTopic, buildShado
 export { coerceToFiniteNumber, coerceToNonEmptyString, coerceToString } from './utils/coerce.js';
 export { buildCanonicalQueryString, createAuthorizationHeader, generateIotDeviceGatewayMqttSignedUrl, generateSigV4AuthHeader } from './utils/awsSigv4Utils.js';
 export { buildMainApiUrl, buildUserCredentialsUrl, ensureValidIdToken, extractTemporaryCredentials, isExpiredTokenAuthError, parseCredentialsErrorMessage, postUserCredentials, refreshUserSession } from './utils/awsUtils.js';
-export { APICallValidationErrorCodes, APIEndpoints, APIOperations, APIPathV1, AWSCredentialsErrorMessages, AuthErrorCodes, AuthSuccessMessages, AutomationStatusValues, AutomationSuccessMessages, CLAIM_CSR_MAX_CHUNKS, CLAIM_DEVICE_CSR_KEYS, CLAIM_DEVICE_MAC_KEYS, CLAIM_MAC_HEX_LENGTHS, CLAIM_MAC_SEPARATORS, CLAIM_MAX_FRAGMENT_SIZE, ClaimCapabilities, ClaimCapabilityPolicies, ClaimEndpoints, ClaimErrorCodes, ClaimProgressMessages, ConfigErrorCodes, DEFAULT_REST_API_VERSION, ESPProvProgressMessages, ESPRMNeoErrorCodes, ESPRMNeoStorageKeys, ESPServiceParamType, ESPServiceType, Endpoint, ErrorLabels, GroupSuccessMessages, GroupUserAliases, HTTPMethods, IntegrationSuccessMessages, NodeSuccessMessages, NodeWarnMessages, ProtocolType, ProvErrorCodes, ProvisionType, SDK_VERSION, ScheduleErrorMessages, ScheduleSuccessMessages, ServiceType, SharingSuccessMessages, StatusMessage, StorageAdapterErrorCodes, StorageKeys, SubscriptionChannelIds, TokenErrorCodes, TriggerErrorMessages, TriggerSuccessMessages, ValidationErrorCodes } from './utils/constants.js';
+export { APICallValidationErrorCodes, APIEndpoints, APIOperations, APIPathV1, AWSCredentialsErrorMessages, AssumeRoleErrorMessages, AuthErrorCodes, AuthSuccessMessages, AutomationStatusValues, AutomationSuccessMessages, CLAIM_CSR_MAX_CHUNKS, CLAIM_DEVICE_CSR_KEYS, CLAIM_DEVICE_MAC_KEYS, CLAIM_MAC_HEX_LENGTHS, CLAIM_MAC_SEPARATORS, CLAIM_MAX_FRAGMENT_SIZE, ClaimCapabilities, ClaimCapabilityPolicies, ClaimEndpoints, ClaimErrorCodes, ClaimProgressMessages, ConfigErrorCodes, DEFAULT_REST_API_VERSION, ESPProvProgressMessages, ESPRMNeoErrorCodes, ESPRMNeoStorageKeys, ESPServiceParamType, ESPServiceType, Endpoint, ErrorLabels, GroupSuccessMessages, GroupUserAliases, HTTPMethods, IntegrationSuccessMessages, NodeSuccessMessages, NodeWarnMessages, ProtocolType, ProvErrorCodes, ProvisionType, RMAKER_LOCAL_CTRL_FRAGMENT_SIZE, RMAKER_LOCAL_CTRL_VERSION_KEY, RMakerLocalCtrlCapability, RMakerLocalCtrlEndpoint, RMakerLocalCtrlSetParamsStatus, RMakerLocalCtrlTxtKey, SDK_VERSION, ScheduleErrorMessages, ScheduleSuccessMessages, ServiceType, SharingSuccessMessages, StatusMessage, StorageAdapterErrorCodes, StorageKeys, SubscriptionChannelIds, TokenErrorCodes, TriggerErrorMessages, TriggerSuccessMessages, ValidationErrorCodes } from './utils/constants.js';
 export { LogLevel, Logger } from './utils/logger.js';
 export { concurrentFetchPool } from './utils/mapLimit.js';
 export { EventEmitter } from './utils/eventEmitter.js';

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/methods/ESPDevice/Provision.js

@@ -65,6 +65,13 @@ async function runChallengeResponseFlow(device, ssid, passphrase, groupId, onPro
         challenge_response: signedChallenge,
         node_id: nodeId,
     });
+    // Association is verified and cannot be repeated; remember what step 6 needs
+    // so `retryNetworkCredentials` can resume from the Wi-Fi step.
+    device.provisionResumeState = {
+        nodeId: nodeId,
+        groupId,
+        options: options,
+    };
     // 5. SET NETWORK CREDENTIALS
     reportProgress(onProgress, ESPProvResponseStatus.onProgress, ESPProvProgressMessages.SETTING_NETWORK_CREDENTIALS);
     await device.setNetworkCredentials(ssid, passphrase);

package/dist/esm/methods/ESPDevice/Provision.js.map

@@ -1 +1 @@
-{"version":3,"file":"Provision.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"Provision.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/methods/ESPDevice/ResetWifiStatus.js

@@ -0,0 +1,24 @@
+import { ESPDevice } from '../../ESPDevice.js';
+import { Logger } from '../../utils/logger.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new Logger("ResetWifiStatus");
+ESPDevice.prototype.resetWifiStatus = async function () {
+    if (!this.ESPProvisionAdapter.resetWifiStatus) {
+        logger.warn(`Adapter has no resetWifiStatus; treating as not acknowledged for "${this.name}"`);
+        return false;
+    }
+    try {
+        const acknowledged = await this.ESPProvisionAdapter.resetWifiStatus(this.name);
+        return acknowledged;
+    }
+    catch (error) {
+        logger.error(`<- device "${this.name}": reset failed`, error);
+        throw error;
+    }
+};
+//# sourceMappingURL=ResetWifiStatus.js.map

package/dist/esm/methods/ESPDevice/ResetWifiStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResetWifiStatus.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;"}