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

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';
@@ -111,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, 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, 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/proto/rmaker_local_ctrl.js

@@ -0,0 +1,271 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Codec for the `rmaker_local_ctrl` endpoint protocol, mirroring the firmware's
+ * `local_ctrl.proto` schema.
+ *
+ * Hand-rolled like {@link ClaimingProtoHelper} rather than generated: the
+ * schema is small, and generated `google-protobuf` modules cannot be pulled
+ * into a downstream Metro/RN bundle (see the note in `utils/export.ts`).
+ *
+ * Field numbers are the wire contract with deployed firmware — treat them as
+ * frozen:
+ * - `RMakerLocalCtrlPayload`: 1 = msg (varint), 10 = cmdGetData, 11 = respGetData
+ * - `CmdGetData`:  1 = DataType (varint), 2 = Offset (varint),
+ *                  3 = Timestamp (varint), 4 = HasTimestamp (varint)
+ * - `RespGetData`: 1 = Status (varint), 2 = Buf
+ * - `PayloadBuf`:  1 = Offset (varint), 2 = Payload (bytes), 3 = TotalLen (varint)
+ *
+ * `Timestamp` / `HasTimestamp` are reserved for a future signed-response
+ * extension and are ignored by current firmware, so the encoder omits them.
+ *
+ * Only `get_params` / `get_config` use this schema; `set_params` carries raw
+ * JSON on the wire.
+ */
+/**
+ * Status returned by the device for a data read.
+ */
+var RMakerLocalCtrlStatus;
+(function (RMakerLocalCtrlStatus) {
+    RMakerLocalCtrlStatus[RMakerLocalCtrlStatus["Success"] = 0] = "Success";
+    RMakerLocalCtrlStatus[RMakerLocalCtrlStatus["Fail"] = 1] = "Fail";
+    RMakerLocalCtrlStatus[RMakerLocalCtrlStatus["InvalidParam"] = 2] = "InvalidParam";
+    RMakerLocalCtrlStatus[RMakerLocalCtrlStatus["NoMemory"] = 3] = "NoMemory";
+})(RMakerLocalCtrlStatus || (RMakerLocalCtrlStatus = {}));
+/**
+ * Selects which document a read targets.
+ */
+var RMakerLocalCtrlDataType;
+(function (RMakerLocalCtrlDataType) {
+    /** The node's params JSON, as served by `get_params`. */
+    RMakerLocalCtrlDataType[RMakerLocalCtrlDataType["TypeParams"] = 0] = "TypeParams";
+    /** The node's config JSON, as served by `get_config`. */
+    RMakerLocalCtrlDataType[RMakerLocalCtrlDataType["TypeConfig"] = 1] = "TypeConfig";
+})(RMakerLocalCtrlDataType || (RMakerLocalCtrlDataType = {}));
+/**
+ * Message type discriminator carried on `RMakerLocalCtrlPayload.msg`.
+ */
+var RMakerLocalCtrlMsgType;
+(function (RMakerLocalCtrlMsgType) {
+    RMakerLocalCtrlMsgType[RMakerLocalCtrlMsgType["TypeCmdGetData"] = 0] = "TypeCmdGetData";
+    RMakerLocalCtrlMsgType[RMakerLocalCtrlMsgType["TypeRespGetData"] = 1] = "TypeRespGetData";
+})(RMakerLocalCtrlMsgType || (RMakerLocalCtrlMsgType = {}));
+/** Tag bytes written by the request encoder: `(fieldNumber << 3) | wireType`. */
+const TAG_FIELD_1_VARINT = 0x08;
+const TAG_FIELD_2_VARINT = 0x10;
+const TAG_FIELD_10_BYTES = 0x52;
+const WIRE_TYPE_VARINT = 0;
+const WIRE_TYPE_BYTES = 2;
+/**
+ * Encoder/decoder for `rmaker_local_ctrl` frames.
+ */
+class RMakerLocalCtrlProtoHelper {
+    /**
+     * Builds a `CmdGetData` request for one fragment.
+     *
+     * An `offset` of 0 makes the device (re)generate and cache the document;
+     * subsequent offsets are served from that cache.
+     *
+     * @param dataType - Document to read.
+     * @param offset - Byte offset to read from.
+     * @returns The serialized request.
+     */
+    static createGetDataRequest(dataType, offset) {
+        const cmdGetData = this.concat([
+            // Both fields are written explicitly, including their proto3 zero values,
+            // matching how the reference clients frame this command.
+            new Uint8Array([TAG_FIELD_1_VARINT]),
+            this.encodeVarint(dataType),
+            new Uint8Array([TAG_FIELD_2_VARINT]),
+            this.encodeVarint(offset),
+        ]);
+        return this.concat([
+            new Uint8Array([TAG_FIELD_1_VARINT]),
+            this.encodeVarint(RMakerLocalCtrlMsgType.TypeCmdGetData),
+            new Uint8Array([TAG_FIELD_10_BYTES]),
+            this.encodeVarint(cmdGetData.length),
+            cmdGetData,
+        ]);
+    }
+    /**
+     * Parses a `RespGetData` frame from the device.
+     *
+     * @param data - Raw response bytes.
+     * @returns The parsed payload. Absent fields keep their proto3 defaults.
+     */
+    static parseGetDataResponse(data) {
+        const result = {
+            msg: RMakerLocalCtrlMsgType.TypeCmdGetData,
+        };
+        let index = 0;
+        while (index < data.length) {
+            const tag = data[index++];
+            const fieldNumber = tag >> 3;
+            const wireType = tag & 0x07;
+            if (fieldNumber === 1 && wireType === WIRE_TYPE_VARINT) {
+                const { value, newIndex } = this.readVarint(data, index);
+                result.msg = value;
+                index = newIndex;
+                continue;
+            }
+            if (fieldNumber === 11 && wireType === WIRE_TYPE_BYTES) {
+                const { value: length, newIndex } = this.readVarint(data, index);
+                result.respGetData = this.parseRespGetData(data.slice(newIndex, newIndex + length));
+                index = newIndex + length;
+                continue;
+            }
+            index = this.skipField(data, index, wireType);
+        }
+        return result;
+    }
+    /**
+     * Whether the device reported a successful read.
+     *
+     * @param response - Parsed response.
+     */
+    static isSuccess(response) {
+        return response.respGetData?.status === RMakerLocalCtrlStatus.Success;
+    }
+    /**
+     * Returns the device's status as its enum name, for diagnostics.
+     *
+     * @param response - Parsed response.
+     * @returns The status name, or `"Unknown"` when absent.
+     */
+    static getStatus(response) {
+        const status = response.respGetData?.status;
+        return status === undefined
+            ? "Unknown"
+            : (RMakerLocalCtrlStatus[status] ?? `Unknown(${status})`);
+    }
+    /**
+     * Offset the device answered with, which must match the requested offset.
+     *
+     * @param response - Parsed response.
+     */
+    static getOffset(response) {
+        return response.respGetData?.buf?.offset ?? 0;
+    }
+    /**
+     * Full document length reported by the device.
+     *
+     * @param response - Parsed response.
+     */
+    static getTotalLen(response) {
+        return response.respGetData?.buf?.totalLen ?? 0;
+    }
+    /**
+     * Fragment bytes carried by the response.
+     *
+     * @param response - Parsed response.
+     */
+    static getPayload(response) {
+        return response.respGetData?.buf?.payload ?? new Uint8Array(0);
+    }
+    // Private helper methods
+    static concat(parts) {
+        const totalLength = parts.reduce((sum, part) => sum + part.length, 0);
+        const result = new Uint8Array(totalLength);
+        let pos = 0;
+        for (const part of parts) {
+            result.set(part, pos);
+            pos += part.length;
+        }
+        return result;
+    }
+    static encodeVarint(value) {
+        const bytes = [];
+        let remaining = value;
+        while (remaining > 127) {
+            bytes.push((remaining & 0x7f) | 0x80);
+            remaining >>>= 7;
+        }
+        bytes.push(remaining & 0x7f);
+        return new Uint8Array(bytes);
+    }
+    static readVarint(data, index) {
+        let value = 0;
+        let shift = 0;
+        let byte;
+        do {
+            byte = data[index++];
+            value |= (byte & 0x7f) << shift;
+            shift += 7;
+        } while (byte & 0x80);
+        return { value, newIndex: index };
+    }
+    /** Advances past a field this codec does not read. */
+    static skipField(data, index, wireType) {
+        if (wireType === WIRE_TYPE_VARINT) {
+            return this.readVarint(data, index).newIndex;
+        }
+        if (wireType === WIRE_TYPE_BYTES) {
+            const { value: length, newIndex } = this.readVarint(data, index);
+            return newIndex + length;
+        }
+        return index + 1;
+    }
+    static parseRespGetData(data) {
+        // In proto3 an absent status defaults to 0, i.e. Success.
+        const result = { status: RMakerLocalCtrlStatus.Success };
+        let index = 0;
+        while (index < data.length) {
+            const tag = data[index++];
+            const fieldNumber = tag >> 3;
+            const wireType = tag & 0x07;
+            if (fieldNumber === 1 && wireType === WIRE_TYPE_VARINT) {
+                const { value, newIndex } = this.readVarint(data, index);
+                result.status = value;
+                index = newIndex;
+                continue;
+            }
+            if (fieldNumber === 2 && wireType === WIRE_TYPE_BYTES) {
+                const { value: length, newIndex } = this.readVarint(data, index);
+                result.buf = this.parsePayloadBuf(data.slice(newIndex, newIndex + length));
+                index = newIndex + length;
+                continue;
+            }
+            index = this.skipField(data, index, wireType);
+        }
+        return result;
+    }
+    static parsePayloadBuf(data) {
+        const result = {
+            offset: 0,
+            payload: new Uint8Array(0),
+            totalLen: 0,
+        };
+        let index = 0;
+        while (index < data.length) {
+            const tag = data[index++];
+            const fieldNumber = tag >> 3;
+            const wireType = tag & 0x07;
+            if (fieldNumber === 1 && wireType === WIRE_TYPE_VARINT) {
+                const { value, newIndex } = this.readVarint(data, index);
+                result.offset = value;
+                index = newIndex;
+                continue;
+            }
+            if (fieldNumber === 2 && wireType === WIRE_TYPE_BYTES) {
+                const { value: length, newIndex } = this.readVarint(data, index);
+                result.payload = data.slice(newIndex, newIndex + length);
+                index = newIndex + length;
+                continue;
+            }
+            if (fieldNumber === 3 && wireType === WIRE_TYPE_VARINT) {
+                const { value, newIndex } = this.readVarint(data, index);
+                result.totalLen = value;
+                index = newIndex;
+                continue;
+            }
+            index = this.skipField(data, index, wireType);
+        }
+        return result;
+    }
+}
+
+export { RMakerLocalCtrlDataType, RMakerLocalCtrlMsgType, RMakerLocalCtrlProtoHelper, RMakerLocalCtrlStatus };
+//# sourceMappingURL=rmaker_local_ctrl.js.map

