AiFace BS Communication Protocol Documentation

This document defines the communication specification between AiFace facial recognition devices and backend servers. The core feature is a unified JSON command set that operates over three transport layers: WebSocket, MQTT, and HTTP.

⚠️ Protocol Role Note: In the BS communication protocol, the device acts as a client that actively connects to the backend server; the server acts as the service endpoint, receiving and responding to the device's connections and requests. Therefore, the BS protocol supports Wide Area Network (WAN) deployment — devices can communicate with remote servers across network segments and geographic locations.

🔴 Transport Recommendation: WebSocket (WS/WSS) is strongly recommended. MQTT/MQTTS and HTTP/HTTPS are not recommended for the following reasons:
- WebSocket (WS/WSS): Long-lived connection, server can push commands in real time with lowest latency and minimal resource usage. This is the preferred solution.
- HTTP/HTTPS: Short-lived connections with no push capability. Devices must rely on heartbeat polling to fetch commands, which severely consumes device memory and CPU resources, while also placing heavy load on the server. Real-time performance cannot be guaranteed.
- MQTT/MQTTS: Requires deploying an additional MQTT Broker server, increasing deployment complexity and operational costs, with real-time performance inferior to direct WebSocket connections.

1. Transport Protocol Specifications

1.1 WebSocket / WSS (WebSocket Secure)

Connection URL Format:

ws://<server_ip>:<port>/<path>
wss://<server_ip>:<port>/<path>

Default Configuration:

• Default WebSocket port: 7788
• Default WSS port: 433
• Default path: pub/chat (full connection URL example: ws://192.168.1.100:7788/pub/chat)
• If port > 7500, defaults to WebSocket mode

Authentication Flow:

1. Device initiates TCP/TLS connection to the server
2. On MG_EV_WS_OPEN event, device immediately sends the reg command (Device Registration)
3. Server responds with ret="reg" containing authorization result and time sync
4. If authorization succeeds, reg_success = TRUE; device begins normal operations

Data Format:

• All messages are JSON text frames (WEBSOCKET_OP_TEXT)
• Encoding: UTF-8

Heartbeat Mechanism:

• Device sends a PING frame every 10 seconds when connected
• If no PONG response is received within 30 seconds, the connection is considered dead and is closed
• Reconnection is attempted automatically by the timer_fn loop

Reconnection Logic:

• For persistent connections (WS/WSS), reconnection is attempted whenever s_conn == NULL
• Network priority: Wired (highest) > WiFi > 4G USB
• If a higher-priority network becomes available, the current connection is closed and re-established

mqtt://<server_ip>:<port>
mqtts://<server_ip>:<port>

JSON{
  "user": "mqtt_username",
  "pass": "mqtt_password",
  "client_id": "device_client_id",
  "sub": "aiface/<sn>/pub",
  "pub": "aiface/<sn>/sub"
}

http://<server_ip>:<port>/<path>
https://<server_ip>:<port>/<path>

POST /<path> HTTP/1.1
Host: <server_ip>:<port>
Content-Type: application/json
Content-Length: <length>

<JSON body>

JSON{
  "cmd": "checklive",
  "sn": "LF00000001",
  "time": "2025-01-01 08: 00: 00"
}

JSON{
  "cmd": "setuserinfo",
  "sn": "LF00000001",
  "userid": 1,
  "name": "Zhang San"
}

JSON{
  "ret": "checklive",
  "cloudtime": "2025-01-01 08: 00: 00"
}

2. Protocol Differences Summary

3. JSON Command Format

3.1 General Request Format

JSON{
  "cmd": "<command_name>",
  "sn": "<device_serial_number>",
  ...additional parameters...
}

3.2 General Response Format

Success:

JSON{
  "ret": "<command_name>",
  "sn": "<device_serial_number>",
  "result": true,
  ...additional fields...
}

Failure:

JSON{
  "ret": "<command_name>",
  "sn": "<device_serial_number>",
  "result": false,
  "reason": <error_code>,
  "msg": "<error_message>"
}

3.3 Error Codes (reason field)

Different commands use different error code systems. Common patterns:

4. backupnum Reference Table

The backupnum field identifies the type of biometric or credential data associated with a user.

Fingerprint 0-Compression Format:

Fingerprint data uses a special compression scheme. Consecutive 0x00 bytes are encoded as (N) where N is the count:

• ff(5)aabb decodes to: ff 00 00 00 00 00 aa bb

5. Device Registration — `reg` Command

5.1 Device → Server (Registration Request)

Also known as Active_send_reg. The device sends this command automatically immediately after establishing a connection (WS open, HTTP connect, or MQTT open).

Request Example:

JSON{
  "cmd": "reg",
  "sn": "LF00000001",
  "devinfo": {
    "modelname": "AiFace",
    "manufacturer": "AiFace Inc.",
    "usersize": 10000,
    "facesize": 10000,
    "avatarsize": 0,
    "fpsize": 10000,
    "palmsize": 10000,
    "cardsize": 10000,
    "pwdsize": 10000,
    "logsize": 300000,
    "useduser": 100,
    "usedface": 50,
    "usedavatar": 0,
    "usedfp": 20,
    "usedpalm": 0,
    "usedcard": 10,
    "usedpwd": 5,
    "usedlog": 1000,
    "usednewlog": 500,
    "usedrtlog": 3,
    "netinuse": 1,
    "usb4g": 0,
    "fpalgo": "thbio3.0",
    "firmware": "1.0.0",
    "time": "2025-01-01 08: 00: 00",
    "intercom": 0,
    "floors": 0,
    "acces_stimes": 0,
    "charid": 0,
    "useosdp": 0,
    "facetemplate": 0,
    "dislanguage": 0,
    "curip": "192.168.001.100",
    "ntp": 1,
    "timezone": "UTC+8",
    "cpu_temp": 45,
    "bandwidth_up": "100Kbps",
    "bandwidth_down": "1Mbps",
    "battery": 100,
    "disksize": 1024.0,
    "useddisk": 512.0,
    "mac": "AA-BB-CC-DD-EE-FF"
  }
}

devinfo Field Descriptions:

5.2 Server → Device (Registration Response)

Success Response:

JSON{
  "ret": "reg",
  "tryseconds": 10,
  "result": true,
  "cloudtime": "2025-01-01 08: 00: 00",
  "nosenduser": false,
  "nosendlog": false,
  "nosendimage": false
}

Failure Response:

JSON{
  "ret": "reg",
  "tryseconds": 30,
  "result": false,
  "reason": "Device not authorized"
}

Periodic Re-registration:

• Device re-sends reg command every tryseconds seconds (default: 300s / 5 minutes) while reg_success = TRUE

6. User Management Commands

6.1 setuserinfo — Set User Information

Downloads and sets user profile information including biometrics.

Request Parameters:

Request Example:

JSON{
  "cmd": "setuserinfo",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001",
  "name": "John Doe",
  "birthday": "01-15",
  "verifymode": 0,
  "card": 12345,
  "pwd": 0,
  "shiftid": 0,
  "zoneid": 0,
  "groupid": 0,
  "access_times": 0,
  "postid": 1,
  "department": "Engineering",
  "enable": 1,
  "starttime": "2025-01-01 00: 00: 00",
  "endtime": "2025-12-31 23: 59: 59",
  "backupnum": 50,
  "admin": 0,
  "userprofile": "{}",
  "record": "base64_encoded_face_data"
}

Success Response:

JSON{
  "ret": "setuserinfo",
  "enrollid": 123,
  "sn": "LF00000001",
  "backupnum": 50,
  "result": true,
  "aliasid": "USR001"
}

Failure Response:

JSON{
  "ret": "setuserinfo",
  "enrollid": 123,
  "sn": "LF00000001",
  "backupnum": 50,
  "result": false,
  "reason": 1,
  "msg": "space overflow",
  "aliasid": "USR001"
}

6.2 deleteuser — Delete User

Deletes a user or specific biometric data for a user.

Request Parameters:

backupnum Values for Deletion:

• 12 or 13: Delete entire user (all biometrics and photo)
• 10: Delete password only
• 11: Delete card only
• 50: Delete face photo
• 51: Delete face feature
• 0-9: Delete specific fingerprint
• 40: Delete left palm vein
• 41: Delete right palm vein

Request Example:

JSON{
  "cmd": "deleteuser",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001",
  "backupnum": 12
}

Success Response:

JSON{
  "ret": "deleteuser",
  "enrollid": 123,
  "sn": "LF00000001",
  "backupnum": 12,
  "result": true,
  "aliasid": "USR001"
}

6.3 cleanuser — Clear All Users

Deletes all users from the device. No parameters.

Request Example:

JSON{
  "cmd": "cleanuser",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "cleanuser",
  "sn": "LF00000001",
  "result": true
}

6.4 setusername — Batch Set User Names

Request Parameters:

Request Example:

JSON{
  "cmd": "setusername",
  "sn": "LF00000001",
  "count": 2,
  "birthday": "06-15",
  "record": [
    {"enrollid": 100, "aliasid": "U100", "name": "Alice", "verifymode": 0},
    {"enrollid": 101, "aliasid": "U101", "name": "Bob", "verifymode": 0}
  ]
}

Success Response:

JSON{
  "ret": "setusername",
  "sn": "LF00000001",
  "result": true
}

Failure Response:

JSON{
  "ret": "setusername",
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "set username fail"
}

6.5 getusername — Get User Name

Request Parameters:

Request Example:

JSON{
  "cmd": "getusername",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001"
}

Success Response:

JSON{
  "ret": "getusername",
  "sn": "LF00000001",
  "result": true,
  "record": "John Doe"
}

Failure Response:

JSON{
  "ret": "getusername",
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "can not find this name"
}

6.6 getuserlist — Get User ID List (Paginated)

Retrieves a paginated list of user IDs. Use stn=1 to reset pagination and start a new query.

Request Parameters:

Pagination Behavior:

• stn=1: Resets internal index to 0 and starts a new query
• Each response contains up to 100 records
• Internal index auto-increments after each response
• Repeat the request to get the next page

Request Example:

JSON{
  "cmd": "getuserlist",
  "sn": "LF00000001",
  "stn": 1
}

Success Response (with data):

JSON{
  "ret": "getuserlist",
  "sn": "LF00000001",
  "result": true,
  "count": 500,
  "from": 0,
  "to": 100,
  "record": [
    {"enrollid": 123, "admin": 0, "backupnum": 50, "enable": 1, "aliasid": "USR001"},
    {"enrollid": 124, "admin": 1, "backupnum": 51, "enable": 1, "aliasid": "USR002"}
  ]
}

Success Response (empty):

JSON{
  "ret": "getuserlist",
  "sn": "LF00000001",
  "result": true,
  "count": 0,
  "from": 0,
  "to": 0,
  "record": []
}

6.7 getuserids — Get All User IDs

Returns all user IDs in a single response (no pagination).

Request Parameters:

None.

Request Example:

JSON{
  "cmd": "getuserids",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getuserids",
  "sn": "LF00000001",
  "result": true,
  "count": 100,
  "record": ["123", "456", "USR001", "USR002"]
}

Returns user IDs as strings. Alias IDs are used when available, otherwise numeric ID strings.

6.8 getunuserdid — Get Next Available User ID

Returns the next available unused user ID.

Request Parameters:

None.

Request Example:

JSON{
  "cmd": "getunuserdid",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getunuserdid",
  "sn": "LF00000001",
  "result": true,
  "enrollid": "100"
}

6.9 checkuserid — Check If User ID Exists

Request Parameters:

Request Example:

JSON{
  "cmd": "checkuserid",
  "sn": "LF00000001",
  "enrollid": 123
}

Success Response (exists):

JSON{
  "ret": "checkuserid",
  "sn": "LF00000001",
  "result": true,
  "exists": true
}

Success Response (not found):

JSON{
  "ret": "checkuserid",
  "sn": "LF00000001",
  "result": true,
  "exists": false
}

6.10 getuserinfo — Get User Detailed Information

Request Parameters:

Without backupnum — returns full user profile (without raw biometric data):

Request Example:

JSON{
  "cmd": "getuserinfo",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001"
}

Success Response:

JSON{
  "ret": "getuserinfo",
  "result": true,
  "sn": "LF00000001",
  "enrollid": 123,
  "name": "John Doe",
  "department": "Engineering",
  "admin": 0,
  "aliasid": "USR001",
  "photourl": "/photos/LF00000123.jpg",
  "card": 12345,
  "pwd": 0,
  "fpflag": 3,
  "fpcnt": 2,
  "palmflag": 0,
  "palmcnt": 0,
  "faceflag": 1,
  "enable": 1,
  "birthday": "01-15",
  "shiftid": 0,
  "verifymode": 0,
  "zoneid": 0,
  "groupid": 0,
  "access_times": 0,
  "postid": 1,
  "starttime": "2025-01-01 00: 00: 00",
  "endtime": "2025-12-31 23: 59: 59",
  "userprofile": "{}"
}

With backupnum — returns raw biometric data:

Request Example (face photo):

JSON{
  "cmd": "getuserinfo",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001",
  "backupnum": 50
}

Success Response:

JSON{
  "ret": "getuserinfo",
  "result": true,
  "sn": "LF00000001",
  "enrollid": 123,
  "name": "John Doe",
  "backupnum": 50,
  "record": "base64_encoded_face_photo_data"
}

Failure Response:

JSON{
  "ret": "getuserinfo",
  "result": false,
  "sn": "LF00000001",
  "enrollid": 123,
  "reason": 1,
  "msg": "can not find this user",
  "aliasid": "USR001"
}

6.11 getallusers — Get All User Data (Paginated, Multi-Record)

Returns all user data in paginated format. Each user may return multiple records (one per biometric type). Use stn=true to start a new query.

Request Parameters:

Request Example:

JSON{
  "cmd": "getallusers",
  "sn": "LF00000001",
  "stn": true
}

Response (password record, backupnum=10):

JSON{
  "ret": "getallusers",
  "sn": "LF00000001",
  "result": true,
  "count": 500,
  "index": 0,
  "enrollid": 123,
  "backupnum": 10,
  "admin": 0,
  "enable": 1,
  "record": 12345,
  "aliasid": "USR001"
}

Response (card record, backupnum=11):

JSON{
  "ret": "getallusers",
  "sn": "LF00000001",
  "result": true,
  "count": 500,
  "index": 1,
  "enrollid": 123,
  "backupnum": 11,
  "admin": 0,
  "enable": 1,
  "record": 1234567890,
  "aliasid": "USR001"
}

Response (face photo, backupnum=50):

JSON{
  "ret": "getallusers",
  "sn": "LF00000001",
  "result": true,
  "count": 500,
  "index": 2,
  "enrollid": 123,
  "backupnum": 50,
  "admin": 0,
  "enable": 1,
  "record": "base64_jpg_data",
  "aliasid": "USR001"
}

Response (face feature, backupnum=51):

JSON{
  "ret": "getallusers",
  "sn": "LF00000001",
  "result": true,
  "count": 500,
  "index": 3,
  "enrollid": 123,
  "backupnum": 51,
  "admin": 0,
  "enable": 1,
  "record": "base64_feat_data",
  "aliasid": "USR001"
}

Response (fingerprint, backupnum=0):

JSON{
  "ret": "getallusers",
  "sn": "LF00000001",
  "result": true,
  "count": 500,
  "index": 5,
  "enrollid": 123,
  "backupnum": 0,
  "admin": 0,
  "enable": 1,
  "record": "hex_fp_data",
  "aliasid": "USR001"
}

Response (palm vein, backupnum=40):

JSON{
  "ret": "getallusers",
  "sn": "LF00000001",
  "result": true,
  "count": 500,
  "index": 10,
  "enrollid": 123,
  "backupnum": 40,
  "admin": 0,
  "enable": 1,
  "record": "base64_palm_data",
  "aliasid": "USR001"
}

Failure Response:

JSON{
  "ret": "getallusers",
  "sn": "LF00000001",
  "backupnum": 50,
  "result": false,
  "reason": 1,
  "msg": "this photo is too big"
}

6.12 adduser — Add User (Device-Side Registration)

Initiates user enrollment on the device. The device processes biometric capture and reports progress.

Request Parameters:

Request Example (start enrollment):

JSON{
  "cmd": "adduser",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001",
  "backupnum": 50,
  "admin": 0,
  "flag": 0,
  "name": "John Doe"
}

Success Response:

JSON{
  "ret": "adduser",
  "enrollid": 123,
  "sn": "LF00000001",
  "backupnum": 50,
  "result": true,
  "aliasid": "USR001"
}

Failure Response:

JSON{
  "ret": "adduser",
  "enrollid": 123,
  "sn": "LF00000001",
  "backupnum": 50,
  "result": false,
  "reason": 1,
  "msg": "userid can not empty"
}

Cancel Enrollment:

JSON{
  "cmd": "adduser",
  "sn": "LF00000001",
  "cancel": true
}

Cancel Response:

JSON{
  "ret": "adduser",
  "result": true,
  "cancel": true
}

6.13 checkregstatus — Check Device-Side Registration Status

Queries the current enrollment progress on the device.

Request Parameters:

None.

Request Example:

JSON{
  "cmd": "checkregstatus",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "checkregstatus",
  "sn": "LF00000001",
  "result": true,
  "status": 1,
  "msg": "Enrollment progress message",
  "image": "base64..."
}

status: 0 = waiting, >=0 = success (value corresponds to backupnum), <0 = failure

6.14 canceladduser — Cancel User Enrollment

Cancels the current user enrollment process. No parameters.

Request Example:

JSON{
  "cmd": "canceladduser",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "canceladduser",
  "result": true
}

6.15 enableuser — Enable/Disable User

Request Parameters:

Request Example:

JSON{
  "cmd": "enableuser",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001",
  "enflag": false
}

Success Response:

JSON{
  "ret": "enableuser",
  "enrollid": 123,
  "sn": "LF00000001",
  "result": true,
  "aliasid": "USR001"
}

6.16 getuserprofile — Get User Custom Profile

Request Parameters:

Request Example:

JSON{
  "cmd": "getuserprofile",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001"
}

Success Response:

JSON{
  "ret": "getuserprofile",
  "sn": "LF00000001",
  "result": true,
  "record": "{...json...}"
}

Failure Response:

JSON{
  "ret": "getuserprofile",
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "userprofile can not empty"
}

6.17 setuserprofile — Set User Custom Profile

Request Parameters:

Request Example:

JSON{
  "cmd": "setuserprofile",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001",
  "profile": "{\"key\": \"value\"}",
  "duration": 5,
  "color": 1
}

Success Response:

JSON{
  "ret": "setuserprofile",
  "enrollid": 123,
  "sn": "LF00000001",
  "result": true,
  "aliasid": "USR001"
}

Failure Response:

JSON{
  "ret": "setuserprofile",
  "enrollid": 123,
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "setuserprofile fail"
}

7. Log Management Commands

7.1 getnewlog — Get New Records

Retrieves new (unread) attendance/access log records with pagination.

Request Parameters:

Request Example:

JSON{
  "cmd": "getnewlog",
  "sn": "LF00000001",
  "stn": 1,
  "logphoto": 1
}

Success Response:

JSON{
  "ret": "getnewlog",
  "sn": "LF00000001",
  "result": true,
  "count": 500,
  "from": 0,
  "to": 100,
  "record": [
    {
      "enrollid": 123,
      "name": "John Doe",
      "time": "2025-01-01 08: 00: 00",
      "mode": 1,
      "inout": 0,
      "event": 0,
      "aliasid": "USR001",
      "image": "base64...",
      "note": ""
    }
  ]
}

Empty Response:

JSON{
  "ret": "getnewlog",
  "sn": "LF00000001",
  "result": true,
  "count": 0,
  "from": 0,
  "to": 0,
  "record": []
}

Record Fields:

7.2 getalllog — Get All Records

Retrieves all log records with optional filtering and pagination.

Request Parameters:

Request Example:

JSON{
  "cmd": "getalllog",
  "sn": "LF00000001",
  "stn": 1,
  "enrollid": 123,
  "from": "2025-01-01",
  "to": "2025-12-31",
  "logphoto": 0
}

Success Response:

JSON{
  "ret": "getalllog",
  "sn": "LF00000001",
  "result": true,
  "count": 1000,
  "from": 0,
  "to": 100,
  "record": [
    {
      "enrollid": 123,
      "name": "John Doe",
      "time": "2025-01-01 08: 00: 00",
      "mode": 1,
      "inout": 0,
      "event": 0,
      "aliasid": "USR001",
      "image": "base64...",
      "note": ""
    }
  ]
}

7.3 cleanlog — Clear All Logs

Deletes all log records from the device. No parameters.

Request Example:

JSON{
  "cmd": "cleanlog",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "cleanlog",
  "sn": "LF00000001",
  "result": true
}

7.4 cleanlogphoto — Clear Log Photos

Deletes all photos associated with log records. No parameters.

Request Example:

JSON{
  "cmd": "cleanlogphoto",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "cleanlogphoto",
  "sn": "LF00000001",
  "result": true
}

8. Device Management Commands

8.1 getdevinfo — Get Device System Parameters

Reads all system parameters. No parameters.

Request Example:

JSON{
  "cmd": "getdevinfo",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getdevinfo",
  "sn": "LF00000001",
  "result": true,
  "param1": "value1",
  "param2": "value2"
}

Returns all parameters from DI_FIRST to DI_END enumeration as key-value pairs.

8.2 setdevinfo — Set Device System Parameters

Sets one or more system parameters.

Request Parameters:

Request Example:

JSON{
  "cmd": "setdevinfo",
  "sn": "LF00000001",
  "nowtime": 1735689600,
  "DI_SERVERIP": "192.168.1.100",
  "DI_SERVERPORT": 7788
}

Success Response:

JSON{
  "ret": "setdevinfo",
  "sn": "LF00000001",
  "result": true
}

Note: Modifying domain name, IP, or port parameters triggers a connection re-establishment (need_close_connection = TRUE).

8.3 getdevcap — Get Device Capacity

Returns device storage capacity information. No parameters.

Request Example:

JSON{
  "cmd": "getdevcap",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getdevcap",
  "sn": "LF00000001",
  "result": true,
  "usersize": 10000,
  "facesize": 10000,
  "avatarsize": 0,
  "fpsize": 10000,
  "palmsize": 10000,
  "cardsize": 10000,
  "pwdsize": 10000,
  "logsize": 300000,
  "useduser": 100,
  "usedface": 50,
  "usedavatar": 0,
  "usedfp": 20,
  "usedpalm": 0,
  "usedcard": 10,
  "usedpwd": 5,
  "usedlog": 1000,
  "usednewlog": 500,
  "usedrtlog": 3
}

8.4 gettime — Get Device Time

Gets the current device time. No parameters.

Request Example:

JSON{
  "cmd": "gettime",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "gettime",
  "sn": "LF00000001",
  "time": "2025-01-01 08: 00: 00"
}

8.5 settime — Set Device Time

Request Parameters:

Request Example:

JSON{
  "cmd": "settime",
  "sn": "LF00000001",
  "cloudtime": "2025-01-01 08: 00: 00",
  "nowtime": 1735689600
}

Success Response:

JSON{
  "ret": "settime",
  "sn": "LF00000001",
  "result": true
}

Failure Response:

JSON{
  "ret": "settime",
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "time format wrong"
}

8.6 initsys — Factory Reset

Performs a factory reset: clears all users and logs, restores default settings, backs up WiFi configuration. No parameters.

Request Example:

JSON{
  "cmd": "initsys",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "initsys",
  "sn": "LF00000001",
  "result": true
}

8.7 initmenu — Reset Menu Settings

Restores default menu settings. Preserves language and backs up WiFi configuration. No parameters.

Request Example:

JSON{
  "cmd": "initmenu",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "initmenu",
  "sn": "LF00000001",
  "result": true
}

8.8 cleandatebase — Clear Database

Clears the entire database. Device must be rebooted after this operation. No parameters.

Request Example:

JSON{
  "cmd": "cleandatebase",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "cleandatebase",
  "sn": "LF00000001",
  "result": true
}

8.9 cleanadmin — Clear All Administrators

Removes all administrator privileges. No parameters.

Request Example:

JSON{
  "cmd": "cleanadmin",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "cleanadmin",
  "sn": "LF00000001",
  "result": true
}

8.10 cleaninactiveuser — Clear Inactive Users

Removes users who have not been active (no attendance records). No parameters.

Request Example:

JSON{
  "cmd": "cleaninactiveuser",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "cleaninactiveuser",
  "sn": "LF00000001",
  "result": true
}

8.11 reboot — Reboot Device

Triggers an immediate device reboot. No response is sent (device restarts).

Request Example:

JSON{
  "cmd": "reboot",
  "sn": "LF00000001"
}

Behavior: No response. Device reboots immediately.

8.12 disabledevice — Disable Device Recognition

Pauses all face, card, fingerprint, and palm detection. No parameters.

Request Example:

JSON{
  "cmd": "disabledevice",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "disabledevice",
  "sn": "LF00000001",
  "result": true
}

8.13 enabledevice — Enable Device Recognition

Resumes all face, card, fingerprint, and palm detection. No parameters.

Request Example:

JSON{
  "cmd": "enabledevice",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "enabledevice",
  "sn": "LF00000001",
  "result": true
}

8.14 getreg — Get Device Registration Information

Retrieves full device registration and capability information. No parameters.

Request Example:

JSON{
  "cmd": "getreg",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getreg",
  "sn": "LF00000001",
  "result": true,
  "devinfo": {
    "modelname": "AiFace",
    "manufacturer": "AiFace Inc.",
    "usersize": 10000,
    "facesize": 10000,
    "avatarsize": 0,
    "fpsize": 10000,
    "palmsize": 10000,
    "cardsize": 10000,
    "pwdsize": 10000,
    "logsize": 300000,
    "useduser": 100,
    "usedface": 50,
    "usedavatar": 0,
    "usedfp": 20,
    "usedpalm": 0,
    "usedcard": 10,
    "usedpwd": 5,
    "usedlog": 1000,
    "usednewlog": 500,
    "usedrtlog": 3,
    "netinuse": 1,
    "usb4g": 0,
    "fpalgo": "thbio3.0",
    "firmware": "1.0.0",
    "time": "2025-01-01 08: 00: 00",
    "intercom": 0,
    "floors": 0,
    "acces_stimes": 0,
    "charid": 0,
    "useosdp": 0,
    "facetemplate": 0,
    "dislanguage": 0,
    "curip": "192.168.001.100",
    "ntp": 1,
    "timezone": "UTC+8",
    "cpu_temp": 45,
    "bandwidth_up": "100Kbps",
    "bandwidth_down": "1Mbps",
    "battery": 100,
    "disksize": 1024.0,
    "useddisk": 512.0,
    "mac": "AA-BB-CC-DD-EE-FF"
  }
}

8.15 checklive — Heartbeat Check (Server-Issued)

A server-initiated heartbeat command to verify device connectivity. Device responds to confirm it is alive and provide server time for synchronization.

Server → Device Request:

JSON{
  "cmd": "checklive",
  "sn": "LF00000001"
}

Device → Server Response:

JSON{
  "ret": "checklive",
  "sn": "LF00000001",
  "result": true
}

9. Access Control Commands

9.1 opendoor — Remote Door Open

Remotely unlocks the door. Optionally sends user ID via Wiegand and displays a message.

Request Parameters:

Request Example:

JSON{
  "cmd": "opendoor",
  "sn": "LF00000001",
  "enrollid": 123,
  "floor": 0,
  "msg": "Welcome"
}

Success Response:

JSON{
  "ret": "opendoor",
  "sn": "LF00000001",
  "result": true
}

9.2 lockctrl — Door Lock Control

Controls the door lock state directly.

Request Parameters:

Request Example:

JSON{
  "cmd": "lockctrl",
  "sn": "LF00000001",
  "fuc": 1
}

Success Response:

JSON{
  "ret": "lockctrl",
  "sn": "LF00000001",
  "result": true
}

9.3 getdoorstatus — Get Door Status

Returns the current door sensor status. No parameters.

Request Example:

JSON{
  "cmd": "getdoorstatus",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getdoorstatus",
  "doorstatus": 0,
  "sn": "LF00000001",
  "result": true
}

doorstatus: 0 = closed, 1 = open (depends on door sensor configuration)

9.4 setdevlock — Set Door Access Parameters

Configures door access control parameters including timing, zones, and Wiegand settings.

Request Parameters:

Request Example:

JSON{
  "cmd": "setdevlock",
  "sn": "LF00000001",
  "opendelay": 5,
  "doorsensor": 0,
  "alarmdelay": 30,
  "InputAlarm": 0,
  "antpass": 0,
  "interlock": 0,
  "mutiopen": 0,
  "tryalarm": 5,
  "access_times": 0,
  "punchtimes": 0,
  "tamper": 0,
  "wgformat": 0,
  "wgoutput": 0,
  "cardformat": 0,
  "wgport": 0
}

Success Response:

JSON{
  "ret": "setdevlock",
  "sn": "LF00000001",
  "result": true
}

9.5 getdevlock — Get Door Access Parameters

Reads the current door access control configuration. No parameters.

Request Example:

JSON{
  "cmd": "getdevlock",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getdevlock",
  "sn": "LF00000001",
  "result": true,
  "opendelay": 5,
  "doorsensor": 0,
  "alarmdelay": 30,
  "InputAlarm": 0,
  "antpass": 0,
  "interlock": 0,
  "mutiopen": 0,
  "tryalarm": 5,
  "access_times": 0,
  "punchtimes": 0,
  "tamper": 0,
  "wgformat": 0,
  "wgoutput": 0,
  "cardformat": 0,
  "wgport": 0,
  "dayzone": [],
  "weekzone": [],
  "lockgroup": [],
  "nopentime": [],
  "visitortime": []
}

9.6 getuserlock — Get User Door Access Parameters

Request Parameters:

Request Example:

JSON{
  "cmd": "getuserlock",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001"
}

Success Response:

JSON{
  "ret": "getuserlock",
  "sn": "LF00000001",
  "result": true,
  "enrollid": 123,
  "birthday": "01-15",
  "verifymode": 0,
  "enable": 1,
  "weekzone": 0,
  "group": 0,
  "access_times": 0,
  "starttime": "2025-01-01 00: 00: 00",
  "endtime": "2025-12-31 23: 59: 59",
  "aliasid": "USR001"
}

Failure Response:

JSON{
  "ret": "getuserlock",
  "enrollid": 123,
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "can not find the user"
}

9.7 setuserlock — Batch Set User Door Access Parameters

Request Parameters:

Request Example:

JSON{
  "cmd": "setuserlock",
  "sn": "LF00000001",
  "count": 2,
  "birthday": "06-15",
  "record": [
    {"enrollid": 100, "aliasid": "U100", "verifymode": 0, "weekzone": 0, "group": 0, "access_times": 0, "starttime": "2025-01-01 00: 00: 00", "endtime": "2025-12-31 23: 59: 59"},
    {"enrollid": 101, "aliasid": "U101", "verifymode": 0, "weekzone": 1, "group": 1, "access_times": 10, "starttime": "2025-01-01 00: 00: 00", "endtime": "2025-12-31 23: 59: 59"}
  ]
}

Success Response:

JSON{
  "ret": "setuserlock",
  "sn": "LF00000001",
  "result": true
}

Failure Response:

JSON{
  "ret": "setuserlock",
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "setuserlock fail"
}

9.8 deleteuserlock — Delete User Door Access Parameters

Request Parameters:

Request Example:

JSON{
  "cmd": "deleteuserlock",
  "sn": "LF00000001",
  "enrollid": 123,
  "aliasid": "USR001"
}

Success Response:

JSON{
  "ret": "deleteuserlock",
  "enrollid": 123,
  "sn": "LF00000001",
  "result": true,
  "aliasid": "USR001"
}

9.9 cleanuserlock — Clear All User Door Access Parameters

Removes door access time zones and restrictions for all users. No parameters.

Request Example:

JSON{
  "cmd": "cleanuserlock",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "cleanuserlock",
  "sn": "LF00000001",
  "result": true
}

10. Attendance Management Commands

10.1 getshift — Get Shift Schedule

Reads the configured shift/roster schedule. No parameters.

Request Example:

JSON{
  "cmd": "getshift",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getshift",
  "sn": "LF00000001",
  "result": true,
  "shifts": [
    {
      "name": "Day Shift",
      "cutoftime": "09: 00",
      "sections": [
        {"start": "08: 00", "end": "12: 00", "type": 0},
        {"start": "13: 00", "end": "17: 00", "type": 1},
        {"start": "17: 00", "end": "18: 00", "type": 2}
      ]
    }
  ]
}

Maximum 8 shifts, each with up to 3 time sections.
Section type: 0=work, 1=rest, 2=overtime

10.2 setshift — Set Shift Schedule

Request Parameters:

Request Example:

JSON{
  "cmd": "setshift",
  "sn": "LF00000001",
  "shifts": [
    {
      "name": "Day Shift",
      "cutoftime": "09: 00",
      "sections": [
        {"start": "08: 00", "end": "12: 00", "type": 0},
        {"start": "13: 00", "end": "17: 00", "type": 1}
      ]
    },
    {
      "name": "Night Shift",
      "cutoftime": "21: 00",
      "sections": [
        {"start": "20: 00", "end": "23: 59", "type": 0},
        {"start": "00: 00", "end": "06: 00", "type": 0}
      ]
    }
  ]
}

Success Response:

JSON{
  "ret": "setshift",
  "sn": "LF00000001",
  "result": true
}

10.3 getbelltime — Get Bell Schedule

Reads configured bell/doorbell time schedules. No parameters.

Request Example:

JSON{
  "cmd": "getbelltime",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getbelltime",
  "sn": "LF00000001",
  "result": true,
  "belltimes": [
    {"time": "08: 00", "flag": 127},
    {"time": "12: 00", "flag": 127}
  ]
}

flag is a bitmask where each bit represents a day of the week (127 = all days)

10.4 setbelltime — Set Bell Schedule

Request Parameters:

Request Example:

JSON{
  "cmd": "setbelltime",
  "sn": "LF00000001",
  "belltimes": [
    {"time": "08: 00", "flag": 127},
    {"time": "12: 00", "flag": 127},
    {"time": "18: 00", "flag": 65}
  ]
}

Success Response:

JSON{
  "ret": "setbelltime",
  "sn": "LF00000001",
  "result": true
}

10.5 setholiday — Set Holiday Schedule

Request Parameters:

Holiday Object Fields:

Request Example:

JSON{
  "cmd": "setholiday",
  "sn": "LF00000001",
  "holidays": [
    {"name": "Spring Festival", "startday": "01-28", "endday": "02-03", "shift": 0, "dayzone": 0},
    {"name": "National Day", "startday": "10-01", "endday": "10-07", "shift": 1, "dayzone": 0}
  ]
}

Success Response:

JSON{
  "ret": "setholiday",
  "sn": "LF00000001",
  "result": true
}

10.6 getholiday — Get Holiday Schedule

Reads configured holiday schedule. No parameters.

Request Example:

JSON{
  "cmd": "getholiday",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getholiday",
  "sn": "LF00000001",
  "result": true,
  "holidays": [
    {"name": "Spring Festival", "startday": "01-28", "endday": "02-03", "shift": 0, "dayzone": 0},
    {"name": "National Day", "startday": "10-01", "endday": "10-07", "shift": 1, "dayzone": 0}
  ]
}

11. Device Active Report Commands

These commands are initiated by the device and sent to the server. The server processes them and sends back a response.

11.1 sendlog — Device Reports Attendance Logs

Device proactively sends attendance/access log records to the server.

Device → Server (Request):

JSON{
  "cmd": "sendlog",
  "sn": "LF00000001",
  "count": 10,
  "logindex": 0,
  "record": [
    {
      "enrollid": 123,
      "name": "John Doe",
      "time": "2025-01-01 08: 00: 00",
      "mode": 1,
      "inout": 0,
      "event": 0,
      "aliasid": "USR001",
      "image": "base64...",
      "note": ""
    }
  ]
}

Server → Device (Response):

JSON{
  "ret": "sendlog",
  "result": true,
  "count": 10,
  "logindex": 0,
  "mark": true,
  "access": 1,
  "message": "Welcome",
  "fontsize": 24,
  "text_color": [255, 0, 0],
  "voice": "tts_url",
  "voiceindex": 0,
  "name": "John Doe",
  "questionnaire": true
}

Server Response Fields:

11.2 senduser — Device Reports User Data Changes

Device proactively sends user enrollment/modification data when biometrics or credentials are enrolled on the device.

Device → Server (Request) — Password Change (backupnum=10):

JSON{
  "cmd": "senduser",
  "sn": "LF00000001",
  "enrollid": 123,
  "name": "John Doe",
  "backupnum": 10,
  "admin": 0,
  "record": 12345,
  "aliasid": "USR001",
  "card": 0,
  "pwd": 12345,
  "fpflag": 0,
  "palmflag": 0,
  "faceflag": 1,
  "enable": 1,
  "birthday": "01-15",
  "shiftid": 0,
  "verifymode": 0,
  "zoneid": 0,
  "groupid": 0,
  "access_times": 0,
  "postid": 0,
  "starttime": "2025-01-01 00: 00: 00",
  "endtime": "2025-12-31 23: 59: 59",
  "profile": "{}"
}

Device → Server (Request) — Card Change (backupnum=11):

JSON{
  "cmd": "senduser",
  "sn": "LF00000001",
  "enrollid": 123,
  "name": "John Doe",
  "backupnum": 11,
  "admin": 0,
  "record": 1234567890,
  "aliasid": "USR001"
}

Device → Server (Request) — Face Photo (backupnum=50):

JSON{
  "cmd": "senduser",
  "sn": "LF00000001",
  "enrollid": 123,
  "name": "John Doe",
  "backupnum": 50,
  "admin": 0,
  "record": "base64_jpg_data",
  "aliasid": "USR001"
}

Device → Server (Request) — Face Feature (backupnum=51):

JSON{
  "cmd": "senduser",
  "sn": "LF00000001",
  "enrollid": 123,
  "name": "John Doe",
  "backupnum": 51,
  "admin": 0,
  "record": "base64_feat_data",
  "aliasid": "USR001"
}

Device → Server (Request) — Fingerprint (backupnum=0-9):

JSON{
  "cmd": "senduser",
  "sn": "LF00000001",
  "enrollid": 123,
  "name": "John Doe",
  "backupnum": 0,
  "admin": 0,
  "record": "hex_fp_data_with_compression",
  "aliasid": "USR001"
}

Device → Server (Request) — Palm Vein (backupnum=40/41):

JSON{
  "cmd": "senduser",
  "sn": "LF00000001",
  "enrollid": 123,
  "name": "John Doe",
  "backupnum": 40,
  "admin": 0,
  "record": "base64_palm_data",
  "aliasid": "USR001"
}

Server → Device (Response):

JSON{
  "ret": "senduser",
  "result": true,
  "enrollid": 123,
  "backupnum": 10
}

11.3 sendpin — Device Reports PIN Input

Device reports when a user enters a PIN code on the device keypad.

Device → Server (Request):

JSON{
  "cmd": "sendpin",
  "sn": "LF00000001",
  "pin": "123456",
  "time": "2025-01-01 08: 00: 00"
}

Server → Device (Response):

JSON{
  "ret": "sendpin",
  "result": true,
  "access": 1,
  "message": "Welcome",
  "fontsize": 24,
  "text_color": [255, 0, 0],
  "voice": "tts_url",
  "voiceindex": 0,
  "aliasid": "USR001",
  "name": "John Doe"
}

Failure Response:

JSON{
  "ret": "sendpin",
  "result": false
}

11.4 sendqrcode — Device Reports QR Code Scan

Device reports when a user scans a QR code.

Device → Server (Request):

JSON{
  "cmd": "sendqrcode",
  "sn": "LF00000001",
  "record": "qrcode_data_string"
}

Server → Device (Response):

JSON{
  "ret": "sendqrcode",
  "result": true,
  "access": 1,
  "enrollid": 123,
  "username": "John Doe",
  "message": "Welcome",
  "fontsize": 24,
  "text_color": [255, 0, 0],
  "voice": "tts_url",
  "voiceindex": 0
}

Failure Response:

JSON{
  "ret": "sendqrcode",
  "result": false
}

11.5 sendgps — Device Reports GPS Location [Requires USE_USB4G]

Device proactively sends GPS location data when a USB 4G module is available.

Device → Server (Request):

JSON{
  "cmd": "sendgps",
  "sn": "LF00000001",
  "satellites": 8,
  "location": "latitude,longitude",
  "timeStamp": 1704067200
}

Request Fields:

Note: The server processes this data but does not send a specific response back to the device.

11.6 otacheck — OTA Update Check

Device checks if a firmware update is available.

Device → Server (Request):

JSON{
  "cmd": "otacheck",
  "sn": "LF00000001",
  "fwname": "ai230_device",
  "version": "1.0.0"
}

Server → Device (Response) — Update Available:

JSON{
  "ret": "otacheck",
  "result": true,
  "filesize": 1048576,
  "filename": "update.pkg",
  "md5": "abc123def456..."
}

Server → Device (Response) — No Update:

JSON{
  "ret": "otacheck",
  "result": false
}

11.7 otaget — OTA File Download

Device requests a chunk of the OTA firmware file.

Device → Server (Request):

JSON{
  "cmd": "otaget",
  "sn": "LF00000001",
  "filename": "update.pkg",
  "index": 0,
  "count": 102400
}

Server → Device (Response):

JSON{
  "ret": "otaget",
  "result": true,
  "index": 0,
  "count": 102400,
  "record": "base64_encoded_firmware_chunk"
}

Failure Response:

JSON{
  "ret": "otaget",
  "result": false
}

12. File Management Commands

12.1 getdir — List Directory Files

Lists files in a specified directory.

Request Parameters:

Request Example:

JSON{
  "cmd": "getdir",
  "sn": "LF00000001",
  "path": "/data/photos"
}

Success Response:

JSON{
  "ret": "getdir",
  "sn": "LF00000001",
  "result": true,
  "files": ["file1.jpg", "file2.txt", "photo3.jpg"]
}

Failure Response:

JSON{
  "ret": "getdir",
  "sn": "LF00000001",
  "result": false
}

12.2 getfile — Read File

Reads the contents of a file and returns it as base64.

Request Parameters:

Request Example:

JSON{
  "cmd": "getfile",
  "sn": "LF00000001",
  "path": "/data/photos/user123.jpg"
}

Success Response:

JSON{
  "ret": "getfile",
  "sn": "LF00000001",
  "result": true,
  "base64": "base64_encoded_file_content"
}

Failure Response:

JSON{
  "ret": "getfile",
  "sn": "LF00000001",
  "result": false
}

12.3 writefile — Write File

Writes base64-encoded content to a file.

Request Parameters:

Request Example:

JSON{
  "cmd": "writefile",
  "sn": "LF00000001",
  "path": "/data/config/settings.json",
  "base64": "base64_encoded_json_data"
}

Success Response:

JSON{
  "ret": "writefile",
  "sn": "LF00000001",
  "result": true
}

Failure Response:

JSON{
  "ret": "writefile",
  "sn": "LF00000001",
  "result": false
}

13. Other Commands

13.1 upgrade — Firmware Upgrade via Server

Uploads firmware upgrade data to the device in chunks.

Request Parameters:

Request Example (first chunk):

JSON{
  "cmd": "upgrade",
  "sn": "LF00000001",
  "filename": "update.pkg",
  "md5": "abc123def456...",
  "allcount": 10485760,
  "index": 0,
  "count": 102400,
  "record": "base64_encoded_chunk_data"
}

Success Response:

JSON{
  "ret": "upgrade",
  "sn": "LF00000001",
  "result": true
}

Failure Responses:

JSON{
  "ret": "upgrade",
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "is not this machine upgrade file"
}

13.2 forceota — Force OTA Update

Triggers an immediate OTA update check and download. No parameters.

Request Example:

JSON{
  "cmd": "forceota",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "forceota",
  "sn": "LF00000001",
  "result": true
}

13.3 setotaserver — Set OTA Server Address

Request Parameters:

Request Example:

JSON{
  "cmd": "setotaserver",
  "sn": "LF00000001",
  "address": "https://ota.example.com"
}

Success Response:

JSON{
  "ret": "setotaserver",
  "sn": "LF00000001",
  "result": true
}

Failure Response:

JSON{
  "ret": "setotaserver",
  "sn": "LF00000001",
  "result": false
}

13.4 getotaserver — Get OTA Server Address

Reads the configured OTA server address. No parameters.

Request Example:

JSON{
  "cmd": "getotaserver",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getotaserver",
  "sn": "LF00000001",
  "result": true,
  "address": "https://ota.example.com"
}

13.5 setscreensaver — Set Screensaver

Configures the device screensaver with an image.

Request Parameters:

Request Example:

JSON{
  "cmd": "setscreensaver",
  "sn": "LF00000001",
  "filename": "screensaver1.jpg",
  "photo": "base64_encoded_image",
  "duration": 30,
  "remove": false,
  "removeall": false
}

Success Response:

JSON{
  "ret": "setscreensaver",
  "sn": "LF00000001",
  "result": true
}

13.6 setvoice — Set Custom Voice

Uploads and optionally plays a custom voice file.

Request Parameters:

Request Example:

JSON{
  "cmd": "setvoice",
  "sn": "LF00000001",
  "index": 10,
  "voice": "base64_encoded_wav_data",
  "play": true,
  "repeat_seconds": 60
}

Success Response:

JSON{
  "ret": "setvoice",
  "sn": "LF00000001",
  "result": true
}

13.7 keypad — Control On-Screen Keypad

Activates or deactivates the on-screen numeric keypad.

Request Parameters:

Request Example:

JSON{
  "cmd": "keypad",
  "sn": "LF00000001",
  "password": true,
  "keep": false,
  "timeout": 30,
  "on": true
}

Success Response:

JSON{
  "ret": "keypad",
  "sn": "LF00000001",
  "result": true
}

13.8 verify — Biometric Verification

Performs face or fingerprint verification on the server side.

Request Parameters:

Request Example:

JSON{
  "cmd": "verify",
  "sn": "LF00000001",
  "enrollid": 123,
  "card": 12345,
  "pwd": 0,
  "name": "John Doe",
  "face": "base64_face_photo",
  "finger": "",
  "finger2": "",
  "profile": "{}"
}

Success Response:

JSON{
  "ret": "verify",
  "enrollid": 123,
  "aliasid": "USR001",
  "sn": "LF00000001",
  "result": true
}

Failure Responses (reason codes):

JSON{
  "ret": "verify",
  "enrollid": 123,
  "aliasid": "USR001",
  "sn": "LF00000001",
  "result": false,
  "reason": 5,
  "msg": "no face in picture"
}

13.9 setdepartment — Set Department List

Request Parameters:

Request Example (set departments):

JSON{
  "cmd": "setdepartment",
  "sn": "LF00000001",
  "delete": false,
  "name": ["Engineering", "Sales", "HR", "Finance", "Operations"]
}

Request Example (clear all):

JSON{
  "cmd": "setdepartment",
  "sn": "LF00000001",
  "delete": true
}

Success Response:

JSON{
  "ret": "setdepartment",
  "sn": "LF00000001",
  "result": true
}

13.10 getdepartment — Get Department List

Reads the configured department list. No parameters.

Request Example:

JSON{
  "cmd": "getdepartment",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getdepartment",
  "sn": "LF00000001",
  "result": true,
  "count": 5,
  "name": ["Engineering", "Sales", "HR", "Finance", "Operations"]
}

Failure Response:

JSON{
  "ret": "getdepartment",
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "can not find department file"
}

13.11 setcompanyname — Set Company Name

Request Parameters:

Request Example:

JSON{
  "cmd": "setcompanyname",
  "sn": "LF00000001",
  "name": "Acme Corporation"
}

Success Response:

JSON{
  "ret": "setcompanyname",
  "sn": "LF00000001",
  "result": true
}

13.12 getcompanyname — Get Company Name

Reads the configured company name. No parameters.

Request Example:

JSON{
  "cmd": "getcompanyname",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getcompanyname",
  "sn": "LF00000001",
  "result": true,
  "name": "Acme Corporation"
}

13.13 setquestionnaire — Set Questionnaire

Configures a questionnaire/survey that is displayed to users after verification.

Request Parameters:

Request Example:

JSON{
  "cmd": "setquestionnaire",
  "sn": "LF00000001",
  "title": "Health Declaration",
  "voice": "health.wav",
  "errmsg": "Please complete the survey",
  "radio": true,
  "optionflag": 0,
  "items": ["Option A", "Option B", "Option C"],
  "schedules": ["08: 00-18: 00*1"],
  "usequestion": true,
  "useschedule": false,
  "card": 0,
  "switch_card": 0,
  "enrollid": 0,
  "open": false
}

Success Response:

JSON{
  "ret": "setquestionnaire",
  "sn": "LF00000001",
  "result": true
}

13.14 getquestionnaire — Get Questionnaire

Reads the current questionnaire configuration. No parameters.

Request Example:

JSON{
  "cmd": "getquestionnaire",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "getquestionnaire",
  "sn": "LF00000001",
  "result": true,
  "title": "Health Declaration",
  "voice": "health.wav",
  "errmsg": "Please complete the survey",
  "radio": true,
  "optionflag": 0,
  "usequestion": true,
  "useschedule": false,
  "card": 0,
  "switch_card": 0,
  "items": ["Option A", "Option B", "Option C"],
  "schedules": ["08: 00-18: 00*1"]
}

Not Configured Response:

JSON{
  "ret": "getquestionnaire",
  "sn": "LF00000001",
  "result": false
}

13.15 cleanquestionnaire — Clear Questionnaire

Removes the questionnaire configuration. No parameters.

Request Example:

JSON{
  "cmd": "cleanquestionnaire",
  "sn": "LF00000001"
}

Success Response:

JSON{
  "ret": "cleanquestionnaire",
  "sn": "LF00000001",
  "result": true
}

14. Video Intercom Commands

Note: These commands require the VIDEO_INTERCOM feature to be enabled on the device.

14.1 enablewebrtc — Enable WebRTC

Configures and enables WebRTC video intercom capabilities.

Request Parameters:

Request Example:

JSON{
  "cmd": "enablewebrtc",
  "sn": "LF00000001",
  "intercom": true,
  "monitor": true,
  "waitseconds": 30,
  "inputmode": 0,
  "stunserver": "stun:stun.example.com: 3478",
  "turnserver": "turn:turn.example.com: 3478",
  "turnusername": "user",
  "turnpassword": "password"
}

Success Response:

JSON{
  "ret": "enablewebrtc",
  "sn": "LF00000001",
  "result": true
}

Failure Response:

JSON{
  "ret": "enablewebrtc",
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "this device have not this function"
}

14.2 callaccept — Accept or Reject Call

Server-side response to an incoming intercom call from the device.

Request Parameters:

Request Example (accept):

JSON{
  "cmd": "callaccept",
  "sn": "LF00000001",
  "result": true,
  "sessionid": "session_abc123"
}

Device Response — Sends WebRTC Offer:

JSON{
  "cmd": "offer",
  "sn": "LF00000001",
  "sessionid": "session_abc123",
  "type": "offer",
  "sdp": "v=0\r\no=..."
}

14.3 viewready — Monitor Ready

Server indicates it is ready to receive video monitoring stream.

Request Parameters:

Request Example:

JSON{
  "cmd": "viewready",
  "sn": "LF00000001",
  "sessionid": "session_abc123"
}

Device Response — Sends WebRTC Offer:

JSON{
  "cmd": "offer",
  "sn": "LF00000001",
  "sessionid": "session_abc123",
  "type": "offer",
  "sdp": "v=0\r\no=..."
}

14.4 answer — Process WebRTC Answer

Server sends the WebRTC answer SDP to the device.

Request Parameters:

Request Example:

JSON{
  "cmd": "answer",
  "sn": "LF00000001",
  "sessionid": "session_abc123",
  "sdp": "v=0\r\no=..."
}

Behavior: No direct response. Device processes the answer internally and may retry sending offer if needed.

14.5 icecandidate — Process ICE Candidate

Server sends an ICE candidate to the device for NAT traversal.

Request Parameters:

Request Example:

JSON{
  "cmd": "icecandidate",
  "sn": "LF00000001",
  "sessionid": "session_abc123",
  "candidate": "candidate: 1 1 UDP 123456 192.168.1.100 12345 typ host"
}

Behavior: No direct response. Device adds the ICE candidate internally.

14.6 callcancel — Cancel Call

Cancels an active or pending intercom call.

Request Parameters:

Request Example:

JSON{
  "cmd": "callcancel",
  "sn": "LF00000001",
  "sessionid": "session_abc123",
  "type": 1
}

Behavior: No direct response.

14.7 talklock — Door Control During Call

Controls the door lock during an active intercom call.

Request Parameters:

Request Example:

JSON{
  "cmd": "talklock",
  "sn": "LF00000001",
  "type": 1
}

Success Response:

JSON{
  "ret": "talklock",
  "sn": "LF00000001",
  "result": true
}

14.8 monitorcall — Start Monitoring

Server initiates a monitoring session to view the device's video feed.

Request Parameters:

Request Example:

JSON{
  "cmd": "monitorcall",
  "sn": "LF00000001",
  "force": false,
  "sessionid": "session_abc123"
}

Success Response:

JSON{
  "ret": "monitorcall",
  "sn": "LF00000001",
  "lanscape": 1,
  "result": true,
  "sessionid": "session_abc123"
}

Busy Response:

JSON{
  "ret": "monitorcall",
  "sn": "LF00000001",
  "lanscape": 1,
  "result": false,
  "reason": 1,
  "msg": "another user have monitored",
  "sessionid": "session_abc123",
  "monitoring": "other_session_id"
}

14.9 setviselection — Set Visual Selection Menu

Configures the interactive visual selection menu displayed on the device's touchscreen.

Each page (building) is either/or: send only items[] (flat mode) or only floors[] (floor mode). Do not send both in the same page.

Request Parameters:

Request Example (Mode 1: Flat / legacy):

JSON{
  "cmd": "setviselection",
  "sn": "LF00000001",
  "title": "Visitor Menu",
  "voice": "Please select a room",
  "pages": [
    {
      "itemtitle": "Building 1",
      "items": [
        {"section": "101", "keynum": 101},
        {"section": "102", "keynum": 102}
      ]
    }
  ]
}

Request Example (Mode 2: Floors / new):

JSON{
  "cmd": "setviselection",
  "sn": "LF00000001",
  "title": "Visitor Menu",
  "voice": "Please select a floor",
  "pages": [
    {
      "itemtitle": "Building 1",
      "floors": [
        {
          "floortitle": "Floor 1",
          "items": [
            {"section": "101", "keynum": 101},
            {"section": "102", "keynum": 102}
          ]
        },
        {
          "floortitle": "Floor 2",
          "items": [
            {"section": "201", "keynum": 201}
          ]
        }
      ]
    }
  ]
}

Success Response:

JSON{
  "ret": "setviselection",
  "sn": "LF00000001",
  "result": true
}

14.10 talkcall — Device Initiates Call

Device proactively initiates an intercom call to the server.

Device → Server (Request):

JSON{
  "cmd": "talkcall",
  "sn": "LF00000001",
  "inputnum": 0,
  "inputmode": 0,
  "landscape": 1
}

Server → Device (Response):

JSON{
  "ret": "talkcall",
  "result": true,
  "sessionid": "session_abc123"
}

Failure Response (reason codes):

JSON{
  "ret": "talkcall",
  "result": false,
  "reason": 1
}

14.11 vicheckonline — Check Online Status

Device checks if subscribers are online.

Device → Server (Request):

JSON{
  "cmd": "vicheckonline",
  "sn": "LF00000001"
}

Server → Device (Response):

JSON{
  "ret": "vicheckonline",
  "result": true,
  "count": 1,
  "online": "key1,key2"
}

14.12 WebRTC DataChannel Extension

After a WebRTC connection is established, the device and its peer (indoor unit / outdoor unit / App) open two additional WebRTC DataChannels for peer-to-peer real-time control commands (they do not go through the server and do not use the WebSocket/MQTT channel):

• Payload is UTF-8 JSON text (not binary); a single message should be < 256 bytes.
• Field style follows the WebSocket/MQTT cmd / ret convention, but messages are peer-to-peer and bypass the server.

1) Peer → Device (received by the device):

