Tencent PalmAI Device-Side M4 Bidirectional Communication Protocol Reference

This document applies to both the Max and Standard versions; the interface content is identical.

Version History

Version	Release Date	Update Description
V2.4.1	2026-08-19	Added the "Delete User" protocol: 0xAF (host → device) + 0xB6 (device → host synchronous response), processable in any work mode; added the "Device QR Code Palm Registration user info confirmation" protocol: 0xAC (host → device, confirm/cancel the registration session) + B1 field completion (user_info / timeout_ms); A6 adds need_high_similarity (default true, controls whether registration returns high-similarity users) and confirm_timeout_ms (exclusive to mode=5, the initial countdown value of the confirmation page, limited to 5000~120000ms); A4 uniformly returns user_id/user_name (carried in all registration final states) and adds countdown_ms (carried in all final states), the error code 50012, and the optional field high_similarity_users (high-similarity user details); added error code 50904 (delete user failure fallback); supplemented recognition/additional-verification error codes as well as the Device QR Code Palm Registration timing and disconnection fallback description; fields newly added in this batch uniformly use snake_case naming
V2.3.0	2026-07-03	Added error code 50308 (registration mode disabled): after the admin console disables the corresponding registration mode, the device rejects the request at the registration entry and reports this error code via A4; B0/AB add the capabilities field, carrying the device registration capability flags (host_register / cpm_register, which is 0 if unavailable for any reason), updated in real time along with the health status frame when the tenant scene configuration changes
V2.2.0	2026-06-02	Added the device health status protocol (B0/AA/AB); added the QR Code Palm Registration (mode=5), recognition progress reporting (B2/B3), and additional-verification interaction (AD/AE/B4/B5) protocols; A6 mode switching supports mode=0 (standalone mode) to exit linkage; A4 extends the register_mode field; B0/AB extend the protocol_version and work_mode=0 fields; the B3 recognition final state adds countdown_ms (result page countdown, to align the host UI with the device); in host disconnection/cancellation/timeout scenarios the device proactively sends the 0xB5 final state (to avoid the host staying in the selection/waiting state); the sub_status.last_error_code of 0xB0 adds 50101/50103/50104, so the host can precisely locate the reason for the non-active state; supplemented detailed field descriptions of the AD/AE/B5 protocols and the complete linked-recognition timing diagram
V2.0.0	2026-03-14	Added the userState/palmDirection fields, supporting dual-palm registration scenarios
V1.8.0	2026-03-10	Supplemented use cases, architecture diagram, and error codes
V1.7.0	2026-01-05	First version

V2.0 Incompatible Change Notice: V2.0 adds the userState, palmDirection, leftPalm, and rightPalm fields to the A4 (report palm registration result) protocol. The host needs to adapt to the new fields to support dual-palm registration scenarios. If a V1.x host does not parse the new fields, existing functions are not affected, but it cannot obtain dual-palm registration status information. It is recommended to upgrade to the V2.0 protocol as soon as possible.

Introduction

Overview

This document is the host bidirectional communication protocol API reference for the M4 Palm Verification Device. It describes how the host interacts with the Palm Verification Device via a USB serial port to implement core functions such as palm registration, palm recognition, and device mode management.

Applicable Scenarios

The current protocol supports three major functions: registration, recognition, and mode switching. Typical business scenarios are as follows:

1. Palm Registration: A counter staff member or a self-service terminal initiates a palm registration request on the host, delivers the user information (ID, name, phone number, bank card number) to the Palm Verification Device via the serial port, the user completes the palm print registration on the device, and the registration result is returned to the host. Dual-palm registration is supported, i.e., the same user can register the left-hand and right-hand palm prints separately in two sessions, and the device reports the current user's palm print registration status via the userState field.
2. Palm Recognition: The host can invoke the device's palm recognition page. After the user completes the palm scan, the device returns the recognized user information (UserId or CardNumber) to the host for identity confirmation, payment, and other business.
3. Mode Switching and Query: The host can query and switch the device's current work mode (recognition mode, Mobile H5 palm registration, device-side palm registration, host palm registration) to flexibly adapt to different business scenarios. mode=0 is supported to exit linkage, and the device returns to standalone work mode.

Core Functions

1. Host Palm Registration: The host delivers user information to the device, the user completes palm print registration on the device, and dual-palm registration is supported
2. Palm Recognition Invocation: The host invokes the device's palm recognition page and obtains the recognized user information
3. Device Mode Management: The host queries and switches the device work mode (recognition, Mobile H5 palm registration, device-side palm registration, host palm registration)

System Architecture

Communication Mode Description:

• The host and the Palm Verification Device are connected via a USB-to-serial adapter (PL2303 chip), and communicate bidirectionally using a command-response mode
• Host → Device: Sends commands (invoke palm registration, cancel palm registration, invoke recognition, switch/query mode)
• Device → Host: Returns confirmations and reports results (palm registration result, recognized user information, mode switching result, current mode)

Quick Start

Environment Requirements

Item	Requirement
Operating System	Windows / macOS / Linux
Serial Driver	PL2303 driver (see the download and enablement instructions below)
Physical Connection	USB-to-serial cable (PL2303 chip)
Serial Parameters	Baud rate 115200, 8 data bits, 1 stop bit, no parity, no flow control

Serial Driver (PL2303): On macOS, in addition to installing the driver, you also need to enable the PL2303Serial driver in "Login Items & Extensions → Driver Extensions". Download: macOS: PL2303 Serial App; for Windows/Linux drivers, obtain them from the Prolific official website

Integration Steps

1. Install the PL2303 serial driver for the corresponding operating system
2. Connect the host and the Palm Verification Device with a USB serial cable
3. Open the serial port according to the physical-layer protocol configuration (115200/8/N/1)
4. First use A6 to switch to the target work mode, then send the business command (host palm registration: A6 mode=4 then send A1; QR Code Palm Registration: A6 mode=5, no A1 needed; linked recognition: A6 mode=1)
5. Parse the response data packet returned by the device

Minimal Example

The following is a hexadecimal example of a complete invoke palm registration (A1) → palm registration info confirmation (A2) interaction:

Host → Device (A1 invoke palm registration):

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

Device → Host (A2 palm registration info confirmation):

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

Data packet structure description: Start bytes (4B) + Packet sequence number (2B, big-endian) + Command code (1B) + Data field length (2B, big-endian) + Data field (NB) + BCC checksum (1B)

API Overview

Interfaces are organized by business module, consistent with the order of the sections below. It is recommended to integrate in the order of "work mode switching → each business module".

Module	Command Code	Function Description	Communication Direction
Common Protocol	AA	Device status query (also serves as the 5s heartbeat)	Host → Device
	AB	Device status query response	Device → Host
	B0	Device status active notification (health/capability change)	Device → Host
	F0	Unknown command code response	Device → Host
Work Mode Switching	A6	Switch mode	Host → Device
	A7	Switching result	Device → Host
	A8	Query current mode	Host → Device
	A9	Query response	Device → Host
