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 MQTT/MQTTS publish/subscribe messaging.

⚠️ 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.2 MQTT / MQTTS

⚠️ Not Recommended — Requires deploying an additional MQTT Broker server, increasing deployment complexity and operational costs. Real-time performance is inferior to direct WebSocket connections.

Connection URL Format:

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

Default Configuration:

• Default MQTT port: 1883
• Default MQTTS port: 8883

Topic Naming Rules:

The serial number () in topic names is dynamically replaced with the device's unique serial number.

Note: If a custom topic configuration file exists at /data/res/mqttpwd.json, the topics defined in that file override the default topics. The file format supports variable substitution with :

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

QoS Configuration:

• Default QoS level: 1 (at least once delivery)
• MQTT KeepAlive interval: 60 seconds

Authentication:

• Username/password from /data/res/mqttpwd.json
• Optional client_id for broker identification
• MQTT clean session flag is set to true

Connection Flow:

1. Device connects to MQTT broker
2. On MG_EV_MQTT_OPEN event, device subscribes to its command topic
3. Device immediately sends reg command via publish
4. Messages received on the subscription topic are parsed by procrecmessage()

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 MQTT 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": 81
}

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