OneKeyHQ
diff --git a/‎docs/pro2-protocol.md‎
Lines changed: 24 additions & 24 deletions b/‎docs/pro2-protocol.md‎
Lines changed: 24 additions & 24 deletions
diff --git a/‎docs/transport.md‎
Lines changed: 40 additions & 36 deletions b/‎docs/transport.md‎
Lines changed: 40 additions & 36 deletions
@@ -4,17 +4,17 @@ This document describes the communication protocol used by OneKey Pro2 hardware
 
 ## Overview
 
-Pro2 uses the **Proto Link** framing protocol, which is different from the legacy Trezor-style `##` header protocol used by older OneKey devices (Classic, Mini, Touch, Pro).
+Pro2 uses the **Protocol V2** framing protocol, which is different from the **Protocol V1** Trezor-style `##` header protocol used by older OneKey devices (Classic, Mini, Touch, Pro1).
 
-| Feature | Legacy (Classic/Mini/Touch/Pro) | Pro2 (Proto Link) |
+| Feature | Protocol V1 (Pro1/Touch/Mini/Classic) | Protocol V2 (Pro2) |
 |---------|-------------------------------|-------------------|
 | Framing | `##` header + type + length | SOF `0x5A` + CRC8 |
 | Chunking | 64-byte USB HID reports | Up to 2200 bytes per frame |
 | Integrity | None (relies on USB) | CRC8 on header and body |
 | Multiplexing | Single channel | Multi-channel (USB, UART, Socket) |
 | Sequence | None | 1-255 with duplicate detection |
 
-## Proto Link Frame Format
+## Protocol V2 Frame Format
 
 ```
 +----------- Pre-Header (4 bytes) -----------+
@@ -86,7 +86,7 @@ function crc8(data: Uint8Array, length: number): number {
 
 ## Protobuf Message Encoding
 
-Proto Link frames carry protobuf messages. The DATA field contains:
+Protocol V2 frames carry protobuf messages. The DATA field contains:
 
 ```
 [MSG_TYPE_L] [MSG_TYPE_H] [PROTOBUF_PAYLOAD...]
@@ -119,11 +119,11 @@ Pro2 system messages (60000+):
 ### Schema Selection
 
 Pro2 uses two protobuf schemas:
-- **Legacy schema** (`messages.json`): Standard SDK messages (Initialize, GetFeatures, etc.)
-- **Pro2 schema** (`messages-pro2.json`): System messages with type ID >= 60000
+- **Protocol V1 schema** (`messages.json`): Standard SDK messages (Initialize, GetFeatures, etc.)
+- **Protocol V2 schema** (`messages-pro2.json`): System messages with type ID >= 60000
 
-When encoding: look up the message name in the Pro2 schema first. If not found, use the legacy schema.
-When decoding: if `msgType >= 60000`, use Pro2 schema; otherwise use legacy schema.
+When encoding: look up the message name in the V2 schema first. If not found, fall back to the V1 schema.
+When decoding: if `msgType >= 60000` (`PROTOCOL_V2_SYS_MESSAGE_THRESHOLD`), use V2 schema; otherwise use V1 schema.
 
 ## WebUSB Transport
 
@@ -138,20 +138,20 @@ When decoding: if `msgType >= 60000`, use Pro2 schema; otherwise use legacy sche
 
 ### Data Flow
 
-1. **Send:** Build Proto V0 frame -> single `transferOut` (no chunking needed, frames fit in one USB transfer)
-2. **Receive:** single `transferIn` (up to 4096 bytes) -> parse Proto V0 frame
+1. **Send:** Build Protocol V2 frame -> single `transferOut` (no chunking needed, frames fit in one USB transfer)
+2. **Receive:** single `transferIn` (up to 4096 bytes) -> parse Protocol V2 frame
 
 Unlike legacy devices (which chunk into 64-byte HID reports), Pro2 sends/receives complete frames in a single USB transfer.
 
 ### Device Detection
 
-Pro2 is identified by USB Product ID `0x53C1`. When this PID is detected during `acquire()`, the transport switches from legacy `##` protocol to Proto V0 `0x5A` framing.
+Pro2 is identified by USB Product ID `0x53C1`. When this PID is detected during `acquire()`, the transport switches from Protocol V1 (`##` header) to Protocol V2 (`0x5A` framing).
 
 ## BLE Transport
 
 ### GATT Service
 
-Pro2 BLE uses the same GATT service/characteristic UUIDs as legacy OneKey devices:
+Pro2 BLE uses the same GATT service/characteristic UUIDs as Protocol V1 OneKey devices:
 
 | Component | UUID |
 |-----------|------|
