@onekeyfe/hd-transport 1.2.0-alpha.13 → 1.2.0-alpha.131

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-transport",
-  "version": "1.2.0-alpha.13",
+  "version": "1.2.0-alpha.131",
   "description": "Transport layer abstractions and utilities for OneKey hardware SDK.",
   "author": "OneKey",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
@@ -28,5 +28,5 @@
     "long": "^4.0.0",
     "protobufjs": "^6.11.2"
   },
-  "gitHead": "a907a7ec140123107f6188b37550a7143f1e0d91"
+  "gitHead": "81b472e983e80e6aa771b991dc9c0c9b1bdcf07b"
 }

package/scripts/protobuf-build.sh

@@ -2,57 +2,137 @@
 
 set -euxo pipefail
 
-echo $#
-
-PARENT_PATH=$( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P )
+PARENT_PATH=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
+PACKAGE_ROOT="$PARENT_PATH/.."
+REPO_ROOT="$PARENT_PATH/../../.."
+CORE_MESSAGES_DIR="$REPO_ROOT/packages/core/src/data/messages"
 
 SRC="../../submodules/firmware/common/protob"
 DIST="."
 LANG="typescript"
 
-if [[ $# -ne 0 && $# -ne 3 ]]
-    then
-        echo "must provide either 3 or 0 arguments. $# provided"
-        exit 1
+if [[ $# -ne 0 && $# -ne 3 ]]; then
+    echo "must provide either 3 or 0 arguments. $# provided"
+    exit 1
+fi
+
+if [[ $# -eq 3 ]]; then
+    SRC=$1
+    DIST=$2
+    LANG=$3
+fi
+
+if [[ "$LANG" != "typescript" && "$LANG" != "flow" ]]; then
+    echo "either typescript or flow must be specified as the third argument"
+    exit 1
 fi
 
-if [[ $# -eq 3 ]]
-    then
-        SRC=$1
-        DIST=$2
-        LANG=$3
+if [[ "$SRC" = /* ]]; then
+    SRC_PATH="$SRC"
+else
+    SRC_PATH="$PACKAGE_ROOT/$SRC"
 fi
 
-if [[ "$LANG" != "typescript" && "$LANG" != "flow" ]];
-    then
-        echo "either typescript or flow must be specified as the third argument"
-        exit 1
+if [[ "$DIST" = /* ]]; then
+    DIST_PATH="$DIST"
+else
+    DIST_PATH="$PACKAGE_ROOT/$DIST"
 fi
 
+V1_TMP_PROTO="$DIST_PATH/messages-tmp.proto"
+V2_TMP_PROTO="$PARENT_PATH/messages-protocol-v2-tmp.proto"
+trap 'rm -f "$V1_TMP_PROTO" "$V2_TMP_PROTO"' EXIT
 
-# BUILD combined messages.proto file from protobuf files
-# this code was copied from ./submodules/firmware/protob Makekile
-# clear protobuf syntax and remove unknown values to be able to work with proto2js
-echo 'syntax = "proto2";' > $DIST/messages.proto
-echo 'import "google/protobuf/descriptor.proto";' >> $DIST/messages.proto
-echo "Build proto file from $SRC"
-grep -hv -e '^import ' -e '^syntax' -e '^package' -e 'option java_' $SRC/messages*.proto \
+echo "=== Building Protocol V1 messages ==="
+echo 'syntax = "proto2";' > "$V1_TMP_PROTO"
+echo 'import "google/protobuf/descriptor.proto";' >> "$V1_TMP_PROTO"
+grep -hv -e '^import ' -e '^syntax' -e '^package' -e 'option java_' "$SRC_PATH"/messages*.proto \
 | sed 's/ hw\.trezor\.messages\.common\./ /' \
 | sed 's/ common\./ /' \
 | sed 's/ ethereum_definitions\./ /' \
 | sed 's/ management\./ /' \
 | sed 's/^option /\/\/ option /' \
-| grep -v '    reserved '>> $DIST/messages.proto
+| grep -v '    reserved ' >> "$V1_TMP_PROTO"
 
-# BUILD messages.json from message.proto
-npx pbjs -t json -p $DIST -o $DIST/messages.json --keep-case messages.proto
-rm $DIST/messages.proto
+npx pbjs -t json -p "$DIST_PATH" -o "$DIST_PATH/messages.json" --keep-case "$V1_TMP_PROTO"
+cp "$DIST_PATH/messages.json" "$CORE_MESSAGES_DIR/messages.json"
 
-echo "generating type definitions for: $LANG"
+echo "=== Building Protocol V2 messages ==="
+SRC_PRO2_LEGACY="$REPO_ROOT/submodules/firmware-pro2/sys/protobuf/onekey_protocol/legacy"
+SRC_PRO2_LATEST="$REPO_ROOT/submodules/firmware-pro2/sys/protobuf/onekey_protocol/latest"
 
-cd "$PARENT_PATH"
+if [[ ! -d "$SRC_PRO2_LEGACY" || ! -d "$SRC_PRO2_LATEST" ]]; then
+    echo "firmware-pro2 protobuf schema is missing"
+    exit 1
+fi
+
+{
+    echo 'syntax = "proto2";'
+    echo 'import "google/protobuf/descriptor.proto";'
+    echo ''
+    grep -hv \
+        -e '^import ' -e '^syntax' -e '^package' -e 'option java_' \
+        "$SRC_PRO2_LEGACY"/messages*.proto \
+        | sed 's/ hw\.onekey\.messages\.[a-zA-Z_]*\./ /g' \
+        | sed 's/ crypto\./ /g' \
+        | sed 's/ ethereum_definitions\./ /g' \
+        | sed 's/ management\./ /g' \
+        | sed 's/^option /\/\/ option /' \
+        | grep -v '    reserved '
+    echo ''
+    echo '// --- Protocol V2 system messages ---'
+    grep -hv \
+        -e '^import ' -e '^syntax' -e '^package' -e 'option java_' -e '^option ' \
+        "$SRC_PRO2_LATEST"/messages*.proto \
+        | grep -v '    reserved '
+} > "$V2_TMP_PROTO"
 
-node ./protobuf-types.js $LANG
+# Protocol V2 latest schema defines common request names that also exist in
+# legacy chain messages. Keep the legacy definitions and remove the duplicate
+# top-level latest declarations before protobufjs parses the flattened schema.
+node - "$V2_TMP_PROTO" <<'NODE'
+const fs = require('fs');
+
+const protoPath = process.argv[2];
+let proto = fs.readFileSync(protoPath, 'utf8');
+
+function removeLastTopLevelMessage(source, name) {
+  const pattern = new RegExp(`(^|\\n)message\\s+${name}\\s*\\{`, 'gm');
+  const matches = Array.from(source.matchAll(pattern));
+  if (matches.length < 2) return source;
+  const match = matches[matches.length - 1];
+  const start = match.index + (match[1] ? match[1].length : 0);
+  let depth = 0;
+  for (let index = start; index < source.length; index += 1) {
+    if (source[index] === '{') depth += 1;
+    if (source[index] === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        let end = index + 1;
+        while (end < source.length && /\\s/.test(source[end])) end += 1;
+        return `${source.slice(0, start)}${source.slice(end)}`;
+      }
+    }
+  }
+  throw new Error(`Unterminated message block: ${name}`);
+}
+
+['Initialize', 'GetFeatures', 'OnekeyGetFeatures', 'Features'].forEach(name => {
+  proto = removeLastTopLevelMessage(proto, name);
+});
+
+fs.writeFileSync(protoPath, proto);
+NODE
+
+npx pbjs -t json -p "$PARENT_PATH" -o "$PACKAGE_ROOT/messages-protocol-v2.json" --keep-case "$V2_TMP_PROTO"
+cp "$PACKAGE_ROOT/messages-protocol-v2.json" "$CORE_MESSAGES_DIR/messages-protocol-v2.json"
+
+echo "generating type definitions for: $LANG"
+cd "$PARENT_PATH"
+node ./protobuf-types.js "$LANG"
 
-yarn prettier --write messages.json
-yarn prettier --write **/messages.ts
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$DIST_PATH/messages.json"
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$CORE_MESSAGES_DIR/messages.json"
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$PACKAGE_ROOT/messages-protocol-v2.json"
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$CORE_MESSAGES_DIR/messages-protocol-v2.json"
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$PACKAGE_ROOT/src/types/messages.ts"

package/scripts/protobuf-patches/index.js

@@ -210,6 +210,7 @@ const TYPE_PATCH = {
   'TonSignMessage.ext_ton_amount': UINT_TYPE,
   'TonSignData.timestamp': UINT_TYPE,
   'TonSignProof.expire_at': UINT_TYPE,
+  'TonSignData.timestamp': UINT_TYPE,
 };
 
 const DEFINITION_PATCH = {

package/scripts/protobuf-types.js

@@ -57,6 +57,9 @@ const ENUM_KEYS = [
   'InputScriptType',
   'OutputScriptType',
   'RequestType',
+  'KaspaInputScriptType',
+  'KaspaOutputScriptType',
+  'KaspaRequestType',
   'BackupType',
   'Capability',
   'SafetyCheckLevel',
@@ -66,6 +69,9 @@ const ENUM_KEYS = [
   'ProtocolV2Capability',
 ];
 
+// Safety checks are accepted as both protobuf enum names and numeric legacy values.
+const ENUM_KEYS_WITH_NUMERIC_VALUES = ['SafetyCheckLevel'];
+
 const parseEnumTypescript = (itemName, item) => {
   const value = [];
   const IS_KEY = ENUM_KEYS.includes(itemName);
@@ -84,7 +90,10 @@ const parseEnumTypescript = (itemName, item) => {
   value.push('}');
 
   if (IS_KEY) {
-    value.push(`export type ${itemName} = keyof typeof Enum_${itemName};`);
+    const numericValue = ENUM_KEYS_WITH_NUMERIC_VALUES.includes(itemName)
+      ? ` | Enum_${itemName}`
+      : '';
+    value.push(`export type ${itemName} = keyof typeof Enum_${itemName}${numericValue};`);
   }
   // empty line
   value.push('');

package/src/constants.ts

@@ -1,50 +1,64 @@
 // ---- Protocol V1 (Pro1 / Touch / Mini / Classic) ----
 
-/** Protocol V1 USB report 标记，ASCII '?'。 */
+/** Protocol V1 USB report marker, ASCII `?`. */
 export const PROTOCOL_V1_REPORT_ID = 0x3f;
 
-/** Protocol V1 envelope 头部标记，ASCII '#'。 */
+/** Protocol V1 envelope marker, ASCII `#`. */
 export const PROTOCOL_V1_HEADER_BYTE = 0x23;
 
-/** Protocol V1 单个 chunk 去掉 report 标记后的可用 payload 长度。 */
+/** Protocol V1 payload bytes per chunk after the report marker. */
 export const PROTOCOL_V1_CHUNK_PAYLOAD_SIZE = 63;
 
-/** Protocol V1 USB packet 长度：report 标记 + chunk payload。 */
+/** Protocol V1 USB packet length: report marker plus chunk payload. */
 export const PROTOCOL_V1_USB_PACKET_SIZE = PROTOCOL_V1_CHUNK_PAYLOAD_SIZE + 1;
 
-/** Protocol V1 message metadata：message type 2 字节 + payload length 4 字节。 */
+/** Protocol V1 message metadata: two-byte type plus four-byte payload length. */
 export const PROTOCOL_V1_MESSAGE_HEADER_SIZE = 2 + 4;
 
-/** Protocol V1 envelope metadata：## + message type + payload length。 */
+/** Protocol V1 envelope metadata: `##`, message type, and payload length. */
 export const PROTOCOL_V1_ENVELOPE_HEADER_SIZE = 1 + 1 + PROTOCOL_V1_MESSAGE_HEADER_SIZE;
 
 // ---- Protocol V2 (Pro2 USB / BLE transports) ----
 
-/** Protocol V2 单帧最大长度，包含 header、payload 和 CRC；需容纳 4000 数据块及 protobuf 开销。 */
-export const PROTOCOL_V2_FRAME_MAX_BYTES = 4608;
+/** Firmware Proto Link runtime limit for a complete V2 frame, including header and CRC. */
+export const PROTOCOL_V2_FRAME_MAX_BYTES = 4200;
 
-/** WebUSB 下 FilesystemFileWrite 的文件数据分块大小。 */
+/** FilesystemFileWrite chunk size over WebUSB. */
 export const PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE = 4000;
 
-/** BLE 下 FilesystemFileWrite 的文件数据分块大小。 */
+/** FilesystemFileWrite chunk size over BLE. */
 export const PROTOCOL_V2_BLE_FILE_CHUNK_SIZE = 1800;
 
-/** BLE 下 FilesystemFileRead 的文件数据分块大小，受 Pro2 UART 1024B TX 缓冲限制。 */
+/**
+ * FirmwareUpdateV4 chunk size for its fixed BLE staging paths.
+ * The longest current path still leaves 28 bytes below the 2048-byte BLE frame limit.
+ */
+export const PROTOCOL_V2_BLE_FIRMWARE_FILE_CHUNK_SIZE = 1960;
+
+/** BLE FilesystemFileRead chunk size, limited by the Pro2 1024-byte UART TX buffer. */
 export const PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE = 900;
 
-/** Pro2 BLE/UART 接收 FIFO 必须容纳完整 Proto Link 帧。 */
+/** Pro2 BLE/UART RX FIFO must hold a complete Proto Link frame. */
 export const PROTOCOL_V2_BLE_FRAME_MAX_BYTES = 2048;
 
-/** @deprecated 使用按传输区分的 PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE / PROTOCOL_V2_BLE_FILE_CHUNK_SIZE。 */
+/** @deprecated Use the transport-specific WebUSB or BLE file chunk constant. */
 export const PROTOCOL_V2_FILE_CHUNK_SIZE = PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE;
 
 /**
- * Protocol V2 路由 channel。
- * USB 端点直接到主 MCU，不需要 proto-link 路由；BLE 需要经过 BLE 协处理器 UART bridge。
+ * Protocol V2 routing channel. USB reaches the main MCU directly, while BLE routes
+ * through the BLE coprocessor UART bridge.
  */
 export const PROTOCOL_V2_CHANNEL_USB = 0;
 export const PROTOCOL_V2_CHANNEL_BLE_UART = 1;
 export const PROTOCOL_V2_CHANNEL_SOCKET = 2;
 
-/** protobuf 命令流的 packet_src，固件侧会把 0 路由到 protobuf dispatcher。 */
+/** packet_src for protobuf commands; firmware routes zero to the protobuf dispatcher. */
 export const PROTOCOL_V2_PACKET_SRC_COMMAND = 0;
+
+/**
+ * Shared upper bound for a Protocol V2 request without a method-specific timeout.
+ * Interactive and signing calls may wait on the device UI, so keep this longer than
+ * ordinary transport timeouts while still preventing a stalled link from blocking
+ * the per-device queue forever.
+ */
+export const PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS = 5 * 60 * 1000;

package/src/index.ts

@@ -36,16 +36,19 @@ export type {
   OneKeyDeviceInfoWithSession,
   MessageFromOneKey,
   TransportCallOptions,
+  TransportWriteMetrics,
   LowlevelTransportSharedPlugin,
   LowLevelDevice,
   OneKeyDeviceInfoBase,
   OneKeyDeviceCommType,
   ProtocolType,
+  TransportDeviceDisconnectEvent,
 } from './types';
 
-export { Messages } from './types';
+export { Messages, TRANSPORT_EVENT } from './types';
 export * from './types/messages';
 export * from './utils/logBlockCommand';
+export * from './utils/transportLog';
 
 export * from './constants';
 export * from './protocols';
@@ -53,6 +56,7 @@ export * as protocolV1 from './protocols/v1';
 export * as protocolV2 from './protocols/v2';
 export * from './protocols/v2/session';
 export * from './protocols/v2/link-manager';
+export * from './protocols/v2/ble-frame-writer';
 export * from './protocols/v2/usb-transport-base';
 
 export default {

package/src/protocols/index.ts

@@ -1,4 +1,5 @@
 import ByteBuffer from 'bytebuffer';
+import { Reader, Type } from 'protobufjs/light';
 
 import { encodeEnvelopeMessage, encodeMessageChunks, encodeTransportPackets } from './v1/packets';
 import { decodeFirstChunk } from './v1/decode';
@@ -6,7 +7,12 @@ import { decodeMessage as decodeV1Message } from './v1/receive';
 import { createMessageFromName, createMessageFromType } from '../serialization/protobuf/messages';
 import { encode as encodeProtobuf } from '../serialization/protobuf/encode';
 import { decode as decodeProtobuf } from '../serialization/protobuf/decode';
-import { decodeFrame as decodeV2Frame, encodeProtobufFrame, isAckFrame } from './v2';
+import {
+  decodeFrame as decodeV2Frame,
+  encodeProtobufFrame,
+  inspectFrameHeader,
+  isAckFrame,
+} from './v2';
 
 import type { Root } from 'protobufjs/light';
 
@@ -24,6 +30,85 @@ type ProtocolV2FrameOptions = {
   seq?: number;
 };
 
+const LEGACY_PROTOCOL_V2_PROTOCOL_INFO = Type.fromJSON('LegacyProtocolInfo', {
+  fields: {
+    version: {
+      rule: 'required',
+      type: 'uint32',
+      id: 1,
+    },
+    supported_messages: {
+      rule: 'repeated',
+      type: 'uint32',
+      id: 2,
+      options: {
+        packed: false,
+      },
+    },
+    protobuf_definition: {
+      type: 'string',
+      id: 3,
+    },
+  },
+});
+
+const decodeLegacyProtocolV2ProtocolInfo = (pbPayload: Uint8Array) => {
+  const byteBuffer = ByteBuffer.wrap(Buffer.from(pbPayload) as unknown as ArrayBuffer);
+  const legacy = decodeProtobuf(LEGACY_PROTOCOL_V2_PROTOCOL_INFO, byteBuffer);
+
+  return {
+    version: legacy.version,
+    build_fingerprint: '',
+    supported_messages: legacy.supported_messages ?? [],
+    // Presence of this legacy field lets Core keep the fallback recovery-only.
+    protobuf_definition: null,
+  };
+};
+
+const isLegacyProtocolV2ProtocolInfoWireLayout = (pbPayload: Uint8Array) => {
+  const reader = Reader.create(pbPayload);
+  let hasVersion = false;
+  try {
+    while (reader.pos < reader.len) {
+      const tag = reader.uint32();
+      // eslint-disable-next-line no-bitwise
+      const fieldNumber = tag >>> 3;
+      // eslint-disable-next-line no-bitwise
+      const wireType = tag & 0x07;
+      if (fieldNumber === 1) {
+        if (wireType !== 0) return false;
+        hasVersion = true;
+      } else if (fieldNumber === 2) {
+        // Legacy field 2 is repeated uint32; current field 2 is a string.
+        if (wireType !== 0) return false;
+      } else if (fieldNumber === 3) {
+        // Legacy field 3 is protobuf_definition; current field 3 is uint32.
+        if (wireType !== 2) return false;
+      } else {
+        return false;
+      }
+      reader.skipType(wireType);
+    }
+  } catch {
+    return false;
+  }
+  return hasVersion;
+};
+
+const tryDecodeLegacyProtocolV2ProtocolInfo = (messageName: string, pbPayload: Uint8Array) => {
+  // TEMPORARY COMPATIBILITY: Remove this fallback after all supported Pro2 and Neo
+  // firmware versions return ProtocolInfo with the current build_fingerprint layout.
+  if (messageName !== 'ProtocolInfo' || !isLegacyProtocolV2ProtocolInfoWireLayout(pbPayload)) {
+    return undefined;
+  }
+
+  try {
+    return decodeLegacyProtocolV2ProtocolInfo(pbPayload);
+  } catch {
+    return undefined;
+  }
+};
+
 const resolveProtocolV2EncodeSchema = (name: string, schemas: ProtocolV2Schemas) => {
   try {
     schemas.protocolV2.lookupType(name);
@@ -71,15 +156,19 @@ export const ProtocolV1 = {
 
 export const ProtocolV2 = {
   isAckFrame,
+  inspectFrameHeader,
 
   inspectFrame(schemas: ProtocolV2Schemas, frame: Uint8Array) {
-    const { messageTypeId, pbPayload, seq } = decodeV2Frame(frame);
+    const { messageTypeId, pbPayload, seq, router, packetSrc, dataType } = decodeV2Frame(frame);
     const { messageName } = createProtocolV2MessageFromType(messageTypeId, schemas);
     return {
       messageName,
       messageTypeId,
       pbPayload,
       seq,
+      router,
+      packetSrc,
+      dataType,
       type: messageName,
     };
   },
@@ -110,7 +199,29 @@ export const ProtocolV2 = {
     const { messageTypeId, pbPayload, seq, messageName } = this.inspectFrame(schemas, frame);
     const { Message } = createProtocolV2MessageFromType(messageTypeId, schemas);
     const rxByteBuffer = ByteBuffer.wrap(Buffer.from(pbPayload) as unknown as ArrayBuffer);
-    const message = decodeProtobuf(Message, rxByteBuffer);
+    let message: ReturnType<typeof decodeProtobuf>;
+    try {
+      message = decodeProtobuf(Message, rxByteBuffer);
+    } catch (cause) {
+      const legacyProtocolInfo = tryDecodeLegacyProtocolV2ProtocolInfo(messageName, pbPayload);
+      if (legacyProtocolInfo) {
+        return {
+          message: legacyProtocolInfo,
+          messageName,
+          messageTypeId,
+          pbPayload,
+          seq,
+          type: messageName,
+        };
+      }
+      const error = new Error(
+        `Protocol V2 protobuf decode failed for "${messageName}" ` +
+          `(${messageTypeId}, ${pbPayload.length}-byte payload); ` +
+          'the payload is malformed or incompatible with the active SDK schema.'
+      );
+      (error as Error & { cause?: unknown }).cause = cause;
+      throw error;
+    }
 
     return {
       message,

package/src/protocols/v2/ble-frame-writer.ts

@@ -0,0 +1,77 @@
+export type ProtocolV2BleFrameWriterOptions = {
+  frame: Uint8Array;
+  packetCapacity: number;
+  writePacket: (packet: Uint8Array, packetIndex: number) => Promise<void>;
+  assertActive?: () => void;
+  signal?: AbortSignal;
+  abortMessage?: string;
+  initialDelayMs?: number;
+  burstSize?: number;
+  burstPauseMs?: number;
+  flushDelayMs?: number;
+  wait?: (timeoutMs: number) => Promise<void>;
+};
+
+const defaultWait = (timeoutMs: number) =>
+  new Promise<void>(resolve => {
+    setTimeout(resolve, timeoutMs);
+  });
+
+export async function writeProtocolV2BleFrame({
+  frame,
+  packetCapacity,
+  writePacket,
+  assertActive,
+  signal,
+  abortMessage = 'Protocol V2 BLE write aborted',
+  initialDelayMs = 0,
+  burstSize,
+  burstPauseMs = 0,
+  flushDelayMs = 0,
+  wait = defaultWait,
+}: ProtocolV2BleFrameWriterOptions): Promise<void> {
+  if (!Number.isInteger(packetCapacity) || packetCapacity <= 0) {
+    throw new Error('Protocol V2 BLE packet capacity must be a positive integer');
+  }
+  if (burstSize !== undefined && (!Number.isInteger(burstSize) || burstSize <= 0)) {
+    throw new Error('Protocol V2 BLE burst size must be a positive integer');
+  }
+
+  const assertWritable = () => {
+    assertActive?.();
+    if (signal?.aborted) {
+      throw new Error(abortMessage);
+    }
+  };
+
+  if (frame.length > 0 && initialDelayMs > 0) {
+    assertWritable();
+    await wait(initialDelayMs);
+    assertWritable();
+  }
+
+  let packetsWritten = 0;
+  for (let offset = 0; offset < frame.length; offset += packetCapacity) {
+    assertWritable();
+    const packet = frame.slice(offset, offset + packetCapacity);
+    await writePacket(packet, packetsWritten);
+    packetsWritten += 1;
+    assertWritable();
+
+    const hasMorePackets = offset + packetCapacity < frame.length;
+    if (
+      hasMorePackets &&
+      burstSize !== undefined &&
+      packetsWritten % burstSize === 0 &&
+      burstPauseMs > 0
+    ) {
+      await wait(burstPauseMs);
+      assertWritable();
+    }
+  }
+
+  if (burstSize !== undefined && packetsWritten > burstSize && flushDelayMs > 0) {
+    await wait(flushDelayMs);
+    assertWritable();
+  }
+}

package/src/protocols/v2/crc8.ts

@@ -22,7 +22,7 @@ export const CRC8_TABLE = new Uint8Array([
 ]);
 
 /**
- * 计算 data 前 len 个字节的 CRC-8，使用与固件侧一致的初始值。
+ * Compute CRC-8 over the first len bytes using the firmware-compatible initial value.
  */
 export function crc8(data: Uint8Array, len: number): number {
   let crc = CRC8_INIT;