@onekeyfe/hd-transport-usb 1.1.27 → 1.2.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-transport-usb",
-  "version": "1.1.27",
+  "version": "1.2.0-alpha.0",
   "description": "OneKey hardware wallet direct USB transport plugin (libusb)",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
   "license": "MIT",
@@ -20,10 +20,10 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@onekeyfe/hd-shared": "1.1.27",
-    "@onekeyfe/hd-transport": "1.1.27",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.0",
+    "@onekeyfe/hd-transport": "1.2.0-alpha.0",
     "bytebuffer": "^5.0.1",
     "usb": "^2.14.0"
   },
-  "gitHead": "f0c80ce0246152fee79f9cae836db5d550bb82f0"
+  "gitHead": "de9efe20b83666b641ab9e8d945e6350f6450904"
 }

package/src/index.ts

@@ -1,14 +1,33 @@
 import ByteBuffer from 'bytebuffer';
 import * as usb from 'usb';
-import transport, { LogBlockCommand } from '@onekeyfe/hd-transport';
+import transport, {
+  LogBlockCommand,
+  PROTOCOL_V1_CHUNK_PAYLOAD_SIZE,
+  PROTOCOL_V1_MESSAGE_HEADER_SIZE,
+  PROTOCOL_V1_REPORT_ID,
+  PROTOCOL_V1_USB_PACKET_SIZE,
+  PROTOCOL_V2_CHANNEL_USB,
+  PROTOCOL_V2_FRAME_MAX_BYTES,
+  ProtocolV2FrameAssembler,
+  ProtocolV2Session,
+  probeProtocolV2 as probeProtocolV2Helper,
+} from '@onekeyfe/hd-transport';
 import { ERRORS, HardwareErrorCode, ONEKEY_WEBUSB_FILTER, wait } from '@onekeyfe/hd-shared';
 
-import { HEADER_LENGTH, PACKET_SIZE, PAYLOAD_SIZE, REPORT_ID } from './constants';
-
 import type EventEmitter from 'events';
-import type { AcquireInput, OneKeyDeviceInfo } from '@onekeyfe/hd-transport';
+import type {
+  AcquireInput,
+  OneKeyDeviceInfo,
+  ProtocolType,
+  TransportCallOptions,
+} from '@onekeyfe/hd-transport';
+
+const { parseConfigure, ProtocolV1, check } = transport;
 
-const { parseConfigure, buildEncodeBuffers, decodeProtocol, receiveOne, check } = transport;
+const PACKET_SIZE = PROTOCOL_V1_USB_PACKET_SIZE;
+const REPORT_ID = PROTOCOL_V1_REPORT_ID;
+const PAYLOAD_SIZE = PROTOCOL_V1_CHUNK_PAYLOAD_SIZE;
+const HEADER_LENGTH = PROTOCOL_V1_MESSAGE_HEADER_SIZE;
 
 /** USB interface number for vendor-specific communication */
 const INTERFACE_NUMBER = 0;
@@ -25,6 +44,7 @@ const SERIAL_READ_TIMEOUT_MS = 5000;
 /** Packet I/O retry configuration (matches WebUsbTransport) */
 const PACKET_IO_MAX_RETRIES = 3;
 const PACKET_IO_RETRY_DELAY = 300;
+const PROTOCOL_PROBE_TIMEOUT = 1000;
 
 /**
  * Opened device state — holds the USB device, claimed interface, and endpoints.
@@ -134,6 +154,32 @@ function transferOutOnce(ep: usb.OutEndpoint, data: Buffer): Promise<void> {
   });
 }
 
+function resetUsbDevice(dev: usb.Device): Promise<void> {
+  return new Promise(resolve => {
+    const reset = (dev as usb.Device & { reset?: (callback: (err?: Error) => void) => void }).reset;
+    if (typeof reset !== 'function') {
+      resolve();
+      return;
+    }
+    reset.call(dev, () => resolve());
+  });
+}
+
+function clearEndpointHalt(ep: usb.InEndpoint | usb.OutEndpoint): Promise<void> {
+  return new Promise(resolve => {
+    const clearHalt = (
+      ep as (usb.InEndpoint | usb.OutEndpoint) & {
+        clearHalt?: (callback: (err?: Error) => void) => void;
+      }
+    ).clearHalt;
+    if (typeof clearHalt !== 'function') {
+      resolve();
+      return;
+    }
+    clearHalt.call(ep, () => resolve());
+  });
+}
+
 /**
  * Skip the 0x3F protocol marker byte from a USB packet.
  */