Host Palm Registration (deliver userId method)	A1	Invoke palm registration (carries userId / userName)	Host → Device
	A2	Palm registration info confirmation	Device → Host
	A3	Cancel palm registration	Host → Device
	A4	Report palm registration result (registration final state)	Device → Host
Device QR Code Palm Registration	B1	Registration intermediate status notification	Device → Host
	AC	Registration confirmation / cancellation (with session_id)	Host → Device
	A4	(Reused) registration final state	Device → Host
Palm Recognition	A5	Invoke recognition	Host → Device
	B2	Recognition progress notification	Device → Host
	B3	Recognition result (including the final state after additional verification)	Device → Host
Linked Recognition · Additional Verification	B4	Additional-verification input prompt	Device → Host
	AD	Additional-verification input response	Host → Device
	AE	Cancel additional verification	Host → Device
	B5	Additional-verification result notification	Device → Host
User Management	AF	Delete user	Host → Device
	B6	Deletion result	Device → Host

Note: A4 is the common final-state frame for all registration methods (shared by host palm registration and Device QR Code Palm Registration, distinguished by the register_mode field); for the business semantics of AA / AB / B0, see the "Device Health Status Protocol" section.

Common Configuration and Protocol

This section is the sole authoritative definition of the frame structure (start bytes / packet sequence number / command code / data field length / data field / checksum). The command sections below will not repeat the frame format table.

Physical-Layer Protocol Configuration

This protocol is local serial direct-connect communication for the device, and requires no handshake authentication or authorization; the device can send and receive commands as soon as it is powered on.

Parameter	Configuration
Baud rate	115200
Data bits	8
Stop bits	1
Parity	None
Flow control	None

Common Data Packet Format Example

Start bytes	Packet sequence number	Command code	Data field length	Data field	Checksum
5A5A5A5A	0001	A1	0001	01	2D

• Start bytes (4 bytes):

  The identifier for the start of the packet, fixed to 0x5A5A5A5A

• Packet sequence number (2 bytes, big-endian):

  Starts from 0 and increments by one for each packet sent; after reaching 0xFFFF it wraps back to 0. The sequence number returned by the Palm Verification Device is consistent with the sequence number of the command packet sent by the host. This parameter is actively updated and maintained by the host

• Command code (1 byte):

  Used to distinguish different types of commands. Related command codes are introduced in the business scenarios

• Data field length (2 bytes, big-endian):

  Indicates the length of the data in the packet's data field. This value does not include the length of the checksum

• Data field (determined by the data field length):

  The meaning of this field is parsed by each command; some commands may not have this field

• Checksum (1 byte)

  BCC checksum is used here, which is the XOR value of all data except the start bytes

Byte Order Description: All multi-byte fields in this protocol (2-byte packet sequence number, 2-byte data field length) use big-endian byte order, i.e., the high-order byte comes first and the low-order byte comes last. For example, the packet sequence number 0x0001 is transmitted over the serial port as 00 01.

Unknown Command Code Response (cmd 0xF0)

[Device → Host] Unknown Command Code

The Palm Verification Device responds when it receives an unknown command code

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol" (the command code and data field are subject to the data format below)

• Transmission Data Format:

  {
      "cmd": 10
  }

• Communication Data Example (hexadecimal):

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

---

Work Mode Switching Protocol

Mode switching is the entry point for all business: only after the host switches the device to the target work mode via A6 can it send the corresponding business command (host palm registration requires mode=4, Device QR Code Palm Registration requires mode=5, linked recognition requires mode=1). This module also includes mode query (A8/A9), used for the host to synchronize the device's current mode after reconnection.

Relationship Between A6 and A1 (Mode First, Then Business)

Before entering palm registration, you must first use A6 to switch to mode=4 (host palm registration mode), then send A1; A6 is only responsible for switching the mode and does not carry user information, which is delivered by A1.

[Host → Device] Switch Mode (cmd 0xA6)

The host controls switching of the device's current palm mode

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format:

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

• Request Field Description:

Field Name	Type	Required	Description
mode	int	Yes	Target work mode, value 0~5 (see the work mode list below)
need_high_similarity	bool	No	[Added in v2.4.1] Controls whether the registration process requires the backend to return a high-similarity user list. Default true: when a legacy host does not pass this field, high-similarity detection is automatically enabled (consistent with the original behavior), covering all registration entries such as host palm registration and Device QR Code Palm Registration. When explicitly set to false, high-similarity detection is disabled, and registration will not return resultCode=50012 and high_similarity_users. It is only meaningful for registration modes (mode=2~5); values passed in recognition mode (mode=1) and standalone mode (mode=0) are ignored
confirm_timeout_ms	int	No	[Added in v2.4.1] The countdown (in milliseconds) of the user info confirmation page for Device QR Code Palm Registration (mode=5). Default 30000. The device limits it to 5000~120000 milliseconds: the lower bound prevents the page from flashing by, and the upper bound prevents a misoperation from hanging for a long time. The host uses this to synchronize its own countdown display; the device's confirmation page uses the same value for timeout judgment. Only meaningful for mode=5; ignored in other modes. If not passed or 0, the default value is used. The timeout_ms field in the B1(122) notification is consistent with this value

• Work Mode List:

Value	Mode	Description
0	Standalone mode (exit linkage) [Added in v2.2.0]	The device exits linkage with the host and works independently according to its locally persisted configuration. The device no longer pushes notifications such as recognition progress (B2), recognition result (B3), additional-verification request (B4), and additional-verification result (B5) to the host. The host can send mode=1~5 again to re-enter linkage mode. **The device is in this mode by default after startup.**
1	Recognition mode	Enters linked recognition mode; palm results are pushed to the host
2	Registration mode - Mobile H5 palm registration	-
3	Registration mode - Device-side palm registration	-
4	Registration mode - Host palm registration	After entering, initiate palm registration via A1 (see "Relationship Between A6 and A1")
5	Registration mode - Device QR Code Palm Registration (Device Scan QR) [Added in v2.2.0]	After entering, A1 is not required; the device scans the QR code to obtain the user, and the result is reported via A4

• Communication Data Example (hexadecimal):

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

[Device → Host] Switching Result (cmd 0xA7)

After receiving the host's mode switching command, the Palm Verification Device returns the mode switching result via this protocol, and the host can determine whether the switch succeeded based on the result

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format:

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

• Error Code List:

Error Code	Description
0	Mode switching succeeded
10100	Parameter error; the mode to switch to is not within the valid range (0~5)
10501	Failed to parse the request data format
50902	The device is not currently on the main screen (triggered only for mode=1~5; mode=0 to exit linkage is not subject to this restriction)
Other	Mode switching failed; please retry

• Communication Data Example (hexadecimal):

  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

[Host → Device] Query Current Mode (cmd 0xA8)

The host queries the mode the device is currently in

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Communication Data Example (hexadecimal):

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

[Device → Host] Query Response (cmd 0xA9)

After the host sends a query command, the device returns the current mode via this protocol

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format:

  {
      "mode": 1
  }

• mode Field Enum Value Description:

Value	Mode
0	Standalone mode (not linked with the host) [Added in v2.2.0]
1	Recognition mode
2	Registration mode - Mobile H5 palm registration
3	Registration mode - Device-side palm registration
4	Registration mode - Host palm registration
5	Registration mode - Device QR Code Palm Registration (Device Scan QR) [Added in v2.2.0]

• Communication Data Example (hexadecimal):

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

Host Palm Registration Protocol

Module Positioning: This protocol refers to the registration method in which the host delivers userId / userName and the device registers the palm for the specified user (A6 mode=4). It does not involve other registration modes on the device—for device-side user self-registration (QR Code Palm Registration), see "Device QR Code Palm Registration Protocol"; before registration, you must first switch to mode=4 via A6. Flow: A6(mode=4) → A1(deliver user info) → A2(device confirmation) → palm scan → A4(final state); it can be cancelled midway via A3.

[Host → Device] Invoke Palm Registration (cmd 0xA1)

The host invokes device palm registration and provides the corresponding palm registration information, including the user ID, user name, phone number, and bank card number. After a successful invocation, the corresponding information is displayed on the device's main screen, prompting the user to start palm print registration

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol" (the command code and data field are subject to the data format below)

• Transmission Data Format:

  {
      "userId": "user123456",
      "userName": "Test User",
      "phone": "13800138000",
      "physicalCardNumber": "12345678"
  }

• Communication Data Example (hexadecimal):

   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

[Device → Host] Palm Registration Info Confirmation (cmd 0xA2)

After receiving the invoke palm registration command sent by the host, the Palm Verification Device sends this command to inform the host that it has received the user data and is in the palm registration process

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol" (the command code and data field are subject to the data format below)

• Communication Data Example (hexadecimal):

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

[Host → Device] Cancel Palm Registration (cmd 0xA3)

While waiting for the user's palm registration result on the Palm Verification Device, the host can send a command to cancel palm registration

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol" (the command code and data field are subject to the data format below)

• Communication Data Example (hexadecimal):

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

[Device → Host] Report Palm Registration Result (cmd 0xA4)

After the user's palm registration succeeds/fails, the Palm Verification Device returns the corresponding palm registration result, and the host can display the corresponding page based on the result

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol" (the command code and data field are subject to the data format below)

• Field Description:

Field Name	Type	Required to Return	Description
resultCode	int	Yes	Palm registration result code; 0 indicates success, non-0 indicates failure (see the error code list for details)
resultMessage	string	Yes	Palm registration result description
palmDirection	string	Yes	The palm direction registered this time. "1" = left hand, "2" = right hand, "-1" = unknown
userState	string	Returned on success	User palm print status (meaningful only when resultCode=0); for specific values, see the userState enum table below
leftPalm	object	No	Left palm details (optional), passing through the left palm JSON object returned by the backend. This field is not included when the backend does not return it. For specific subfields, see the leftPalm/rightPalm structure description below
rightPalm	object	No	Right palm details (optional), passing through the right palm JSON object returned by the backend. This field is not included when the backend does not return it. For specific subfields, see the leftPalm/rightPalm structure description below
register_mode	string	Yes	[Added in v2.2.0] Registration method: host (host palm registration) / cpm (Device QR Code Palm Registration). The host can use this to distinguish the results of the two registration flows
user_id	string	No	[Added in v2.4.1] The user ID bound in this registration. Both host palm registration and Device QR Code Palm Registration final states carry it: host palm registration backfills the userId delivered by A1; Device QR Code Palm Registration passes through the userId bound by scanning. Legacy devices may not return it or return an empty string
user_name	string	No	[Added in v2.4.1] The user name bound in this registration. Both host palm registration and Device QR Code Palm Registration final states carry it: host palm registration backfills the userName delivered by A1; Device QR Code Palm Registration passes through the userName bound by scanning. Legacy devices may not return it or return an empty string
high_similarity_users	array<object>	No	[Added in v2.4.1] Returned when registration detects a high-similarity registered user (resultCode=50012). Controlled by the need_high_similarity parameter of A6 (default true, covering all registration entries such as host palm registration and Device QR Code Palm Registration). Each item contains user_id, user_name, card_no, and user_tags (tag_id/tag_name); when local user information is not synchronized, only user_id is guaranteed to have a value
countdown_ms	int	No	[Added in v2.4.1] The auto-close countdown (in milliseconds) of the registration result page, with the same semantics as the countdown_ms of the B3 recognition final state. Carried in all final states (common to host palm registration and Device QR Code Palm Registration): default 1000 on success and 3000 on failure, which can be adjusted by tenant theme configuration. The host can use it to synchronize the timing of closing the result page, or ignore it

• palmDirection Value Description:

Value	Description
"1"	Left hand
"2"	Right hand
"-1"	Unknown (abnormal case)

• userState Value Description:

Value	Description	Can Continue to Register the Other Hand
both_unregistered	Neither palm registered (newly created user)	Yes
not_activated	User not activated	Yes
left_valid	Left palm registered	Yes (can register the right hand)
right_valid	Right palm registered	Yes (can register the left hand)
both_valid	Both palms registered	No (both palms are full)

• leftPalm / rightPalm Object Structure Description (PalmInfo):

Field Name	Type	Description
PalmState	string	Palm status: unregistered / pre_registered (aerial palm scan completed) / registered
RegisterType	string	Registration method: Device (device-side palm registration) / Mobile (Mobile H5 palm registration)
PreRegisterTime	string	Aerial palm scan time, in RFC3339 format (e.g., "2026-03-16T12:00:00Z")
RegisterTime	string	Palm registration completion time, in RFC3339 format
ExpireTime	string	Palm print expiration time, in RFC3339 format

• Error Code List:

Note: This document (V2.0) uses a 5-digit error code encoding system.

Error Code	Description
0	Palm registration succeeded
20102	Network request failed (the device cannot connect to the cloud service)
20407	The cloud service returned a business error; refer to the resultMessage field for the specific reason
30001	Task stopped
30002	Task timeout: the confirmation page countdown expired, the scan/palm registration stage timed out, etc.; it is recommended that the host display it as "Registration timeout"
50003	Palm print module runtime error (module exception during palm registration)
50006	Registration canceled: user actively canceled (device screen cancel button / host 0xAC cancel). It is recommended that the host display it neutrally as "Registration canceled" or silently, rather than rendering it as "Registration failed". The confirmation page countdown expiration does not return this code; it returns 30002
50010	The user's palm print is already registered (duplicate registration, including device-side local detection)
50011	Registration failed (generic registration error)
50012	[Added in v2.4.1] Registration detected a high-similarity registered user (controlled by A6 need_high_similarity, enabled by default). A4 will carry the high_similarity_users field to return the high-similarity user details
50305	The corresponding user was not found in the cloud (user ID mismatch)
50306	The user name does not match the cloud record
50901	The user information delivered by the host is invalid (userId or userName is empty)
Other	Unknown error; retry is recommended. Refer to the resultMessage field for the specific reason

