M4 双向通信协议接口文档

本文档 Max 与 Standard 两个版本通用，接口内容一致。

版本更新记录

版本号	发布日期	更新类型	更新内容
V2.3.0	2026-07-03	新增	新增错误码 kRegisterModeDisabled（50308）：管理后台禁用对应注册模式（如 enable_pc_registration=false）后，设备端在注册入口拒绝请求并通过 A4 上报该错误码；B0/AB 新增 capabilities 字段，携带设备注册能力标志（pc_registration_enabled / device_qrcode_enabled），租户场景配置变化时随健康状态帧实时更新
V2.2.0	2026-06-02	新增	新增设备健康状态协议（B0/AA/AB）；新增滴码注册（mode=5）、识别进度上报（B2/B3）、加验交互（AD/AE/B4/B5）协议；A6 切换模式支持 mode=0（独立模式）退出联动；A4 扩展 register_mode 字段；B0/AB 扩展 protocol_version、work_mode=0 字段；B3 识别终态新增 countdown_ms（结果页倒计时，便于上位机 UI 与设备对齐）；上位机断连/取消/超时场景下设备主动下发 0xB5 终态（避免上位机停留在选择/等待状态）；0xB0 的 sub_status.last_error_code 补充 50101/50103/50104，便于上位机精确定位非激活原因；补全 AD/AE/B5 协议详细字段说明与联动识别完整时序图
V2.0.0	2026-03-14	新增	新增 userState/palmDirection 字段，支持双掌注册场景
V1.8.0	2026-03-10	功能增强	补充使用场景、架构图、错误码
V1.7.0	2026-01-05	新增	第一版

V2.0 不兼容变更说明： V2.0 版本在 A4（上报录掌结果）协议中新增了 userState、palmDirection、leftPalm、rightPalm 字段。上位机需适配新字段以支持双掌注册场景。V1.x 版本上位机如不解析新字段，不影响已有功能，但无法获取双掌注册状态信息。建议尽快升级至 V2.0 协议。

简介

接口概述

本文档为 M4 刷掌设备的上位机双向通信协议接口文档，描述上位机如何通过 USB 串口与刷掌设备进行指令交互，实现录掌注册、刷掌识别和设备模式管理等核心功能。

适用场景

当前协议支持注册、识别、模式切换三大功能，典型业务场景如下：

1. 录掌注册：柜台工作人员或自助终端在上位机端发起录掌请求，将用户信息（ID、姓名、手机号、银行卡号）通过串口下发到刷掌设备，用户在设备上完成掌纹录入，录入结果回传上位机。支持双掌注册，即同一用户可分两次分别录入左手和右手掌纹，设备会通过 userState 字段反馈当前用户的掌纹录入状态。
2. 刷掌识别：上位机可唤起设备刷掌识别页面，用户完成刷掌后设备将识别到的用户信息（UserId 或 CardNumber）回传上位机，用于身份确认、支付等业务。
3. 模式切换与查询：上位机可查询和切换设备当前的工作模式（识别模式、手机H5录掌、设备端录掌、上位机录掌），灵活适配不同业务场景。支持 mode=0 退出联动，设备恢复为独立工作模式。

核心功能

1. 上位机录掌注册：上位机下发用户信息至设备，用户在设备端完成掌纹录入，支持双掌注册
2. 刷掌识别唤起：上位机唤起设备刷掌识别页面，获取识别到的用户信息
3. 设备模式管理：上位机查询和切换设备工作模式（识别、手机H5录掌、设备端录掌、上位机录掌）

快速开始

环境要求

项目	要求
操作系统	Windows / macOS / Linux
串口驱动	PL2303 驱动（见通用配置章节下载链接）
物理连接	USB 转串口线（PL2303 芯片）
串口参数	波特率 115200，8 位数据位，1 位停止位，无校验，无流控

集成步骤

1. 安装对应操作系统的 PL2303 串口驱动
2. 用 USB 串口线连接上位机与刷掌设备
3. 按照物理层协议配置（115200/8/N/1）打开串口
4. 根据业务场景发送对应命令码（录掌注册用 A1、刷掌识别用 A5、模式切换用 A6）
5. 解析设备返回的响应数据包

最小示例

以下为一次完整的 唤起录掌（A1）→ 录掌信息确认（A2） 交互的 16 进制示例：

上位机 → 设备（A1 唤起录掌）：

5A 5A 5A 5A 00 01 A1 00 65 7B 22 75 73 65 72 49 64 22 3A 22 61 61 61 61 61 61 61 61 22 2C 22 75 73 65 72 4E 61 6D 65 22 3A 22 E6 B5 8B E8 AF 95 E4 BA BA E5 91 98 22 2C 22 70 68 6F 6E 65 22 3A 22 31 35 39 39 37 34 37 35 36 38 30 22 2C 22 70 68 79 73 69 63 61 6C 43 61 72 64 4E 75 6D 62 65 72 22 3A 22 31 32 33 34 35 36 37 38 22 7D AA

设备 → 上位机（A2 录掌信息确认）：

5A 5A 5A 5A 00 01 A2 00 00 A3

数据包结构说明：起始字符(4B) + 包序号(2B, 大端) + 命令码(1B) + 数据域长度(2B, 大端) + 数据域(NB) + BCC校验(1B)

接口概览

使用场景

本文档描述上位机（如PC、收银机、自助终端等外部主机）如何通过串口（USB转串口，芯片型号PL2303）与**刷掌设备（M4）**进行双向通信的协议规范。

前置条件

• 设备与上位机通过 USB 串口线（PL2303 芯片）物理连接
• 上位机已安装对应操作系统的串口驱动，注意，macos还要启用驱动：登录项与扩展--驱动扩展程序--开启 PL2303Serial驱动
• 设备端需切换至**上位机录掌模式（mode=4）**方可执行录掌注册协议

系统架构

通讯模式说明：