@@ -163,6 +209,9 @@ function toArrayBuffer(buf: Buffer): ArrayBuffer {
 export default class NodeUsbTransport {
   messages: ReturnType<typeof transport.parseConfigure> | undefined;
 
+  /** Protobuf schema for Protocol V2 transports. */
+  messagesV2: ReturnType<typeof transport.parseConfigure> | undefined;
+
   name = 'NodeUsbTransport';
 
   version = '';
@@ -181,6 +230,18 @@ export default class NodeUsbTransport {
   /** path → opened device state */
   private openDevices = new Map<string, OpenDevice>();
 
+  /** Per-path protocol type detected by active wire-level probe. */
+  private deviceProtocol: Map<string, ProtocolType> = new Map();
+
+  /** Per-path Protocol V2 frame assembler, preserving buffered frames during reads. */
+  private protocolV2Assemblers: Map<string, ProtocolV2FrameAssembler> = new Map();
+
+  /** Per-path Protocol V2 session, preserving seq across API calls on the same device path. */
+  private protocolV2Sessions: Map<string, ProtocolV2Session> = new Map();
+
+  /** Current Protocol V2 read timeout, consumed by cached session readFrame closures. */
+  private protocolV2ReadTimeouts: Map<string, number | undefined> = new Map();
+
   /** per-path reconnect lock to prevent concurrent reconnects */
   private reconnectLocks = new Map<string, Promise<OpenDevice>>();
 
@@ -204,6 +265,13 @@ export default class NodeUsbTransport {
     return Promise.resolve();
   }
 
+  configureProtocolV2(signedData: any) {
+    this.messagesV2 = parseConfigure(signedData);
+    this.protocolV2Sessions.clear();
+    this.protocolV2ReadTimeouts.clear();
+    this.Log?.debug('[NodeUsbTransport] Protocol V2 schema configured');
+  }
+
   listen() {
     // empty — could add hotplug events via usb.on('attach'/'detach')
   }
@@ -220,7 +288,7 @@ export default class NodeUsbTransport {
     if (!this.messages) {
       throw ERRORS.TypedError(HardwareErrorCode.TransportNotConfigured);
     }
-    const encodeBuffers = buildEncodeBuffers(this.messages, name, data);
+    const encodeBuffers = ProtocolV1.encodeMessageChunks(this.messages, name, data);
     await this.sendAllChunksWithRetry(path, encodeBuffers);
   }
 
@@ -237,7 +305,7 @@ export default class NodeUsbTransport {
     if (!this.messages) {
       throw ERRORS.TypedError(HardwareErrorCode.TransportNotConfigured);
     }
-    return receiveOne(this.messages, resData);
+    return ProtocolV1.decodeMessage(this.messages, resData);
   }
 
   /**
@@ -275,15 +343,19 @@ export default class NodeUsbTransport {
   /**
    * Acquire device — open USB device, claim interface, return path (string).
    */
-  acquire(input: AcquireInput): Promise<string> {
+  async acquire(input: AcquireInput): Promise<string> {
+    this.cancelled = false;
+
     const path = input.path ?? '';
     if (!path) {
       throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound, 'No device path provided');
     }
 
     try {
-      this.openDevice(path);
-      return Promise.resolve(path);
+      await this.closeOpenDevice(path);
+      await this.openDevice(path);
+      await this.detectProtocol(path, input.expectedProtocol);
+      return path;
     } catch (error: any) {
       this.Log?.debug('NodeUsbTransport acquire error: ', error);
       throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound, error.message ?? String(error));
@@ -294,6 +366,12 @@ export default class NodeUsbTransport {
    * Release device — release interface and close.
    */
   async release(path: string, _onclose?: boolean): Promise<void> {
+    await this.closeOpenDevice(path);
+    this.deviceProtocol.delete(path);
+    this.protocolV2Assemblers.delete(path);
+  }
+
+  private async closeOpenDevice(path: string): Promise<void> {
     const openDev = this.openDevices.get(path);
     if (!openDev) return;
 
@@ -322,7 +400,12 @@ export default class NodeUsbTransport {
    * Call device method — encode protobuf, send packets, receive response.
    * This is the core method that replaces LowlevelTransport's call + UsbPlugin's send/receive.
    */
-  async call(path: string, name: string, data: Record<string, unknown>) {
+  async call(
+    path: string,
+    name: string,
+    data: Record<string, unknown>,
+    options?: TransportCallOptions
+  ) {
     this.cancelled = false;
 
     if (!this.messages) {
@@ -333,26 +416,57 @@ export default class NodeUsbTransport {
       throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound, `Device not acquired: ${path}`);
     }
 
-    const { messages } = this;
+    const protocol = this.deviceProtocol.get(path);
+    if (!protocol) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.RuntimeError,
+        `Device protocol has not been detected for ${path}`
+      );
+    }
     if (LogBlockCommand.has(name)) {
-      this.Log?.debug('NodeUsbTransport call-', ' name: ', name);
+      this.Log?.debug('NodeUsbTransport call-', ' name: ', name, ' protocol: ', protocol);
     } else {
-      this.Log?.debug('NodeUsbTransport call-', ' name: ', name, ' data: ', data);
+      this.Log?.debug(
+        'NodeUsbTransport call-',
+        ' name: ',
+        name,
+        ' data: ',
+        data,
+        ' protocol: ',
+        protocol
+      );
     }
 
+    if (protocol === 'V2') {
+      return this.callProtocolV2(path, name, data, options);
+    }
+
+    return this.callProtocolV1(path, name, data, options);
+  }
+
+  private async callProtocolV1(
+    path: string,
+    name: string,
+    data: Record<string, unknown>,
+    options?: TransportCallOptions
+  ) {
+    const { messages } = this;
+    if (!messages) {
+      throw ERRORS.TypedError(HardwareErrorCode.TransportNotConfigured);
+    }
     // Encode protobuf message into 63-byte chunks (same as WebUsbTransport)
-    const encodeBuffers = buildEncodeBuffers(messages, name, data);
+    const encodeBuffers = ProtocolV1.encodeMessageChunks(messages, name, data);
 
     // Send all chunks with retry — if any chunk fails and reconnects,
     // restart the entire send sequence from chunk 0 (device resets state on reconnect)
     await this.sendAllChunksWithRetry(path, encodeBuffers);
 
     // Receive response — re-resolve in case reconnect happened during send
-    const resData = await this.receiveData(path, this.getOpenDevice(path));
+    const resData = await this.receiveData(path, this.getOpenDevice(path), options?.timeoutMs);
     if (typeof resData !== 'string') {
       throw ERRORS.TypedError(HardwareErrorCode.NetworkError, 'Returning data is not string.');
     }
-    const jsonData = receiveOne(messages, resData);
+    const jsonData = ProtocolV1.decodeMessage(messages, resData);
     return check.call(jsonData);
   }
 
@@ -401,6 +515,21 @@ export default class NodeUsbTransport {
     );
   }
 
+  private getDeviceInterface(dev: usb.Device): usb.Interface {
+    const { interfaces } = dev;
+    if (!interfaces?.length) {
+      throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound, 'USB interface not found');
+    }
+
+    const vendorInterface = interfaces.find(iface => iface.descriptor.bInterfaceClass === 0xff);
+    const defaultInterface = interfaces.find(
+      iface => iface.descriptor.bInterfaceNumber === INTERFACE_NUMBER
+    );
+    const iface = vendorInterface ?? defaultInterface ?? interfaces[0];
+
+    return iface;
+  }
+
   /**
    * Reconnect device before retrying a failed transfer (aligned with WebUsbTransport).
    * Uses per-path lock to prevent concurrent reconnects to the same device.
@@ -423,16 +552,16 @@ export default class NodeUsbTransport {
       );
       await wait(attempt * PACKET_IO_RETRY_DELAY);
 
-      // Close the existing device
+      // Close the existing device without clearing the detected protocol cache.
       try {
-        await this.release(path);
+        await this.closeOpenDevice(path);
       } catch (releaseError) {
         this.Log?.debug('[NodeUsbTransport] release before retry error:', releaseError);
       }
 
       // Re-enumerate to refresh device list, then re-open
       await this.enumerate();
-      this.openDevice(path);
+      await this.openDevice(path);
 
       const openDev = this.openDevices.get(path);
       if (!openDev) {
@@ -535,7 +664,7 @@ export default class NodeUsbTransport {
   /**
    * Open a USB device by path (serial number), claim interface, cache endpoints.
    */
-  private openDevice(path: string): void {
+  private async openDevice(path: string): Promise<void> {
     const existing = this.openDevices.get(path);
     if (existing) return;
 
@@ -547,12 +676,20 @@ export default class NodeUsbTransport {
       throw ERRORS.TypedError(HardwareErrorCode.DeviceNotFound, `USB device not found: ${path}`);
     }
 
-    dev.open();
-
     try {
+      dev.open();
       dev.timeout = TRANSFER_TIMEOUT_MS;
 
-      const iface = dev.interface(INTERFACE_NUMBER);
+      await resetUsbDevice(dev);
+
+      try {
+        dev.open();
+      } catch {
+        // libusb keeps some devices open across reset; continue with the current handle.
+      }
+      dev.timeout = TRANSFER_TIMEOUT_MS;
+
+      const iface = this.getDeviceInterface(dev);
 
       // On Linux, detach kernel driver if active
       if (process.platform === 'linux') {
@@ -567,12 +704,14 @@ export default class NodeUsbTransport {
 
       iface.claim();
 
-      const epIn = iface.endpoints.find(
-        (e): e is usb.InEndpoint => e.direction === 'in' && e.address === ENDPOINT_IN
-      );
-      const epOut = iface.endpoints.find(
-        (e): e is usb.OutEndpoint => e.direction === 'out' && e.address === ENDPOINT_OUT
-      );
+      const epIn =
+        iface.endpoints.find(
+          (e): e is usb.InEndpoint => e.direction === 'in' && e.address === ENDPOINT_IN
+        ) ?? iface.endpoints.find((e): e is usb.InEndpoint => e.direction === 'in');
+      const epOut =
+        iface.endpoints.find(
+          (e): e is usb.OutEndpoint => e.direction === 'out' && e.address === ENDPOINT_OUT
+        ) ?? iface.endpoints.find((e): e is usb.OutEndpoint => e.direction === 'out');
 
       if (!epIn || !epOut) {
         throw ERRORS.TypedError(
@@ -584,6 +723,10 @@ export default class NodeUsbTransport {
       epIn.timeout = TRANSFER_TIMEOUT_MS;
       epOut.timeout = TRANSFER_TIMEOUT_MS;
 
+      await clearEndpointHalt(epIn);
+      await clearEndpointHalt(epOut);
+      await this.drainStaleInput(epIn);
+
       this.openDevices.set(path, { device: dev, iface, epIn, epOut });
     } catch (err) {
       try {
@@ -595,17 +738,301 @@ export default class NodeUsbTransport {
     }
   }
 
+  private async drainStaleInput(epIn: usb.InEndpoint): Promise<void> {
+    const originalTimeout = epIn.timeout;
+    epIn.timeout = 50;
+    try {
+      // Drain a small bounded number of packets left by the previous USB session.
+      for (let index = 0; index < 16; index += 1) {
+        try {
+          await transferInOnce(epIn, PACKET_SIZE);
+        } catch {
+          break;
+        }
+      }
+    } finally {
+      epIn.timeout = originalTimeout;
+    }
+  }
+
+  private createProtocolMismatchError(expected: ProtocolType) {
+    return ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      `Device protocol mismatch: expected ${expected}, but device did not respond to expected protocol`
+    );
+  }
+
+  private createProtocolDetectionError() {
+    return ERRORS.TypedError(
+      HardwareErrorCode.RuntimeError,
+      'Unable to detect USB protocol: device did not respond to Protocol V1 Initialize or Protocol V2 Ping'
+    );
+  }
+
+  private async detectProtocol(
+    path: string,
+    expectedProtocol?: ProtocolType
+  ): Promise<ProtocolType> {
+    if (expectedProtocol === 'V1') {
+      if (await this.probeProtocolV1(path)) {
+        this.deviceProtocol.set(path, 'V1');
+        this.Log?.debug(`[NodeUsbTransport] detectProtocol: path=${path} -> V1 (expected)`);
+        return 'V1';
+      }
+      throw this.createProtocolMismatchError(expectedProtocol);
+    }
+
+    if (expectedProtocol === 'V2') {
+      if (await this.probeProtocolV2(path)) {
+        this.deviceProtocol.set(path, 'V2');
+        this.Log?.debug(`[NodeUsbTransport] detectProtocol: path=${path} -> V2 (expected)`);
+        return 'V2';
+      }
+      throw this.createProtocolMismatchError(expectedProtocol);
+    }
+
+    if (this.deviceProtocol.get(path) === 'V2' && (await this.probeProtocolV2(path))) {
+      this.deviceProtocol.set(path, 'V2');
+      this.Log?.debug(`[NodeUsbTransport] detectProtocol: path=${path} -> V2 (cached)`);
+      return 'V2';
+    }
+
+    if (await this.probeProtocolV1(path)) {
+      this.deviceProtocol.set(path, 'V1');
+      this.Log?.debug(`[NodeUsbTransport] detectProtocol: path=${path} -> V1`);
+      return 'V1';
+    }
+
+    if (await this.probeProtocolV2(path)) {
+      this.deviceProtocol.set(path, 'V2');
+      this.Log?.debug(`[NodeUsbTransport] detectProtocol: path=${path} -> V2`);
+      return 'V2';
+    }
+
+    this.deviceProtocol.delete(path);
+    throw this.createProtocolDetectionError();
+  }
+
+  private async resetConnectionAfterProbe(path: string) {
+    this.protocolV2Assemblers.get(path)?.reset();
+    this.protocolV2Sessions.delete(path);
+    this.protocolV2ReadTimeouts.delete(path);
+
+    try {
+      await this.closeOpenDevice(path);
+    } catch (error) {
+      this.Log?.debug('[NodeUsbTransport] close after protocol probe error:', error);
+    }
+
+    await this.enumerate();
+    await this.openDevice(path);
+  }
+
+  private async withProtocolReadTimeout<T>(
+    path: string,
+    promise: Promise<T>,
+    timeoutMs: number,
+    protocol: ProtocolType
+  ): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+    const waitForeverAfterTimeout = () => new Promise<never>(() => {});
+    const guardedPromise = promise.then(
+      value => (timedOut ? waitForeverAfterTimeout() : value),
+      error => {
+        if (timedOut) {
+          return waitForeverAfterTimeout();
+        }
+        throw error;
+      }
+    );
+    try {
+      return await Promise.race([
+        guardedPromise,
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(async () => {
+            timedOut = true;
+            try {
+              await this.resetConnectionAfterProbe(path);
+            } catch (error) {
+              this.Log?.debug(
+                `[NodeUsbTransport] reset after Protocol ${protocol} timeout failed:`,
+                error
+              );
+            } finally {
+              reject(new Error(`Protocol ${protocol} read timeout after ${timeoutMs}ms`));
+            }
+          }, timeoutMs);
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  private async probeProtocolV1(path: string) {
+    if (!this.messages) {
+      return false;
+    }
+
+    try {
+      await this.callProtocolV1(path, 'Initialize', {}, { timeoutMs: PROTOCOL_PROBE_TIMEOUT });
+      return true;
+    } catch (error) {
+      this.Log?.debug('[NodeUsbTransport] Protocol V1 Initialize probe failed:', error);
+      return false;
+    }
+  }
+
+  private async probeProtocolV2(path: string) {
+    if (!this.messages || !this.messagesV2) {
+      return false;
+    }
+
+    return probeProtocolV2Helper({
+      call: (name, data, options) => this.callProtocolV2(path, name, data, options),
+      timeoutMs: PROTOCOL_PROBE_TIMEOUT,
+      logger: this.Log,
+      logPrefix: 'ProtocolV2 NodeUSB',
+      onProbeFailed: () => this.resetConnectionAfterProbe(path),
+    });
+  }
+
+  private async writeProtocolV2Frame(path: string, frame: Uint8Array) {
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= PACKET_IO_MAX_RETRIES; attempt++) {
+      if (this.cancelled) {
+        throw ERRORS.TypedError(HardwareErrorCode.DeviceInterruptedFromOutside, 'Cancelled');
+      }
+      try {
+        await transferOutOnce(this.getOpenDevice(path).epOut, Buffer.from(frame));
+        return;
+      } catch (error) {
+        lastError = error;
+        const shouldRetry = attempt < PACKET_IO_MAX_RETRIES && this.isRetryableError(error);
+        if (!shouldRetry) {
+          throw error;
+        }
+        try {
+          await this.reconnectForRetry(path, 'out', attempt, error);
+        } catch (reconnectError) {
+          lastError = reconnectError;
+          this.Log?.debug(
+            `[NodeUsbTransport] Protocol V2 write reconnect failed on retry ${attempt}/${PACKET_IO_MAX_RETRIES}: ${this.getErrorMessage(
+              reconnectError
+            )}`
+          );
+          break;
+        }
+      }
+    }
+    throw lastError;
+  }
+
+  private async receiveProtocolV2Frame(path: string, timeoutMs?: number): Promise<Uint8Array> {
+    let assembler = this.protocolV2Assemblers.get(path);
+    if (!assembler) {
+      assembler = new ProtocolV2FrameAssembler(PROTOCOL_V2_FRAME_MAX_BYTES);
+      this.protocolV2Assemblers.set(path, assembler);
+    }
+
+    let frame: Uint8Array | undefined = assembler.push(new Uint8Array(0));
+    const deadline = timeoutMs ? Date.now() + timeoutMs : undefined;
+
+    while (!frame) {
+      const transferIn = this.transferInWithRetry(
+        path,
+        this.getOpenDevice(path),
+        PROTOCOL_V2_FRAME_MAX_BYTES
+      );
+      const packet = deadline
+        ? await this.withProtocolReadTimeout(
+            path,
+            transferIn,
+            Math.max(deadline - Date.now(), 1),
+            'V2'
+          )
+        : await transferIn;
+      const bytes = new Uint8Array(
+        packet.buffer.slice(packet.byteOffset, packet.byteOffset + packet.byteLength)
+      );
+      try {
+        frame = assembler.push(bytes);
+      } catch (error) {
+        throw ERRORS.TypedError(
+          HardwareErrorCode.NetworkError,
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+    return frame;
+  }
+
+  private async callProtocolV2(
+    path: string,
+    name: string,
+    data: Record<string, unknown>,
+    options?: TransportCallOptions
+  ) {
+    const protocolV1Messages = this.messages;
+    if (!this.messagesV2) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.TransportNotConfigured,
+        'Protocol V2 schema not configured'
+      );
+    }
+    if (!protocolV1Messages) {
+      throw ERRORS.TypedError(HardwareErrorCode.TransportNotConfigured);
+    }
+
+    let session = this.protocolV2Sessions.get(path);
+    if (!session) {
+      session = new ProtocolV2Session({
+        schemas: {
+          protocolV1: protocolV1Messages,
+          protocolV2: this.messagesV2,
+        },
+        router: PROTOCOL_V2_CHANNEL_USB,
+        writeFrame: (frame: Uint8Array) => this.writeProtocolV2Frame(path, frame),
+        readFrame: () => this.receiveProtocolV2Frame(path, this.protocolV2ReadTimeouts.get(path)),
+        logger: this.Log,
+        logPrefix: 'ProtocolV2 NodeUSB',
+        createTimeoutError: (messageName: string, timeoutMs: number) =>
+          new Error(`Protocol V2 response timeout after ${timeoutMs}ms for ${messageName}`),
+      });
+      this.protocolV2Sessions.set(path, session);
+    }
+
+    this.protocolV2ReadTimeouts.set(path, options?.timeoutMs);
+    this.protocolV2Assemblers.get(path)?.reset();
+    try {
+      return await session.call(name, data, options);
+    } finally {
+      this.protocolV2ReadTimeouts.delete(path);
+    }
+  }
+
   /**
    * Receive a complete protobuf response from the device.
    * Reads 64-byte packets, strips 0x3F marker, reassembles into hex string.
    */
-  private async receiveData(path: string, dev: OpenDevice): Promise<string> {
+  private async receiveData(path: string, dev: OpenDevice, timeoutMs?: number): Promise<string> {
+    const deadline = timeoutMs ? Date.now() + timeoutMs : undefined;
+    const readPacket = async () => {
+      const transferIn = this.transferInWithRetry(path, this.getOpenDevice(path), PACKET_SIZE);
+      return deadline
+        ? this.withProtocolReadTimeout(path, transferIn, Math.max(deadline - Date.now(), 1), 'V1')
+        : transferIn;
+    };
+
     // Read first packet, skip report byte
-    const firstPacket = await this.transferInWithRetry(path, dev, PACKET_SIZE);
+    const firstPacket = timeoutMs
+      ? await readPacket()
+      : await this.transferInWithRetry(path, dev, PACKET_SIZE);
     const firstData = skipReportByte(firstPacket);
 
     // Decode header: ## marker → { typeId, length, restBuffer }
-    const { length, typeId, restBuffer } = decodeProtocol.decodeChunked(toArrayBuffer(firstData));
+    const { length, typeId, restBuffer } = ProtocolV1.decodeFirstChunk(toArrayBuffer(firstData));
 
     // Allocate result: typeId(2) + length(4) + payload(length)
     const lengthWithHeader = Number(length) + HEADER_LENGTH;
@@ -619,7 +1046,7 @@ export default class NodeUsbTransport {
     // Read subsequent packets until complete
     // Re-resolve device on each iteration so we use a fresh handle after any reconnect
     while (decoded.offset < lengthWithHeader) {
-      const packet = await this.transferInWithRetry(path, this.getOpenDevice(path), PACKET_SIZE);
+      const packet = await readPacket();
       const pktData = skipReportByte(packet);
       const buf = toArrayBuffer(pktData);
       if (lengthWithHeader - decoded.offset >= PAYLOAD_SIZE) {
@@ -633,6 +1060,8 @@ export default class NodeUsbTransport {
     const result = decoded.toBuffer();
     return Buffer.from(result as unknown as ArrayBuffer).toString('hex');
   }
-}
 
-export { PACKET_SIZE } from './constants';
+  getProtocolType(path: string): ProtocolType | undefined {
+    return this.deviceProtocol.get(path);
+  }
+}