• Success Response Example (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"
      }
  }

• Failure Response Example (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"
      }
  }

• High-Similarity User Response Example (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"}
              ]
          }
      ]
  }

Note: leftPalm and rightPalm are optional fields, included in the response only when the backend interface returns the corresponding palm print information. The field content is a PalmInfo JSON object passed through verbatim from the backend, and its subfields (PalmState, RegisterType, PreRegisterTime, RegisterTime, ExpireTime) may be partially missing depending on the backend's actual return.

Palm Registration Result User Data Structure (PalmInfo / PalmState)

The structure definition of the leftPalm / rightPalm fields:

PalmInfo is used to describe the registration status information of a single palm, and is returned via the leftPalm / rightPalm fields when A4 reports the palm registration result.

Field Name	Type	Description
PalmState	string	Palm status; for values, see the PalmState enum below
RegisterType	string	Registration method: Device (device-side palm registration) / Mobile (Mobile H5 palm registration)
PreRegisterTime	string	Aerial palm scan time, in RFC3339 format (e.g., 2026-03-16T12:00:00Z)
RegisterTime	string	Palm registration completion time, in RFC3339 format
ExpireTime	string	Palm print expiration time, in RFC3339 format

PalmState Enum

PalmState indicates the registration status of a single palm; the complete values are as follows:

Enum Value	Description
unregistered	Not registered
pre_registered	Aerial palm scan completed (awaiting device-side registration confirmation)
registered	Registration completed

Host Palm Registration Timing

Dual-Palm Registration Business Flow

The device supports dual-palm registration, i.e., the same user can register the left-hand and right-hand palm prints separately in two sessions. The host can determine the current user's palm print registration progress via the userState field in the returned result, and decide whether to guide the user to register the other hand:

Host Handling Recommendations:

userState Received	Recommended Behavior
both_unregistered / not_activated	First palm scan succeeded (new user); the user can be guided to continue registering the other hand
left_valid	The left hand has been registered; the user can be guided to register the right hand
right_valid	The right hand has been registered; the user can be guided to register the left hand
both_valid	Both palms have been registered; the registration flow is complete

Device QR Code Palm Registration Protocol

Module Positioning: Device QR Code Palm Registration (A6 mode=5)—a registration flow initiated by the device after the user scans a QR code on the device screen to complete identity association. The difference from host palm registration (delivering userId): the user information comes from the scan binding and is not input through the host; during registration, the device pushes intermediate states via B1, among which the user info confirmation state requires the host to display a confirmation UI and reply AC to confirm/cancel. B1 also carries the intermediate states of host palm registration (120/121 progress), and the frame definition is described uniformly in this module.

[Device → Host] Registration Intermediate Status Notification (cmd 0xB1)

At key nodes of the Device QR Code Palm Registration flow, the device pushes registration progress notifications to the host. This frame is an intermediate event and can be pushed multiple times; the final state is subject to A4.

• Communication Protocol: Start 5A5A5A5A + packet sequence number + command code B1 + data field + BCC

• Transmission Data Format:

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

• Field Description:

Field Name	Type	Required to Return	Description
session_id	string	Yes	The ID of this Device QR Code Palm Registration session, generated by the device; consistent with the AC and A4 final states
status_code	int	Yes	Registration stage status enum (see the status_code enum table below)
register_mode	string	Yes	Registration method: cpm (Device QR Code Palm Registration) / host (host palm registration)
user_info	object	No	[Added in v2.4.1] User info object, carried only when status_code=122 (entering the confirmation page). For the structure, see the user_info object description below
timeout_ms	int	No	[Added in v2.4.1] The confirmation page countdown (in milliseconds), carried only when status_code=122, consistent with A6 confirm_timeout_ms

• status_code Enum (Device QR Code Mode):

Enum Value	Meaning	Extension Fields Carried
120	Scan ready (waiting for the phone to present the QR code)	None
121	Scan verifying (calling the backend to verify the QR code)	None
122	Entered the user info confirmation page (waiting for confirmation/cancellation by the device screen or the host)	user_info + timeout_ms
123	Cloud binding (the user has confirmed; binding the palm in the cloud)	None

Note: The confirmation decision events of Device QR Code Palm Registration (device-side local confirmation/cancellation, host AC confirmation/cancellation, UI countdown timeout) do not add a new B1 status_code; the existing B1(123 binding)/A4 final state is used to inform the host of the result. The timeout is handled by the device-side UI itself, and AC is equivalent to the device-side local confirm/cancel button.

• user_info Object Structure:

Field Name	Type	Description
user_id	string	User ID (returned by the backend DescribeQrCodeScanSession)
user_name	string	User name (returned by the backend, may be an empty string)

[Host → Device] Device QR Code Palm Registration Confirmation/Cancellation (cmd 0xAC)

After receiving B1 (status_code=122 entering the confirmation page), the host can send the AC command to make a confirmation/cancellation decision on the Device QR Code Palm Registration session. This command is equivalent to the user clicking the confirm/cancel button on the device screen. The device flow is device-local first, and the host's AC is only an auxiliary operation entry—if the host does not respond, the device can still complete independently or fail on timeout.

• Communication Protocol: Start 5A5A5A5A + packet sequence number + command code AC + data field + BCC

• Transmission Data Format:

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

• Field Description:

Field Name	Type	Required	Description
session_id	string	Yes	Must fill back the session_id delivered by B1, otherwise the device silently discards it
action	string	Yes	Decision action: confirm (confirm, equivalent to clicking the device-local confirm button) / cancel (cancel, equivalent to clicking the device-local cancel button)

• Device-Side Behavior:

Scenario	Device Behavior
Received action=confirm	The device processes it with the same logic as the local confirm button (equivalent to a device-local confirm) → pushes B1(123 binding) → enters cloud binding → A4 final state
Received action=cancel	The device processes it with the same logic as the local cancel button (equivalent to a device-local cancel) → A4 failure final state (carrying countdown_ms)
session_id mismatch	Silently discard + log alert (to prevent a delayed host AC from mistakenly affecting a new session)
AC parsing failed / action invalid	Reply F0 (UnsupportedCmd)
Received in a non-PalmModeRegister mode	Reply F0 (UnsupportedCmd)
Duplicate confirmation from both the device UI and AC entries	Device-side deduplication mechanism: the first confirmation entry takes effect, and subsequent duplicate confirmations are silently ignored (the UI deduplication only prevents double-clicks; cross-entry deduplication is guaranteed internally by the device)

• Error Handling: The device does not immediately reply with an ACK, but informs the result via the existing B1(123) + A4 final state. The host can set a business timeout (e.g., confirm_timeout_ms + 5s) as a fallback.

Disconnection Fallback Description: When the Device QR Code Palm Registration is on the confirmation page (status=122) and the host disconnects (USB unplugged, process crash), the Device QR Code Palm Registration flow continues to run independently—the user can still confirm/cancel on the device, or end the flow via timeout (30002) after the UI countdown expires. B1 is a notification and does not require the host to reply with AC. After reconnecting, the host can query the current mode via A8 and listen to subsequent B1/A4 to synchronize the state.