package/dist/esm/proto/rmaker_local_ctrl.js.map

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

package/dist/esm/services/ESPTransport/ESPDiscovery/ESPDiscoveryManager.js

@@ -12,9 +12,10 @@ import { ServiceType } from '../../../utils/constants.js';
  * adapter (see {@link ESPRMNeoBase.setLocalDiscoveryAdapter}).
  *
  * - With no discovery config, the default local protocol is used
- *   (mDNS service `_esp_local_ctrl._tcp.` in the `local` domain).
- * - A custom {@link DiscoveryParamsInterface} can be supplied for other
- *   discovery protocols.
+ *   (mDNS service `_esp_rmaker_ctrl._tcp.` in the `local` domain — the
+ *   service advertised by RainMaker Neo firmware).
+ * - A custom {@link DiscoveryParamsInterface} can be supplied to browse any
+ *   other service type.
  */
 class ESPDiscoveryManager {
     /** Discovery parameters (service type / domain) passed to the adapter. */
@@ -29,7 +30,7 @@ class ESPDiscoveryManager {
             throw new Error("ESPLocalDiscoveryAdapter not set");
         }
         this.params = discoveryConfig || {
-            serviceType: ServiceType.ESP_LOCAL_CTRL_TCP,
+            serviceType: ServiceType.ESP_RMAKER_LOCAL_CTRL_TCP,
             domain: ESPDiscoveryProtocol.local,
         };
     }

package/dist/esm/services/ESPTransport/ESPDiscovery/ESPDiscoveryManager.js.map

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

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 };