Example (unlock, on intercom_channel or monitor_channel):

JSON{"cmd":"opendoor","type": 1,"enrollid": 123456,"floor": 5}

Example (talk switch during monitoring, monitor_channel only):

JSON{"cmd":"talk","enable": 1}

Example (screen message):

JSON{"msg":"Please wait"}

2) Device → Peer (sent by the device):

JSON{"ret":"opendoor","result": true,"type": 1}

intercom_channel and monitor_channel share exactly the same message format; only the session type differs. talk is valid on monitor_channel only.

15. Appendix

Appendix A: backupnum Value Reference

Appendix B: verifymode Reference

verifymode selects the verification method(s) a user may use. Every method — including combinations such as "face + card" — has a fixed value; use one of the values below.

Notes:

• A value of 0 means no restriction and is the factory default; a user without its own setting follows the device default.
• Only use methods the device supports. A method the device does not support has no effect: the user keeps the previous setting and no error is returned.
• Use one of the values listed above (values are independent and cannot be added together); do not use values that are not listed.

Appendix C: mode Field in Log Records

The mode field of a log record reports the verification method actually used and uses the same values as verifymode:

The event field of a record reports access-control events (door open/close, duress, ...) and is a different field from mode.
In exported xls reports the text of this column is derived by the device itself, so a few methods may appear under a similar name; values read through the API are always the raw values.