Complete Timing of Host Device QR Code Palm Registration

The following diagram shows the complete bidirectional interaction in Device QR Code Palm Registration mode (mode=5) from A6 switching to the A4 final state, covering the four branches of normal confirmation, host cancellation, UI countdown timeout, and dual-entry race.

Design Points:

• AC is equivalent to the device-local confirm/cancel button, returning the result via the existing final-state path, without adding a new B1 status_code
• The countdown is led by the device-side UI, and the host UI displays it synchronously (initial value = A6 confirm_timeout_ms)
• The dual-entry race protection only prevents "triggering cloud binding repeatedly"; duplicate cancellation/failure is made idempotent internally by the device, and the host does not need to handle it
• Host disconnection does not affect the device's independent operation (B1 is a notification and does not require the host to reply with AC)

Host Palm Recognition Protocol

Note: This protocol flow can only be executed correctly when the device is in recognition mode

[Host → Device] Invoke Palm Recognition (cmd 0xA5)

The host invokes device palm recognition. After a successful invocation, the device pops up a page to prompt the user to scan the palm (this protocol only invokes the prompt page; even without this protocol, the palm can still be scanned via the device)

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Communication Data Example (hexadecimal):

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

[Device → Host] Recognized User Info Return (A5 Response)

After the user's palm recognition succeeds, the Palm Verification Device returns the corresponding user information. The information type can be selected as UserId or CardNumber in the device's Output Mode setting

• Communication Protocol: Raw data transmission, which does not follow the common data protocol above. The device directly sends the raw byte data of the user information (a UTF-8 encoded string) via the serial port, without encapsulation such as a packet header, packet sequence number, command code, or checksum.

• Field Description:

  Based on the Output Mode setting, the device returns one of the following two fields:

Field Name	Type	Output Mode	Description
UserId	string	UserID mode (mode=1)	The unique user identifier, consistent with the userId delivered by the host during palm registration. The length is not fixed, usually 6~32 ASCII characters
CardNumber	string	CardNumber mode (mode=2)	The user's bank card number, consistent with the physicalCardNumber delivered by the host during palm registration. The length is not fixed, usually a 10~19 digit numeric string

• Data Format Description:

  Based on the Output Mode setting, the device returns one of the following two formats:

  Mode 1: UserId Mode

  The device directly sends the UTF-8 byte stream of the user ID string, for example:

  user123456

  The corresponding hexadecimal data:

  75 73 65 72 31 32 33 34 35 36

  Mode 2: CardNumber Mode

  The device directly sends the UTF-8 byte stream of the bank card number string, for example:

  6222021234567890

  The corresponding hexadecimal data:

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

• Data Transmission End Marker Description:

  This protocol uses raw data transmission and has no explicit data transmission end marker. The host should determine that data reception is complete by the following methods:

  1. Serial idle timeout: After receiving the first byte, the host starts a short timeout timer (a value of 100~200ms is recommended). If no new data is received within the timeout period, this transmission is considered complete
  2. Data length prediction: A UserId is usually 632 bytes, and a CardNumber is usually 1019 bytes. The host can assist the judgment by combining the length of the received data
  3. Distinguish protocol frames from raw data: Raw data does not start with 0x5A5A5A5A, so the host can distinguish this protocol from common protocol frame data by checking the first 4 bytes of the received data

• Host Handling Description:

  1. After receiving the serial data, the host decodes it as a string in UTF-8 to obtain the user information
  2. Determine whether the returned value is a UserId or a CardNumber based on the device's current Output Mode setting
  3. If recognition fails, the device does not send data via this protocol (no response)
  4. Recognition timeout handling: After the host sends A5 to invoke recognition, it is recommended to set a business timeout (e.g., 30 seconds). If no user information is received from the device within the timeout, it should be regarded as no result for this recognition, and the user can be prompted to retry or other business logic can be executed
  5. Exception scenario handling: If the serial connection is disconnected (e.g., the device is unplugged), the host should capture the serial exception event, terminate the current waiting, and prompt the user to check the device connection

• Recognition Error Code Description:

  The recognition response of the A5 protocol uses raw data transmission. On successful recognition, the device directly returns the user information string; on failed recognition, the device does not send any data (no response). The host should determine whether recognition failed via a timeout mechanism.

  The following are scenarios that may cause recognition to have no response:

Scenario	Description	Host Handling Recommendation
Recognition timeout	The user did not complete the palm scan within the valid time	Prompt the user to retry
No matched user	The palm print was recognized successfully but no matching registered user was found	Prompt the user to register the palm print first
Device not ready	The device module is not initialized or is in an abnormal state	Check the device status and restart the device if necessary
Unqualified palm print quality	The quality of the captured palm print image did not meet the recognition requirements	Prompt the user to adjust the palm posture and retry
Network exception	The device cannot connect to the cloud service in cloud recognition mode	Check the device network connection

[Device → Host] Recognition Progress Notification (cmd 0xB2)

During the recognition process, the device pushes key stage events to the host, making it convenient for the host to refresh the UI / count business. This frame is an intermediate event (not a final state), and it may be pushed multiple times in the same recognition.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format:

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

• Field Description:

Field	Type	Description
session_id	string	The current recognition session ID, generated by the device, consistent with the B3 / B4 / B5 frames within the same session
event_id	int	Recognition stage event enum, such as palm print detected / algorithm pre-selection / business verification and other nodes
error_code	int	The error code of this stage; 0 indicates the stage succeeded
error_msg	string	The error description of this stage (when non-empty, it is human-readable text that can be displayed directly or logged)

If the host does not care about the recognition intermediate process, it can ignore this frame; it only needs to consume the B3 final state to complete the recognition business closed loop.

[Device → Host] Recognition Result (cmd 0xB3)

The recognition final-state result. Each complete recognition session has at most one B3 frame, which serves as the final conclusion of this recognition.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format (Success Example):

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

• Transmission Data Format (Failure Example):

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

• Field Description:

Field	Type	Description
session_id	string	The current recognition session ID, consistent with B2 / B4 / B5 of this session, used by the host to link multiple frames of the same recognition
result_code	int	The final recognition result error code; 0 indicates recognition success (the business can be directly allowed), and non-0 indicates failure
error_msg	string	A human-readable description of the failure reason; an empty string when result_code=0
palm_id	string	Palm print feature ID. Non-empty when recognition hits; may be an empty string when recognition misses or fails
user_id	string	The business ID of the hit user. Must be non-empty when result_code=0; may be empty when recognition misses (e.g., blocklist / additional verification failed / not registered)
user_name	string	The business nickname of the hit user. An empty string when recognition misses
retrieve_source	int	The source of the retrieval result: 0=unknown/not applicable, 1=device-side retrieval, 2=aerial palm scan small-library retrieval, 3=cloud large-library retrieval
countdown_ms	int	[Added in v2.2.0] The device recognition result page countdown (in milliseconds); when it expires, the device automatically returns to the home page to prepare for the next recognition. When result_code=0, it takes the success page countdown (default 1000ms); when non-0, it takes the failure page countdown (default 3000ms). The host can align its own UI countdown display with this value to avoid the device already returning to the home page while the host still stays on the result page

