Event API
Log
message EventLog {
uint32 ID;
uint32 timestamp;
uint32 deviceID;
string userID;
uint32 entityID;
uint32 eventCode;
uint32 subCode;
tna.Key TNAKey;
bool hasImage;
bool changedOnDevice;
uint32 temperature;
bytes cardData;
DetectInputInfo inputInfo;
AlarmZoneInfo alarmZoneInfo;
InterlockZoneInfo interlockZoneInfo;
}
- ID
- 4 byte identifier of the log record. Each device manages a monotonic increasing counter for this identifier. You can use this value to specify the starting position when reading logs from devices.
- timestamp
- In Unix time format. The number of seconds elapsed since January 1, 1970.
- userID/entityID
- For user related events such as EVENT_VERIFY_SUCCESS or EVENT_USER_ENROLL_SUCCESS, the userID will be set. For other types of events, the entity_ID could be either a door ID or zone ID.
- eventCode
- 16 bit code identifying the event type.
Category Code Value Description Auth BS2_EVENT_VERIFY_SUCCESS 0x1000 1:1 authentication success BS2_EVENT_VERIFY_FAIL 0x1100 1:1 authentication failure BS2_EVENT_VERIFY_DURESS 0x1200 1:1 authentication success under duress BS2_EVENT_IDENTIFY_SUCCESS 0x1300 1:N authentication success BS2_EVENT_IDENTIFY_FAIL 0x1400 1:N authentication failure BS2_EVENT_IDENTIFY_DURESS 0x1500 1:N authentication success under duress BS2_EVENT_DUAL_AUTH_SUCCESS 0x1600 dual authentication success BS2_EVENT_DUAL_AUTH_FAIL 0x1700 dual authentication failure BS2_EVENT_AUTH_FAILED 0x1800 unregistered credential BS2_EVENT_ACCESS_DENIED 0x1900 user without access privileges or violation of zone rules BS2_EVENT_FAKE_FINGER_DETECTED 0x1A00 fake finger detected User BS2_EVENT_USER_ENROLL_SUCCESS 0x2000 user enrollment success BS2_EVENT_USER_ENROLL_FAIL 0x2100 user enrollment failure BS2_EVENT_USER_UPDATE_SUCCESS 0x2200 user update success BS2_EVENT_USER_UPDATE_FAIL 0x2300 user update failure BS2_EVENT_USER_DELETE_SUCCESS 0x2400 user delete success BS2_EVENT_USER_DELETE_FAIL 0x2500 user delete failure BS2_EVENT_USER_DELETE_ALL_SUCCESS 0x2600 delete all user success BS2_EVENT_USER_ISSUE_AOC_SUCCESS 0x2700 issuance of an AOC card success BS2_EVENT_USER_DUPLICATE_CREDENTIAL 0x2800 duplicate credential Device BS2_EVENT_DEVICE_SYSTEM_RESET 0x3000 system reset BS2_EVENT_DEVICE_SYSTEM_STARTED 0x3100 system started BS2_EVENT_DEVICE_TIME_SET 0x3200 system time set BS2_EVENT_DEVICE_TIMEZONE_SET 0x3201 timezone changed BS2_EVENT_DEVICE_DST_SET 0x3202 DST changed BS2_EVENT_DEVICE_LINK_CONNECTED 0x3300 LAN cable connected BS2_EVENT_DEVICE_LINK_DISCONNECTED 0x3400 LAN cable disconnected BS2_EVENT_DEVICE_DHCP_SUCCESS 0x3500 IP address acquired by DHCP BS2_EVENT_DEVICE_ADMIN_MENU 0x3600 enter administrator menu BS2_EVENT_DEVICE_UI_LOCKED 0x3700 device locked BS2_EVENT_DEVICE_UI_UNLOCKED 0x3800 device unlocked BS2_EVENT_DEVICE_TCP_CONNECTED 0x3B00 TCP connected BS2_EVENT_DEVICE_TCP_DISCONNECTED 0x3C00 TCP disconnected BS2_EVENT_DEVICE_RS485_CONNECTED 0x3D00 RS485 connected BS2_EVENT_DEVICE_RS485_DISCONNECTED 0x3E00 RS485 disconnected BS2_EVENT_DEVICE_INPUT_DETECTED 0x3F00 input signal detected BS2_EVENT_DEVICE_TAMPER_ON 0x4000 tamper SW is on BS2_EVENT_DEVICE_TAMPER_OFF 0x4100 tamper SW is off BS2_EVENT_DEVICE_EVENT_LOG_CLEARED 0x4200 log records cleared BS2_EVENT_DEVICE_FIRMWARE_UPGRADED 0x4300 firmware upgraded BS2_EVENT_DEVICE_RESOURCE_UPGRADED 0x4400 resource upgraded BS2_EVENT_DEVICE_CONFIG_RESET 0x4500 system configurations initialized (including network) BS2_EVENT_DEVICE_DATABASE_RESET 0x4501 database initialized BS2_EVENT_DEVICE_FACTORY_RESET 0x4502 factory reset BS2_EVENT_DEVICE_CONFIG_RESET_EX 0x4503 system configurations initialized (excluding network) BS2_EVENT_SUPERVISED_INPUT_SHORT 0x4600 short circuit of a supervised input detected BS2_EVENT_SUPERVISED_INPUT_OPEN 0x4700 disconnection of a supervised input detected Door BS2_EVENT_DOOR_UNLOCKED 0x5000 door unlocked BS2_EVENT_DOOR_LOCKED 0x5100 door locked BS2_EVENT_DOOR_OPENED 0x5200 door open detected by sensor BS2_EVENT_DOOR_CLOSED 0x5300 door closed detected by sensor BS2_EVENT_DOOR_FORCED_OPEN 0x5400 door forced open BS2_EVENT_DOOR_HELD_OPEN 0x5500 door held open too long BS2_EVENT_DOOR_FORCED_OPEN_ALARM 0x5600 forced open alarm BS2_EVENT_DOOR_FORCED_OPEN_ALARM_CLEAR 0x5700 forced open alarm cleared BS2_EVENT_DOOR_HELD_OPEN_ALARM 0x5800 held open alarm BS2_EVENT_DOOR_HELD_OPEN_ALARM_CLEAR 0x5900 held open alarm cleared BS2_EVENT_DOOR_APB_ALARM 0x5A00 anti-passback alarm on a door BS2_EVENT_DOOR_APB_ALARM_CLEAR 0x5B00 anti-passback alarm on a door cleared BS2_EVENT_DOOR_RELEASE 0x5C00 door status reset BS2_EVENT_DOOR_LOCK 0x5D00 lock door BS2_EVENT_DOOR_UNLOCK 0x5E00 unlock door Zone BS2_EVENT_ZONE_APB_VIOLATION 0x6000 APB zone violated BS2_EVENT_ZONE_APB_ALARM 0x6100 APB zone alarm BS2_EVENT_ZONE_APB_ALARM_CLEAR 0x6200 APB zone alarm cleared BS2_EVENT_ZONE_TIMED_APB_VIOLATION 0x6300 timed APB zone violated BS2_EVENT_ZONE_TIMED_APB_ALARM 0x6400 timed APB zone alarm BS2_EVENT_ZONE_TIMED_APB_ALARM_CLEAR 0x6500 timed APB zone alarm cleared BS2_EVENT_ZONE_FIRE_ALARM_INPUT 0x6600 fire alarm input detected BS2_EVENT_ZONE_FIRE_ALARM 0x6700 fire alarm BS2_EVENT_ZONE_FIRE_ALARM_CLEAR 0x6800 fire alarm cleared BS2_EVENT_ZONE_SCHEDULED_LOCK_VIOLATION 0x6900 scheduled lock zone violated BS2_EVENT_ZONE_SCHEDULED_LOCK_START 0x6A00 start of lock schedule BS2_EVENT_ZONE_SCHEDULED_LOCK_END 0x6B00 end of lock schedule BS2_EVENT_ZONE_SCHEDULED_UNLOCK_START 0x6C00 start of unlock schedule BS2_EVENT_ZONE_SCHEDULED_UNLOCK_END 0x6D00 end of unlock schedule BS2_EVENT_ZONE_SCHEDULED_LOCK_ALARM 0x6E00 scheduled lock zone alarm BS2_EVENT_ZONE_SCHEDULED_LOCK_ALARM_CLEAR 0x6F00 scheduled lock zone alarm cleared BS2_EVENT_ZONE_INTRUSION_ALARM_VIOLATION 0x9000 intrusion zone violated BS2_EVENT_ZONE_INTRUSION_ALARM_ARM_GRANTED 0x9100 arming intrusion zone BS2_EVENT_ZONE_INTRUSION_ALARM_ARM_SUCCESS 0x9200 intrusion zone armed BS2_EVENT_ZONE_INTRUSION_ALARM_ARM_FAIL 0x9300 arming intrusion zone failure BS2_EVENT_ZONE_INTRUSION_ALARM_DISARM_GRANTED 0x9400 disarming intrusion zone BS2_EVENT_ZONE_INTRUSION_ALARM_DISARM_SUCCESS 0x9500 intrusion zone disarmed BS2_EVENT_ZONE_INTRUSION_ALARM_DISARM_FAIL 0x9600 disarming intrusion zone failure BS2_EVENT_ZONE_INTRUSION_ALARM 0x9800 intrusion alarm BS2_EVENT_ZONE_INTRUSION_ALARM_CLEAR 0x9900 intrusion alarm cleared BS2_EVENT_ZONE_INTRUSION_ALARM_ARM_DENIED 0x9A00 arming intrusion zone denied BS2_EVENT_ZONE_INTRUSION_ALARM_DISARM_DENIED 0x9B00 disarming intrusion zone denied Lift BS2_EVENT_FLOOR_ACTIVATED 0x7000 floor activated BS2_EVENT_FLOOR_DEACTIVATED 0x7100 floor deactivated BS2_EVENT_FLOOR_RELEASE 0x7200 floor status reset BS2_EVENT_FLOOR_ACTIVATE 0x7300 activate floor BS2_EVENT_FLOOR_DEACTIVATE 0x7400 deactivate floor BS2_EVENT_LIFT_ALARM_INPUT 0x7500 lift alarm input detected BS2_EVENT_LIFT_ALARM 0x7600 lift alarm BS2_EVENT_LIFT_ALARM_CLEAR 0x7700 lift alarm cleared BS2_EVENT_ALL_FLOOR_ACTIVATED 0x7800 all floor activated BS2_EVENT_ALL_FLOOR_DEACTIVATED 0x7900 all floor deactivated - subCode
- Some event types have an additional 8 bit code providing auxiliary information. For example, BS2_EVENT_VERIFY_XXXX events have a sub code denoting the authentication mode. If the eventCode is BS2_EVENT_VERIFY_SUCCESS and the subCode is BS2_SUB_EVENT_VERIFY_CARD_FINGER, it means that the user authenticated Card + Fingerprint successfully.
Category Code Value Description Verify BS2_SUB_EVENT_VERIFY_ID_PIN 0x01 ID + PIN BS2_SUB_EVENT_VERIFY_ID_FINGER 0x02 ID + fingerprint BS2_SUB_EVENT_VERIFY_ID_FINGER_PIN 0x03 ID + fingerprint + PIN BS2_SUB_EVENT_VERIFY_ID_FACE 0x04 ID + face BS2_SUB_EVENT_VERIFY_ID_FACE_PIN 0x05 ID + face + PIN BS2_SUB_EVENT_VERIFY_CARD 0x06 card only BS2_SUB_EVENT_VERIFY_CARD_PIN 0x07 card + PIN BS2_SUB_EVENT_VERIFY_CARD_FINGER 0x08 card + fingerprint BS2_SUB_EVENT_VERIFY_CARD_FINGER_PIN 0x09 card + fingerprint + PIN BS2_SUB_EVENT_VERIFY_CARD_FACE 0x0A card + face BS2_SUB_EVENT_VERIFY_CARD_FACE_PIN 0x0B card + face + PIN BS2_SUB_EVENT_VERIFY_AOC 0x0C AOC card BS2_SUB_EVENT_VERIFY_AOC_PIN 0x0D AOC card + PIN BS2_SUB_EVENT_VERIFY_AOC_FINGER 0x0E AOC card + fingerprint BS2_SUB_EVENT_VERIFY_AOC_FINGER_PIN 0x0F AOC card + fingerprint + PIN BS2_SUB_EVENT_VERIFY_CARD_FACE_FINGER 0x10 card + face + fingerprint BS2_SUB_EVENT_VERIFY_CARD_FINGER_FACE 0x11 card + fingerprint + face BS2_SUB_EVENT_VERIFY_ID_FACE_FINGER 0x12 ID + face + fingerprint BS2_SUB_EVENT_VERIFY_ID_FINGER_FACE 0x13 ID + fingerprint + face Identify BS2_SUB_EVENT_IDENTIFY_FINGER 0x01 fingerprint only BS2_SUB_EVENT_IDENTIFY_FINGER_PIN 0x02 fingerprint + PIN BS2_SUB_EVENT_IDENTIFY_FACE 0x03 face only BS2_SUB_EVENT_IDENTIFY_FACE_PIN 0x04 face + PIN BS2_SUB_EVENT_IDENTIFY_FACE_FINGER 0x05 face + fingerprint BS2_SUB_EVENT_IDENTIFY_FACE_FINGER_PIN 0x06 face + fingerprint + PIN BS2_SUB_EVENT_IDENTIFY_FINGER_FACE 0x07 fingerprint + face BS2_SUB_EVENT_IDENTIFY_FINGER_FACE_PIN 0x08 fingerprint + face + PIN Dual Auth BS2_SUB_EVENT_DUAL_AUTH_FAIL_TIMEOUT 0x01 timeout for dual authentication BS2_SUB_EVENT_DUAL_AUTH_FAIL_ACCESS_GROUP 0x02 invalid access group for dual authentication Invalid Credential BS2_SUB_EVENT_CREDENTIAL_ID 0x01 invalid user ID BS2_SUB_EVENT_CREDENTIAL_CARD 0x02 invalid card BS2_SUB_EVENT_CREDENTIAL_PIN 0x03 invalid PIN BS2_SUB_EVENT_CREDENTIAL_FINGER 0x04 invalid fingerprint BS2_SUB_EVENT_CREDENTIAL_FACE 0x05 invalid face BS2_SUB_EVENT_CREDENTIAL_AOC_PIN 0x06 invalid AOC PIN BS2_SUB_EVENT_CREDENTIAL_AOC_FINGER 0x07 invalid AOC fingerprint Auth Fail BS2_SUB_EVENT_AUTH_FAIL_INVALID_AUTH_MODE 0x01 invalid authentication mode BS2_SUB_EVENT_AUTH_FAIL_INVALID_CREDENTIAL 0x02 invalid credential BS2_SUB_EVENT_AUTH_FAIL_TIMEOUT 0x03 authentication timeout Access Denied BS2_SUB_EVENT_ACCESS_DENIED_ACCESS_GROUP 0x01 invalid access group BS2_SUB_EVENT_ACCESS_DENIED_DISABLED 0x02 disabled user BS2_SUB_EVENT_ACCESS_DENIED_EXPIRED 0x03 expired user BS2_SUB_EVENT_ACCESS_DENIED_ON_BLACKLIST 0x04 blacklisted user BS2_SUB_EVENT_ACCESS_DENIED_APB 0x05 denied by APB rule BS2_SUB_EVENT_ACCESS_DENIED_TIMED_APB 0x06 denied by timed APB rule BS2_SUB_EVENT_ACCESS_DENIED_SCHEDULED_LOCK 0x07 denied by scheduled lock zone BS2_SUB_EVENT_ACCESS_DENIED_FACE_DETECTION 0x0A face not detected BS2_SUB_EVENT_ACCESS_DENIED_FAKE_FINGER 0x0C fake finger detected BS2_SUB_EVENT_ACCESS_DENIED_INTRUSION_ALARM 0x0E denied by intrusion alarm zone BS2_SUB_EVENT_ACCESS_DENIED_INTRUSION_ALARM 0x0E denied by intrusion alarm zone BS2_SUB_EVENT_ACCESS_DENIED_INTERLOCK 0x0F denied by interlock zone BS2_SUB_EVENT_ACCESS_DENIED_HIGH_TEMPERATURE 0x13 too high temperature BS2_SUB_EVENT_ACCESS_DENIED_UNMASKED_FACE 0x15 no mask - TNAKey
- When a T&A key is selected for an authentication event, this field will be set to the key. Refer to TNA.Key.
- hasImage
- True if the event has an image log related to it. You can read image logs using GetImageLog.
- changedOnDevice
- True if the user is enrolled, changed, or deleted at the device.
- temperature
- Temperature of the user. Refer to Thermal API for the related options.
- cardData
- If eventCode is BS2_EVENT_VERIFY_FAIL and subCode is BS2_SUB_EVENT_CREDENTIAL_CARD, this field will have the failed card data.
- inputInfo
- If eventCode is BS2_EVENT_DEVICE_INPUT_DETECTED, BS2_EVENT_SUPERVISED_INPUT_SHORT, or BS2_EVENT_SUPERVISED_INPUT_OPEN, it will have additional information about the input port.
- alarmZoneInfo
- If eventCode is BS2_EVENT_ZONE_INTRUSION_ALARM_ARM_FAIL or BS2_EVENT_ZONE_INTRUSION_ALARM, it will have additional information about the alarm zone.
- interlockZoneInfo
- If eventCode is BS2_EVENT_ZONE_INTERLOCK_VIOLATION, it will have additional information about the interlock zone.
message DetectInputInfo {
uint32 ioDeviceID;
uint32 port;
PortValue value;
}
- ioDeviceID
- The device ID of the input port.
- port
- The index of the port
- value
- The detected value of the port.
enum PortValue {
OPEN = 0;
CLOSED = 1;
SUPERVISED_SHORT = 2;
SUPERVISED_OPEN = 3;
};
- OPEN
- The port is open.
- CLOSED
- The port is closed.
- SUPERVISED_SHORT
- The supervised port is short-circuited.
- SUPERVISED_OPEN
- The supervised port is open.
message AlarmZoneInfo {
uint32 zoneID;
uint32 doorID;
uint32 ioDeviceID;
uint32 port;
}
message InterlockZoneInfo {
uint32 zoneID;
repeated uint32 doorIDs;
}
GetLog
Read event logs from a device. You can limit the search range using startEventID and maxNumOfLog. For T&A specific APIs, refer to the T&A API.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceID | uint32 | The ID of the device |
| startEventID | uint32 | The ID of the first event log to be read. If it is 0, read logs from the start |
| maxNumOfLog | uint32 | The maximum number of logs to be read. If it is 0, try to read all the event logs |
| Response |
| Parameter | Type | Description |
|---|---|---|
| events | EventLog[] | The event logs read from the device |
[Deprecated] GetLogWithFilter
[Important]
It is recommended that logs be received in bulk from the device using the GetLog API, and that logs occurring after the current time be received in real time using the EnableMonitoring and SubscribeRealtimeLog APIs, so that the server stores all logs in an appropriate DBMS and filters the logs from the DBMS.
ClearLog
Delete all event logs stored on a device.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceID | uint32 | The ID of the device |
ClearLogMulti
Delete all event logs stored on multiple devices.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceIDs | uint32[] | The IDs of the devices |
Image log
Some devices can record an image in addition to an event log. Please check if the device supports CapabilityInfo.imageLogSupported. You have to specify the event types for which an image is recorded using SetImageFilter.
message ImageLog {
uint32 ID;
uint32 timestamp;
uint32 deviceID;
string userID;
uint32 eventCode;
uint32 subCode;
bytes JPGImage;
}
- ID
- 4 byte identifier of the log record.
- timestamp
- In Unix time format. The number of seconds elapsed since January 1, 1970.
- eventCode
- 16 bit code identifying the event type.
- subCode
- Some event types have an additional 8 bit code providing auxiliary information.
- JPGImage
- The image recorded in JPG file format.
GetImageLog
Read image logs from a device. You can limit the search range using startEventID and maxNumOfLog.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceID | uint32 | The ID of the device |
| startEventID | uint32 | The ID of the first image log to be read. If it is 0, read logs from the start |
| maxNumOfLog | uint32 | The maximum number of logs to be read. If it is 0, try to read all the image logs. Since image logs are quite larger than textual event logs, you had better set this parameter to a non-zero value |
| Response |
| Parameter | Type | Description |
|---|---|---|
| imageEvents | ImageLog[] | The image logs read from the device |
GetImageFilter
Get the current image filters which specify event types for recording images.
message ImageFilter {
uint32 eventCode;
uint32 scheduleID;
}
- eventCode
- Event type for which an image will be recorded
- scheduleID
- You can limit the recording further by specifying a schedule. Refer to Schedule.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceID | uint32 | The ID of the device |
| Response |
| Parameter | Type | Description |
|---|---|---|
| filters | ImageFilter[] | The filters set to the device |
SetImageFilter
Set image filters which specify event types for recording images.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceID | uint32 | The ID of the device |
| filters | ImageFilter[] | The filters to be set to the device |
SetImageFilterMulti
Set image filters to multiple devices.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceIDs | uint32[] | The IDs of the devices |
| filters | ImageFilter[] | The filters to be set to the devices |
Monitoring
To receive real-time events, you have to do the following steps.
- Enable monitoring on some devices using EnableMonitoring or EnableMonitoringMulti.
- Subscribe to an event channel using SubscribeRealtimeLog.
EnableMonitoring
Enable monitoring on a device.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceID | uint32 | The ID of the device |
EnableMonitoringMulti
Enable monitoring on multiple devices.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceIDs | uint32[] | The IDs of the devices |
DisableMonitoring
Disable monitoring on a device.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceID | uint32 | The ID of the device |
DisableMonitoringMulti
Disable monitoring on multiple devices.
| Request |
| Parameter | Type | Description |
|---|---|---|
| deviceIDs | uint32[] | The IDs of the devices |
SubscribeRealtimeLog
message SubscribeRealtimeLogRequest {
int32 queueSize;
repeated uint32 deviceIDs;
repeated int32 eventCodes;
}
- queueSize
- If the queue is full, the gateway will discard the real-time events. So, it should be large enough for receiving concurrent events.
- deviceIDs
- If it is not empty, receive events from the specified devices only.
- eventCodes
- If it is not empty, receive the specified events only.
The way of receiving real-time events will vary according to your selected language. Please refer to the quick start guide for details.