Appendix D: Device Capacity Field Descriptions

Appendix E: Unknown Command Default Response

When a command is not recognized by the device:

JSON{
  "ret": "<original_command>",
  "sn": "LF00000001",
  "result": false,
  "reason": 1,
  "msg": "can not find this command"
}

Command Summary Table

AiFace Device Web API Protocol Documentation (English)

Version: 1.0

Based on: webserver.cpp source code analysis

Protocol: HTTP + JSON

⚠️ Protocol Role Note: In the WebServer API, the device acts as an HTTP server, and browsers or other clients access the device as requesters. Therefore, this protocol is restricted to Local Area Network (LAN) use only — clients must be on the same network segment as the device to access it.

1. Overview

This document describes the HTTP API protocol of the embedded web server in AiFace facial recognition access control devices.

1.1 Server Architecture

• Maximum concurrent connections: 20
• Idle connection timeout: 10 seconds
• Timeout response: HTTP 408 Timeout
• Server busy response: HTTP 503 Busy

2. Connection & Authentication

2.1 Login Flow

Except for the getlang command, all /api commands require a password field in the request. The password is configured in the device's settings menu (mapped to DI_WEBSERVER_PWD).

Note: If no password has been set on the device (empty password), all password-required endpoints will return an error.

2.2 Request Endpoint