B3 is pushed only once per recognition. If recognition hits and no additional verification is required, B3 is the final state; if additional verification is required, B3 is aggregated and sent by the device after the additional-verification flow ends (together with the B5 additional-verification result, it forms the final state).

Linked Recognition · Additional Verification Protocol

In linked recognition mode (A6 mode=1), after the device recognizes a pre-selected user, it may require the host side to complete additional verification (last four digits of the phone number, etc.). This module covers the entire additional-verification interaction process (B4 prompt → AD response / AE cancel → B5 additional-verification result); for the main recognition flow (A5/B2/B3), see "Palm Recognition Protocol".

[Device → Host] Additional-Verification Input Prompt (cmd 0xB4)

When the device requires further user input due to the additional-verification policy (phone number / custom field / QR code scan), it pushes this frame to the host, and the host pops up an input UI to collect the user input.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format (Phone Number Additional-Verification Example):

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

• Transmission Data Format (Custom Field Additional-Verification Example):

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

• Transmission Data Format (QR Code Scan Additional-Verification Example):

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

• Field Description:

Field	Type	Required	Description
session_id	string	Yes	The current recognition session ID, consistent with B2 / B3 / B5 of this session; the host must fill it back when replying with AD / AE, otherwise the device cannot associate
verify_method	string	Yes	Additional-verification method enum: • phone_no: phone number additional verification; the host pops up a phone number input box • custom_field: custom field additional verification; the host pops up a custom text input box (the label is specified by custom_field_label) • qr_code: QR code scan additional verification; the host guides the user to scan a mini-program code to complete verification (no need to collect user input, only a prompt)
user_ids	string[]	Yes	The candidate user ID list, produced by the device recognition pre-selection stage: • length = 1: single-candidate pre-check scenario (e.g., high-similarity hit on a single user) • length > 1: multi-candidate scenario (requires the user to input the additional-verification value to further disambiguate) This field is only for the host's display reference; it does **not** need to be provided again when replying with AD (the device reuses it by session_id)
timeout_ms	int	Yes	The additional-verification input timeout (in milliseconds); the host should render the countdown accordingly. If AD is not returned within this duration, it is regarded as an additional-verification timeout, and the device proactively ends this recognition and delivers B5 / B3
custom_field_label	string	No	The input box label for custom field additional verification (e.g., "Job Number" / "Employee ID"). Present only when verify_method=custom_field; the device does not deliver this field for other additional-verification methods

• Subsequent Frame Timing:

  After receiving this frame, the host should perform any of the following operations within timeout_ms:

  1. The user completes the input → the host replies with 0xAD (carrying session_id + verify_method + input_value), the device initiates backend verification, and delivers 0xB5 after the verification is completed
  2. The user actively cancels → the host replies with 0xAE (carrying only session_id), and the device immediately terminates this additional verification
  3. The user takes no action until timeout → the host does not reply, and the device rolls back on its own when timeout_ms expires, and delivers 0xB5 to indicate the additional verification failed

[Host → Device] Additional-Verification Input Response (cmd 0xAD)

The host returns the additional-verification value input by the user (phone number / custom field) to the device, and the device initiates backend verification accordingly.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format (Phone Number Example):

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

• Transmission Data Format (Custom Field Example):

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

• Field Description:

Field	Type	Required	Description
session_id	string	Yes	Must fill back the session_id delivered in 0xB4, otherwise the device cannot associate this additional verification
verify_method	string	Yes	Consistent with the verify_method delivered in 0xB4: phone_no / custom_field. Note: qr_code additional verification completes the scan closed loop on the device side and does **not** require the host to reply with AD
input_value	string	Yes	The additional-verification value input by the user (phone number or custom field text). The device interprets this field according to verify_method

After receiving AD, the device enters the backend verification stage, and finally delivers 0xB5 to notify the additional-verification conclusion; subsequently it delivers 0xB3 as the final state of the entire recognition.

[Host → Device] Cancel Additional Verification (cmd 0xAE)

The host user actively cancels the additional-verification input, and the device immediately terminates this additional verification and aggregates and delivers 0xB5 / 0xB3 along the "additional verification failed" path.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format:

  {
      "session_id": "sess_a1b2c3"
  }

• Field Description:

Field	Type	Required	Description
session_id	string	Yes	The additional-verification session ID to cancel, which must be consistent with 0xB4

After receiving AE, the device immediately delivers 0xB5 (code = 30000, user cancelled), and then delivers 0xB3 (result_code = 50903 (user cancelled)) as the final state of the entire recognition.

[Device → Host] Additional-Verification Result Notification (cmd 0xB5)

The device pushes the final conclusion of the additional-verification link to the host in the scenarios of additional-verification backend verification completion, additional-verification cancellation, additional-verification timeout, or the fallback after host disconnection. This frame is only the final state of the additional-verification link; the final state of the entire recognition is still subject to 0xB3.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format (Additional-Verification Passed Example):

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

• Transmission Data Format (User Cancelled Example):

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

• Transmission Data Format (Additional-Verification Timeout Example):

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

• Field Description:

Field	Type	Description
session_id	string	The current recognition session ID, consistent with B2 / B3 / B4 of this session
code	int	Additional-verification result error code: • 0: additional verification passed • 30000 (user cancelled): the user actively cancelled (including AE cancellation, device-side UI cancellation, and host disconnection fallback cancellation) • 30002: additional-verification timeout (including timeout_ms expiration and device-side UI countdown expiration) • Other: the specific business error code of a backend verification failure
msg	string	Result text description (human-readable; a success description when code=0, otherwise the failure reason)
pass_user_id	string	The user ID hit when additional verification passes. Must be non-empty when code=0; this field is omitted on a non-0 failure, and the host should handle it as default/empty string when parsing

Disconnection Fallback Description: When the device is in the "waiting for the host to reply with AD" state, if the USB is physically unplugged or the host process exits causing the serial connection to disconnect, the device will proactively trigger a cancellation/timeout recovery: first push B5 with code=30000 (fire-and-forget, which will actually not reach the host in a disconnection scenario, only used for internal state cleanup), then deliver the 0xB3 final state to end this recognition session, avoiding the device staying in the additional-verification intermediate state.

Complete Timing of Host Linked Recognition

The following diagram shows the complete bidirectional interaction in linked recognition mode (mode=1) from the device starting recognition to the B3 final state. It covers the following branches: recognition hit → direct pass, hit pre-selection → additional verification required → input passed, additional verification required → user cancels, additional verification required → host disconnection fallback.

Session Linking: The B2 / B3 / B4 / B5 / AD / AE frames of the same recognition all use the same session_id. When the device enters the next round of recognition, it generates a new session_id; when the host receives a B2 carrying a new session, it should immediately clear the display state of the previous round (recognition result page / additional-verification input box).

