M4 Bidirectional Communication Protocol Interface Documentation

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

Version History

Version	Release Date	Update Type	Update Description
V2.3.0	2026-07-03	Added	Added error code kRegisterModeDisabled (50308): after the corresponding registration mode is disabled in the admin console (e.g., enable_pc_registration=false), the device rejects the request at the registration entry and reports this error code via A4; B0/AB added a capabilities field carrying the device registration capability flags (pc_registration_enabled / device_qrcode_enabled), which are updated in real time along with the health status frame when the tenant scenario configuration changes
V2.2.0	2026-06-02	Added	Added device health status protocol (B0/AA/AB); added CPM QR Code enrollment (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 coordination; A4 extended with register_mode field; B0/AB extended with protocol_version and work_mode=0 fields; B3 recognition final state added countdown_ms (result page countdown for host UI alignment with the device); on host disconnect/cancel/timeout, the device proactively sends 0xB5 final state (to prevent the host from remaining in selection/waiting state); 0xB0 sub_status.last_error_code supplemented with 50101/50103/50104 for precise host diagnosis of deactivation causes; completed detailed field descriptions for AD/AE/B5 protocols and full coordinated recognition sequence diagram
V2.0.0	2026-03-14	Added	Added userState/palmDirection fields to support dual palm registration scenarios
V1.8.0	2026-03-10	Enhancement	Added usage scenarios, architecture diagram, and error codes
V1.7.0	2026-01-05	Added	Initial release

V2.0 Breaking Change Notice: V2.0 introduced userState, palmDirection, leftPalm, and rightPalm fields in the A4 (Report Palm Registration Result) protocol. Host applications must adapt to the new fields to support dual palm registration scenarios. V1.x hosts that do not parse the new fields will not lose existing functionality, but will be unable to retrieve dual palm registration status information. Immediate upgrade to V2.0 protocol is recommended.

Introduction

Interface Overview

This document is the host bidirectional communication protocol interface documentation for the M4 Palm Verification Device, describing how the host interacts with the palm verification device via USB serial port to implement core functions such as palm registration, palm print recognition, and device mode management.

Applicable Scenarios

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

1. Palm Registration: Counter staff or self-service kiosks initiate a palm registration request from the host side, sending user information (ID, name, phone number, bank card number) to the palm verification device via the serial port. The user completes palm print capture on the device, and the enrollment result is sent back to the host. Supports dual palm registration, meaning the same user can enroll the left and right palm prints in two separate sessions, with the device returning the user's palm print enrollment status via the userState field.
2. Palm Print Recognition: The host can invoke the device's palm print recognition page. After the user completes palm scanning, the device returns the recognized user information (UserId or CardNumber) to the host for identity confirmation, payment, and other business purposes.
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-side palm registration), flexibly adapting to different business scenarios. Supports mode=0 to exit coordination, returning the device to standalone work mode.

Core Features

1. Host-Side Palm Registration: The host sends user information to the device, and the user completes palm print capture on the device; supports dual palm registration
2. Palm Print Recognition Invocation: The host invokes the device's palm print recognition page and retrieves recognized user information
3. Device Mode Management: The host queries and switches device work modes (recognition, mobile H5 palm registration, device-side palm registration, host-side palm registration)

Quick Start

Environment Requirements

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

Integration Steps

1. Install the PL2303 serial driver for the corresponding operating system
2. Connect the host to the palm verification device using a USB-to-serial cable
3. Open the serial port according to the physical layer protocol configuration (115200/8/N/1)
4. Send the corresponding command code based on the business scenario (A1 for palm registration, A5 for palm print recognition, A6 for mode switching)
5. Parse the response data packet returned by the device

Minimal Example

The following is a complete Invoke Palm Registration (A1) → Enrollment Information Confirmation (A2) interaction example in hexadecimal:

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 Enrollment Information Confirmation):

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

Data packet structure: Start Characters (4B) + Packet Sequence Number (2B, big-endian) + Command Code (1B) + Data Field Length (2B, big-endian) + Data Field (NB) + BCC Checksum (1B)

Interface Overview