• 上位机与刷掌设备通过 USB 转串口（PL2303 芯片）连接，采用命令-响应模式进行双向通信
• 上位机→设备：发送指令（唤起录掌、取消录掌、唤起识别、切换/查询模式）
• 设备→上位机：返回确认、上报结果（录掌结果、识别用户信息、模式切换结果、当前模式）

上位机录掌注册时序

通用配置与协议

上位机驱动

**命令码**	**功能描述**	**通信方向**
A1	唤起录掌	上位机 → 设备
A2	录掌信息确认	设备 → 上位机
A3	取消录掌	上位机 → 设备
A4	上报录掌结果	设备 → 上位机
A5	唤起刷掌识别	上位机 → 设备
A5（响应）	上报刷掌用户信息	设备 → 上位机
A6	切换模式（mode=0 退出联动 / mode=1~5 进入联动）	上位机 → 设备
A7	上报切换模式结果	设备 → 上位机
A8	查询设备模式	上位机 → 设备
A9	响应查询模式	设备 → 上位机
F0	未知命令码错误响应	设备 → 上位机
AD	回传加验值（phone_no / custom_field）[v2.2.0 新增]	上位机 → 设备
AE	取消加验 [v2.2.0 新增]	上位机 → 设备
B1	注册中间状态通知（滴码注册进度）[v2.2.0 新增]	设备 → 上位机
B2	识别阶段事件通知 [v2.2.0 新增]	设备 → 上位机
B3	识别终态结果 [v2.2.0 新增]	设备 → 上位机
B4	拉起加验输入（含 timeout_ms）[v2.2.0 新增]	设备 → 上位机
B5	加验终态结果 [v2.2.0 新增]	设备 → 上位机