Host Delete User Protocol

This section was introduced in V2.4.1. Independent of the device mode: 0xAF can be processed in any work mode (standalone mode / recognition mode / registration mode, etc.); after receiving it, the device requests the cloud to delete the user and synchronously replies with 0xB6 to inform the result.

Synchronous reply mode: the host delivers the request → the device requests the cloud to delete → the device immediately replies with the final state. Unlike the "asynchronous dual-frame" of palm registration (A1 initiation / A4 final state), this protocol is one request and one answer, suitable for the "short operation + immediate result return" deletion scenario.

Local Data Linkage: the device does not proactively clean up the local user record. After the cloud deletion succeeds, the local data is naturally updated according to the cloud state at the next auto-sync (the deletion takes effect automatically without extra operations).

[Host → Device] Delete User Request (cmd 0xAF)

The host delivers the user ID, requesting the device to delete the user (the device will synchronously request the cloud).

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format:

  {
      "user_id": "user123456"
  }

• Field Description:

Field Name	Type	Required to Return	Description
user_id	string	Yes	The user ID to be deleted, consistent with the userId delivered by the host during palm registration (A1 field). A non-empty string with a length of 1~64, allowing only letters, digits, hyphens, and underscores

• Communication Data Example (hexadecimal):

  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

[Device → Host] Delete User Response (cmd 0xB6)

After receiving 0xAF, the device requests the cloud to delete the user, and replies according to the cloud return result. The response fields are exactly the same as 0xA7 SwitchModeResp (code + message), and the host can reuse the same parser.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol · Physical-Layer Protocol Configuration" (the command code and data field are subject to the JSON below)

• Transmission Data Format (Success Example):

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

• Transmission Data Format (Failure Example):

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

• Field Description:

Field Name	Type	Required to Return	Description
code	int	Yes	0 indicates deletion succeeded, non-0 indicates failure (see the error code list for details)
message	string	Yes	Result description. "Success" on success, and a human-readable failure reason on failure

• Error Code List:

Error Code	Description
0	Deletion succeeded
10501	Request JSON parsing failed (the data field is not valid JSON)
10100	Parameter error: UserId is empty or missing
20102	Network request failed (the device cannot connect to the cloud service)
20407	Cloud business error (e.g., the user does not exist); refer to the message field for the specific reason
50904	[Added in v2.4.1] Host delete user failure fallback code: used when the cloud returns non-0 but there is no specific biz_code
Other	Unknown error; retry is recommended. Refer to the message field for the specific reason

• Success Response Example (JSON):

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

• Failure Response Example (JSON):

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

Interaction Description: 0xAF → the device calls the cloud → 0xB6 synchronously replies with the final state (unlike the A1/A4 asynchronous dual-frame). It is recommended that the host set a 30s business timeout as a fallback. For the success/failure code, see the field description and error code table above; the device does not linkage-clean the local DB.

Host Device Health Status Protocol

This section was introduced in V2.1.0. After the device aggregates multiple types of sources such as "network / palm print module / activation / tenant / authorization", it exposes a unified high-level health_state field externally, allowing the host to use a single metric to decide the UI display and text, and informs whether manual intervention is needed and what to do via the sub_status sub-status field.

Trigger Timing

The device sends cmd 0xB0 in any of the following situations:

1. Periodic reporting: After the device starts, it automatically reports once every 30s (consistent with "auto-refresh every 30 seconds")
2. Immediate reporting on abnormal change: When any of the following states changes, a frame is pushed within 100ms (consecutive changes within a short time are merged into one frame to avoid screen flooding):
   • Network online/offline status change (Wi-Fi / Ethernet)
   • Palm print module work status changes to Error / Blocked or recovers from an exception
   • The device needs QR code scan activation (needActivation)
   • Tenant enable/disable switch (tenantStatusChanged)
   • Service initialization failure hits 50000 / 50001 / 50105
   • Heartbeat/activation state is cleared by the cloud: 50101 / 50103 / 50104; the device clears the local activation data and delivers health_state=20, with sub_status.last_error_code indicating the specific reason code
   • [Added in v2.3.0] Tenant scene configuration change (e.g., the registration capability is enabled/disabled by the admin console); the capabilities field carries the latest value along with the frame
3. Host active query: The host sends cmd 0xAA, and the device replies with 0xAB within 1 second, with a payload field set exactly the same as 0xB0

Note: A legacy host (that does not recognize 0xB0/0xAA/0xAB) should ignore the frame when it receives an unrecognized cmd; the device is only responsible for sending according to the specification.

health_state Value Table (the larger the value, the more severe; take the most severe one among all sources)

Value	Enum Name	Meaning	human_action_hint
0	HEALTHY	All dimensions are normal and can be used normally (including sleep states S0/S1)	""
10	WARN_NETWORK_OFFLINE	Only the network is offline; other dimensions are healthy	check_network
20	NEED_INTERVENTION_NOT_ACTIVATED	The device is not activated; QR code scan activation is required	scan_qr_to_activate
21	NEED_INTERVENTION_TENANT_DISABLED	The tenant is disabled	contact_admin_tenant_disabled
22	NEED_INTERVENTION_SERVICE_DISABLED	The service is disabled	contact_admin_service_disabled
30	ERROR_PALM_AUTH_FAILED	Module authorization failed/expired	contact_admin_palm_auth
31	ERROR_PALM_MODULE	Palm print module exception	check_palm_module
32	ERROR_PALM_BLOCKED	Palm print module blocklisted/blocked	check_palm_module
99	UNKNOWN	A valid state has not yet been obtained in the early startup stage	""

[Device → Host] Device Status Active Notification (cmd 0xB0)

The device proactively reports the current health status.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol" (the command code and data field are subject to the data format below)

• Data Field JSON Fields:

Field	Type	Description
sn	string	Device serial number
timestamp	string	Millisecond-level Unix timestamp (carried as a string to avoid large-integer precision loss)
app_version	string	Device application version number
work_mode	int	The current work mode (0=standalone mode, 1~5=linkage mode, consistent with the mode field of A9)
health_state	int	High-level health status (see the value table above)
network_status	int	0=offline, 1=online
network_type	int	0=not connected, 1=wired, 2=Wi-Fi
protocol_version	string	[Added in v2.2.0] Protocol version number (e.g., "1.1.0"); the host can use it to determine which extension capabilities the device supports; "1.1.0" indicates support for the QR Code Palm Registration / recognition progress / additional-verification interaction protocols
sub_status	object	Sub-status details (see the table below)
capabilities	object	[Added in v2.3.0] Device registration capability flags (see the table below). A legacy host should ignore this field when it receives it; when a legacy device does not carry this field, the host defaults to both registration methods being available

• sub_status Sub-fields: (all required; when there is no corresponding source, fill in the default value, do not omit the key)