All JSON API requests are sent to:

POST http://<device_IP>:<port>/api
Content-Type: application/json

3. Common Request Format

JSON{
  "cmd": "<command_name>",
  "password": "<device_password>",
  // ... command-specific parameters
}

4. Common Response Format

JSON{
  "ret": "<command_name>",
  "sn": "<device_serial_number>",
  "result": true/false,
  // ... command-specific response data
}

5. Error Codes

6. HTTP Route Endpoints

7. JSON API Command Reference

7.1 Authentication & Device Info

7.1.1 `getlang` — Get Current Language

No password required

Request:

JSON{ "cmd": "getlang" }

Response:

JSON{
  "ret": "getlang",
  "sn": "SN123456",
  "result": true,
  "lang": "English"
}

7.1.2 `getlangoption` — Get Available Language List

Request:

JSON{ "cmd": "getlangoption", "password": "xxx" }

Response:

JSON{
  "ret": "getlangoption",
  "sn": "SN123456",
  "result": true,
  "lang": "English",
  "langs": [
    { "lvalue": 0, "ltitle": "English" },
    { "lvalue": 1, "ltitle": "简体中文" }
  ]
}

7.1.3 `login` — Login Verification

Request:

JSON{
  "cmd": "login",
  "username": "admin",
  "password": "xxx"
}