@@ -161,15 +161,15 @@ Pro2 BLE uses the same GATT service/characteristic UUIDs as legacy OneKey device
 
 ### Data Flow
 
-1. **Send:** Build Proto V0 frame (with CHANNEL=1 for UART) -> GATT write to write characteristic
-2. **Receive:** Subscribe to notify characteristic -> reassemble Proto V0 frame from notifications -> parse
+1. **Send:** Build Protocol V2 frame (with CHANNEL=1 for UART) -> GATT write to write characteristic
+2. **Receive:** Subscribe to notify characteristic -> reassemble Protocol V2 frame from notifications -> parse
 
 ### BLE-Specific Considerations
 
 - **Channel ID:** BLE uses CHANNEL=1 (UART), because the BLE coprocessor communicates with the main MCU via UART
 - **Packet Source:** Command/response data uses `packet_src=1` (FRAME_COMMON_PKT_COMMAND_DATA)
 - **MTU:** BLE MTU is negotiated during connection. Default is 23 bytes (BLE 4.0). ATT overhead is 3 bytes, so default payload is 20 bytes. Pro2 typically negotiates higher MTU (e.g., 512 bytes)
-- **Frame Reassembly:** A single Proto V0 frame may arrive across multiple BLE notifications if the frame exceeds the negotiated MTU. The receiver must accumulate notification data until a complete frame (determined by the LEN field) is received
+- **Frame Reassembly:** A single Protocol V2 frame may arrive across multiple BLE notifications if the frame exceeds the negotiated MTU. The receiver must accumulate notification data until a complete frame (determined by the LEN field) is received
 
 ### Device Detection
 
@@ -179,7 +179,7 @@ Pro2 BLE devices can be identified by:
 
 ## File Transfer Protocol
 
-Pro2 supports file operations via protobuf messages over Proto Link:
+Pro2 supports file operations via protobuf messages over Protocol V2:
 
 ### FileWrite
 
@@ -218,7 +218,7 @@ max_chunk = min(negotiated_mtu - 3, 244)  // ATT overhead = 3 bytes
 
 For USB:
 ```
-max_chunk = 2048  // Proto V0 frames can be up to 2200 bytes
+max_chunk = 2048  // Protocol V2 frames can be up to 2200 bytes
 ```
 
 ## Ping Protocol