**Command Code**	**Function Description**	**Communication Direction**
A1	Invoke Palm Registration	Host → Device
A2	Enrollment Information Confirmation	Device → Host
A3	Cancel Palm Registration	Host → Device
A4	Report Palm Registration Result	Device → Host
A5	Invoke Palm Print Recognition	Host → Device
A5 (Response)	Report Recognized User Information	Device → Host
A6	Switch Mode (mode=0 exit coordination / mode=1~5 enter coordination)	Host → Device
A7	Report Mode Switching Result	Device → Host
A8	Query Device Mode	Host → Device
A9	Respond with Current Mode	Device → Host
F0	Unknown Command Code Error Response	Device → Host
AD	Return Additional Verification Value (phone_no / custom_field) [Added in v2.2.0]	Host → Device
AE	Cancel Additional Verification [Added in v2.2.0]	Host → Device
B1	Enrollment Intermediate Status Notification (CPM QR Code Enrollment Progress) [Added in v2.2.0]	Device → Host
B2	Recognition Stage Event Notification [Added in v2.2.0]	Device → Host
B3	Recognition Final Result [Added in v2.2.0]	Device → Host
B4	Invoke Additional Verification Input (with timeout_ms) [Added in v2.2.0]	Device → Host
B5	Additional Verification Final Result [Added in v2.2.0]	Device → Host

Usage Scenarios

This document describes the protocol specification for the host (such as PC, cash register, self-service kiosk, or other external host) to communicate bidirectionally with the palm verification device (M4) via a serial port (USB-to-serial, chip model PL2303).

Prerequisites

• The device and host are physically connected via a USB-to-serial cable (PL2303 chip)
• The host has installed the serial driver for the corresponding operating system. Note: on macOS you must also enable the driver: Login Items & Extensions → Driver Extensions → enable the PL2303Serial driver
• The device must be switched to host-side palm registration mode (mode=4) to correctly execute palm registration protocols

System Architecture

Communication Mode Description:

• The host and palm verification device are connected via USB-to-serial (PL2303 chip), using a command-response mode for bidirectional communication
• Host → Device: Sends commands (invoke palm registration, cancel palm registration, invoke recognition, switch/query mode)
• Device → Host: Returns confirmation, reports results (palm registration result, recognized user information, mode switching result, current mode)

Host-Side Palm Registration Sequence

General Configuration and Protocol

Host Driver

