@robotical/raftjs 2.1.3 → 2.1.5

package/src/RaftAttributeHandler.ts

@@ -11,6 +11,23 @@ import CustomAttrHandler from "./RaftCustomAttrHandler";
 import { DeviceTypeAttribute, DeviceTypePollRespMetadata, decodeAttrUnitsEncoding, isAttrTypeSigned } from "./RaftDeviceInfo";
 import { DeviceAttributesState, DeviceTimeline } from "./RaftDeviceStates";
 import { structSizeOf, structUnpack } from "./RaftStruct";
+import RaftUtils from "./RaftUtils";
+
+// Optional diagnostic context for attribute decoding. When provided, the
+// handler emits a detailed warning if an attribute would read past the
+// declared sample boundary or the end of the message buffer. This is used to
+// track down firmware/schema mismatches.
+export interface AttrDecodeDiagContext {
+    deviceKey?: string;
+    deviceType?: string;
+    debugMsgIndex?: number;
+    // Inclusive start (in msgBuffer) of the current sample's bytes (after the
+    // 1-byte sampleLen prefix). When provided together with sampleEndIdx, the
+    // handler will bound-check attribute reads against this range.
+    sampleStartIdx?: number;
+    // Exclusive end (in msgBuffer) of the current sample's bytes.
+    sampleEndIdx?: number;
+}
 
 export default class AttributeHandler {
 
@@ -23,8 +40,18 @@ export default class AttributeHandler {
     private POLL_RESULT_RESOLUTION_US = 100;
 
     public processMsgAttrGroup(msgBuffer: Uint8Array, msgBufIdx: number, deviceTimeline: DeviceTimeline, pollRespMetadata: DeviceTypePollRespMetadata,
-                        devAttrsState: DeviceAttributesState, maxDataPoints: number, msgEndIdx = msgBuffer.length): number {
-
+                        devAttrsState: DeviceAttributesState, maxDataPoints: number,
+                        msgEndIdxOrDiagCtx: number | AttrDecodeDiagContext = msgBuffer.length,
+                        diagCtx?: AttrDecodeDiagContext): number {
+
+        // Merge rationale: Robotical's devbin compatibility parser needs an
+        // explicit sample boundary; upstream's diagnostics need per-sample
+        // context. Accept both call styles so malformed samples are skipped
+        // without losing useful overrun warnings.
+        const msgEndIdx = typeof msgEndIdxOrDiagCtx === "number"
+            ? msgEndIdxOrDiagCtx
+            : msgEndIdxOrDiagCtx.sampleEndIdx ?? msgBuffer.length;
+        const effectiveDiagCtx = typeof msgEndIdxOrDiagCtx === "number" ? diagCtx : msgEndIdxOrDiagCtx;
         // console.log(`processMsgAttrGroup msg ${msgHexStr} timestamp ${timestamp} origTimestamp ${origTimestamp} msgBufIdx ${msgBufIdx}`)
         const boundedMsgEndIdx = Math.min(Math.max(msgEndIdx, msgBufIdx), msgBuffer.length);
 
@@ -39,6 +66,11 @@ export default class AttributeHandler {
 
         // New attribute values (in order as they appear in the attributes JSON)
         let newAttrValues: (number | string)[][] = [];
+        // Tracks whether any individual attribute decode failed in the non-custom path.
+        // When true, the detailed per-attribute overrun warning has already been emitted
+        // by processMsgAttribute, so we suppress the redundant downstream length/empty
+        // warnings that would otherwise fire every poll.
+        let attrDecodeFailed = false;
         if ("c" in pollRespMetadata) {
 
             // Extract attribute values using custom handler
@@ -83,13 +115,15 @@ export default class AttributeHandler {
                 if (!("t" in attrDef)) {
                     console.warn(`DeviceManager msg unknown msgBuffer ${msgBuffer} tsUs ${timestampUs} attrDef ${JSON.stringify(attrDef)}`);
                     newAttrValues.push([]);
+                    attrDecodeFailed = true;
                     continue;
                 }
 
                 // console.log(`RaftAttrHdlr.processMsgAttrGroup attr ${attrDef.n} msgBufIdx ${msgBufIdx} timestampUs ${timestampUs} attrDef ${JSON.stringify(attrDef)}`);
 
                 // Process the attribute
-                const { values, newMsgBufIdx } = this.processMsgAttribute(attrDef, msgBuffer, msgBufIdx, msgDataStartIdx, boundedMsgEndIdx);
+                const { values, newMsgBufIdx } = this.processMsgAttribute(attrDef, msgBuffer, msgBufIdx, msgDataStartIdx,
+                    boundedMsgEndIdx, pollRespMetadata, effectiveDiagCtx);
                 if (newMsgBufIdx < 0) {
                     return -1;
                 }
@@ -114,14 +148,18 @@ export default class AttributeHandler {
         const numNewDataPoints = newAttrValues[0].length;
         for (let i = 1; i < newAttrValues.length; i++) {
             if (newAttrValues[i].length !== numNewDataPoints) {
-                console.warn(`DeviceManager msg attrGroup ${pollRespMetadata} attrName ${pollRespMetadata.a[i].n} newAttrValues ${newAttrValues} do not have the same length`);
+                if (!attrDecodeFailed) {
+                    console.warn(`DeviceManager msg attrGroup ${JSON.stringify(pollRespMetadata)} attrName ${pollRespMetadata.a[i].n} newAttrValues lengths ${newAttrValues.map(v => v.length).join(",")} do not match`);
+                }
                 return msgDataStartIdx+pollRespSizeBytes;
             }
         }
 
         // All attributes in the schema should have values
         if (newAttrValues.length !== pollRespMetadata.a.length) {
-            console.warn(`DeviceManager msg attrGroup ${pollRespMetadata} newAttrValues ${newAttrValues} length does not match attrGroup.a length`);
+            if (!attrDecodeFailed) {
+                console.warn(`DeviceManager msg attrGroup ${JSON.stringify(pollRespMetadata)} newAttrValues length ${newAttrValues.length} does not match attrGroup.a length ${pollRespMetadata.a.length}`);
+            }
             return msgDataStartIdx+pollRespSizeBytes;
         }
 
@@ -272,7 +310,9 @@ export default class AttributeHandler {
         }
     }
 
-    private processMsgAttribute(attrDef: DeviceTypeAttribute, msgBuffer: Uint8Array, msgBufIdx: number, msgDataStartIdx: number, msgEndIdx: number): { values: (number | string)[], newMsgBufIdx: number} {
+    private processMsgAttribute(attrDef: DeviceTypeAttribute, msgBuffer: Uint8Array, msgBufIdx: number, msgDataStartIdx: number,
+                                msgEndIdx: number, pollRespMetadata?: DeviceTypePollRespMetadata,
+                                diagCtx?: AttrDecodeDiagContext): { values: (number | string)[], newMsgBufIdx: number} {
 
         // Current field message string index
         let curFieldBufIdx = msgBufIdx;
@@ -295,7 +335,9 @@ export default class AttributeHandler {
                 // Copy bytes from the specified positions
                 for (let i = 0; i < attrDef.at.length && i < elemSize; i++) {
                     const sourceIdx = msgDataStartIdx + attrDef.at[i];
-                    if (sourceIdx >= boundedMsgEndIdx) {
+                    if (sourceIdx < msgDataStartIdx || sourceIdx >= boundedMsgEndIdx) {
+                        this.warnAttrOverrun(attrDef, msgBuffer, sourceIdx, elemSize, msgDataStartIdx,
+                            true, pollRespMetadata, diagCtx, sourceIdx >= msgBuffer.length ? "msgBuffer" : "sample");
                         return { values: [], newMsgBufIdx: -1 };
                     }
                     bytesForType[i] = msgBuffer[sourceIdx];
@@ -312,11 +354,15 @@ export default class AttributeHandler {
             attrUsesAbsPos = true;
         }
 
-        // Check if outside bounds of message
+        // Merge rationale: keep Robotical's hard sample bounds as the source of
+        // truth, but emit upstream's one-shot diagnostic when a schema tries to
+        // read beyond the sample or buffer.
         const attrEndIdx = curFieldBufIdx + numBytesConsumed;
         const effectiveMsgEndIdx = Math.min(Math.max(msgEndIdx, curFieldBufIdx), msgBuffer.length);
         if (curFieldBufIdx >= effectiveMsgEndIdx || attrEndIdx > effectiveMsgEndIdx) {
-            // console.warn(`DeviceManager msg outside bounds msgBuffer ${msgBuffer} attrName ${attrDef.n}`);
+            this.warnAttrOverrun(attrDef, msgBuffer, curFieldBufIdx, numBytesConsumed, msgDataStartIdx,
+                                 attrUsesAbsPos, pollRespMetadata, diagCtx,
+                                 attrEndIdx > msgBuffer.length ? "msgBuffer" : "sample");
             return { values: [], newMsgBufIdx: -1 };
         }
 
@@ -439,6 +485,40 @@ export default class AttributeHandler {
         return { values: attrValues, newMsgBufIdx: msgBufIdx };
     }
 
+    // One-shot detailed warning when an attribute decode would overrun the
+    // sample/message bounds. Includes the exact bytes and schema so the
+    // firmware vs. registered device-type schema can be reconciled.
+    private _overrunWarnSeen: Set<string> = new Set();
+    private warnAttrOverrun(attrDef: DeviceTypeAttribute, msgBuffer: Uint8Array, curFieldBufIdx: number,
+                            attrTypeSize: number, msgDataStartIdx: number, attrUsesAbsPos: boolean,
+                            pollRespMetadata: DeviceTypePollRespMetadata | undefined,
+                            diagCtx: AttrDecodeDiagContext | undefined, overrunOf: "msgBuffer" | "sample"): void {
+        const sampleStart = diagCtx?.sampleStartIdx ?? msgDataStartIdx;
+        const sampleEnd = diagCtx?.sampleEndIdx;
+        const dedupeKey = `${diagCtx?.deviceKey ?? "?"}|${diagCtx?.deviceType ?? "?"}|${attrDef.n}|${attrDef.t}|${attrUsesAbsPos ? attrDef.at : "rel"}`;
+        if (this._overrunWarnSeen.has(dedupeKey)) {
+            return;
+        }
+        this._overrunWarnSeen.add(dedupeKey);
+        const sampleHex = sampleEnd !== undefined
+            ? RaftUtils.bufferToHex(msgBuffer.slice(sampleStart, sampleEnd))
+            : "<unknown sample bounds>";
+        const availableInSample = sampleEnd !== undefined ? Math.max(0, sampleEnd - curFieldBufIdx) : -1;
+        const availableInBuffer = Math.max(0, msgBuffer.length - curFieldBufIdx);
+        console.warn(
+            `AttributeHandler decode overrun (${overrunOf}): ` +
+            `deviceKey=${diagCtx?.deviceKey ?? "?"} deviceType=${diagCtx?.deviceType ?? "?"} ` +
+            `debugMsgIndex=${diagCtx?.debugMsgIndex ?? "?"} attr.n=${attrDef.n} attr.t=${attrDef.t} ` +
+            `attrTypeSize=${attrTypeSize} attrUsesAbsPos=${attrUsesAbsPos} attr.at=${JSON.stringify(attrDef.at)} ` +
+            `curFieldBufIdx=${curFieldBufIdx} msgBuffer.length=${msgBuffer.length} ` +
+            `sampleStartIdx=${sampleStart} sampleEndIdx=${sampleEnd ?? "?"} ` +
+            `availableInSample=${availableInSample} availableInBuffer=${availableInBuffer} ` +
+            `sampleHex=${sampleHex} ` +
+            `pollRespMetadata.b=${pollRespMetadata?.b} ` +
+            `schema=${JSON.stringify(pollRespMetadata?.a)}`
+        );
+    }
+
     private signExtend(value: number, mask: number): number {
         const signBitMask = (mask + 1) >> 1;
         const signBit = value & signBitMask;

package/src/RaftChannelWebSerial.ts

@@ -192,9 +192,30 @@ export default class RaftChannelWebSerial implements RaftChannel {
 
     RaftLog.debug(`RaftChannelWebSerial.disconnect attempting to close webserial`);
 
-    while (this._reader) {
+    const reader = this._reader;
+    if (reader) {
+      try {
+        await Promise.race([
+          reader.cancel(),
+          new Promise((resolve) => setTimeout(resolve, 1000)),
+        ]);
+      } catch (err) {
+        RaftLog.debug(`RaftChannelWebSerial.disconnect reader cancel failed ${err}`);
+      }
+    }
+
+    const readerReleaseStartMs = Date.now();
+    while (this._reader && Date.now() - readerReleaseStartMs < 1000) {
       await new Promise((resolve) => setTimeout(resolve, 100));
     }
+    if (this._reader) {
+      try {
+        this._reader.releaseLock();
+      } catch (err) {
+        RaftLog.debug(`RaftChannelWebSerial.disconnect reader release failed ${err}`);
+      }
+      this._reader = undefined;
+    }
 
     // Disconnect webserial
     try {
@@ -417,4 +438,4 @@ export default class RaftChannelWebSerial implements RaftChannel {
     RaftLog.debug(`sendTxMsgRawAndWaitForReply - not implemented`);
     return null as T;
   }  
-}
+}

package/src/RaftConnector.ts

@@ -25,6 +25,24 @@ import { RaftUpdateEvent, RaftUpdateEventNames } from "./RaftUpdateEvents";
 import RaftUpdateManager from "./RaftUpdateManager";
 import { createBLEChannel } from "./RaftChannelBLEFactory";import { getHostPosixTZ } from './RaftTimezone';
 
+const DISCONNECT_SUBSCRIPTION_TIMEOUT_MS = 1000;
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+    promise.then(
+      (value) => {
+        clearTimeout(timeout);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      }
+    );
+  });
+}
+
 export default class RaftConnector {
 
   // Get system type callback
@@ -387,6 +405,18 @@ export default class RaftConnector {
       const channelToDisconnect = this._raftChannel;
       this._raftChannel = null;
 
+      if (this._systemType?.subscribeForUpdates && channelToDisconnect.requiresSubscription()) {
+        try {
+          await withTimeout(
+            this._systemType.subscribeForUpdates(this._raftSystemUtils, false),
+            DISCONNECT_SUBSCRIPTION_TIMEOUT_MS
+          );
+          RaftLog.info("disconnect unsubscribed from updates");
+        } catch (error) {
+          RaftLog.warn(`disconnect unsubscribe for updates failed ${error}`);
+        }
+      }
+      
       // Check if there is a RICREST command to send before disconnecting
       const ricRestCommand = channelToDisconnect.ricRestCmdBeforeDisconnect();
       if (ricRestCommand) {

package/src/RaftDeviceInfo.ts

@@ -136,6 +136,7 @@ export interface DeviceTypeInfo {
     desc: string;
     manu: string;
     type: string;
+    role?: string;
     resp?: DeviceTypePollRespMetadata;
     clas?: Array<string>;
     actions?: DeviceTypeAction[];
@@ -148,5 +149,8 @@ export interface DeviceTypeInfoRecs {
 export type RaftDevTypeInfoResponse = {
     req: string;
     rslt: string;
-    devinfo: DeviceTypeInfo;
+    devinfo?: DeviceTypeInfo;
+    dtIdx?: number;
+    name?: string;
+    role?: string;
   };

package/src/RaftDeviceManager.ts

@@ -403,8 +403,14 @@ export class DeviceManager implements RaftDeviceMgrIF{
             // Check if a device state already exists
             if (!(deviceKey in this._devicesState) || (this._devicesState[deviceKey].deviceTypeInfo === undefined)) {
 
-                // Get the device type info
-                const deviceTypeInfo = resolvedDeviceTypeInfo ?? await this.getDeviceTypeInfo(busNum.toString(), devTypeIdx.toString());
+                // Merge rationale: upstream's deviceid lookup carries
+                // per-instance name/role fields, while Robotical's simulator
+                // and older firmware still expose bus/type lookup. Try the
+                // richer endpoint first and fall back to the type record that
+                // was already loaded for payload-format detection.
+                const deviceTypeInfo = await this.getDeviceTypeInfo(deviceKey)
+                    ?? resolvedDeviceTypeInfo
+                    ?? await this.getDeviceTypeInfo(busNum.toString(), devTypeIdx.toString());
                 
                 // Debug
                 // console.log(`DevMan.handleClientMsgBinary debugIdx ${debugMsgIndex} pollDataPos ${pollDataPos} busNum ${busNum} devAddr 0x${devAddr.toString(16)} devTypeIdx ${devTypeIdx} deviceTypeInfo ${JSON.stringify(deviceTypeInfo)}`);
@@ -482,11 +488,21 @@ export class DeviceManager implements RaftDeviceMgrIF{
 
                         const sampleStartPos = pollDataPos;
                         const sampleEndPos = pollDataPos + sampleLen;
+                        // Merge rationale: keep Robotical's explicit sample
+                        // boundary and add upstream diagnostics so malformed
+                        // samples can be skipped with useful context.
                         const newMsgBufIdx = this._attributeHandler.processMsgAttrGroup(rxMsg, sampleStartPos,
                             deviceState.deviceTimeline, pollRespMetadata,
                             deviceState.deviceAttributes,
                             this._maxDatapointsToStore,
-                            sampleEndPos);
+                            sampleEndPos,
+                            {
+                                deviceKey,
+                                deviceType: deviceState.deviceType,
+                                debugMsgIndex,
+                                sampleStartIdx: sampleStartPos,
+                                sampleEndIdx: sampleEndPos,
+                            });
 
                         if (newMsgBufIdx < 0)
                         {
@@ -515,11 +531,21 @@ export class DeviceManager implements RaftDeviceMgrIF{
                         while (pollDataPos + legacySampleLen <= samplesEndPos) {
                             const sampleStartPos = pollDataPos;
                             const sampleEndPos = pollDataPos + legacySampleLen;
+                            // Legacy raw records are not length-prefixed, but
+                            // the fixed sample span gives the same bound and
+                            // diagnostic context to the attribute handler.
                             const newMsgBufIdx = this._attributeHandler.processMsgAttrGroup(rxMsg, sampleStartPos,
                                 deviceState.deviceTimeline, pollRespMetadata,
                                 deviceState.deviceAttributes,
                                 this._maxDatapointsToStore,
-                                sampleEndPos);
+                                sampleEndPos,
+                                {
+                                    deviceKey,
+                                    deviceType: deviceState.deviceType,
+                                    debugMsgIndex,
+                                    sampleStartIdx: sampleStartPos,
+                                    sampleEndIdx: sampleEndPos,
+                                });
 
                             if (newMsgBufIdx < 0)
                             {
@@ -632,8 +658,11 @@ export class DeviceManager implements RaftDeviceMgrIF{
                 // Check if a device state already exists
                 if (!(deviceKey in this._devicesState) || (this._devicesState[deviceKey].deviceTypeInfo === undefined)) {
 
-                    // Get the device type info
-                    const deviceTypeInfo = await this.getDeviceTypeInfo(busName, deviceTypeName);
+                    // Prefer upstream's per-instance deviceid endpoint, but
+                    // keep Robotical's bus/type fallback for simulated and
+                    // older JSON publishers.
+                    const deviceTypeInfo = await this.getDeviceTypeInfo(deviceKey)
+                        ?? await this.getDeviceTypeInfo(busName, deviceTypeName);
 
                     // Check if device record exists
                     if (deviceKey in this._devicesState) {
@@ -802,71 +831,87 @@ export class DeviceManager implements RaftDeviceMgrIF{
     // Get device type info
     ////////////////////////////////////////////////////////////////////////////
 
-    private async getDeviceTypeInfo(busName: string, deviceType: string): Promise<DeviceTypeInfo | undefined> {
+    private async getDeviceTypeInfo(deviceKey: string): Promise<DeviceTypeInfo | undefined>;
+    private async getDeviceTypeInfo(busName: string, deviceType: string): Promise<DeviceTypeInfo | undefined>;
+    private async getDeviceTypeInfo(deviceKeyOrBusName: string, deviceType?: string): Promise<DeviceTypeInfo | undefined> {
+        const cacheKey = deviceType === undefined ? deviceKeyOrBusName : deviceType;
+        const requestLabel = deviceType === undefined ? `deviceKey ${deviceKeyOrBusName}` : `deviceType ${deviceType}`;
+
         // Check if already in cache
-        if (deviceType in this._cachedDeviceTypeRecs) {
-            return this._cachedDeviceTypeRecs[deviceType];
+        if (cacheKey in this._cachedDeviceTypeRecs) {
+            return this._cachedDeviceTypeRecs[cacheKey];
         }
 
-        // Check if there's already a pending request for this device type
-        if (deviceType in this._pendingDeviceTypeRequests) {
-            // console.log(`DevMan.getDeviceTypeInfo joining existing request queue for deviceType ${deviceType}`);
-            
+        // Check if there's already a pending request for this device/type
+        if (cacheKey in this._pendingDeviceTypeRequests) {
             // Add this request to the waiting queue
             return new Promise<DeviceTypeInfo | undefined>((resolve, reject) => {
-                this._pendingDeviceTypeRequests[deviceType].waitingQueue.push({ resolve, reject });
+                this._pendingDeviceTypeRequests[cacheKey].waitingQueue.push({ resolve, reject });
             });
         }
 
         // Check rate limiting for new requests
-        if (deviceType in this._cachedDeviceTypePreviousAttemptTimes) {
-            const timeSinceLastAttempt = Date.now() - this._cachedDeviceTypePreviousAttemptTimes[deviceType];
+        if (cacheKey in this._cachedDeviceTypePreviousAttemptTimes) {
+            const timeSinceLastAttempt = Date.now() - this._cachedDeviceTypePreviousAttemptTimes[cacheKey];
             if (timeSinceLastAttempt < this._minTimeBetweenDeviceTypeInfoRetrievalMs) {
-                console.log(`DevMan.getDeviceTypeInfo rate limited for deviceType ${deviceType}`);
+                console.log(`DevMan.getDeviceTypeInfo rate limited for ${requestLabel}`);
                 return undefined;
             }
         }
 
         // Create and cache the promise with an empty waiting queue
-        const requestPromise = this.executeDeviceTypeInfoRequest(busName, deviceType);
-        this._pendingDeviceTypeRequests[deviceType] = {
+        const requestPromise = this.executeDeviceTypeInfoRequest(deviceKeyOrBusName, deviceType);
+        this._pendingDeviceTypeRequests[cacheKey] = {
             promise: requestPromise,
             waitingQueue: []
         };
 
         try {
             const result = await requestPromise;
-            
+
             // Resolve all waiting requests with the same result
-            const waitingQueue = this._pendingDeviceTypeRequests[deviceType].waitingQueue;
+            const waitingQueue = this._pendingDeviceTypeRequests[cacheKey].waitingQueue;
             waitingQueue.forEach(({ resolve }) => resolve(result));
-            
+
             return result;
         } catch (error) {
             // Reject all waiting requests with the same error
-            const waitingQueue = this._pendingDeviceTypeRequests[deviceType].waitingQueue;
+            const waitingQueue = this._pendingDeviceTypeRequests[cacheKey].waitingQueue;
             waitingQueue.forEach(({ reject }) => reject(error));
-            
-            console.warn(`DevMan.getDeviceTypeInfo failed for ${deviceType}: ${error}`);
+
+            console.warn(`DevMan.getDeviceTypeInfo failed for ${requestLabel}: ${error}`);
             return undefined;
         } finally {
             // Clean up the pending request
-            delete this._pendingDeviceTypeRequests[deviceType];
+            delete this._pendingDeviceTypeRequests[cacheKey];
         }
     }
 
-    private async executeDeviceTypeInfoRequest(busName: string, deviceType: string): Promise<DeviceTypeInfo | undefined> {
-        this._cachedDeviceTypePreviousAttemptTimes[deviceType] = Date.now();
-        
+    private async executeDeviceTypeInfoRequest(deviceKeyOrBusName: string, deviceType?: string): Promise<DeviceTypeInfo | undefined> {
+        const cacheKey = deviceType === undefined ? deviceKeyOrBusName : deviceType;
+        this._cachedDeviceTypePreviousAttemptTimes[cacheKey] = Date.now();
+
         try {
-            const cmd = "devman/typeinfo?bus=" + busName + "&type=" + deviceType;
+            // Merge rationale: support both upstream's per-device endpoint and
+            // Robotical's older bus/type endpoint. The deviceid response may
+            // include instance-specific name/role; the bus/type response keeps
+            // simulators and older firmware working.
+            const cmd = deviceType === undefined
+                ? "devman/typeinfo?deviceid=" + deviceKeyOrBusName
+                : "devman/typeinfo?bus=" + deviceKeyOrBusName + "&type=" + deviceType;
             const msgHandler = this._systemUtils?.getMsgHandler();
-            
+
             if (msgHandler) {
                 const msgRslt = await msgHandler.sendRICRESTURL<RaftDevTypeInfoResponse>(cmd);
                 if (msgRslt && msgRslt.rslt === "ok") {
-                    this._cachedDeviceTypeRecs[deviceType] = msgRslt.devinfo;
-                    return msgRslt.devinfo;
+                    // Merge devinfo (type-level) with top-level per-instance overrides (name, role)
+                    const base: DeviceTypeInfo = msgRslt.devinfo
+                        ? { ...msgRslt.devinfo }
+                        : { name: "", desc: "", manu: "", type: "" };
+                    if (msgRslt.name !== undefined) base.name = msgRslt.name;
+                    if (msgRslt.role !== undefined) base.role = msgRslt.role;
+                    this._cachedDeviceTypeRecs[cacheKey] = base;
+                    return base;
                 }
             }
             return undefined;

package/src/main.ts

@@ -11,7 +11,7 @@
 import { createBLEChannel } from './RaftChannelBLEFactory';
 const raftChannel = createBLEChannel();
 export { raftChannel as RaftChannelBLE };
-
+ 
 export { default as RaftCommsStats } from './RaftCommsStats';
 export { default as RaftConnector } from './RaftConnector';
 export { default as RaftChannel } from './RaftChannel';