腾讯刷掌设备端M4双向通信协议接口文档

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

版本更新记录

版本号	发布日期	更新内容
V2.4.1	2026-08-19	新增「删除用户」协议：0xAF（上位机→设备）+ 0xB6（设备→上位机同步回包），任意工作模式可处理；新增「设备滴码注册用户信息确认」协议：0xAC（上位机→设备，确认/取消注册会话）+ B1 字段补全（user_info / timeout_ms）；A6 新增 `need_high_similarity`（默认 true，控制注册是否返回高相似用户）与 `confirm_timeout_ms`（mode=5 专属，确认页倒计时初始值，限 5000~120000ms）；A4 统一返回 `user_id`/`user_name`（所有注册终态携带）并新增 `countdown_ms`（所有终态携带）与错误码 50012 + 可选字段 `high_similarity_users`（高相似用户详情）；新增错误码 50904（删除用户失败兜底）；补充识别/加验错误码与设备滴码注册时序、断连兜底说明；本批次新增字段统一 snake_case 命名
V2.3.0	2026-07-03	新增错误码 50308（注册模式被禁用）：管理后台禁用对应注册模式后，设备端在注册入口拒绝请求并通过 A4 上报该错误码；B0/AB 新增 `capabilities` 字段，携带设备注册能力标志（`host_register` / `cpm_register`，任一原因不可用即为 0），租户场景配置变化时随健康状态帧实时更新
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 串口与刷掌设备进行指令交互，实现录掌注册、刷掌识别和设备模式管理等核心功能。

适用场景

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

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

核心功能

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

系统架构

通讯模式说明：

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

快速开始

环境要求

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

串口驱动（PL2303）：macOS 除安装驱动外还需在「登录项与扩展 → 驱动扩展程序」中开启 PL2303Serial 驱动。下载：macOS：‎PL2303 Serial App；Windows/Linux 驱动请从 Prolific 官网获取

集成步骤

安装对应操作系统的 PL2303 串口驱动
用 USB 串口线连接上位机与刷掌设备
按照物理层协议配置（115200/8/N/1）打开串口
先用 A6 切换到目标工作模式，再发业务命令（上位机录掌：A6 mode=4 后发 A1；滴码注册：A6 mode=5，无需 A1；联动识别：A6 mode=1）
解析设备返回的响应数据包

最小示例

以下为一次完整的 唤起录掌（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)

接口概览

接口按业务模块组织，与后文章节顺序一致。建议按「工作模式切换 → 各业务模块」的顺序接入。

所属模块	命令码	功能描述	通信方向
通用协议	AA	设备状态查询（兼作 5s 心跳）	上位机→设备
	AB	设备状态查询响应	设备→上位机
	B0	设备状态主动通知（健康/能力变化）	设备→上位机
	F0	未知命令码响应	设备→上位机
工作模式切换	A6	切换模式	上位机→设备
	A7	切换结果	设备→上位机
	A8	查询当前模式	上位机→设备
	A9	查询响应	设备→上位机
上位机录掌注册（下发 userId 方式）	A1	唤起录掌（携带 userId / userName）	上位机→设备
	A2	录掌信息确认	设备→上位机
	A3	取消录掌	上位机→设备
	A4	上报录掌结果（注册终态）	设备→上位机
设备滴码注册	B1	注册中间状态通知	设备→上位机
	AC	注册确认 / 取消（带 session_id）	上位机→设备
	A4	（复用）注册终态	设备→上位机
刷掌识别	A5	唤起识别	上位机→设备
	B2	识别进度通知	设备→上位机
	B3	识别结果（含加验后终态）	设备→上位机
联动识别·加验	B4	加验输入提示	设备→上位机
	AD	加验输入回传	上位机→设备
	AE	取消加验	上位机→设备
	B5	加验结果通知	设备→上位机
用户管理	AF	删除用户	上位机→设备
	B6	删除结果	设备→上位机

注：A4 为所有注册方式的通用终态帧（上位机录掌、设备滴码注册共用，register_mode 字段区分）；AA / AB / B0 的业务语义详见「设备健康状态协议」章节。