**Operating System**	**Download Link**
macOS	[‎PL2303 Serial App](https://apps.apple.com/cn/app/pl2303-serial/id1624835354?mt=12)
Windows	[PL2303GL](https://www.prolific.com.tw/portfolio-item/pl2303gl/)

Authentication Method

This protocol is a device-local serial communication protocol. The host and palm verification device are physically connected directly via USB, and no handshake authentication or authorization is required. The device can receive host commands once powered on, without any prerequisite process such as device activation or key exchange. The device's cloud authentication (such as token authentication) is managed internally by the device and is unrelated to the host serial communication.

Physical Layer Protocol Configuration

**Parameter**	**Configuration**
Baud Rate	115200
Data Bits	8
Stop Bits	1
Parity	None
Flow Control	None

General Data Packet Format Example

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	A1	0001	01	2D

• Start Characters (4 bytes):

  The identifier marking the beginning of the packet, fixed as 0x5A5A5A5A

• Packet Sequence Number (2 bytes, Big-Endian):

  Starts from 0 and increments by one each time a packet is sent, cycling back to 0 after reaching 0xFFFF. 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. Relevant 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 data field length):

  The meaning of this field is parsed according to 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 characters.

Byte Order Note: 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.

Host-Side Palm Registration Protocol

Note: This protocol flow can only be executed correctly when the device is in host-side palm registration mode.

【Host → Device】 Invoke Palm Registration

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

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**A1**	Determined by data length	User information	Obtained by BCC calculation

• Transmission Data Format:

  {
      "userId": "user123456",
      "userName": "Test User",
      "phone": "15997475680",
      "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】Enrollment Information Confirmation

After the palm verification device receives the Invoke Palm Registration command sent by the host, it sends this command to inform the host that it has received the user data and is now in the enrollment flow.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**A2**	0000	None	A3

• Communication Data Example (Hexadecimal):

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

【Host → Device】Cancel Palm Registration

While waiting for the palm registration result from the palm verification device, the host can send a command to cancel palm registration.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**A3**	0000	None	A2

• Communication Data Example (Hexadecimal):

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

【Device → Host】Report Palm Registration Result

After the user's palm registration succeeds or fails, the palm verification device returns the corresponding enrollment result, and the host can display the corresponding interface based on the result.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**A4**	Determined by data length	Palm enrollment result	Obtained by BCC calculation

• Transmission Data Format:

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

• Field Descriptions:

**Field Name**	**Type**	**Required**	**Description**
resultCode	int	Yes	Palm enrollment result code, 0 indicates success, non-0 indicates failure (see the error code list for details)
resultMessage	string	Yes	Palm enrollment result description
palmDirection	string	Yes	The palm direction enrolled this time. "1" = left hand, "2" = right hand, "-1" = unknown
userState	string	Returned on success	User palm print status (only meaningful when resultCode=0). See the userState enumeration table below for specific values
leftPalm	object	No	Left palm details (optional), passes through the left palm JSON object returned by the backend. This field is not included when the backend does not return it. See the leftPalm/rightPalm structure description below for specific sub-fields
rightPalm	object	No	Right palm details (optional), passes through the right palm JSON object returned by the backend. This field is not included when the backend does not return it. See the leftPalm/rightPalm structure description below for specific sub-fields
register_mode	string	Yes	[Added in v2.2.0] Registration method: host (host-side palm registration) / cpm (CPM QR Code enrollment). The host can use this to distinguish between the results of the two enrollment flows

• leftPalm / rightPalm Object Structure Description (PalmInfo):

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

• palmDirection Value Description:

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

• userState Value Description:

**Value**	**Description**	**Can Continue to Enroll the Other Hand**
both_unregistered	Neither palm has been enrolled (newly created user)	Yes
not_activated	User not activated	Yes
left_valid	Left palm has been enrolled	Yes (right hand can be enrolled)
right_valid	Right palm has been enrolled	Yes (left hand can be enrolled)
both_valid	Both palms have been enrolled	No (both palms are full)

• Error Code List:

Note: This document (V2.0) uses a 5-digit error code encoding system. Subsequent versions will migrate further to a unified TxCode encoding system.

**Error Code**	**Description**
0	Palm enrollment succeeded
20102	Network request failed (device cannot connect to cloud service)
20407	Cloud service returned a business error; refer to the resultMessage field for the specific reason
50003	Palm module runtime error (module exception during enrollment)
50010	The user's palm print is already registered (duplicate registration, including device-side local detection)
50011	Registration failed (general registration error)
50305	Corresponding user not found in the cloud (user ID mismatch)
50306	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",
      "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",
      "palmDirection": "2",
      "userState": "",
      "leftPalm": {
          "PalmState": "registered",
          "RegisterType": "Device",
          "RegisterTime": "2026-03-15T08:30:00Z",
          "ExpireTime": "2027-03-15T08:30:00Z"
      },
      "rightPalm": {
          "PalmState": "unregistered"
      }
  }

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 the PalmInfo JSON object passed through as-is from the backend, and each sub-field (PalmState, RegisterType, PreRegisterTime, RegisterTime, ExpireTime) may be partially absent depending on the actual backend response.

Dual Palm Registration Business Flow

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

Host Processing Recommendations:

Received userState	Recommended Behavior
both_unregistered / not_activated	First enrollment succeeded (new user); can guide the user to continue enrolling the other hand
left_valid	Left hand enrolled; can guide the user to enroll the right hand
right_valid	Right hand enrolled; can guide the user to enroll the left hand
both_valid	Both palms enrolled; enrollment flow complete

Host-Side Palm Print Recognition Protocol

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

【Host → Device】Invoke Palm Print Recognition

The host invokes device palm print recognition. After a successful invocation, the device pops up a page prompting the user to scan their palm (this protocol only invokes the prompt page; palm scanning on the device is still possible without this protocol).

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**A5**	0000	None	A4

• Communication Data Example (Hexadecimal):

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

【Device → Host】Report Recognized User Information

After the user's palm print recognition succeeds, the palm verification device returns the corresponding user information. This information type can be selected as UserId or CardNumber in the device's Output Mode settings.

• Communication Protocol: Raw data transmission, not following the general data protocol above. The device sends the raw byte data of the user information (UTF-8 encoded string) directly over the serial port, without any packaging such as packet header, packet sequence number, command code, or checksum.

• Field Descriptions:

  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)	User unique 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)	User 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

  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

  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 with no explicit data transmission end marker. The host should determine that data reception is complete by the following methods:

  1. Serial Port Idle Timeout: After receiving the first byte, the host starts a short timeout timer (recommended 100~200ms). If no new data is received within the timeout period, the transmission is considered complete
  2. Data Length Estimation: UserId is usually 632 bytes, and CardNumber is usually 1019 bytes. The host can use the length of the received data to assist in the determination
  3. Distinguishing Protocol Frames from Raw Data: Raw data does not start with 0x5A5A5A5A. The host can distinguish this protocol from general protocol frame data by checking the first 4 bytes of the received data

