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

package/dist/esm/services/ESPTransport/ESPLocalControlTransport.js

@@ -1,154 +1,221 @@
-import { ESPRMNeoBase } from '../../ESPRMNeoBase.js';
-import { Status } from '../../proto/constants.js';
-import { LocalCtrlMessage, LocalCtrlMsgType, CmdSetPropertyValues, PropertyValue, CmdGetPropertyCount, CmdGetPropertyValues } from '../../proto/esp_local_ctrl.js';
-import { Endpoint } from '../../utils/constants.js';
+import { RMakerLocalCtrlDataType, RMakerLocalCtrlProtoHelper } from '../../proto/rmaker_local_ctrl.js';
+import { ESPLocalControlProtocol } from '../../types/transport.js';
+import { RMakerLocalCtrlEndpoint, RMakerLocalCtrlSetParamsStatus, RMAKER_LOCAL_CTRL_VERSION_KEY } from '../../utils/constants.js';
 import { uint8ArrayToBase64, base64ToUint8Array } from '../ESPRMNeoHelpers/TransformEncoding.js';
+import { getLocalControlAdapter, ensureLocalControlSession } from './LocalControlSession.js';
 
 /*
  * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-/** Property index of the writable "params" property exposed by RMNeo local-control firmware. */
-const LOCAL_CONTROL_PARAMS_INDEX = 1;
 /**
- * Built-in `local` transport. Communicates with the node over the LAN through
- * the app-supplied {@link ESPRMNeoBase.ESPLocalControlAdapter} using the
- * `esp_local_ctrl` protobuf protocol. Connection metadata (`baseUrl`,
- * `securityType`, `pop`, and `username` for sec2) is supplied via the transport
- * config by {@link delegatedTransportHandler}.
+ * Tail of the in-flight fragmented-read chain, per node id.
+ *
+ * Module-level on purpose: {@link delegatedTransportHandler} builds a fresh
+ * transport for every call, so a queue held on the instance would serialize
+ * nothing. Keyed by node, because the transfer cache is per device.
+ */
+const nodeReadQueues = new Map();
+/**
+ * Runs `read` after every fragmented read already queued for `nodeId`.
+ *
+ * A failed read must not wedge the queue, so the chain advances on rejection
+ * too, while the caller still sees the original rejection. The map entry is
+ * dropped once the chain drains, so a long-lived app doesn't retain one promise
+ * per node it has ever talked to.
+ *
+ * @param nodeId - Node whose reads are being serialized.
+ * @param read - Pull loop to run once the node is free.
+ */
+function enqueueNodeRead(nodeId, read) {
+    const previous = nodeReadQueues.get(nodeId) ?? Promise.resolve();
+    const result = previous.then(read, read);
+    const tail = result.then(() => undefined, () => undefined);
+    nodeReadQueues.set(nodeId, tail);
+    void tail.then(() => {
+        // Only the current tail clears the entry; otherwise a newer read owns it.
+        if (nodeReadQueues.get(nodeId) === tail) {
+            nodeReadQueues.delete(nodeId);
+        }
+    });
+    return result;
+}
+/** Session endpoints of the `rmaker_local_ctrl` protocol, passed to the adapter. */
+const RMAKER_SESSION_OPTIONS = {
+    protocol: ESPLocalControlProtocol.rmakerLocalCtrl,
+    sessionPath: RMakerLocalCtrlEndpoint.SESSION,
+    versionPath: RMakerLocalCtrlEndpoint.VERSION,
+    versionKey: RMAKER_LOCAL_CTRL_VERSION_KEY,
+};
+/**
+ * The built-in `local` transport, speaking the `rmaker_local_ctrl` endpoint
+ * protocol over the app-supplied {@link ESPRMNeoBase.ESPLocalControlAdapter}:
+ *
+ * - `set_params` carries the same raw JSON body as a cloud set-params call and
+ *   answers `{"status":"success"}` / `{"status":"fail","description":…}`.
+ * - `get_params` / `get_config` exchange protobuf `CmdGetData`/`RespGetData` and
+ *   are fragmented — the client pulls fixed-size chunks by offset until
+ *   `TotalLen` is covered.
+ *
+ * Connection metadata (`baseUrl`, `securityType`, `pop`, and `username` for
+ * sec2) is supplied via the transport config by {@link
+ * delegatedTransportHandler}; security 0 is not offered by this protocol.
  */
 class ESPLocalControlTransport {
-    payload;
     metadata;
-    propertyInfo = {};
     constructor(transportConfig) {
         this.metadata = transportConfig.metadata ?? {};
     }
     get adapter() {
-        const adapter = ESPRMNeoBase.getLocalControlAdapter();
-        if (!adapter) {
-            throw new Error("Local control adapter is not configured");
-        }
-        return adapter;
-    }
-    /**
-     * Connects to the node, retrying on failure. RMNeo's adapter resolves on a
-     * successful connection and rejects otherwise, so a resolved call is treated
-     * as connected.
-     */
-    async connectWithRetry(nodeId, baseUrl, securityType, pop, username, maxRetries = 3) {
-        let attempt = 0;
-        let lastError;
-        while (attempt < maxRetries) {
-            try {
-                await this.adapter.connect(nodeId, baseUrl, securityType, pop, username);
-                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}`);
+        return getLocalControlAdapter();
     }
     async ensureConnected(nodeId) {
-        const isConnected = await this.adapter.isConnected(nodeId);
-        if (!isConnected) {
-            await this.connectWithRetry(nodeId, this.metadata.baseUrl, this.metadata.securityType ?? 0, this.metadata.pop, this.metadata.username);
-        }
+        await ensureLocalControlSession(this.adapter, nodeId, this.metadata, RMAKER_SESSION_OPTIONS);
     }
+    /**
+     * Applies params over `set_params`.
+     *
+     * @param payload - `{ node_id, payload }`, where `payload` is the
+     *   `{ <deviceOrServiceName>: { <paramName>: value } }` map to write.
+     * @throws {Error} When the device reports a non-success status.
+     */
     async setParam(payload, _nodeRef) {
-        this.payload = payload;
-        await this.ensureConnected(this.payload?.node_id);
-        const success = await this.setProperty(this.payload?.payload ?? {});
-        if (!success) {
-            throw new Error("Failed to set device params over local control");
-        }
+        const nodeId = payload?.node_id;
+        await this.ensureConnected(nodeId);
+        const request = uint8ArrayToBase64(new TextEncoder().encode(JSON.stringify(payload?.payload ?? {})));
+        const response = await this.adapter.sendData(nodeId, RMakerLocalCtrlEndpoint.SET_PARAMS, request);
+        this.assertSetParamsAccepted(response);
         return { message: "Parameters updated successfully", statusCode: 200 };
     }
+    /**
+     * Reads the node's full params document over `get_params`.
+     *
+     * @param payload - `{ node_id }` identifying the node to read.
+     * @returns The params JSON, keyed by device/service name.
+     */
     async getParams(payload, _nodeRef) {
-        this.payload = payload;
-        await this.ensureConnected(this.payload?.node_id);
-        return this.getPropertyInfo();
+        const nodeId = payload?.node_id;
+        await this.ensureConnected(nodeId);
+        return this.readJsonDocument(nodeId, RMakerLocalCtrlDataType.TypeParams, RMakerLocalCtrlEndpoint.GET_PARAMS);
     }
-    // ── set ──────────────────────────────────────────────────────────────────
-    async setProperty(json) {
-        const request = this.buildSetPropertyRequest(json);
-        const response = await this.adapter.sendData(this.payload?.node_id, Endpoint.LOCAL_CTRL, request);
-        return this.processSetPropertyResponse(response);
-    }
-    buildSetPropertyRequest(json) {
-        const message = new LocalCtrlMessage();
-        message.msg = LocalCtrlMsgType.TypeCmdSetPropertyValues;
-        const cmd = new CmdSetPropertyValues();
-        const prop = new PropertyValue();
-        prop.index = LOCAL_CONTROL_PARAMS_INDEX;
-        prop.value = new TextEncoder().encode(JSON.stringify(json ?? {}));
-        cmd.props.push(prop);
-        message.cmd_set_prop_vals = cmd;
-        return uint8ArrayToBase64(message.serialize());
-    }
-    processSetPropertyResponse(response) {
-        const deserialized = LocalCtrlMessage.deserialize(base64ToUint8Array(response));
-        return deserialized.resp_set_prop_vals.status === Status.Success;
+    /**
+     * Reads the node's config document over `get_config`. Not part of
+     * {@link ESPTransportInterface} — the node config normally comes from the
+     * cloud; this serves LAN-only flows.
+     *
+     * @param nodeId - Node to read from.
+     * @returns The node config JSON.
+     */
+    async getConfig(nodeId) {
+        await this.ensureConnected(nodeId);
+        return this.readJsonDocument(nodeId, RMakerLocalCtrlDataType.TypeConfig, RMakerLocalCtrlEndpoint.GET_CONFIG);
     }
-    // ── get ──────────────────────────────────────────────────────────────────
-    /** Fetches the property count, then reads each property value into propertyInfo. */
-    async getPropertyInfo() {
-        this.propertyInfo = {};
-        const count = await this.fetchPropertyCount();
-        for (let index = 0; index < count; index++) {
-            await this.fetchPropertyValue(index);
+    // ── set ──────────────────────────────────────────────────────────────────
+    /**
+     * Validates a `set_params` raw-JSON response.
+     *
+     * @throws {Error} When the body is unparseable or reports a failure.
+     */
+    assertSetParamsAccepted(response) {
+        const text = new TextDecoder().decode(base64ToUint8Array(response ?? ""));
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
         }
-        return this.propertyInfo;
-    }
-    async fetchPropertyCount() {
-        const response = await this.adapter.sendData(this.payload?.node_id, Endpoint.LOCAL_CTRL, this.buildGetPropertyCountRequest());
-        return this.processGetPropertyCountResponse(response);
-    }
-    buildGetPropertyCountRequest() {
-        const request = new LocalCtrlMessage();
-        request.msg = LocalCtrlMsgType.TypeCmdGetPropertyCount;
-        request.cmd_get_prop_count = new CmdGetPropertyCount();
-        return uint8ArrayToBase64(request.serialize());
-    }
-    processGetPropertyCountResponse(response) {
-        const deserialized = LocalCtrlMessage.deserialize(base64ToUint8Array(response));
-        if (deserialized.resp_get_prop_count.status !== Status.Success) {
-            throw new Error("Failed to retrieve property count from device");
+        catch {
+            throw new Error(`Unexpected set_params response from device: ${text || "<empty>"}`);
+        }
+        if (parsed?.status !== RMakerLocalCtrlSetParamsStatus.SUCCESS) {
+            throw new Error(parsed?.description ??
+                "Failed to set device params over local control (rmaker_local_ctrl)");
         }
-        return deserialized.resp_get_prop_count.count;
     }
-    async fetchPropertyValue(index) {
-        const response = await this.adapter.sendData(this.payload?.node_id, Endpoint.LOCAL_CTRL, this.buildGetPropertyValueRequest(index));
-        const property = this.processGetPropertyValueResponse(response);
-        if (property) {
-            this.propertyInfo[property.name] = property.value;
+    // ── get ──────────────────────────────────────────────────────────────────
+    /**
+     * Pulls a fragmented document and parses it as JSON, serialized against every
+     * other fragmented read of the same node.
+     *
+     * The device holds **one global transfer cache**, not one per session: an
+     * offset-0 request regenerates it and it is freed after the last fragment. So
+     * a `getParams()` racing a `getConfig()` on the same node would clobber the
+     * other — the second offset-0 regenerates the cache mid-transfer, and the
+     * first read's next fragment comes back `Fail` (or, worse, carries bytes from
+     * the wrong document). The queue makes that interleaving impossible rather
+     * than detecting it after the fact.
+     *
+     * @param nodeId - Node to read from.
+     * @param dataType - Which document to read (params or config).
+     * @param endpoint - Endpoint serving that document.
+     * @throws {Error} When the device reports a failure, the response is
+     *   malformed, or a fragment makes no forward progress.
+     */
+    readJsonDocument(nodeId, dataType, endpoint) {
+        return enqueueNodeRead(nodeId, () => this.pullJsonDocument(nodeId, dataType, endpoint));
+    }
+    /** The client-pull loop itself; always reached via {@link readJsonDocument}. */
+    async pullJsonDocument(nodeId, dataType, endpoint) {
+        const fragments = [];
+        let offset = 0;
+        let totalLength = 0;
+        do {
+            const response = await this.adapter.sendData(nodeId, endpoint, this.buildGetDataRequest(dataType, offset));
+            const buf = this.processGetDataResponse(response, offset);
+            totalLength = buf.totalLength;
+            if (totalLength === 0) {
+                return {};
+            }
+            if (buf.payload.length === 0) {
+                // Without forward progress the pull loop would never terminate.
+                throw new Error(`Device returned an empty fragment at offset ${offset} of ${totalLength} on ${endpoint}`);
+            }
+            fragments.push(buf.payload);
+            offset += buf.payload.length;
+        } while (offset < totalLength);
+        if (offset > totalLength) {
+            throw new Error(`Fragmented read of ${endpoint} overran: got ${offset} bytes, expected ${totalLength}`);
         }
+        return this.parseJsonFragments(fragments, endpoint);
     }
-    buildGetPropertyValueRequest(index) {
-        const request = new LocalCtrlMessage();
-        request.msg = LocalCtrlMsgType.TypeCmdGetPropertyValues;
-        const cmd = new CmdGetPropertyValues();
-        cmd.indices.push(index);
-        request.cmd_get_prop_vals = cmd;
-        return uint8ArrayToBase64(request.serialize());
+    buildGetDataRequest(dataType, offset) {
+        return uint8ArrayToBase64(RMakerLocalCtrlProtoHelper.createGetDataRequest(dataType, offset));
     }
-    processGetPropertyValueResponse(response) {
-        const deserialized = LocalCtrlMessage.deserialize(base64ToUint8Array(response));
-        if (deserialized.resp_get_prop_vals.status !== Status.Success) {
-            throw new Error("Failed to get property values from device response");
+    /**
+     * Parses one `RespGetData` and checks it answers the requested offset.
+     *
+     * @param response - Base64 protobuf response from the adapter.
+     * @param requestedOffset - Offset asked for, used to detect a desynced pull.
+     */
+    processGetDataResponse(response, requestedOffset) {
+        const parsed = RMakerLocalCtrlProtoHelper.parseGetDataResponse(base64ToUint8Array(response));
+        if (!RMakerLocalCtrlProtoHelper.isSuccess(parsed)) {
+            throw new Error(`Device rejected the local-control read (status ${RMakerLocalCtrlProtoHelper.getStatus(parsed)})`);
+        }
+        const fragmentOffset = RMakerLocalCtrlProtoHelper.getOffset(parsed);
+        if (fragmentOffset !== requestedOffset) {
+            throw new Error(`Device answered offset ${fragmentOffset}, expected ${requestedOffset}`);
         }
-        const prop = deserialized.resp_get_prop_vals.props[0];
-        if (!prop)
-            return undefined;
         return {
-            name: prop.name || "unknown",
-            value: JSON.parse(new TextDecoder().decode(prop.value)),
+            payload: RMakerLocalCtrlProtoHelper.getPayload(parsed),
+            totalLength: RMakerLocalCtrlProtoHelper.getTotalLen(parsed),
         };
     }
+    /** Joins the pulled fragments and parses the result as JSON. */
+    parseJsonFragments(fragments, endpoint) {
+        const joined = new Uint8Array(fragments.reduce((length, fragment) => length + fragment.length, 0));
+        let position = 0;
+        for (const fragment of fragments) {
+            joined.set(fragment, position);
+            position += fragment.length;
+        }
+        const text = new TextDecoder().decode(joined);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Device returned malformed JSON on ${endpoint}`);
+        }
+    }
 }
 
 export { ESPLocalControlTransport };

