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 operating over WebSocket (WS/WSS) for real-time bidirectional communication.

⚠️ 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.

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

2. JSON Command Format

2.1 General Request Format

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

2.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>"
}

2.3 Error Codes (reason field)

Different commands use different error code systems. Common patterns:

3. 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

4. Device Registration — `reg` Command

4.1 Device → Server (Registration Request)

Also known as Active_send_reg. The device sends this command automatically immediately after the WebSocket connection is established.

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:

4.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

5. User Management Commands

5.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"
}

5.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"
}

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

5.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"
}

5.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"
}

5.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": []
}

5.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.

5.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"
}

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

5.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"
}

5.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"
}

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

5.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

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

5.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"
}

5.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"
}

5.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"
}

6. Log Management Commands

6.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:

6.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": ""
    }
  ]
}

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

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

7. Device Management Commands

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

7.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).

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

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

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

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

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

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

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

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

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

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

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

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

7.15 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. Access Control Commands

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

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

8.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)

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

8.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": []
}

8.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"
}

8.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"
}

8.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"
}

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

9. Attendance Management Commands

9.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

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

9.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)

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

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

9.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}
  ]
}

10. 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.

10.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:

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

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

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

10.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.

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

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

11. File Management Commands

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

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

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

12. Other Commands

12.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"
}

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

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

12.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"
}

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

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

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

12.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"
}

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

12.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"
}

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

12.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"
}

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

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

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

13. Video Intercom Commands

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

13.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"
}

13.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=..."
}

13.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=..."
}

13.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.

13.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.

13.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.

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

13.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"
}

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

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

13.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"
}

13.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.

14. 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