• Host Processing Description:

  1. After receiving the serial data, the host decodes it as a UTF-8 string to obtain the user information
  2. Determine whether the returned data is UserId or CardNumber based on the current device's 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 treated as no result for this recognition, and the host can prompt the user to retry or execute other business logic
  5. Exception Scenario Handling: If the serial connection is disconnected (device unplugged, etc.), the host should capture the serial exception event, terminate the current wait, and prompt the user to check the device connection

• Recognition Error Code Description:

  The A5 protocol's recognition response 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 has failed via a timeout mechanism.

  The following are scenarios that may cause no recognition response:

**Scenario**	**Description**	**Host Processing Recommendation**
Recognition timeout	User did not complete palm scanning within the valid time	Prompt the user to retry
No matching user	Palm Print recognition succeeded but no matching registered user was found	Prompt the user to enroll their palm print first
Device not ready	Device module not initialized or in an abnormal state	Check the device status and restart the device if necessary
Palm Print quality unqualified	The captured palm print image quality did not meet the recognition requirements	Prompt the user to adjust their palm posture and retry
Network exception	The device cannot connect to the cloud service in cloud recognition mode	Check the device network connection

Host-Side Mode Switching Protocol

Note: mode=1~5 coordinated mode switching can only be executed correctly when the device is on the main interface; mode=0 exit coordination is not subject to this restriction.

【Host → Device】 Switch Mode

The host controls the switching of the palm scanning mode the device is currently in.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**A6**	Determined by data length	Mode to switch to	Obtained by BCC calculation

• Transmission Data Format:

  {
      "mode": 1
  }

• Work Mode List:

**Value**	**Mode**	**Description**
0	Standalone Mode (Exit Coordination) [Added in v2.2.0]	The device exits coordination with the host and works independently according to the locally persisted configuration. The device no longer pushes recognition progress (B2), recognition results (B3), additional verification requests (B4), additional verification results (B5), or other notifications to the host. The host can send mode=1~5 again to re-enter coordination mode. **The device is in this mode by default after startup.**
1	Recognition Mode	Enter coordinated recognition mode; palm scanning results are pushed to the host
2	Registration Mode - Mobile H5 Palm Registration	-
3	Registration Mode - Device-Side Palm Registration	-
4	Registration Mode - Host-Side Palm Registration	-
5	Registration Mode - CPM QR Code Enrollment	-

• 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】Report Switched Mode

After receiving the mode switching command from the host, 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:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**A7**	Determined by data length	Mode switching result	Obtained by BCC calculation