Field	Type	Description
module_status	int	Palm print module status; unknown/not connected=0, normal>0
is_activated	int	0=not activated, 1=activated
tenant_status	int	1=enabled, 2=disabled, 0=unknown
palm_auth_ok	int	0=authorization failed/expired, 1=authorization normal
service_enabled	int	1=service available, 0=disabled in the backend
last_error_code	int	The error code that most recently triggered a "non-HEALTHY" state; 0 if none. Common values (used together with health_state=20 to determine the intervention reason): 50101 authorization expired / 50103 site changed / 50104 site unbound / 50105 not registered
cpm_register	int	1=supports Device QR Code Palm Registration (mode=5), 0=not supported. Determined by the tenant registration capability configuration

• JSON Example:

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

[Host → Device] Device Status Query (cmd 0xAA)

The host proactively queries the device health status.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol" (the command code and data field are subject to the data format below)

• Description: The query does not require any input parameters; even if an invalid / empty payload is carried, the device ignores the payload and replies normally with 0xAB, without returning UnsupportedCmdNotify.
• Response: The device replies with cmd 0xAB within 1 second.
• Communication Data Example (hexadecimal):

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

[Device → Host] Device Status Query Response (cmd 0xAB)

The device responds to the host's health status query, with a payload field set exactly the same as 0xB0, making it convenient for the host to use the same parser.

• Communication Protocol:

For the frame structure, see "Common Configuration and Protocol" (the command code and data field are subject to the data format below)

The device can respond to this query in any work mode (recognition / palm registration / host palm registration, etc.), regardless of page or mode; it can reply normally even when the whole is in NEED_INTERVENTION_* / ERROR_* (such as not activated, module exception), ensuring the host can always obtain the latest fault details.

Appendix: Global Error Code Summary

The following is a summary of all error codes that may be encountered during communication between the host and the device, organized by scenario.

Palm Registration Error Codes (A4 Report Palm Registration Result)

When the device reports the palm registration result via command code A4, resultCode may take the following values:

Value	Description	Handling Recommendation
0	Palm registration succeeded	-
20102	Network request failed (the device cannot connect to the cloud service)	Check the device network connection and retry
20407	The cloud service returned a business error	Refer to the resultMessage field for the specific reason
50003	Palm print module runtime error	Restart the device and retry
50010	The user's palm print is already registered (duplicate registration, including device-side local detection)	Prompt the user that registration is complete; no need to re-scan the palm
50011	Registration failed (generic registration error)	Retry; if it keeps failing, check the device status
50012	Registration detected a high-similarity registered user (controlled by A6 need_high_similarity, enabled by default)	Display and check the high_similarity_users user details; registration did not create a new palm print
50305	The corresponding user was not found in the cloud (user ID mismatch)	Confirm the userId is consistent with the cloud
50306	The user name does not match the cloud record	Confirm the userName is consistent with the cloud
50901	The user information delivered by the host is invalid (userId or userName is empty)	Check that the userId and userName fields in the A1 command are not empty
50308	Host registration mode has been disabled by the admin console (added in v2.3.0)	Contact the administrator to enable the host registration permission in the backend and retry
Other	Unknown error	Refer to the resultMessage field; retry is recommended

Mode Switching Error Codes (A7 Report Switching Result)

Value	Description	Handling Recommendation
0	Mode switching succeeded	-
10100	Parameter error; the target mode is not within the valid range (0~5)	Check whether the mode field value is 0~5
10501	Failed to parse the request data format	Check whether the A6 command data field JSON format is correct
50902	The device is not currently on the main screen and cannot switch mode	Wait for the device to return to the main screen and retry
Other	Mode switching failed	Retry

Common Error Codes

Note: This document (V2.0) uses a 5-digit error code encoding system with a PPCCSS segmented structure. The table below lists all error codes that may be encountered in host communication.

Value	Description	Handling Recommendation
0	Success	-
10100	Invalid parameter	Check whether the command data field values are valid
10501	JSON data parsing failed	Check whether the data field JSON format is correct
20102	Network request failed (the device cannot connect to the cloud service)	Check the device network connection and retry
20407	The cloud service returned a business error	Refer to the resultMessage field for the specific reason
50003	Palm print module runtime error	Restart the device and retry
50010	Duplicate registration (including device-side local detection)	Prompt the user that registration is complete; no need to re-scan the palm
50011	Registration failed (generic registration error)	Retry; if it keeps failing, check the device status
50012	Registration detected a high-similarity registered user (controlled by A6 need_high_similarity, enabled by default)	Display and check the high_similarity_users user details; registration did not create a new palm print
50305	User not found	Confirm the userId is consistent with the cloud
50306	User information mismatch	Confirm the userName is consistent with the cloud
50900	The host is not connected (the serial port is not connected)	Check whether the USB serial cable connection is normal
50901	The user information delivered by the host is invalid	Check that the userId and userName fields are not empty
50902	The device is not currently on the main screen (triggered only for linkage mode=1~5 switching)	Wait for the device to return to the main screen and retry
50903	The host user cancelled additional verification (B3 result_code may take this value)	The business side silently discards it and does not display a failure final state
50904	Host delete user failure fallback (v2.4.1, B6 code may take this value)	Refer to the message field; retry is recommended
50308	The current registration mode has been disabled by the admin console (added in v2.3.0)	Contact the administrator to enable the corresponding registration mode permission in the backend and retry
30000	The task was cancelled (e.g., the additional-verification input was cancelled, the device proactively cancelled)	Regard it as the user actively cancelling; the UI silently recovers
30002	The task timed out (e.g., the additional-verification input timed out, the scan timed out)	Regard it as a timeout; the user can be prompted to retry

Recognition / Additional-Verification Error Codes (B3 result_code / B5 code)

When the device reports the recognition/additional-verification final state via B3 (result_code field) and B5 (code field), it may return the following business error codes. Except for 50006 (ignorable) and 50903 (user cancelled) which are handled silently, it is recommended that the host display a failure prompt for the rest.

Value	Description	Handling Recommendation
50000	Module authorization failed/expired	The device will jump to the authorization page; contact the administrator to reactivate
50001	Module hardware error	The device will jump to the module exception page; restarting the device is recommended
50002	Palm print retrieval is empty (unregistered user)	Prompt the user to register the palm print first
50003	PalmManager non-ignorable error	Prompt the user to retry; contact the administrator if it keeps failing
50004	The application DB cannot find the user information	Contact the administrator to check the user data
50005	Module blocklist interception	Contact the administrator to remove the blocklist
50006	Ignorable error (user cancelled / hand out of bounds, etc.)	Silently discard; do not display a failure final state
50007	First-time verification activation failed	Prompt the user to check the phone number and retry
50008	Verification failed	Prompt the user to retry
50200	User list interception	Contact the administrator to grant permission
50201	Time rule interception	Prompt that it is not within the allowed time period
50203	Online verification failed (fallback)	Contact the administrator to check the online verification configuration
50206	Count limit rule interception	Prompt that the verification count has reached the upper limit; retry later
50207	Online verification request failed/timed out	Prompt to check the network and retry
50208	Online verification service error	Prompt that the service is temporarily unavailable; retry later
50209	Third-party service verification failed	Contact the administrator to check the third-party verification result