Response (success):

JSON{
  "ret": "login",
  "sn": "SN123456",
  "result": true
}

Response (failure):

JSON{
  "ret": "login",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "username error"
}

7.1.4 `reg` — Get Full Device Registration Info

Request:

JSON{ "cmd": "reg", "password": "xxx" }

Response devinfo field breakdown:

7.1.5 `getdevinfo` — Get Device Configuration Parameters

Request:

JSON{ "cmd": "getdevinfo", "password": "xxx" }

Response: Returns all DI_* configuration key-value pairs.

Response Example:

JSON{
  "ret": "getdevinfo",
  "sn": "SN123456",
  "result": true,
  "deviceid": 1,
  "language": 0,
  "managers": 1,
  "verifymode": 0,
  "volume": 80,
  "netipaddress": "192.168.1.100",
  "serverip": "192.168.1.200",
  "wlan_ssid": "MyWiFi",
  "door_opentime": 5,
  "live_detect": 1,
  "fcmatch_level": 60
}

Complete Configuration Parameter List:

##### General Settings

##### Biometric Settings

##### Serial & Network Settings

##### Server Settings

##### Door Access Settings

##### Wiegand Settings

##### Card & Security Settings

##### Other Settings

Type Notes: number = numeric, IP = IP address string (e.g. "192.168.1.100"), string = plain string.

