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

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

@@ -1,156 +1,223 @@
 'use strict';
 
-var ESPRMNeoBase = require('../../ESPRMNeoBase.js');
-var constants$1 = require('../../proto/constants.js');
-var esp_local_ctrl = require('../../proto/esp_local_ctrl.js');
+var rmaker_local_ctrl = require('../../proto/rmaker_local_ctrl.js');
+var transport = require('../../types/transport.js');
 var constants = require('../../utils/constants.js');
 var TransformEncoding = require('../ESPRMNeoHelpers/TransformEncoding.js');
+var LocalControlSession = require('./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: transport.ESPLocalControlProtocol.rmakerLocalCtrl,
+    sessionPath: constants.RMakerLocalCtrlEndpoint.SESSION,
+    versionPath: constants.RMakerLocalCtrlEndpoint.VERSION,
+    versionKey: constants.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.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 LocalControlSession.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 LocalControlSession.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 = TransformEncoding.uint8ArrayToBase64(new TextEncoder().encode(JSON.stringify(payload?.payload ?? {})));
+        const response = await this.adapter.sendData(nodeId, constants.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, rmaker_local_ctrl.RMakerLocalCtrlDataType.TypeParams, constants.RMakerLocalCtrlEndpoint.GET_PARAMS);
     }
-    // ── set ──────────────────────────────────────────────────────────────────
-    async setProperty(json) {
-        const request = this.buildSetPropertyRequest(json);
-        const response = await this.adapter.sendData(this.payload?.node_id, constants.Endpoint.LOCAL_CTRL, request);
-        return this.processSetPropertyResponse(response);
-    }
-    buildSetPropertyRequest(json) {
-        const message = new esp_local_ctrl.LocalCtrlMessage();
-        message.msg = esp_local_ctrl.LocalCtrlMsgType.TypeCmdSetPropertyValues;
-        const cmd = new esp_local_ctrl.CmdSetPropertyValues();
-        const prop = new esp_local_ctrl.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 TransformEncoding.uint8ArrayToBase64(message.serialize());
-    }
-    processSetPropertyResponse(response) {
-        const deserialized = esp_local_ctrl.LocalCtrlMessage.deserialize(TransformEncoding.base64ToUint8Array(response));
-        return deserialized.resp_set_prop_vals.status === constants$1.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, rmaker_local_ctrl.RMakerLocalCtrlDataType.TypeConfig, constants.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(TransformEncoding.base64ToUint8Array(response ?? ""));
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
         }
-        return this.propertyInfo;
-    }
-    async fetchPropertyCount() {
-        const response = await this.adapter.sendData(this.payload?.node_id, constants.Endpoint.LOCAL_CTRL, this.buildGetPropertyCountRequest());
-        return this.processGetPropertyCountResponse(response);
-    }
-    buildGetPropertyCountRequest() {
-        const request = new esp_local_ctrl.LocalCtrlMessage();
-        request.msg = esp_local_ctrl.LocalCtrlMsgType.TypeCmdGetPropertyCount;
-        request.cmd_get_prop_count = new esp_local_ctrl.CmdGetPropertyCount();
-        return TransformEncoding.uint8ArrayToBase64(request.serialize());
-    }
-    processGetPropertyCountResponse(response) {
-        const deserialized = esp_local_ctrl.LocalCtrlMessage.deserialize(TransformEncoding.base64ToUint8Array(response));
-        if (deserialized.resp_get_prop_count.status !== constants$1.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 !== constants.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, constants.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 esp_local_ctrl.LocalCtrlMessage();
-        request.msg = esp_local_ctrl.LocalCtrlMsgType.TypeCmdGetPropertyValues;
-        const cmd = new esp_local_ctrl.CmdGetPropertyValues();
-        cmd.indices.push(index);
-        request.cmd_get_prop_vals = cmd;
-        return TransformEncoding.uint8ArrayToBase64(request.serialize());
+    buildGetDataRequest(dataType, offset) {
+        return TransformEncoding.uint8ArrayToBase64(rmaker_local_ctrl.RMakerLocalCtrlProtoHelper.createGetDataRequest(dataType, offset));
     }
-    processGetPropertyValueResponse(response) {
-        const deserialized = esp_local_ctrl.LocalCtrlMessage.deserialize(TransformEncoding.base64ToUint8Array(response));
-        if (deserialized.resp_get_prop_vals.status !== constants$1.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 = rmaker_local_ctrl.RMakerLocalCtrlProtoHelper.parseGetDataResponse(TransformEncoding.base64ToUint8Array(response));
+        if (!rmaker_local_ctrl.RMakerLocalCtrlProtoHelper.isSuccess(parsed)) {
+            throw new Error(`Device rejected the local-control read (status ${rmaker_local_ctrl.RMakerLocalCtrlProtoHelper.getStatus(parsed)})`);
+        }
+        const fragmentOffset = rmaker_local_ctrl.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: rmaker_local_ctrl.RMakerLocalCtrlProtoHelper.getPayload(parsed),
+            totalLength: rmaker_local_ctrl.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}`);
+        }
+    }
 }
 
 exports.ESPLocalControlTransport = ESPLocalControlTransport;

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/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

@@ -475,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. */
@@ -484,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.
@@ -641,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.
@@ -887,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/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.