通用配置与协议

本章节为帧结构的唯一权威定义（起始字符 / 包序号 / 命令码 / 数据域长度 / 数据域 / 校验位），后文各命令章节不再重复帧格式表。

物理层协议配置

本协议为设备本地串口直连通信，无需握手认证或鉴权，设备上电即可收发指令。

参数	配置
波特率	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。

未知命令码响应（cmd 0xF0）

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

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

通信协议：

帧结构见「通用配置与协议」（命令码与数据域以下述数据格式为准）

传输数据格式：
```
{
    "cmd": 10
}
```
通信数据示例（16进制）：

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

工作模式切换协议

模式切换是一切业务的入口：上位机通过 A6 将设备切入目标工作模式后，才能发送对应的业务命令（上位机录掌需 mode=4，设备滴码注册需 mode=5，联动识别需 mode=1）。本模块同时包含模式查询（A8/A9），用于上位机重连后同步设备当前模式。

A6 与 A1 的关系（先模式，后业务）

进入录掌注册前必须先 A6 切到 mode=4（上位机录掌模式），再发 A1；A6 只负责切模式，不携带用户信息，用户信息由 A1 下发。

【上位机→设备】切换模式（cmd 0xA6）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

传输数据格式：

{
    "mode": 4,
    "need_high_similarity": true,
    "confirm_timeout_ms": 30000
}

请求字段说明：

字段名	类型	必选	说明
mode	int	是	目标工作模式，取值 0~5（见下方工作模式列表）
need_high_similarity	bool	否	[v2.4.1 新增] 控制注册过程是否要求后台返回高相似用户列表。默认 `true`：旧上位机不传该字段时自动启用高相似检测（与原有行为一致），覆盖上位机录掌、设备滴码注册等所有注册入口。显式传 `false` 时关闭高相似检测，注册不会返回 `resultCode=50012` 与 `high_similarity_users`。仅对注册模式（mode=2~5）有意义；识别模式（mode=1）与独立模式（mode=0）传入的值会被忽略
confirm_timeout_ms	int	否	[v2.4.1 新增] 设备滴码注册（mode=5）用户信息确认页倒计时（毫秒）。默认 30000。设备端将其限制在 5000~120000 毫秒：下限防止界面闪过，上限防止误操作长时间挂起。上位机借此同步自身倒计时显示；设备端确认页界面使用同一值做超时判定。仅 mode=5 有意义，其他模式忽略。不传或为 0 时使用默认值。B1(122) 通知中 `timeout_ms` 字段与该值一致

工作模式列表：

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

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

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

【设备→上位机】切换结果（cmd 0xA7）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

传输数据格式：