• 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 out of the valid range (0~5)
10501	Request data format parsing failed
50902	The device is currently not on the main interface (only triggered for mode=1~5; mode=0 exit coordination 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-Side Mode Query Protocol

【Host → Device】Query Device Mode

The host queries the mode the device is currently in.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**A8**	0000	None	A9

• Communication Data Example (Hexadecimal):

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

【Device → Host】 Respond with Current Mode

After the host sends a query command, the device returns the mode it is currently in via this protocol.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**A9**	Determined by data length	Current mode	Obtained by BCC calculation

• Transmission Data Format:

  {
      "mode": 1
  }

• mode Field Enumeration Value Description:

**Value**	**Mode**
0	Standalone Mode (not coordinated 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-Side Palm Registration
5	Registration Mode - CPM QR Code Enrollment

• 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-Side Coordinated Recognition · Recognition Progress and Additional Verification Interaction Protocol

This chapter was introduced in V2.2.0. It only takes effect in coordinated recognition mode (mode=1). After the device enters standalone mode (mode=0), it will not push the B2/B3/B4/B5 frames defined in this chapter, and AD/AE frames will no longer be processed.

【Device → Host】RecognizeProgressNotify (cmd 0xB2)

During recognition, the device pushes key stage events to the host to facilitate host UI refresh / business counting. This frame is an intermediate event (non-final state), and may be pushed multiple times within the same recognition session.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**B2**	Determined by data length	Recognition stage event	Obtained by BCC calculation

• Transmission Data Format:

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

• Field Descriptions:

**Field**	**Type**	**Description**
session_id	string	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 enumeration (PalmProcessEventId), such as palm print detected / algorithm pre-selection / business validation and other nodes
error_code	int	The error code for this stage; 0 indicates the stage succeeded
error_msg	string	The error description for 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; consuming only the B3 final state result is sufficient to complete the recognition business loop.

【Device → Host】RecognizeResultReq (cmd 0xB3)

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

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**B3**	Determined by data length	Recognition final state result	Obtained by BCC calculation

• 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 Descriptions:

**Field**	**Type**	**Description**
session_id	string	Current recognition session ID, consistent with B2 / B4 / B5 of this session, used by the host to correlate multiple frames of the same recognition
result_code	int	Final recognition result error code. 0 indicates recognition success (business can proceed directly), non-0 indicates failure
error_msg	string	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	Business ID of the matched user. Must be non-empty when result_code=0; may be empty when recognition misses (e.g., blocklist / additional verification failure / not registered)
user_name	string	Business nickname of the matched user. An empty string when recognition misses
retrieve_source	int	Retrieval result source: 0=unknown/not applicable, 1=device-side retrieval, 2=aerial palm registration small-library retrieval, 3=cloud large-library retrieval
countdown_ms	int	[Added in v2.2.0] Device recognition result page countdown (milliseconds). When it expires, the device automatically returns to the home page ready for the next recognition. When result_code=0, the success page countdown is used (default 1000ms); when non-0, the failure page countdown is used (default 3000ms). The host can align its own UI countdown display with this value to avoid the device having returned to the home page while the host still remains 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 sent by the device in aggregate after the additional verification flow ends (together with the B5 additional verification result, forming the final state).

【Device → Host】VerifyPromptNotify (cmd 0xB4)

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

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**B4**	Determined by data length	Additional verification input prompt	Obtained by BCC calculation

• 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 Additional Verification Example):

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

• Field Descriptions:

**Field**	**Type**	**Required**	**Description**
session_id	string	Yes	Current recognition session ID, consistent with B2 / B3 / B5 of this session; the host must fill this value back when returning AD / AE, otherwise the device will be unable to correlate
verify_method	string	Yes	Additional verification method enumeration: • 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 (label specified by custom_field_label) • qr_code: QR code additional verification, the host guides the user to scan the mini-program code to complete the verification (no need to collect user input, only prompt)
user_ids	string[]	Yes	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 user to input a additional verification value for further disambiguation) This field is for host display reference only; it does **not** need to be provided again when returning AD (the device reuses it by session_id)
timeout_ms	int	Yes	Additional verification input timeout (milliseconds); the host should render a countdown accordingly. If AD is not returned within this duration, it is treated as a additional verification timeout, and the device will proactively end this recognition and send B5 / B3
custom_field_label	string	No	The input box label for custom field additional verification (e.g., "Employee ID" / "Staff No."). Exists only when verify_method=custom_field; the device does not send this field under other additional verification methods

• Subsequent Frame Sequence:

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

  1. User completes input → the host returns 0xAD VerifyInputResp (carrying session_id + verify_method + input_value), the device initiates backend validation, and sends 0xB5 VerifyResultNotify after validation completes
  2. User actively cancels → the host returns 0xAE VerifyCancelReq (carrying only session_id), and the device immediately terminates this additional verification
  3. User does not act before timeout → the host does not return a packet, and the device rolls back on its own when timeout_ms expires, sending 0xB5 to indicate additional verification failure