7.1.6 `setdevinfo` — Set Device Configuration Parameters

Request:

JSON{
  "cmd": "setdevinfo",
  "password": "xxx",
  "nowtime": 1700000000,
  "deviceid": 1,
  "volume": 80,
  "live_detect": 1,
  "fcmatch_level": 60
}

Type Rules:
- IP-type fields (e.g. netipaddress, serverip, etc.) accept IP address strings like "192.168.1.100"
- String-type fields (e.g. wlan_ssid, excel_password, cpucard_key, etc.) accept string values
- All other fields are numeric and accept numbers

7.1.7 `getdevcap` — Get Device Capacity Info

Request:

JSON{ "cmd": "getdevcap", "password": "xxx" }

Response:

JSON{
  "ret": "getdevcap",
  "sn": "SN123456",
  "result": true,
  "usersize": 10000,
  "facesize": 10000,
  "avatarsize": 10000,
  "fpsize": 30000,
  "palmsize": 30000,
  "cardsize": 10000,
  "pwdsize": 10000,
  "logsize": 100000,
  "useduser": 150,
  "usedface": 148,
  "usedavatar": 100,
  "usedfp": 10,
  "usedpalm": 0,
  "usedcard": 50,
  "usedpwd": 20,
  "usedlog": 5000,
  "usednewlog": 100,
  "usedrtlog": 5
}