{
    "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

【上位机→设备】查询当前模式（cmd 0xA8）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

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

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

【设备→上位机】查询响应（cmd 0xA9）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

传输数据格式：
```
{
    "mode": 1
}
```
mode 字段枚举值说明：

值	模式
0	独立模式（未与上位机联动）[v2.2.0 新增]
1	识别模式
2	注册模式 - 手机H5录掌
3	注册模式 - 设备端录掌
4	注册模式 - 上位机录掌
5	注册模式 - 设备滴码注册（Device Scan QR）[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

上位机录掌注册协议

模块定位：本协议指上位机下发 userId / userName、设备为该指定用户录掌的注册方式（A6 mode=4）。它不涉及设备上的其他注册模式——设备端用户自行注册（滴码注册）见「设备滴码注册协议」；注册前必须先经 A6 切到 mode=4。流程：A6(mode=4) → A1(下发用户信息) → A2(设备确认) → 刷掌 → A4(终态)；中途可 A3 取消。

【上位机→设备】唤起录掌（cmd 0xA1）

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

通信协议：

帧结构见「通用配置与协议」（命令码与数据域以下述数据格式为准）

传输数据格式：

{
    "userId": "user123456",
    "userName": "Test User",
    "phone": "13800138000",
    "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

【设备→上位机】录掌信息确认（cmd 0xA2）

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

通信协议：

帧结构见「通用配置与协议」（命令码与数据域以下述数据格式为准）

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

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

【上位机→设备】取消录掌（cmd 0xA3）

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

通信协议：

帧结构见「通用配置与协议」（命令码与数据域以下述数据格式为准）

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

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

【设备→上位机】上报录掌结果（cmd 0xA4）

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

通信协议：

帧结构见「通用配置与协议」（命令码与数据域以下述数据格式为准）

字段说明：

字段名	类型	必返回	说明
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`（设备滴码注册）。上位机可据此区分两种注册流程的结果
user_id	string	否	[v2.4.1 新增] 本次注册绑定的用户 ID。上位机录掌、设备滴码注册终态均携带：上位机录掌回填 A1 下发的 userId；设备滴码注册透传扫码绑定的 userId。旧设备可能不返回或为空串
user_name	string	否	[v2.4.1 新增] 本次注册绑定的用户名。上位机录掌、设备滴码注册终态均携带：上位机录掌回填 A1 下发的 userName；设备滴码注册透传扫码绑定的 userName。旧设备可能不返回或为空串
high_similarity_users	array<object>	否	[v2.4.1 新增] 当注册检测到高相似用户（resultCode=50012）时返回。由 A6 的 `need_high_similarity` 参数控制（默认 true，覆盖上位机录掌、设备滴码注册等所有注册入口）。每项包含 user_id、user_name、card_no、user_tags（tag_id/tag_name）；本地用户信息未同步时仅保证 user_id 有值
countdown_ms	int	否	[v2.4.1 新增] 注册结果页自动关闭倒计时（毫秒），语义与 B3 识别终态 `countdown_ms` 一致。所有终态均携带（上位机录掌、设备滴码注册通用）：成功默认 1000，失败默认 3000，可由租户主题配置下发调整。上位机可用它同步结果页关闭时机，也可忽略

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 位数错误码编码体系。

错误码	说明
0	录掌注册成功
20102	网络请求失败（设备无法连接云端服务）
20407	云端服务返回业务错误，具体原因参考 resultMessage 字段
30001	任务被停止
30002	任务超时：确认页倒计时到期、扫码/录掌阶段超时等，建议上位机按「注册超时」展示
50003	掌纹模组运行时错误（录掌过程中模组异常）
50006	注册已取消：用户主动取消（设备屏取消按钮 / 上位机 0xAC cancel）。建议上位机按中性「注册已取消」展示或静默，不建议渲染为「注册失败」。确认页倒计时到期不返回此码，返回 30002
50010	该用户掌纹已注册（重复注册，含设备端本地检测）
50011	注册失败（通用注册错误）
50012	[v2.4.1 新增] 注册检测到高相似已注册用户（由 A6 `need_high_similarity` 控制，默认开启）。A4 会携带 `high_similarity_users` 字段返回高相似用户详情
50305	云端未找到对应用户（用户ID不匹配）
50306	用户名与云端记录不匹配
50901	上位机下发的用户信息无效（userId 或 userName 为空）
其他	未知错误，建议重试。具体原因参考 resultMessage 字段

成功响应示例（JSON）：

{
    "resultCode": 0,
    "resultMessage": "success",
    "countdown_ms": 1000,
    "register_mode": "host",
    "user_id": "user123456",
    "user_name": "Test User",
    "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",
    "countdown_ms": 3000,
    "register_mode": "host",
    "user_id": "user123456",
    "user_name": "Test User",
    "palmDirection": "2",
    "userState": "",
    "leftPalm": {
        "PalmState": "registered",
        "RegisterType": "Device",
        "RegisterTime": "2026-03-15T08:30:00Z",
        "ExpireTime": "2027-03-15T08:30:00Z"
    },
    "rightPalm": {
        "PalmState": "unregistered"
    }
}

高相似用户响应示例（JSON）：

{
    "resultCode": 50012,
    "resultMessage": "high similarity detected",
    "palmDirection": "1",
    "userState": "",
    "register_mode": "host",
    "high_similarity_users": [
        {
            "user_id": "existing-user-id",
            "user_name": "Alice",
            "card_no": "100001",
            "user_tags": [
                {"tag_id": "staff", "tag_name": "Staff"}
            ]
        }
    ]
}

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

录掌结果用户数据结构（PalmInfo / PalmState）

leftPalm / rightPalm 字段的结构定义：

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`	已完成注册

上位机录掌注册时序

双掌注册业务流程

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

上位机处理建议：

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

设备滴码注册协议

模块定位：设备滴码注册（A6 mode=5）——用户在设备屏幕上扫描二维码（滴码）完成身份关联后，由设备端发起的注册流程。与上位机录掌（下发 userId）的区别：用户信息来自扫码绑定，不经上位机输入；注册过程中设备会通过 B1 推送中间状态，其中用户信息确认状态需要上位机展示确认界面并回 AC 确认/取消。 B1 同时也承载上位机录掌的中间状态（120/121 进度），帧定义在本模块统一说明。

【设备→上位机】注册中间状态通知（cmd 0xB1）

设备端在设备滴码注册流程的关键节点，向下位机推送注册进度通知。该帧为中间事件，可多次推送；终态以 A4 为准。

通信协议： 起始 5A5A5A5A + 包序号 + 命令码 B1 + 数据域 + BCC

传输数据格式：

{
    "session_id": "reg_a1b2c3",
    "status_code": 122,
    "register_mode": "cpm",
    "user_info": {
        "user_id": "user123456",
        "user_name": "张三"
    },
    "timeout_ms": 30000
}

字段说明：

字段名	类型	必返回	说明
session_id	string	是	本次设备滴码注册会话 ID，由设备生成；与 AC、A4 终态保持一致
status_code	int	是	注册阶段状态枚举（见下方 status_code 枚举表）
register_mode	string	是	注册方式：`cpm`（设备滴码注册）/ `host`（上位机录掌）
user_info	object	否	[v2.4.1 新增] 用户信息对象，仅 `status_code=122`（进入确认页）时携带。结构见下方 user_info 对象说明
timeout_ms	int	否	[v2.4.1 新增] 确认页倒计时（毫秒），仅 `status_code=122` 时携带，与 A6 `confirm_timeout_ms` 一致

status_code 枚举（设备滴码模式）：

枚举值	含义	携带扩展字段
120	扫码就绪（等待手机出示二维码）	无
121	扫码验证中（正在调后台验证二维码）	无
122	进入用户信息确认页（等待设备屏或上位机确认/取消）	user_info + timeout_ms
123	云端绑定中（用户已确认，正在云端绑定手掌）	无

注：设备滴码注册确认决策事件（设备本地确认/取消、上位机 AC 确认/取消、界面倒计时超时）不新增 B1 status_code，沿用既有 B1(123 绑定中)/A4 终态告知上位机结果。超时由设备端界面自行处理，AC 等价于设备本地确认/取消按钮。

user_info 对象结构：

字段名	类型	说明
user_id	string	用户 ID（由后台 DescribeQrCodeScanSession 返回）
user_name	string	用户名（由后台返回，可能为空串）

【上位机→设备】设备滴码注册确认/取消（cmd 0xAC）

上位机在收到 B1(status_code=122 进入确认页) 后，可向下位机发送 AC 指令对设备滴码注册会话进行确认/取消决策。该指令等价于用户在设备屏幕上点击确认/取消按钮，设备流程以本地为主，上位机的 AC 只是辅助操作入口——若上位机不响应，设备仍可独立完成或超时失败。

通信协议： 起始 5A5A5A5A + 包序号 + 命令码 AC + 数据域 + BCC

传输数据格式：

{
    "session_id": "reg_a1b2c3",
    "action": "confirm"
}

字段说明：

字段名	类型	必选	说明
session_id	string	是	必须填回 B1 下发的 session_id，否则设备静默丢弃
action	string	是	决策动作：`confirm`（确认，等价于设备本地点确认按钮）/ `cancel`（取消，等价于设备本地点取消按钮）

设备侧行为：

场景	设备行为
收到 `action=confirm`	设备按本地确认按钮同等逻辑处理（与设备本地点确认等价） → 推 B1(123 绑定中) → 进入云端绑定 → A4 终态
收到 `action=cancel`	设备按本地取消按钮同等逻辑处理（与设备本地点取消等价） → A4 失败终态（携带 countdown_ms）
session_id 不匹配	静默丢弃 + 日志告警（防止上位机延迟 AC 误伤新会话）
AC 解析失败 / action 非法	回 F0（UnsupportedCmd）
非 `PalmModeRegister` 模式收到	回 F0（UnsupportedCmd）
设备界面与 AC 双入口重复确认	设备端防重机制：首个确认入口生效，后续重复确认静默忽略（界面防重只防双击，跨入口防重由设备内部保证）

错误处理： 设备不立即回 ACK，靠既有 B1(123) + A4 终态告知结果。上位机可设业务超时（如 confirm_timeout_ms + 5s）兜底。

断连兜底说明： 当设备滴码注册处于确认页（status=122）时上位机断连（USB 拔出、进程崩溃），设备滴码注册流程继续独立运行——用户仍可在设备上确认/取消，或界面倒计时到期后按超时（30002）结束流程。B1 是通知性质，不要求上位机必须回 AC。上位机重连后可通过 A8 查询当前 mode + 监听后续 B1/A4 同步状态。

上位机设备滴码注册完整时序

下图展示**设备滴码注册模式（mode=5）**下，从 A6 切入到 A4 终态的完整双向交互，覆盖正常确认、上位机取消、界面倒计时超时、双入口竞态四个分支。

设计要点：

AC 等价于设备本地确认/取消按钮，按既有终态路径返回结果，不新增 B1 status_code

倒计时由设备端界面主导，上位机 UI 同步显示（初始值 = A6 confirm_timeout_ms）

双入口竞态防护仅防"重复触发云端绑定"，重复取消/失败由设备内部保证幂等，上位机无需处理

上位机断连不影响设备独立运行（B1 是通知性质，不要求上位机必须回 AC）

上位机刷掌识别协议

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

【上位机→设备】唤起刷掌识别（cmd 0xA5）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

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

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

【设备→上位机】识别用户信息回传（A5 响应）

刷掌设备在用户刷掌识别成功后会返回对应的用户信息，该信息类型可在设备 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 通常为 6~~32 字节，CardNumber 通常为 10~~19 字节。上位机可结合已接收数据长度辅助判断
3. 区分协议帧与裸数据：裸数据不以 0x5A5A5A5A 起始，上位机可通过检查接收数据的前 4 字节来区分本协议与通用协议帧数据
上位机处理说明：
1. 上位机收到串口数据后，按 UTF-8 解码为字符串即可获得用户信息
2. 根据当前设备的 Output Mode 设置判断返回的是 UserId 还是 CardNumber
3. 如识别失败，设备不会通过该协议发送数据（无响应）
4. 识别超时处理：上位机发送 A5 唤起识别后，建议设置一个业务超时（如 30 秒）。若超时未收到设备返回的用户信息，应视为本次识别无结果，可提示用户重试或执行其他业务逻辑
5. 异常场景处理：若串口连接断开（设备拔线等），上位机应捕获串口异常事件，终止当前等待并提示用户检查设备连接
识别错误码说明：

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

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

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

【设备→上位机】识别进度通知（cmd 0xB2）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

传输数据格式：

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

字段说明：

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

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

【设备→上位机】识别结果（cmd 0xB3）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

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

{
    "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 加验结果共同构成终态）。

联动识别·加验协议

联动识别模式下（A6 mode=1），设备识别出预选用户后，可能要求上位机侧完成附加验证（手机号后四位等）。本模块覆盖加验交互全过程（B4 提示 → AD 回传 / AE 取消 → B5 加验结果），识别主流程（A5/B2/B3）见「刷掌识别协议」。

【设备→上位机】加验输入提示（cmd 0xB4）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

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

{
    "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": "Employee ID"
}

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

{
    "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（携带 session_id + verify_method + input_value），设备端发起后台校验，校验完成后下发 0xB5
2. 用户主动取消 → 上位机回传 0xAE（仅携带 session_id），设备端立即终止本次加验
3. 用户超时未操作 → 上位机不回包，设备端在 timeout_ms 到期时自行回退，并下发 0xB5 表明加验失败

【上位机→设备】加验输入回传（cmd 0xAD）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

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

{
    "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 通告加验结论；随后再下发 0xB3 作为整次识别的终态。

【上位机→设备】取消加验（cmd 0xAE）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

传输数据格式：
```
{
    "session_id": "sess_a1b2c3"
}
```
字段说明：

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

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

【设备→上位机】加验结果通知（cmd 0xB5）

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

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

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

{
    "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`（用户取消）：用户主动取消（含 AE 取消、设备端界面取消、上位机断连兜底取消） • `30002`：加验超时（含 timeout_ms 到期、设备端界面倒计时到期） • 其他：后台校验失败的具体业务错误码
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.4.1 引入。与设备 mode 无关：任意工作模式下（独立模式 / 识别模式 / 注册模式等）都可处理 0xAF，设备收到后请求云端删除该用户，并同步回包 0xB6 告知结果。

同步回包模式：上位机下发请求 → 设备请求云端删除 → 设备立即回包终态。与录掌注册的"异步双帧"（A1 发起 / A4 终态）不同，本协议一问一答，适合"短操作 + 立即返回结果"的删除场景。

本地数据联动：设备端不主动清理本地用户记录。云端删除成功后，本地数据在下次自动同步时按云端状态自然更新（删除会自动生效，无需额外操作）。

【上位机→设备】删除用户请求（cmd `0xAF`）

上位机下发用户 ID，请求设备删除该用户（设备将同步请求云端）。

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

传输数据格式：
```
{
    "user_id": "user123456"
}
```
字段说明：

字段名	类型	必返回	说明
user_id	string	是	待删除的用户 ID，与录掌注册时上位机下发的 userId（A1 字段）一致。非空字符串，长度 1~64，仅允许字母、数字、短横线、下划线

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

5A 5A 5A 5A 00 01 AF 00 18 7B 22 75 73 65 72 5F 69 64 22 3A 22 75 73 65 72 31 32 33 34 35 36 22 7D DF

【设备→上位机】删除用户响应（cmd `0xB6`）

设备收到 0xAF 后，请求云端删除该用户，根据云端返回结果回包。响应字段与 0xA7 SwitchModeResp 完全一致（code + message），上位机可复用同一套解析器。

通信协议：

帧结构见「通用配置与协议 · 物理层协议配置」（命令码与数据域以下述 JSON 为准）

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

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

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

{
    "code": 20407,
    "message": "user not found"
}

字段说明：

字段名	类型	必返回	说明
code	int	是	0 表示删除成功，非 0 表示失败（具体见错误码列表）
message	string	是	结果描述。成功时为 "Success"，失败时为人类可读的失败原因

错误码列表：

错误码	说明
0	删除成功
10501	请求 JSON 解析失败（数据域非合法 JSON）
10100	参数错误：UserId 为空或缺失
20102	网络请求失败（设备无法连接云端服务）
20407	云端业务错误（如用户不存在等），具体原因参考 message 字段
50904	[v2.4.1 新增] 上位机删除用户失败兜底码：云端返回非 0 但无具体 biz_code 时使用
其他	未知错误，建议重试。具体原因参考 message 字段

成功响应示例（JSON）：

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

失败响应示例（JSON）：

{
    "code": 20407,
    "message": "user not found"
}

交互说明：0xAF → 设备调云端 → 0xB6 同步回终态（与 A1/A4 异步双帧不同）。建议上位机设 30s 业务超时兜底。成功/失败 code 见上方字段说明与错误码表；设备不联动清理本地 DB。

上位机设备健康状态协议

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

触发时机

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

周期上报：设备启动后每 30s 自动上报一次（与"每30秒自动刷新"保持一致）
异常变化即时上报：以下任一状态发生变化时，100ms 内推送一帧（短时间内的连续变化会合并为一帧，避免刷屏）：
- 网络在/离线状态变化（Wi-Fi / 以太网）
- 掌纹模组工作状态变化为 Error / Blocked 或从异常恢复
- 设备需要扫码激活（needActivation）
- 租户启用/禁用切换（tenantStatusChanged）
- 服务初始化失败命中 50000 / 50001 / 50105
- 心跳/激活态被云端清除：50101 / 50103 / 5010 (50104)，设备会清空本地激活数据并下发 health_state=20，sub_status.last_error_code` 指示具体原因码
- [v2.3.0 新增] 租户场景配置变化（如注册能力被管理后台开启/关闭），capabilities 字段随帧携带最新值
上位机主动查询：上位机发送 cmd 0xAA，设备 1 秒内回包 0xAB，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	掌纹模组异常	check_palm_module
32	ERROR_PALM_BLOCKED	掌纹模组黑名单/阻塞	check_palm_module
99	UNKNOWN	启动初期尚未取到有效状态	""

【设备→上位机】设备状态主动通知（cmd 0xB0）

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

通信协议：

帧结构见「通用配置与协议」（命令码与数据域以下述数据格式为准）

数据域 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	掌纹模组状态，未知/未连接=0，正常>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"的错误码，无则为 0。常见取值（用于配合 health_state=20 判断干预原因）：50101 授权过期 / 50103 场地变更 / 50104 场地解绑 / 50105 未注册
cpm_register	int	1=支持设备滴码注册（mode=5），0=不支持。由租户注册能力配置决定

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
  }
}

【上位机→设备】设备状态查询（cmd 0xAA）

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

通信协议：

帧结构见「通用配置与协议」（命令码与数据域以下述数据格式为准）

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

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

【设备→上位机】设备状态查询响应（cmd 0xAB）

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

通信协议：

帧结构见「通用配置与协议」（命令码与数据域以下述数据格式为准）

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

附录：全局错误码汇总

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

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

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

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

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

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

通用错误码

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

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

识别/加验错误码（B3 result_code / B5 code）

设备通过 B3（result_code 字段）和 B5（code 字段）上报识别/加验终态时，可能返回以下业务错误码。除 50006（可忽略）和 50903（用户取消）静默处理外，其余均建议上位机展示失败提示。

值	描述	处理建议
50000	模组授权失败/过期	设备会跳转授权页，联系管理员重新激活
50001	模组硬件错误	设备会跳转模组异常页，建议重启设备
50002	掌纹检索为空（未注册用户）	提示用户先注册掌纹
50003	PalmManager 不可忽略错误	提示用户重试，持续失败联系管理员
50004	应用 DB 找不到用户信息	联系管理员核对用户数据
50005	模组黑名单拦截	联系管理员解除黑名单
50006	可忽略错误（用户取消/手出界等）	静默丢弃，不展示失败终态
50007	首次核验激活失败	提示用户检查手机号后重试
50008	增加核验失败	提示用户重试
50200	用户名单拦截	联系管理员开通权限
50201	时间规则拦截	提示不在允许时段内
50203	在线核验失败（兜底）	联系管理员核查在线核验配置
50206	次数上限规则拦截	提示验证次数已达上限，稍后重试
50207	在线核验请求失败/超时	提示检查网络后重试
50208	在线核验服务报错	提示服务暂不可用，稍后重试
50209	三方服务核验不通过	联系管理员核查三方核验结果

版本更新记录​

简介​

接口概述​

适用场景​

核心功能​

系统架构​

快速开始​

环境要求​

集成步骤​

最小示例​

接口概览​

通用配置与协议​

物理层协议配置​

通用数据包格式示例​

未知命令码响应（cmd 0xF0）​

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

工作模式切换协议​

A6 与 A1 的关系（先模式，后业务）​

【上位机→设备】切换模式（cmd 0xA6）​

【设备→上位机】切换结果（cmd 0xA7）​

【上位机→设备】查询当前模式（cmd 0xA8）​

【设备→上位机】查询响应（cmd 0xA9）​

上位机录掌注册协议​

【上位机→设备】唤起录掌（cmd 0xA1）​

【设备→上位机】录掌信息确认（cmd 0xA2）​

【上位机→设备】取消录掌（cmd 0xA3）​

【设备→上位机】上报录掌结果（cmd 0xA4）​

录掌结果用户数据结构（PalmInfo / PalmState）​

PalmState 枚举​

上位机录掌注册时序​

双掌注册业务流程​

设备滴码注册协议​

【设备→上位机】注册中间状态通知（cmd 0xB1）​

【上位机→设备】设备滴码注册确认/取消（cmd 0xAC）​

上位机设备滴码注册完整时序​

上位机刷掌识别协议​

【上位机→设备】唤起刷掌识别（cmd 0xA5）​

【设备→上位机】识别用户信息回传（A5 响应）​

【设备→上位机】识别进度通知（cmd 0xB2）​

【设备→上位机】识别结果（cmd 0xB3）​

联动识别·加验协议​

【设备→上位机】加验输入提示（cmd 0xB4）​

【上位机→设备】加验输入回传（cmd 0xAD）​

【上位机→设备】取消加验（cmd 0xAE）​

【设备→上位机】加验结果通知（cmd 0xB5）​

上位机联动识别完整时序​

上位机删除用户协议​

【上位机→设备】删除用户请求（cmd 0xAF）​

【设备→上位机】删除用户响应（cmd 0xB6）​

上位机设备健康状态协议​

触发时机​

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

【设备→上位机】设备状态主动通知（cmd 0xB0）​

【上位机→设备】设备状态查询（cmd 0xAA）​

【设备→上位机】设备状态查询响应（cmd 0xAB）​

附录：全局错误码汇总​

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

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

通用错误码​

识别/加验错误码（B3 result_code / B5 code）​

版本更新记录

简介

接口概述

适用场景

核心功能

系统架构

快速开始

环境要求

集成步骤

最小示例

接口概览

通用配置与协议

物理层协议配置

通用数据包格式示例

未知命令码响应（cmd 0xF0）

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

工作模式切换协议

A6 与 A1 的关系（先模式，后业务）

【上位机→设备】切换模式（cmd 0xA6）

【设备→上位机】切换结果（cmd 0xA7）

【上位机→设备】查询当前模式（cmd 0xA8）

【设备→上位机】查询响应（cmd 0xA9）

上位机录掌注册协议

【上位机→设备】唤起录掌（cmd 0xA1）

【设备→上位机】录掌信息确认（cmd 0xA2）

【上位机→设备】取消录掌（cmd 0xA3）

【设备→上位机】上报录掌结果（cmd 0xA4）

录掌结果用户数据结构（PalmInfo / PalmState）

PalmState 枚举

上位机录掌注册时序

双掌注册业务流程

设备滴码注册协议

【设备→上位机】注册中间状态通知（cmd 0xB1）

【上位机→设备】设备滴码注册确认/取消（cmd 0xAC）

上位机设备滴码注册完整时序

上位机刷掌识别协议

【上位机→设备】唤起刷掌识别（cmd 0xA5）

【设备→上位机】识别用户信息回传（A5 响应）

【设备→上位机】识别进度通知（cmd 0xB2）

【设备→上位机】识别结果（cmd 0xB3）

联动识别·加验协议

【设备→上位机】加验输入提示（cmd 0xB4）

【上位机→设备】加验输入回传（cmd 0xAD）

【上位机→设备】取消加验（cmd 0xAE）

【设备→上位机】加验结果通知（cmd 0xB5）

上位机联动识别完整时序

上位机删除用户协议

【上位机→设备】删除用户请求（cmd `0xAF`）

【设备→上位机】删除用户响应（cmd `0xB6`）

上位机设备健康状态协议

触发时机

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

【设备→上位机】设备状态主动通知（cmd 0xB0）

【上位机→设备】设备状态查询（cmd 0xAA）

【设备→上位机】设备状态查询响应（cmd 0xAB）

附录：全局错误码汇总

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

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

通用错误码

识别/加验错误码（B3 result_code / B5 code）