**操作系统**	**下载链接**
macOS	[‎PL2303 Serial App](https://apps.apple.com/cn/app/pl2303-serial/id1624835354?mt=12)
Windows	[PL2303GL](https://www.prolific.com.tw/portfolio-item/pl2303gl/)

鉴权方式

本协议为设备本地串口通信协议，上位机与刷掌设备通过 USB 物理直连，不需要握手认证或鉴权。设备上电后即可接收上位机指令，无需设备激活、密钥交换等前置流程。设备端的云端鉴权（如 token 认证）由设备内部自行管理，与上位机串口通信无关。

物理层协议配置

**参数**	**配置**
波特率	115200
数据位	8
停止位	1
校验位	None
流控	None

通用数据包格式示例

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	A1	0001	01	2D

• 起始字符（4字节）：

  包开始的标识，固定为 0x5A5A5A5A

• 包序号（2字节，大端字节序 Big-Endian）：

  从0开始，每发送一个数据包就加一，累加至 0xFFFF 后再循环至 0，刷掌设备返回序号与上位机发送命令包序号一致，该参数由上位机主动更新维护

• 命令码（1字节）：

  用于区分不同类的命令，在业务场景会介绍相关命令码

• 数据域长度（2字节，大端字节序 Big-Endian）：

  用来表示包中数据域中数据的长度，该值不包含校验位的长度

• 数据域（根据数据域长度确定）：

  此字段的含义按各命令解析，有的命令可能没有此字段

• 校验位（1字节）

  这里采用 BCC 校验，为除起始字符外其他数据的异或值

字节序说明： 本协议中所有多字节字段（包序号 2 字节、数据域长度 2 字节）均采用大端字节序（Big-Endian），即高位字节在前、低位字节在后。例如包序号 0x0001 在串口上传输为 00 01。

上位机录掌注册协议

注：该协议流程需在设备端处于上位机录掌模式下才可正确执行

【上位机→设备】 唤起录掌

上位机唤起设备录掌，并提供相应录掌信息，包括用户ID、用户名、手机号以及银行卡号。唤起成功后，相应信息会显示在设备主界面，提示用户开始注册掌纹

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**A1**	数据长度决定	用户信息	BCC 计算获得

• 传输数据格式：

  {
      "userId": "user123456",
      "userName": "测试人员",
      "phone": "15997475680",
      "physicalCardNumber": "12345678"
  }

• 通信数据示例（16进制）：

   5A 5A 5A 5A 00 01 A1 00 65 7B 22 75 73 65 72 49 64 22 3A 22 61 61 61 61 61 61 61 61 22 2C 22 75 73 65 72 4E 61 6D 65 22 3A 22 E6 B5 8B E8 AF 95 E4 BA BA E5 91 98 22 2C 22 70 68 6F 6E 65 22 3A 22 31 35 39 39 37 34 37 35 36 38 30 22 2C 22 70 68 79 73 69 63 61 6C 43 61 72 64 4E 75 6D 62 65 72 22 3A 22 31 32 33 34 35 36 37 38 22 7D AA

【设备→上位机】录掌信息确认

刷掌设备接收到上位机发送的唤起录掌指令后，发送该指令告知上位机，已经接收到用户数据，并处于录掌流程中

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**A2**	0000	无	A3

• 通信数据示例（16进制）：

   5A 5A 5A 5A 00 01 A2 00 00 A3

【上位机→设备】取消录掌

上位机在等待用户在刷掌设备录掌结果的过程中，可以发送指令取消录掌

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**A3**	0000	无	A2

• 通信数据示例（16进制）：

   5A 5A 5A 5A 00 01 A3 00 00 A2

【设备→上位机】上报录掌结果

刷掌设备在用户录掌成功/失败后会返回对应的录掌结果，上位机可根据结果显示对应界面

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**A4**	数据长度决定	录掌结果	BCC 计算获得

• 传输数据格式：

  {
      "resultCode": 0,
      "resultMessage": "success",
      "palmDirection": "1",
      "userState": "left_valid",
      "leftPalm": {},
      "rightPalm": {}
  }

• 字段说明：

**字段名**	**类型**	**必返回**	**说明**
resultCode	int	是	录掌结果码，0 表示成功，非 0 表示失败（具体见错误码列表）
resultMessage	string	是	录掌结果描述
palmDirection	string	是	本次录入的刷掌方向。"1" = 左手，"2" = 右手，"-1" = 未知
userState	string	成功时返回	用户掌纹状态（仅 resultCode=0 时有意义），具体取值见下方 userState 枚举表
leftPalm	object	否	左掌详细信息（可选），透传后端返回的左掌 JSON 对象。后端未返回时不包含此字段。具体子字段见下方 leftPalm/rightPalm 结构说明
rightPalm	object	否	右掌详细信息（可选），透传后端返回的右掌 JSON 对象。后端未返回时不包含此字段。具体子字段见下方 leftPalm/rightPalm 结构说明
register_mode	string	是	[v2.2.0 新增] 注册方式：host（上位机录掌）/ cpm（滴码注册）。上位机可据此区分两种注册流程的结果

• leftPalm / rightPalm 对象结构说明（PalmInfo）：

**字段名**	**类型**	**说明**
PalmState	string	手掌状态：unregistered（未注册）/ pre_registered（空中录掌已完成）/ registered（已注册）
RegisterType	string	注册方式：Device（设备端录掌）/ Mobile（手机H5录掌）
PreRegisterTime	string	空中录掌时间，RFC3339 格式（如 "2026-03-16T12:00:00Z"）
RegisterTime	string	完成录掌时间，RFC3339 格式
ExpireTime	string	掌纹过期时间，RFC3339 格式

• palmDirection 取值说明：

**值**	**说明**
"1"	左手
"2"	右手
"-1"	未知（异常情况）

• userState 取值说明：

**值**	**说明**	**是否可继续录另一只手**
both_unregistered	双掌均未录入（新创建用户）	是
not_activated	用户未激活	是
left_valid	左掌已录入	是（可录右手）
right_valid	右掌已录入	是（可录左手）
both_valid	双掌均已录入	否（双掌已满）

• 错误码列表：

注意： 本文档（V2.0）使用 5 位数错误码编码体系，后续版本将进一步迁移至统一的 TxCode 编码体系。

**错误码**	**说明**
0	录掌注册成功
20102	网络请求失败（设备无法连接云端服务）
20407	云端服务返回业务错误，具体原因参考 resultMessage 字段
50003	掌纹模组运行时错误（录掌过程中模组异常）
50010	该用户掌纹已注册（重复注册，含设备端本地检测）
50011	注册失败（通用注册错误）
50305	云端未找到对应用户（用户ID不匹配）
50306	用户名与云端记录不匹配
50901	上位机下发的用户信息无效（userId 或 userName 为空）
其他	未知错误，建议重试。具体原因参考 resultMessage 字段

• 成功响应示例（JSON）：

  {
      "resultCode": 0,
      "resultMessage": "success",
      "palmDirection": "1",
      "userState": "left_valid",
      "leftPalm": {
          "PalmState": "registered",
          "RegisterType": "Device",
          "PreRegisterTime": "2026-03-16T10:00:00Z",
          "RegisterTime": "2026-03-16T12:00:00Z",
          "ExpireTime": "2027-03-16T12:00:00Z"
      }
  }

• 失败响应示例（JSON）：

  {
      "resultCode": 50010,
      "resultMessage": "duplicate register",
      "palmDirection": "2",
      "userState": "",
      "leftPalm": {
          "PalmState": "registered",
          "RegisterType": "Device",
          "RegisterTime": "2026-03-15T08:30:00Z",
          "ExpireTime": "2027-03-15T08:30:00Z"
      },
      "rightPalm": {
          "PalmState": "unregistered"
      }
  }

注： leftPalm 和 rightPalm 为可选字段，仅在后端接口返回了对应掌纹信息时才会包含在响应中。字段内容为后端原样透传的 PalmInfo JSON 对象，各子字段（PalmState、RegisterType、PreRegisterTime、RegisterTime、ExpireTime）根据后端实际返回情况可能部分缺省。

双掌注册业务流程

设备支持双掌注册，即同一用户可分两次分别录入左手和右手掌纹。上位机可通过返回结果中的 userState 字段判断当前用户的掌纹录入进度，并决定是否需要引导用户录入另一只手：

上位机处理建议：

收到的 userState	建议行为
both_unregistered / not_activated	首次录掌成功（新用户），可引导用户继续录另一只手
left_valid	左手已录入，可引导用户录入右手
right_valid	右手已录入，可引导用户录入左手
both_valid	双掌均已录入，注册流程完成

上位机刷掌识别协议

注：该协议流程需在设备端处于识别模式下才可正确执行

【上位机→设备】唤起刷掌识别

上位机唤起设备刷掌识别，唤起成功后，设备会弹出页面提示用户刷掌（该协议仅唤起提示页面，不通过该协议仍可通过设备刷掌）

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**A5**	0000	无	A4

• 通信数据示例（16进制）：

   5A 5A 5A 5A 00 01 A5 00 00 A4

【设备→上位机】上报刷掌用户信息

刷掌设备在用户刷掌识别成功后会返回对应的用户信息，该信息类型可在设备 Output Mode 设置中选择 UserId 或 CardNumber

• **通信协议：**裸数据传输，不走上述通用数据协议。设备直接通过串口发送用户信息的原始字节数据（UTF-8 编码字符串），无包头、包序号、命令码、校验位等封装。

• 字段说明：

  设备根据 Output Mode 设置，返回以下两种字段之一：

**字段名**	**类型**	**Output Mode**	**说明**
UserId	string	UserID 模式（mode=1）	用户唯一标识，与录掌注册时上位机下发的 userId 一致。长度不固定，通常为 6~32 个 ASCII 字符
CardNumber	string	CardNumber 模式（mode=2）	用户银行卡号，与录掌注册时上位机下发的 physicalCardNumber 一致。长度不固定，通常为 10~19 位数字字符串

• 数据格式说明：

  设备根据 Output Mode 设置，返回以下两种格式之一：

  模式一：UserId 模式

  设备直接发送用户 ID 字符串的 UTF-8 字节流，例如：

  user123456

  对应 16 进制数据：

  75 73 65 72 31 32 33 34 35 36

  模式二：CardNumber 模式

  设备直接发送银行卡号字符串的 UTF-8 字节流，例如：

  6222021234567890

  对应 16 进制数据：

  36 32 32 32 30 32 31 32 33 34 35 36 37 38 39 30

• 数据传输结束标志说明：

  该协议采用裸数据传输，无显式的数据传输结束标志。上位机应通过以下方式判断数据接收完成：

  1. 串口空闲超时：上位机在收到第一个字节后，启动一个短超时计时器（建议 100~200ms）。若在超时时间内未收到新数据，则认为本次传输完成
  2. 数据长度预判：UserId 通常为 632 字节，CardNumber 通常为 1019 字节。上位机可结合已接收数据长度辅助判断
  3. 区分协议帧与裸数据：裸数据不以 0x5A5A5A5A 起始，上位机可通过检查接收数据的前 4 字节来区分本协议与通用协议帧数据

• 上位机处理说明：

  1. 上位机收到串口数据后，按 UTF-8 解码为字符串即可获得用户信息
  2. 根据当前设备的 Output Mode 设置判断返回的是 UserId 还是 CardNumber
  3. 如识别失败，设备不会通过该协议发送数据（无响应）
  4. 识别超时处理：上位机发送 A5 唤起识别后，建议设置一个业务超时（如 30 秒）。若超时未收到设备返回的用户信息，应视为本次识别无结果，可提示用户重试或执行其他业务逻辑
  5. 异常场景处理：若串口连接断开（设备拔线等），上位机应捕获串口异常事件，终止当前等待并提示用户检查设备连接

• 识别错误码说明：

  A5 协议的识别响应采用裸数据传输，识别成功时设备直接返回用户信息字符串；识别失败时设备不发送任何数据（无响应）。上位机应通过超时机制判断识别是否失败。

  以下为可能导致识别无响应的场景：

**场景**	**说明**	**上位机处理建议**
识别超时	用户未在有效时间内完成刷掌	提示用户重试
未匹配用户	掌纹识别成功但未找到匹配的注册用户	提示用户先注册掌纹
设备未就绪	设备模组未初始化或处于异常状态	检查设备状态，必要时重启设备
掌纹质量不合格	采集的掌纹图像质量未达到识别要求	提示用户调整手掌姿势后重试
网络异常	云端识别模式下设备无法连接云端服务	检查设备网络连接

上位机模式切换协议

注：mode=1~5 联动模式切换需在设备端处于主界面下才可正确执行；mode=0 退出联动不受此限制

【上位机→设备】 切换模式

上位机控制切换设备当前所处刷掌模式

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**A6**	数据长度决定	需切换的模式	BCC 计算获得

• 传输数据格式：

  {
      "mode": 1
  }

• 工作模式列表：

**值**	**模式**	**说明**
0	独立模式（退出联动）[v2.2.0 新增]	设备退出与上位机的联动，按本地持久化配置独立工作。设备不再向上位机推送识别进度（B2）、识别结果（B3）、加验请求（B4）、加验结果（B5）等通知。上位机再次发送 mode=1~5 可重新进入联动模式。**设备启动后默认处于此模式。**
1	识别模式	进入联动识别模式，刷掌结果推送给上位机
2	注册模式 - 手机H5录掌	-
3	注册模式 - 设备端录掌	-
4	注册模式 - 上位机录掌	-
5	注册模式 - 滴码注册（CPM QR Code）[v2.2.0 新增]	-

• 通信数据示例（16进制）：

   5A 5A 5A 5A 00 01 A6 00 0B 7B 22 6D 6F 64 65 22 3A 20 31 7D 82

【设备→上位机】上报切换的模式

刷掌设备在接收到上位机模式切换指令后，通过该协议返回模式切换结果，上位机可根据结果判断切换是否成功

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**A7**	数据长度决定	模式切换结果	BCC 计算获得

• 传输数据格式：

  {
      "code": 0,
      "message": "Success"
  }

• 错误码列表：

**错误码**	**说明**
0	模式切换成功
10100	参数错误，切换的模式不在合法范围内（0~5）
10501	请求数据格式解析失败
50902	当前设备未处在主界面（仅 mode=1~5 时触发，mode=0 退出联动不受此限制）
其他	模式切换失败，请重试

• 通信数据示例（16进制）：

  5A 5A 5A 5A 00 01 A7 00 1E 7B 22 63 6F 64 65 22 3A 20 30 2C 22 6D 65 73 73 61 67 65 22 3A 20 22 53 75 63 63 65 73 73 22 7D D9

上位机模式查询协议

【上位机→设备】查询设备模式

上位机查询设备当前所处模式

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**A8**	0000	无	A9

• 通信数据示例（16进制）：

   5A 5A 5A 5A 00 01 A8 00 00 A9

【设备→上位机】 响应查询模式

在上位机发送查询指令后，设备通过该协议返回当前所处模式

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**A9**	数据长度决定	当前所处模式	BCC 计算获得

• 传输数据格式：

  {
      "mode": 1
  }

• mode 字段枚举值说明：

**值**	**模式**
0	独立模式（未与上位机联动）[v2.2.0 新增]
1	识别模式
2	注册模式 - 手机H5录掌
3	注册模式 - 设备端录掌
4	注册模式 - 上位机录掌
5	注册模式 - 滴码注册（CPM QR Code）[v2.2.0 新增]

• 通信数据示例（16进制）：

   5A 5A 5A 5A 00 01 A9 00 0B 7B 22 6D 6F 64 65 22 3A 20 31 7D 8D

上位机联动识别·识别进度与加验交互协议

本章节自 V2.2.0 引入。仅在联动识别模式 (mode=1) 下生效。设备进入独立模式（mode=0）后不会推送本章节定义的 B2/B3/B4/B5 帧，AD/AE 帧也不再处理。

【设备→上位机】RecognizeProgressNotify（cmd 0xB2）

设备在识别过程中将关键阶段事件推送给上位机，便于上位机刷新 UI / 业务计数。本帧为中间事件（非终态），同一次识别可能会推送多次。

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**B2**	数据长度决定	识别阶段事件	BCC 计算获得

• 传输数据格式：

  {
      "session_id": "sess_a1b2c3",
      "event_id": 11,
      "error_code": 0,
      "error_msg": ""
  }

• 字段说明：

**字段**	**类型**	**说明**
session_id	string	当前识别会话 ID，由设备生成，与同会话内 B3 / B4 / B5 帧保持一致
event_id	int	识别阶段事件枚举（PalmProcessEventId），如检测到掌纹 / 算法预选 / 业务校验 等节点
error_code	int	该阶段的错误码，0 表示阶段成功
error_msg	string	该阶段的错误描述（非空时为人类可读文案，可直接展示或记录日志）

上位机如不关心识别中间过程，可忽略本帧；只消费 B3 终态结果即可完成识别业务闭环。

【设备→上位机】RecognizeResultReq（cmd 0xB3）

识别终态结果。每一次完整识别会话至多一帧 B3，作为该次识别的最终结论。

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**B3**	数据长度决定	识别终态结果	BCC 计算获得

• 传输数据格式（成功示例）：

  {
      "session_id": "sess_a1b2c3",
      "result_code": 0,
      "error_msg": "",
      "palm_id": "palm_xxx",
      "user_id": "user_001",
      "user_name": "Alice",
      "retrieve_source": 1,
      "countdown_ms": 1000
  }

• 传输数据格式（失败示例）：

  {
      "session_id": "sess_a1b2c3",
      "result_code": 30002,
      "error_msg": "verify user timeout",
      "palm_id": "",
      "user_id": "",
      "user_name": "",
      "retrieve_source": 0,
      "countdown_ms": 3000
  }

• 字段说明：

**字段**	**类型**	**说明**
session_id	string	当前识别会话 ID，与本会话 B2 / B4 / B5 一致，用于上位机串联同一次识别的多帧消息
result_code	int	识别最终结果错误码，0 表示识别成功（可直接放行业务），非 0 表示失败
error_msg	string	失败原因的人类可读描述，result_code=0 时为空字符串
palm_id	string	掌纹特征 ID。识别命中时非空；识别未命中或失败可能为空字符串
user_id	string	命中用户的业务 ID。result_code=0 时必非空；识别未命中（如黑名单 / 加验失败 / 未注册）时可能为空
user_name	string	命中用户的业务昵称。识别未命中时为空字符串
retrieve_source	int	检索结果来源：0=未知/不适用，1=设备端检索，2=空中开掌小库检索，3=云端大库检索
countdown_ms	int	[v2.2.0 新增] 设备识别结果页倒计时（毫秒），到时设备会自动回到首页准备下一次识别。result_code=0 时取成功页倒计时（默认 1000ms），非 0 时取失败页倒计时（默认 3000ms）；上位机可与该值对齐自身 UI 倒计时显示，避免设备已回首页而上位机仍停留在结果页

同一次识别 B3 仅推送一次。若识别命中且无加验需求，B3 即为终态；若需要加验，B3 会在加验流程结束后由设备汇总发送（与 B5 加验结果共同构成终态）。

【设备→上位机】VerifyPromptNotify（cmd 0xB4）

设备端因加验策略需要进一步用户输入（手机号 / 自定义字段 / 扫码）时，将本帧推送给上位机，由上位机弹出输入界面收集用户输入。

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**B4**	数据长度决定	加验输入提示	BCC 计算获得

• 传输数据格式（手机号加验示例）：

  {
      "session_id": "sess_a1b2c3",
      "verify_method": "phone_no",
      "user_ids": ["user_001", "user_002"],
      "timeout_ms": 30000
  }

• 传输数据格式（自定义字段加验示例）：

  {
      "session_id": "sess_a1b2c3",
      "verify_method": "custom_field",
      "user_ids": ["user_001"],
      "timeout_ms": 30000,
      "custom_field_label": "工号"
  }

• 传输数据格式（扫码加验示例）：

  {
      "session_id": "sess_a1b2c3",
      "verify_method": "qr_code",
      "user_ids": ["user_001", "user_002", "user_003"],
      "timeout_ms": 30000
  }

• 字段说明：

**字段**	**类型**	**必选**	**说明**
session_id	string	是	当前识别会话 ID，与本会话 B2 / B3 / B5 一致；上位机回传 AD / AE 时必须填回该值，否则设备将无法关联
verify_method	string	是	加验方式枚举： • phone_no：手机号加验，上位机弹出手机号输入框 • custom_field：自定义字段加验，上位机弹出自定义文本输入框（label 由 custom_field_label 指定） • qr_code：扫码加验，上位机引导用户扫描小程序码完成核验（无需收集用户输入，仅做提示）
user_ids	string[]	是	候选用户 ID 列表，由设备识别预选阶段产生： • 长度 = 1：单候选预检查场景（如高相似度命中单一用户） • 长度 > 1：多候选场景（需要用户输入加验值进一步消歧） 该字段仅供上位机展示参考，回传 AD 时**不**需要再次提供（设备会按 session_id 复用）
timeout_ms	int	是	加验输入超时时间（毫秒），上位机应据此渲染倒计时；超过该时长未回传 AD 则视为加验超时，设备会主动结束本次识别并下发 B5 / B3
custom_field_label	string	否	自定义字段加验的输入框 label（如 "工号" / "员工号"）。仅在 verify_method=custom_field 时存在；其他加验方式下设备不下发该字段

• 后续帧时序：

  收到本帧后，上位机应在 timeout_ms 内执行下列任一操作：

  1. 用户完成输入 → 上位机回传 0xAD VerifyInputResp（携带 session_id + verify_method + input_value），设备端发起后台校验，校验完成后下发 0xB5 VerifyResultNotify
  2. 用户主动取消 → 上位机回传 0xAE VerifyCancelReq（仅携带 session_id），设备端立即终止本次加验
  3. 用户超时未操作 → 上位机不回包，设备端在 timeout_ms 到期时自行回退，并下发 0xB5 表明加验失败

【上位机→设备】VerifyInputResp（cmd 0xAD）

上位机将用户输入的加验值（手机号 / 自定义字段）回传给设备，设备据此发起后台校验。

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**AD**	数据长度决定	加验输入值	BCC 计算获得

• 传输数据格式（手机号示例）：

  {
      "session_id": "sess_a1b2c3",
      "verify_method": "phone_no",
      "input_value": "13800001111"
  }

• 传输数据格式（自定义字段示例）：

  {
      "session_id": "sess_a1b2c3",
      "verify_method": "custom_field",
      "input_value": "EMP10086"
  }

• 字段说明：

**字段**	**类型**	**必选**	**说明**
session_id	string	是	必须填回 0xB4 中下发的 session_id，否则设备无法关联本次加验
verify_method	string	是	与 0xB4 中下发的 verify_method 一致：phone_no / custom_field。 注：qr_code 加验在设备端完成扫码闭环，**不**需要上位机回传 AD
input_value	string	是	用户输入的加验值（手机号或自定义字段文本）。设备端按 verify_method 解释该字段

设备端接收到 AD 后会进入后台校验阶段，最终下发 0xB5 VerifyResultNotify 通告加验结论；随后再下发 0xB3 RecognizeResultReq 作为整次识别的终态。

【上位机→设备】VerifyCancelReq（cmd 0xAE）

上位机用户主动取消加验输入，设备端立即终止本次加验，并按"加验失败"路径汇总下发 0xB5 / 0xB3。

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**AE**	数据长度决定	取消加验	BCC 计算获得

• 传输数据格式：

  {
      "session_id": "sess_a1b2c3"
  }

• 字段说明：

**字段**	**类型**	**必选**	**说明**
session_id	string	是	要取消的加验会话 ID，必须与 0xB4 一致

设备端收到 AE 后会立即下发 0xB5（code = 30000 kTaskCancelled），随后下发 0xB3（result_code = 50903 kHostVerifyUserCancel）作为整次识别的终态。

【设备→上位机】VerifyResultNotify（cmd 0xB5）

设备端在加验后台校验完成、加验取消、加验超时、或上位机断连后的兜底场景下，将加验环节的最终结论推送给上位机。该帧仅作为加验环节的终态，整次识别的终态仍以 0xB3 为准。

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**B5**	数据长度决定	加验终态结果	BCC 计算获得

• 传输数据格式（加验通过示例）：

  {
      "session_id": "sess_a1b2c3",
      "code": 0,
      "msg": "verify success",
      "pass_user_id": "user_001"
  }

• 传输数据格式（用户取消示例）：

  {
      "session_id": "sess_a1b2c3",
      "code": 30000,
      "msg": "user cancel"
  }

• 传输数据格式（加验超时示例）：

  {
      "session_id": "sess_a1b2c3",
      "code": 30002,
      "msg": "verify user timeout"
  }

• 字段说明：

**字段**	**类型**	**说明**
session_id	string	当前识别会话 ID，与本会话 B2 / B3 / B4 一致
code	int	加验结果错误码： • 0：加验通过 • 30000 kTaskCancelled：用户主动取消（含 AE 取消、本地 LoadingPage 取消、上位机断连兜底取消） • 30002 kTaskTimeout：加验超时（含 timeout_ms 到期、本地 LoadingPage 倒计时到期） • 其他：后台校验失败的具体业务错误码
msg	string	结果文字描述（人类可读，code=0 时为成功描述，否则为失败原因）
pass_user_id	string	加验通过时命中的用户 ID。code=0 时必非空；非 0 失败时该字段被省略，上位机解析时按缺省/空字符串处理

断连兜底说明： 当设备端处于"等待上位机回传 AD"状态时，若 USB 物理拔出或上位机进程退出导致串口断连，设备端会主动触发取消/超时回收：先按 code=30000 推送 B5（fire-and-forget，断连情况下实际不会到达上位机，仅用于内部状态收尾），再下发 0xB3 终态结束本次识别会话，避免设备停留在加验中间态。

上位机联动识别完整时序

下图展示联动识别模式（mode=1） 下，从设备启动识别到 B3 终态的完整双向交互。覆盖以下分支：识别命中→直接放行、命中预选→需要加验→输入通过、需要加验→用户取消、需要加验→上位机断连兜底。

会话串联： 同一次识别的 B2 / B3 / B4 / B5 / AD / AE 帧均使用同一个 session_id。设备进入下一轮识别时会生成新的 session_id，上位机收到 B2 携带新 session 时应立即清空上一轮的展示状态（识别结果页 / 加验输入框）。

上位机设备健康状态协议

本章节自 V2.1.0 引入。设备端聚合"网络 / PDM 模组 / 激活 / 租户 / 授权"等多类来源后，对外暴露统一的高阶 health_state 字段，让上位机用单一指标决定 UI 显示与文案，并通过 sub_status 子状态字段告知是否需要人工干预、要做什么。

触发时机

设备端在以下任一情形下发送 cmd 0xB0 DeviceStatusNotify：

1. 周期上报：设备启动后每 30s 自动上报一次（与"每30秒自动刷新"保持一致）
2. 异常变化即时上报：以下任一信号触发健康状态翻转时，100ms 内推送一帧（带 200ms 单次延时合并去抖）：
   • 网络在/离线状态翻转（Wi-Fi / 以太网）
   • PDM 模组工作状态变化为 Error / Blocked 或从异常恢复
   • 设备需要扫码激活（needActivation）
   • 租户启用/禁用切换（tenantStatusChanged）
   • 服务初始化失败命中 kPalmAuthFailed (50000) / kPalmModuleError (50001) / kIotNotRegistered (50105)
   • 心跳/激活态被云端清除：kKeyExpired (50101) / kHeartbeatOCodeChanged (50103) / kHeartbeatUnbindFromScene (50104)，设备会清空本地激活数据并下发 health_state=20，sub_status.last_error_code 指示具体原因码
   • [v2.3.0 新增] 租户场景配置变化（enable_pc_registration / enable_device_qrcode 等注册能力标志更新），capabilities 字段随帧携带最新值
3. 上位机主动查询：上位机发送 cmd 0xAA QueryDeviceStatusReq，设备 1 秒内回包 0xAB QueryDeviceStatusResp，payload 字段集合与 0xB0 完全一致

注意：旧版上位机（不识别 0xB0/0xAA/0xAB）收到不识别的 cmd 时应忽略该帧，设备端只负责按规范发送。

health_state 取值表（数值越大越严重，取所有源中最严重的一个）

**取值**	**枚举名**	**含义**	**human_action_hint**
0	HEALTHY	所有维度正常，可正常使用（含睡眠态 S0/S1）	""
10	WARN_NETWORK_OFFLINE	仅网络离线，其他维度健康	check_network
20	NEED_INTERVENTION_NOT_ACTIVATED	设备未激活，需扫码激活	scan_qr_to_activate
21	NEED_INTERVENTION_TENANT_DISABLED	租户被禁用	contact_admin_tenant_disabled
22	NEED_INTERVENTION_SERVICE_DISABLED	服务被禁用	contact_admin_service_disabled
30	ERROR_PALM_AUTH_FAILED	模组授权失败/过期	contact_admin_palm_auth
31	ERROR_PALM_MODULE	PDM 模组异常	check_palm_module
32	ERROR_PALM_BLOCKED	PDM 模组黑名单/阻塞	check_palm_module
99	UNKNOWN	启动初期尚未取到有效状态	""

【设备→上位机】DeviceStatusNotify（cmd 0xB0）

设备主动上报当前健康状态。

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**B0**	数据长度决定	JSON（见下方字段表）	BCC 计算获得

• 数据域 JSON 字段：

**字段**	**类型**	**说明**
sn	string	设备序列号
timestamp	string	毫秒级 Unix 时间戳（避免大整数精度丢失，用 string 承载）
app_version	string	设备应用版本号
work_mode	int	当前工作模式（0=独立模式，1~5=联动模式，与 A9 的 mode 字段一致）
health_state	int	高阶健康状态（取值见上表）
network_status	int	0=离线，1=在线
network_type	int	0=未连接，1=有线，2=Wi-Fi
protocol_version	string	[v2.2.0 新增] 协议版本号（如 "1.1.0"），上位机可据此判断设备支持哪些扩展能力；"1.1.0" 表示支持滴码注册/识别进度/加验交互协议
sub_status	object	子状态明细（见下表）
capabilities	object	[v2.3.0 新增] 设备注册能力标志（见下表）。旧版上位机收到此字段时应忽略；旧版设备不携带此字段时，上位机默认两种注册方式均可用

• sub_status 子字段：（全部必传，无对应来源时填默认值，不省略 key）

**字段**	**类型**	**说明**
module_status	int	PDM 模组状态（yt_aikit::DeviceStatus），未知/未连接=0
is_activated	int	0=未激活，1=已激活
tenant_status	int	1=启用，2=禁用，0=未知
palm_auth_ok	int	0=授权失败/过期，1=授权正常
service_enabled	int	1=服务可用，0=后台已禁用
last_error_code	int	最近一次触发"非 HEALTHY"的 TxCode，无则为 0。 常见取值（用于配合 health_state=20 NEED_INTERVENTION_NOT_ACTIVATED 精确定位激活/解绑原因）： • 50101 kKeyExpired：设备 Key 过期被清除 • 50103 kHeartbeatOCodeChanged：心跳发现主体变化（如被云端删除后重新分配） • 50104 kHeartbeatUnbindFromScene：心跳从场景解绑/换绑 • 50105 kIotNotRegistered：设备从未激活 • 50000 kPalmAuthFailed / 50001 kPalmModuleError：模组授权或运行异常
human_action_hint	string	简短英文操作提示（由上位机做 i18n 翻译，取值见 health_state 表）

• capabilities 子字段：

**字段**	**类型**	**说明**
host_register	int	1=支持上位机注册（用户名注册，mode=4），0=不支持。综合编译选项（YT_DISABLE_HOST_REGISTER）和租户配置（enable_pc_registration）两个维度，任一不可用则为 0
cpm_register	int	1=支持滴码注册（CPM，mode=5），0=不支持。由租户配置（enable_device_qrcode）决定

• JSON 示例：

{
  "sn": "M4-DEV-2026-001",
  "timestamp": "1716700000000",
  "app_version": "v2.1.0.0-abc123",
  "work_mode": 1,
  "health_state": 0,
  "network_status": 1,
  "network_type": 1,
  "sub_status": {
    "module_status": 5,
    "is_activated": 1,
    "tenant_status": 1,
    "palm_auth_ok": 1,
    "service_enabled": 1,
    "last_error_code": 0,
    "human_action_hint": ""
  },
  "capabilities": {
    "host_register": 1,
    "cpm_register": 1
  }
}

【上位机→设备】QueryDeviceStatusReq（cmd 0xAA）

上位机主动查询设备健康状态。

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**AA**	0000	无	BCC 计算获得

• 说明： 查询不需要任何入参；即使携带非法 / 空 payload，设备端也会忽略 payload 并正常回包 0xAB，不会返回 UnsupportedCmdNotify。
• 响应： 设备在 1 秒内回包 cmd 0xAB。
• 通信数据示例（16进制）：

   5A 5A 5A 5A 00 01 AA 00 00 AA

【设备→上位机】QueryDeviceStatusResp（cmd 0xAB）

设备响应上位机的健康状态查询，payload 字段集合与 0xB0 完全一致，便于上位机用同一个解析器。

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**AB**	数据长度决定	JSON（同 0xB0）	BCC 计算获得

设备处于任何工作模式（识别 / 录掌 / 上位机录掌等）时都能响应该查询，不限页面、不限模式；即使整体处于 NEED_INTERVENTION_* / ERROR_*（如未激活、模组异常）也能正常回包，保证上位机始终能拿到最新故障详情。

错误状态响应协议

【设备→上位机】未知命令码

刷掌设备在接收到未知命令码时做出响应

• 通信协议：

**起始字符**	**包序号**	**命令码**	**数据域长度**	**数据域**	**校验位**
5A5A5A5A	0001	**F0**	数据长度决定	未知命令码	BCC 计算获得

• 传输数据格式：

  {
      "cmd": 10
  }

• 通信数据示例（16进制）：

   5A 5A 5A 5A 00 01 F0 00 0B 7B 22 63 6D 64 22 3A 20 31 30 7D 8D

数据结构定义

PalmInfo 结构体

PalmInfo 用于描述单只手掌的注册状态信息，在 A4 上报录掌结果时通过 leftPalm / rightPalm 字段返回。

字段名	类型	说明
PalmState	string	手掌状态，取值见下方 PalmState 枚举
RegisterType	string	注册方式：Device（设备端录掌）/ Mobile（手机H5录掌）
PreRegisterTime	string	空中录掌时间，RFC3339 格式（如 2026-03-16T12:00:00Z）
RegisterTime	string	完成录掌时间，RFC3339 格式
ExpireTime	string	掌纹过期时间，RFC3339 格式

PalmState 枚举

PalmState 表示单只手掌的注册状态，完整取值如下：

枚举值	说明
unregistered	未注册
pre_registered	空中录掌已完成（待设备端确认录入）
registered	已完成注册

---

全局错误码汇总

以下为上位机与设备通信过程中可能遇到的所有错误码汇总，按场景分类整理。

录掌注册错误码（A4 上报录掌结果）

设备通过命令码 A4 上报录掌结果时，resultCode 可能出现以下值：

错误码名	值	描述	处理建议
kSuccess	0	录掌注册成功	-
kNetworkFailed	20102	网络请求失败（设备无法连接云端服务）	检查设备网络连接后重试
kCloudBizError	20407	云端服务返回业务错误	参考 resultMessage 字段获取具体原因
kModuleRuntimeError	50003	掌纹模组运行时错误	重启设备后重试
kDuplicateRegister	50010	该用户掌纹已注册（重复注册，含设备端本地检测）	提示用户已完成注册，无需重复录掌
kRegisterFailed	50011	注册失败（通用注册错误）	重试，若持续失败请检查设备状态
kUserNotFound	50305	云端未找到对应用户（用户ID不匹配）	确认 userId 与云端一致
kUserInfoMismatch	50306	用户名与云端记录不匹配	确认 userName 与云端一致
kInvalidUserInfo	50901	上位机下发的用户信息无效（userId 或 userName 为空）	检查 A1 指令中 userId 和 userName 字段不为空
kRegisterModeDisabled	50308	上位机注册模式已被管理后台禁用（v2.3.0 新增）	联系管理员在后台开启上位机注册权限后重试
-	其他	未知错误	参考 resultMessage 字段，建议重试

模式切换错误码（A7 上报切换结果）

错误码名	值	描述	处理建议
kSuccess	0	模式切换成功	-
kInvalidParam	10100	参数错误，目标模式不在合法范围内（0~5）	检查 mode 字段取值是否为 0~5
kParseError	10501	请求数据格式解析失败	检查 A6 指令数据域 JSON 格式是否正确
kNotInMainPage	50902	当前设备未处在主界面，无法切换模式	等待设备回到主界面后重试
-	其他	模式切换失败	重试

通用错误码

注意： 本文档（V2.0）使用 5 位数错误码编码体系，采用 PPCCSS 分段结构。下表列出上位机通信中可能遇到的所有错误码。

错误码名	值	描述	处理建议
kSuccess	0	成功	-
kInvalidParam	10100	参数无效	检查指令数据域字段取值是否合法
kParseError	10501	JSON 数据解析失败	检查数据域 JSON 格式是否正确
kNetworkFailed	20102	网络请求失败（设备无法连接云端服务）	检查设备网络连接后重试
kCloudBizError	20407	云端服务返回业务错误	参考 resultMessage 字段获取具体原因
kModuleRuntimeError	50003	掌纹模组运行时错误	重启设备后重试
kDuplicateRegister	50010	重复注册（含设备端本地检测）	提示用户已完成注册，无需重复录掌
kRegisterFailed	50011	注册失败（通用注册错误）	重试，若持续失败请检查设备状态
kUserNotFound	50305	用户未找到	确认 userId 与云端一致
kUserInfoMismatch	50306	用户信息不匹配	确认 userName 与云端一致
kHostNotConnected	50900	上位机未连接（串口未连接）	检查 USB 串口线连接是否正常
kInvalidUserInfo	50901	上位机下发的用户信息无效	检查 userId 和 userName 字段不为空
kNotInMainPage	50902	设备当前不在主界面（仅联动 mode=1~5 切换时触发）	等待设备回到主界面后重试
kHostVerifyUserCancel	50903	上位机用户取消加验（B3 result_code 可能取该值）	业务侧静默丢弃，不展示失败终态
kRegisterModeDisabled	50308	当前注册模式已被管理后台禁用（v2.3.0 新增）	联系管理员在后台开启对应注册模式权限后重试
kTaskCancelled	30000	任务被取消（如加验输入被取消、设备主动取消）	视为用户主动取消，UI 静默回收
kTaskTimeout	30002	任务超时（如加验输入超时、扫码超时）	视为超时，可提示用户重试