@@ -236,7 +236,7 @@ message Ping {
 
 ## Reliability
 
-Proto Link provides several reliability mechanisms:
+Protocol V2 provides several reliability mechanisms:
 
 - **CRC8 validation:** Header CRC and body CRC detect corruption
 - **Sequence numbers:** 1-255, wraps from 255 to 1 (0 is reserved)
@@ -250,17 +250,17 @@ Proto Link provides several reliability mechanisms:
 
 | Transport | Class | Protocol | Target |
 |-----------|-------|----------|--------|
-| WebUSB (legacy) | `WebUsbTransport` | `##` header | Browser |
-| WebUSB (Pro2) | `WebUsbTransport` | Proto V0 | Browser |
-| BLE (legacy) | `ElectronBleTransport` | `##` header | Electron |
-| BLE (Pro2) | `ElectronPro2BleTransport` | Proto V0 | Electron |
+| WebUSB (Pro1 / Touch / Mini / Classic) | `WebUsbTransport` | V1 (`##` header) | Browser |
+| WebUSB (Pro2) | `WebUsbTransport` | V2 (`0x5A` framing) | Browser |
+| BLE (Pro1 / Touch) | `ElectronBleTransport` | V1 (`##` header) | Electron |
+| BLE (Pro2) | `ElectronPro2BleTransport` | V2 (`0x5A` framing) | Electron |
 
 ### Code References
 
-- Proto V0 encode/decode: `packages/hd-transport/src/serialization/protocol-v0/`
+- Protocol V2 encode/decode: `packages/hd-transport/src/serialization/protocol-v2/`
 - Pro2 protobuf definitions: `packages/hd-transport/messages-pro2.json`
 - WebUSB transport: `packages/hd-transport-web-device/src/webusb.ts`
 - BLE Pro2 transport: `packages/hd-transport-web-device/src/electron-pro2-ble-transport.ts`
 - BLE legacy transport: `packages/hd-transport-web-device/src/electron-ble-transport.ts`
 - Noble BLE handler: `packages/hd-transport-electron/src/noble-ble-handler.ts`
-- Proto Link spec: `firmware-pro2/sys/frame_codec/proto_link/proto_link.md`
+- Protocol V2 spec: `firmware-pro2/sys/frame_codec/proto_link/proto_link.md`
@@ -2,14 +2,14 @@
 
 ## 两句话总结
 
-- **Legacy**（Pro1/Mini/Touch/Classic）：USB 每包 64 字节，分包传输，连接后必须先发 `Initialize` 握手。
-- **Proto V0**（Pro2）：USB 单帧最大 2048 字节，无需握手，直接调用系统级 API（文件系统、固件更新）。
+- **Protocol V1**（Pro1 / Mini / Touch / Classic）：USB 每包 64 字节，分包传输，连接后必须先发 `Initialize` 握手。
+- **Protocol V2**（Pro2）：USB 单帧最大 2048 字节，无需握手，直接调用系统级 API（文件系统、固件更新）。
 
 ---
 
 ## 核心差异速查
 
-| | Legacy | Proto V0 (Pro2) |
+| | Protocol V1 | Protocol V2 (Pro2) |
 |---|---|---|
 | SOF 字节 | `0x3F` (`?`) | `0x5A` |
 | 单次传输上限 | **64 bytes**（固定分包） | **2048 bytes**（单帧） |
@@ -25,7 +25,7 @@
 
 ## 帧格式对比
 
-### Legacy — 固定 64 字节分包
+### Protocol V1 — 固定 64 字节分包
 
 ```
 每个 USB 包（64 bytes）:
@@ -47,10 +47,10 @@
 
 ---
 
-### Proto V0 — 单帧最大 2048 字节
+### Protocol V2 — 单帧最大 2048 字节
 
 ```
-Proto V0 Frame（最大 2048 bytes）:
+Protocol V2 Frame（最大 2048 bytes）:
 ┌──────┬──────┬──────┬───────────┬────────┬──────┬─────┬──────────┬──────────┬──────────┬─────┐
 │ 0x5A │ LenL │ LenH │ HeaderCRC │ Router │ Attr │ Seq │ MsgTypeL │ MsgTypeH │ PB Data  │ CRC │
 └──────┴──────┴──────┴───────────┴────────┴──────┴─────┴──────────┴──────────┴──────────┴─────┘
@@ -67,7 +67,7 @@ MsgType   = Little-endian uint16
 
 ## 连接与初始化流程
 
-### Legacy：必须握手
+### Protocol V1：必须握手
 
 ```
 enumerate() → acquire() → Initialize → Features
@@ -83,71 +83,75 @@ SDK 依赖这些信息选择正确的 protobuf schema。
 
 ---
 
-### Proto V0（Pro2）：跳过握手
+### Protocol V2（Pro2）：跳过握手
 
 ```
 enumerate() → acquire()
                   ↓
            detectProtocol(path)
-           发送 0x5A 探测帧，读响应首字节：
-             0x5A → PRO2
-             0x3F → LEGACY
+           按 USB Product ID 识别：
+             PID 0x53C1 (PID_PRO2) → V2
+             其他 PID                → V1
                   ↓
-           originalDescriptor.protocolType = 'PRO2'  ← 写回设备描述符
+           originalDescriptor.protocolType = 'V2'  ← 写回设备描述符
                   ↓
-           initialize() 检测到 PRO2，跳过 Initialize
+           initialize() 检测到 V2，跳过 Initialize
                   ↓
            _initializePro2()
-           合成 Features { vendor, device_type: 'pro2' }
-           TransportManager.reconfigure(undefined, 'PRO2')
+           合成 Features { vendor, onekey_device_type: Pro2 }
+           TransportManager.reconfigure(undefined, 'V2')
            加载 messages-pro2.json
                   ↓
            设备就绪，直接调用 pro2* 系方法
 ```
 
 Pro2 **不支持** `Initialize` 消息。发送它会收到 `Failure_UnexpectedMessage`。
 
-> **关键实现细节**：`detectProtocol()` 在 `acquire()` 内部运行，结果写入
+> **关键实现细节**：`detectProtocol()` 在 `acquire()` 内部按 PID 立即判定，结果写入
 > `WebUsbTransport.deviceProtocol: Map<path, ProtocolType>`。
 > `acquire()` 完成后立即将结果同步到 `device.originalDescriptor.protocolType`，
 > 这样 `initialize()` 才能正确判断分支。
+>
+> BLE 路径不需要探测：Pro2 BLE 走独立的 `ElectronPro2BleTransport` 类，
+> `getProtocolType()` 直接返回 `'V2'`。
 
 ---
 
 ## 协议自动检测
 
 ```typescript
 // packages/hd-transport-web-device/src/webusb.ts
-private async detectProtocol(path: string): Promise<ProtocolType> {
-  // 发送最小 Proto V0 探测帧（Ping, msgType=60206, 空 payload）
-  // 读响应首字节：
-  //   0x5A → PRO2
-  //   0x3F 或超时 → LEGACY
+private detectProtocol(path: string): ProtocolType {
+  const deviceInfo = this.deviceList.find(d => d.path === path);
+  const protocol: ProtocolType =
+    deviceInfo?.device.productId === PID_PRO2 ? 'V2' : 'V1';
+  this.deviceProtocol.set(path, protocol);
+  return protocol;
 }
 
 getProtocolType(path: string): ProtocolType {
-  return this.deviceProtocol.get(path) ?? 'LEGACY';
+  return this.deviceProtocol.get(path) ?? 'V1';
 }
 ```
 
 `call()` 根据检测结果自动分支：
-- `PRO2` → `callProtoV0()`，使用 `messages-pro2.json`
-- `LEGACY` → 原有路径，使用 `messages.json`
+- `V2` → `callProtocolV2()`，使用 `messages-pro2.json`
+- `V1` → 原有路径，使用 `messages.json`
 
 ---
 
-## Schema 选择（callProtoV0 内部）
+## Schema 选择（callProtocolV2 内部）
 
-Pro2 帧内同时可能包含 Pro2 消息和 Legacy 消息（如未来扩展），选择规则：
+V2 帧内同时可能包含 V2 消息和 V1 消息（如未来扩展），选择规则：
 
 ```
 编码（发送）:
-  messagesProV0.lookupType(name) 成功  → 用 Pro2 schema
-  失败（name 只在 legacy schema 中）   → 回退 legacy messages schema
+  messagesV2.lookupType(name) 成功     → 用 V2 schema
+  失败（name 只在 V1 schema 中）       → 回退 V1 messages schema
 
 解码（接收）:
-  rxMsgType >= 60000  → Pro2 schema
-  rxMsgType <  60000  → legacy schema
+  rxMsgType >= 60000  → V2 schema (PROTOCOL_V2_SYS_MESSAGE_THRESHOLD)
+  rxMsgType <  60000  → V1 schema
 ```
 
 ---
@@ -195,7 +199,7 @@ await HardwareSDK.fileDelete(connectId, { path: '/tmp/test.txt' });
 await HardwareSDK.dirMake(connectId, { path: '/tmp/mydir' });
 await HardwareSDK.dirRemove(connectId, { path: '/tmp/mydir' });
 
-// 设备管理 (使用通用 API，内部自动分发到 Pro2 协议)
+// 设备管理 (使用通用 API，内部自动分发到 Protocol V2)
 await HardwareSDK.deviceRebootToBootloader(connectId);
 await HardwareSDK.deviceRebootToBoardloader(connectId);
 ```
@@ -237,7 +241,7 @@ function crc8(data: Uint8Array, init = 0x30): number {
 **Pro2 schema 特殊处理**：
 - `messages_emmc.proto` 中消息名带 `Emmc` 前缀（如 `EmmcFileRead`），构建脚本用 `sed` 去除前缀
 - `Success`/`Failure` 来自 `messages_common.proto`（不在 management proto 中）
-- `Reboot` 是 Proto V0 专属，无对应 proto 源文件，在脚本中手动追加
+- `Reboot` 是 Protocol V2 专属，无对应 proto 源文件，在脚本中手动追加
 - `FailureType` 的限定名（`hw.trezor.messages.common.FailureType`）需 `sed` 去除命名空间，否则 pbjs 静默丢弃
 
 ---
@@ -252,10 +256,10 @@ SDK Interface (@onekeyfe/hd-core)
 Transport Abstraction (@onekeyfe/hd-transport)
     ↓  call() 自动分支
 WebUSB Transport (@onekeyfe/hd-transport-web-device)
-    ├── Legacy path  → buildEncodeBuffers() → 64B 分包 → receiveOne()
-    └── Proto V0 path → buildPbFrame() → 单帧 → parseProtoV0Frame()
+    ├── Protocol V1 path → buildEncodeBuffers() → 64B 分包 → receiveOne()
+    └── Protocol V2 path → buildPbFrame() → 单帧 → parseProtoV2Frame()
     ↓
 Hardware Device
-    ├── Pro1 / Mini / Touch / Classic  (LEGACY)
-    └── Pro2                           (PRO2)
+    ├── Pro1 / Mini / Touch / Classic  (V1)
+    └── Pro2                           (V2)
 ```