【Host → Device】VerifyInputResp (cmd 0xAD)

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

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**AD**	Determined by data length	Additional verification input value	Obtained by BCC calculation

• 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 Descriptions:

**Field**	**Type**	**Required**	**Description**
session_id	string	Yes	Must fill back the session_id delivered in 0xB4, otherwise the device cannot correlate 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 loop on the device side and does **not** require the host to return AD
input_value	string	Yes	The additional verification value entered 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 validation stage, and finally sends 0xB5 VerifyResultNotify to announce the additional verification conclusion; it then sends 0xB3 RecognizeResultReq as the final state of the entire recognition.

【Host → Device】VerifyCancelReq (cmd 0xAE)

The host user actively cancels the additional verification input. The device immediately terminates this additional verification and sends 0xB5 / 0xB3 in aggregate along the "additional verification failure" path.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**AE**	Determined by data length	Cancel additional verification	Obtained by BCC calculation

• Transmission Data Format:

  {
      "session_id": "sess_a1b2c3"
  }

• Field Descriptions:

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

After receiving AE, the device immediately sends 0xB5 (code = 30000 kTaskCancelled), then sends 0xB3 (result_code = 50903 kHostVerifyUserCancel) as the final state of the entire recognition.

【Device → Host】VerifyResultNotify (cmd 0xB5)

In scenarios where the device's additional verification backend validation completes, additional verification is canceled, additional verification times out, or as a fallback after host disconnection, the device pushes the final conclusion of the additional verification stage to the host. This frame serves only as the final state of the additional verification stage; the final state of the entire recognition is still determined by 0xB3.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**B5**	Determined by data length	Additional verification final state result	Obtained by BCC calculation

• 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 Cancel 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 Descriptions:

**Field**	**Type**	**Description**
session_id	string	Current recognition session ID, consistent with B2 / B3 / B4 of this session
code	int	Additional verification result error code: • 0: additional verification passed • 30000 kTaskCancelled: user actively canceled (including AE cancellation, local LoadingPage cancellation, host disconnection fallback cancellation) • 30002 kTaskTimeout: additional verification timeout (including timeout_ms expiration, local LoadingPage countdown expiration) • Other: specific business error code for backend validation 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 that passed additional verification. Must be non-empty when code=0; this field is omitted on non-0 failure, and the host should handle it as absent/empty string when parsing

Disconnection Fallback Note: When the device is in the "waiting for the host to return AD" state, if the USB is physically unplugged or the host process exits causing the serial port to disconnect, the device will proactively trigger cancel/timeout recovery: it first pushes B5 with code=30000 (fire-and-forget; in the disconnection case it will not actually reach the host, and is only used for internal state cleanup), then sends the 0xB3 final state to end this recognition session, avoiding the device remaining in the additional verification intermediate state.

Host-Side Coordinated Recognition Full Sequence

The following diagram shows the complete bidirectional interaction in coordinated 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 cancel, additional verification required → host disconnection fallback.

Session Correlation: 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 B2 carrying a new session, it should immediately clear the display state of the previous round (recognition result page / additional verification input box).

Host-Side Device Health Status Protocol

This chapter was introduced in V2.1.0. After aggregating multiple sources such as "network / PDM module / activation / tenant / authorization", the device exposes a unified high-level health_state field externally, allowing the host to use a single metric to decide 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 DeviceStatusNotify in any of the following situations:

1. Periodic Reporting: The device automatically reports once every 30s after startup (consistent with "auto-refresh every 30 seconds")
2. Immediate Reporting on Abnormal Changes: When any of the following signals triggers a health status flip, a frame is pushed within 100ms (with a 200ms single-shot delayed merge for debouncing):
   • Network online/offline status flip (Wi-Fi / Ethernet)
   • PDM module work status changes to Error / Blocked or recovers from an exception
   • The device needs QR code activation (needActivation)
   • Tenant enable/disable switch (tenantStatusChanged)
   • Service initialization failure hits kPalmAuthFailed (50000) / kPalmModuleError (50001) / kIotNotRegistered (50105)
   • Heartbeat/activation status cleared by the cloud: kKeyExpired (50101) / kHeartbeatOCodeChanged (50103) / kHeartbeatUnbindFromScene (50104). The device clears the local activation data and sends health_state=20, with sub_status.last_error_code indicating the specific reason code
   • [Added in v2.3.0] Tenant scenario configuration change (registration capability flags such as enable_pc_registration / enable_device_qrcode are updated); the capabilities field carries the latest values along with the frame