7.2 User Management

7.2.1 `getuserlist` — Get User List (Paginated)

Request:

JSON{
  "cmd": "getuserlist",
  "password": "xxx",
  "stn": 1
}

Response:

JSON{
  "ret": "getuserlist",
  "sn": "SN123456",
  "result": true,
  "count": 100,
  "to": 50,
  "record": [
    {
      "id": "1001",
      "name": "John Doe",
      "department": "Engineering",
      "shift": 0,
      "admin": 0,
      "fingerprint": 2,
      "palm": 0,
      "face": 1,
      "password": 0,
      "card": 12345678,
      "weekzone": 0,
      "group": 0,
      "access_times": 0,
      "verifymode": 0,
      "enable": 1,
      "birthday": "01-15",
      "starttime": "2024-01-01 00: 00",
      "endtime": "2025-12-31 23: 59",
      "photourl": "/photos/LF00001001.jpg"
    }
  ]
}

Returns up to 50 records per call. Call repeatedly with stn=0 until to >= count or to == 0.

7.2.2 `getuserids` — Get All User IDs

Request:

JSON{ "cmd": "getuserids", "password": "xxx" }

Response:

JSON{
  "ret": "getuserids",
  "sn": "SN123456",
  "result": true,
  "count": 3,
  "record": ["1001", "1002", "1003"]
}

7.2.3 `getunuserdid` — Get Next Available User ID

Request:

JSON{ "cmd": "getunuserdid", "password": "xxx" }

Response:

JSON{
  "ret": "getunuserdid",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1004"
}

7.2.4 `checkuserid` — Check If User ID Exists

Request:

JSON{
  "cmd": "checkuserid",
  "password": "xxx",
  "enrollid": "1001"
}

Response:

JSON{
  "ret": "checkuserid",
  "sn": "SN123456",
  "result": true,
  "exists": true
}

7.2.5 `getuserinfo` — Get Single User Details

Request:

JSON{
  "cmd": "getuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 50
}

Response (with face photo, backupnum=50):

JSON{
  "ret": "getuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "name": "John Doe",
  "department": "Engineering",
  "admin": 0,
  "pwd": 0,
  "card": 12345678,
  "fpflag": 3,
  "fpcnt": 2,
  "palmflag": 1,
  "palmcnt": 1,
  "faceflag": 1,
  "birthday": "01-15",
  "starttime": "2024-01-01 00: 00: 00",
  "endtime": "2025-12-31 23: 59: 59",
  "photourl": "/photos/LF00001001.jpg",
  "backupnum": 50,
  "record": "<Base64-encoded face photo>"
}

Response (user not found):

JSON{
  "ret": "getuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "can not find the user",
  "enrollid": "1001"
}

record format by backupnum:

An exported record can be pushed verbatim to another device with setuserinfo (using the same backupnum) to migrate biometric templates.

7.2.6 `setuserinfo` — Add or Update User Information

Request:

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "name": "John Doe",
  "admin": 0,
  "pwd": 123456,
  "card": 12345678,
  "department": "Engineering",
  "birthday": "01-15",
  "starttime": "2024-01-01 00: 00: 00",
  "endtime": "2025-12-31 23: 59: 59",
  "verifymode": 0,
  "shiftid": 1,
  "zoneid": 1,
  "groupid": 0,
  "access_times": 0,
  "enable": 1,
  "face": "<Base64-encoded face photo>"
}

How each biometric type is pushed:

⚠️ The fingerprint record is not Base64 — it is a "hex + zero run-length" text string. Only palm vein and face feature use Base64. The decoded length must match the table exactly, otherwise the device replies "xxx data error".

record encoding rules:

Recommended call order: create the user first with a setuserinfo call that carries no biometric data, then push each template by backupnum. Pushing backupnum=51 for a non-existent user fails with "face error".

Response (success):

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "backupnum": 50
}

Response (failure):

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 5,
  "msg": "no face",
  "enrollid": "1001"
}

Face enrollment failure reason codes:

Example 1 — push a face photo (face field, device extracts the feature on site):

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "name": "John Doe",
  "face": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL..."
}

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001"
}

Example 2 — push a fingerprint (slot 0, backupnum=0, record is the compressed hex string):

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 0,
  "record": "0a1f2b(807)"
}

The sample above is a complete, format-valid payload: 3 hex bytes followed by (807) (807 0x00 bytes), which decodes to exactly 810 bytes. Minimal testable payload: "record": "(810)", which decodes to 810 0x00 bytes and passes format validation. To push a real template, export the same encoding from an enrolled device with getuserinfo (backupnum=0) or bioread.

Example 3 — push a palm vein template (left hand, backupnum=40; right hand is 41):

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 40,
  "record": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."
}

record is standard Base64 and must decode to exactly 1548 bytes (the Base64 string is always 2064 characters). Minimal testable payload: Base64 of 1548 0x00 bytes (2064 A characters).

Example 4 — push a face feature with key points (backupnum=51, record is Base64):

JSON{
  "cmd": "setuserinfo",
  "password": "xxx",
  "enrollid": "1001",
  "backupnum": 51,
  "record": "CAYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."
}

record is standard Base64 and must decode to exactly 1074 bytes. Minimal testable payload: 08 06 + 1072 0x00 bytes, i.e. a Base64 string starting with CAYA followed by 1428 A characters (1432 characters in total); on BOARD_CORE_810 use the 08 10 header instead (Base64 starts with CBAA). Export real features from an enrolled device with getuserinfo (backupnum=51) and feed them back to other devices unchanged.

Response (success):

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": true,
  "enrollid": "1001",
  "backupnum": 51
}

The response echoes backupnum whenever it was present in the request.

Response (failures):

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 12,
  "msg": "finger already used,id=1002",
  "finger": 0,
  "enrollid": "1001",
  "backupnum": 0
}

JSON{
  "ret": "setuserinfo",
  "sn": "SN123456",
  "result": false,
  "reason": 1,
  "msg": "palm data error",
  "palm": 0,
  "enrollid": "1001",
  "backupnum": 40
}