package/dist/esm/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/esm/services/ESPTransport/LocalControlSession.js

@@ -0,0 +1,59 @@
+import { ESPRMNeoBase } from '../../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.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}`);
+}
+
+export { ensureLocalControlSession, getLocalControlAdapter };
+//# sourceMappingURL=LocalControlSession.js.map

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

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

package/dist/esm/services/NodeMQTTOrchestrator.js

@@ -139,8 +139,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`).
@@ -149,9 +149,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/esm/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/esm/types/transport.js

@@ -17,6 +17,29 @@ var ESPTransportMode;
     /** Communication is routed through MQTT (RainMaker Neo cloud: AWS shadow). */
     ESPTransportMode["mqtt"] = "mqtt";
 })(ESPTransportMode || (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.
+ */
+var ESPLocalControlProtocol;
+(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";
+})(ESPLocalControlProtocol || (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 = 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.
@@ -26,5 +49,5 @@ const DEFAULT_TRANSPORT_ORDER = [
     ESPTransportMode.mqtt,
 ];
 
-export { DEFAULT_TRANSPORT_ORDER, ESPTransportMode };
+export { DEFAULT_LOCAL_CONTROL_PROTOCOL, DEFAULT_TRANSPORT_ORDER, ESPLocalControlProtocol, ESPTransportMode };
 //# sourceMappingURL=transport.js.map

package/dist/esm/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/esm/utils/constants.js

@@ -391,6 +391,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).
  */
@@ -464,8 +473,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. */
@@ -473,6 +480,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.
@@ -630,8 +695,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.
@@ -840,5 +909,5 @@ const SubscriptionChannelIds = {
     MQTT: "mqtt",
 };
 
-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 };
+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 };
 //# sourceMappingURL=constants.js.map

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

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