3. Host Active Query: The host sends cmd 0xAA QueryDeviceStatusReq, and the device replies with 0xAB QueryDeviceStatusResp within 1 second, with a payload field set identical to 0xB0

Note: Legacy hosts (that do not recognize 0xB0/0xAA/0xAB) should ignore unrecognized cmd frames when received; the device is only responsible for sending according to the specification.

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

**Value**	**Enum Name**	**Meaning**	**human_action_hint**
0	HEALTHY	All dimensions normal, ready for use (including sleep states S0/S1)	""
10	WARN_NETWORK_OFFLINE	Only network offline, other dimensions healthy	check_network
20	NEED_INTERVENTION_NOT_ACTIVATED	Device not activated, QR code activation required	scan_qr_to_activate
21	NEED_INTERVENTION_TENANT_DISABLED	Tenant disabled	contact_admin_tenant_disabled
22	NEED_INTERVENTION_SERVICE_DISABLED	Service disabled	contact_admin_service_disabled
30	ERROR_PALM_AUTH_FAILED	Module authorization failed/expired	contact_admin_palm_auth
31	ERROR_PALM_MODULE	PDM module exception	check_palm_module
32	ERROR_PALM_BLOCKED	PDM module blacklisted/blocked	check_palm_module
99	UNKNOWN	No valid status has been obtained yet during the early startup phase	""

【Device → Host】DeviceStatusNotify (cmd 0xB0)

The device proactively reports the current health status.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**B0**	Determined by data length	JSON (see field table below)	Obtained by BCC calculation

• Data Field JSON Fields:

**Field**	**Type**	**Description**
sn	string	Device serial number
timestamp	string	Millisecond-level Unix timestamp (carried as a string to avoid loss of large-integer precision)
app_version	string	Device application version number
work_mode	int	Current work mode (0=standalone mode, 1~5=coordinated mode, consistent with the mode field of A9)
health_state	int	High-level health status (see the table above for values)
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 this to determine which extended capabilities the device supports; "1.1.0" indicates support for the CPM QR Code enrollment / 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). Legacy hosts should ignore this field when received; when a legacy device does not carry this field, the host assumes both registration methods are available by default

• sub_status Sub-fields: (all required; fill with default values when there is no corresponding source, do not omit keys)

**Field**	**Type**	**Description**
module_status	int	PDM module status (yt_aikit::DeviceStatus), unknown/not connected=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 most recent TxCode that triggered a "non-HEALTHY" state, 0 if none. Common values (used together with health_state=20 NEED_INTERVENTION_NOT_ACTIVATED to precisely locate the activation/unbinding reason): • 50101 kKeyExpired: device Key expired and was cleared • 50103 kHeartbeatOCodeChanged: heartbeat detected an entity change (e.g., deleted and reassigned by the cloud) • 50104 kHeartbeatUnbindFromScene: heartbeat unbound/rebound from the scene • 50105 kIotNotRegistered: device has never been activated • 50000 kPalmAuthFailed / 50001 kPalmModuleError: module authorization or runtime exception
human_action_hint	string	Short English operation hint (i18n-translated by the host; see the health_state table for values)

• capabilities Sub-fields:

**Field**	**Type**	**Description**
host_register	int	1=supports host-side registration (user name registration, mode=4), 0=not supported. Combines the compile option (YT_DISABLE_HOST_REGISTER) and the tenant configuration (enable_pc_registration) dimensions; if either is unavailable, it is 0
cpm_register	int	1=supports CPM QR Code enrollment (CPM, mode=5), 0=not supported. Determined by the tenant configuration (enable_device_qrcode)

• 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】QueryDeviceStatusReq (cmd 0xAA)

The host proactively queries the device health status.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**AA**	0000	None	Obtained by BCC calculation

• Description: The query does not require any input parameters; even if an illegal / empty payload is carried, the device will ignore the payload and reply normally with 0xAB, and will not return 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】QueryDeviceStatusResp (cmd 0xAB)

The device responds to the host's health status query, with a payload field set identical to 0xB0, allowing the host to use the same parser.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**AB**	Determined by data length	JSON (same as 0xB0)	Obtained by BCC calculation

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

Error Status Response Protocol

【Device → Host】Unknown Command Code

The palm verification device responds when it receives an unknown command code.

• Communication Protocol:

**Start Characters**	**Packet Sequence Number**	**Command Code**	**Data Field Length**	**Data Field**	**Checksum**
5A5A5A5A	0001	**F0**	Determined by data length	Unknown command code	Obtained by BCC calculation

• 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

Data Structure Definitions

PalmInfo Struct

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

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

PalmState Enumeration

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 registration completed (pending device-side enrollment confirmation)
registered	Registration completed

---

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, categorized 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:

Error Code Name	Value	Description	Handling Recommendation
kSuccess	0	Palm enrollment succeeded	-
kNetworkFailed	20102	Network request failed (device cannot connect to cloud service)	Check the device network connection and retry
kCloudBizError	20407	Cloud service returned a business error	Refer to the resultMessage field for the specific reason
kModuleRuntimeError	50003	Palm module runtime error	Restart the device and retry
kDuplicateRegister	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-enroll
kRegisterFailed	50011	Registration failed (general registration error)	Retry; if it persistently fails, check the device status
kUserNotFound	50305	Corresponding user not found in the cloud (user ID mismatch)	Confirm that userId is consistent with the cloud
kUserInfoMismatch	50306	User name does not match the cloud record	Confirm that userName is consistent with the cloud
kInvalidUserInfo	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
kRegisterModeDisabled	50308	Host-side registration mode has been disabled in the admin console (Added in v2.3.0)	Contact the administrator to enable host-side 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)

Error Code Name	Value	Description	Handling Recommendation
kSuccess	0	Mode switching succeeded	-
kInvalidParam	10100	Parameter error, the target mode is out of the valid range (0~5)	Check whether the mode field value is 0~5
kParseError	10501	Request data format parsing failed	Check whether the A6 command data field JSON format is correct
kNotInMainPage	50902	The device is currently not on the main interface and cannot switch modes	Wait for the device to return to the main interface 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 following table lists all error codes that may be encountered in host communication.

Error Code Name	Value	Description	Handling Recommendation
kSuccess	0	Success	-
kInvalidParam	10100	Invalid parameter	Check whether the command data field values are valid
kParseError	10501	JSON data parsing failed	Check whether the data field JSON format is correct
kNetworkFailed	20102	Network request failed (device cannot connect to cloud service)	Check the device network connection and retry
kCloudBizError	20407	Cloud service returned a business error	Refer to the resultMessage field for the specific reason
kModuleRuntimeError	50003	Palm module runtime error	Restart the device and retry
kDuplicateRegister	50010	Duplicate registration (including device-side local detection)	Prompt the user that registration is complete, no need to re-enroll
kRegisterFailed	50011	Registration failed (general registration error)	Retry; if it persistently fails, check the device status
kUserNotFound	50305	User not found	Confirm that userId is consistent with the cloud
kUserInfoMismatch	50306	User information mismatch	Confirm that userName is consistent with the cloud
kHostNotConnected	50900	Host not connected (serial port not connected)	Check whether the USB serial cable connection is normal
kInvalidUserInfo	50901	The user information delivered by the host is invalid	Check that the userId and userName fields are not empty
kNotInMainPage	50902	The device is currently not on the main interface (only triggered during coordinated mode=1~5 switching)	Wait for the device to return to the main interface and retry
kHostVerifyUserCancel	50903	Host user canceled additional verification (B3 result_code may take this value)	The business side silently discards it, does not display a failure final state
kRegisterModeDisabled	50308	The current registration mode has been disabled in the admin console (Added in v2.3.0)	Contact the administrator to enable the corresponding registration mode permission in the backend and retry
kTaskCancelled	30000	Task canceled (e.g., additional verification input canceled, device actively canceled)	Treat as user active cancellation, UI silently recycles
kTaskTimeout	30002	Task timeout (e.g., additional verification input timeout, QR code scan timeout)	Treat as timeout, can prompt the user to retry