事件类型

本文档定义门锁上报的所有事件类型及其详情格式。

事件结构

protobuf

message Event {
  uint64 event_id = 1;          // 事件ID
  EventType type = 2;           // 事件类型
  uint64 timestamp = 3;         // 发生时间（UNIX毫秒时间戳）
  uint32 user_id = 4;           // 关联用户ID（0=系统事件）
  uint32 credential_id = 5;     // 关联凭证ID（0=无关联凭证）
  CredentialType credential_type = 6; // 凭证类型
  string detail = 7;            // 事件详情（JSON格式）
}

字段	类型	说明
`event_id`	uint64	事件唯一ID
`type`	EventType	事件类型枚举
`timestamp`	uint64	发生时间（UNIX毫秒时间戳）
`user_id`	uint32	关联用户ID，系统事件为 0
`credential_id`	uint32	关联凭证ID，无关联凭证为 0
`credential_type`	CredentialType	凭证类型
`detail`	string	事件详情，JSON 格式字符串

事件类型总览

protobuf

enum EventType {
  // 锁状态事件 (0x00-0x0F)
  UNLOCK = 0;                   // 开锁（配合 credential_type 区分开锁方式）
  LOCK = 1;                     // 上锁
  DEADLOCK = 2;                 // 反锁
  DOOR_OPEN = 3;                // 门已打开（门磁感应）
  DOOR_CLOSED = 4;              // 门已关闭（门磁感应）
  PASSAGE_MODE_ON = 5;          // 常开模式开启
  PASSAGE_MODE_OFF = 6;         // 常开模式关闭
  // 预留 9 个 (0x07-0x0F)

  // 用户管理事件 (0x10-0x1F)
  USER_ADDED = 16;              // 添加用户
  USER_DELETED = 17;            // 删除用户
  USER_UPDATED = 18;            // 更新用户
  USERS_CLEARED = 19;           // 清空所有用户
  // 预留 12 个 (0x14-0x1F)

  // 凭证管理事件 (0x20-0x2F)
  CREDENTIAL_ADDED = 32;        // 添加凭证
  CREDENTIAL_DELETED = 33;      // 删除凭证
  CREDENTIAL_UPDATED = 34;      // 更新凭证
  CREDENTIALS_CLEARED = 35;     // 清空某类凭证（配合 credential_type）
  // 预留 12 个 (0x24-0x2F)

  // 报警事件 (0x40-0x5F)
  DURESS = 64;                  // 胁迫报警（使用胁迫凭证触发）
  TAMPER = 65;                  // 防撬报警
  INTRUSION = 66;               // 入侵报警（多次错误尝试）
  LOITER = 67;                  // 逗留/徘徊报警
  OBSTRUCTION = 68;             // 遮挡报警（摄像头/传感器被遮挡）
  DOOR_AJAR = 69;               // 门未关好报警（门磁开启超时）
  // 预留 26 个 (0x46-0x5F)

  // 系统事件 (0x60-0x7F)
  LOW_BATTERY = 96;             // 低电量警告
  POWER_OFF = 97;               // 电池耗尽关机
  TIME_SYNC = 98;               // 时间同步
  SETTINGS_CHANGED = 99;        // 设置变更
  FACTORY_RESET = 100;          // 恢复出厂设置
  FIRMWARE_UPDATED = 101;       // 固件升级完成
  // 预留 26 个 (0x66-0x7F)

  // 其他事件 (0x80-0x8F)
  DOORBELL = 128;               // 门铃
  REMOTE_UNLOCK = 129;          // 远程开锁（云端下发）
  INSIDE_UNLOCK = 130;          // 室内开锁（按键/把手）
  // 预留 13 个 (0x83-0x8F)
}

锁状态事件 (0x00-0x0F)

记录门锁的开关状态变化。

值	标识	说明	detail
0	`UNLOCK`	开锁	无
1	`LOCK`	上锁	无
2	`DEADLOCK`	反锁（室内反锁）	无
3	`DOOR_OPEN`	门已打开（门磁感应）	无
4	`DOOR_CLOSED`	门已关闭（门磁感应）	无
5	`PASSAGE_MODE_ON`	常开模式开启	有
6	`PASSAGE_MODE_OFF`	常开模式关闭	无

开锁

枚举值：UNLOCK

通过凭证开锁，开锁方式通过 credential_type 字段区分：

credential_type	开锁方式
`KEY`	APP/小程序开锁
`PASSWORD`	密码开锁
`OFFLINE_PASSWORD`	离线密码开锁
`CARD`	卡片开锁
`FINGERPRINT`	指纹开锁
`FACE`	人脸开锁
`PALM_VEIN`	掌静脉开锁
`REMOTE`	遥控器开锁

常开模式开启

枚举值：PASSAGE_MODE_ON

json

{
  "expire_at": 1735689600000
}

字段	类型	说明
`expire_at`	uint64	常开模式结束时间（UNIX毫秒，0=手动关闭）

用户管理事件 (0x10-0x1F)

记录用户的增删改操作。

值	标识	说明	detail
16	`USER_ADDED`	添加用户	有
17	`USER_DELETED`	删除用户	有
18	`USER_UPDATED`	更新用户信息	有
19	`USERS_CLEARED`	清空所有用户	无

添加/删除/更新用户

枚举值：USER_ADDED / USER_DELETED / USER_UPDATED

json

{
  "target_user_id": 5,
  "target_role": 0
}

字段	类型	说明
`target_user_id`	uint32	被操作的用户ID
`target_role`	uint32	用户角色（0=普通用户，1=管理员，2=拥有者）

凭证管理事件 (0x20-0x2F)

记录凭证的增删改操作。

值	标识	说明	detail
32	`CREDENTIAL_ADDED`	添加凭证	有
33	`CREDENTIAL_DELETED`	删除凭证	有
34	`CREDENTIAL_UPDATED`	更新凭证	有
35	`CREDENTIALS_CLEARED`	清空某类凭证	有

添加/删除/更新凭证

枚举值：CREDENTIAL_ADDED / CREDENTIAL_DELETED / CREDENTIAL_UPDATED

json

{
  "target_credential_id": 10,
  "target_credential_type": 4,
  "target_user_id": 5
}

字段	类型	说明
`target_credential_id`	uint32	被操作的凭证ID
`target_credential_type`	uint32	凭证类型
`target_user_id`	uint32	凭证归属用户ID

清空某类凭证

枚举值：CREDENTIALS_CLEARED

json

{
  "target_credential_type": 4,
  "count": 3
}

字段	类型	说明
`target_credential_type`	uint32	被清空的凭证类型
`count`	uint32	清空数量

报警事件 (0x40-0x5F)

记录各类报警，需要及时通知用户。

值	标识	说明	detail
64	`DURESS`	胁迫报警	无
65	`TAMPER`	防撬报警	无
66	`INTRUSION`	入侵报警（多次错误尝试）	有
67	`LOITER`	逗留/徘徊报警	有
68	`OBSTRUCTION`	遮挡报警	有
69	`DOOR_AJAR`	门未关好报警	有

胁迫报警

枚举值：DURESS

使用胁迫凭证开锁时触发。门正常打开，同时静默上报此事件。

胁迫信息通过 Event 的 credential_type 和 credential_id 字段获取。

防撬报警

枚举值：TAMPER

门锁被撬动或拆卸时触发。

入侵报警

枚举值：INTRUSION

多次错误尝试后触发，门锁进入锁定状态。

json

{
  "attempt_count": 5,
  "lockout_minutes": 3,
  "credential_type": 1
}

字段	类型	说明
`attempt_count`	uint32	错误尝试次数
`lockout_minutes`	uint32	锁定时长（分钟）
`credential_type`	uint32	尝试的凭证类型（密码/指纹等）

逗留报警

枚举值：LOITER

有人在门前逗留/徘徊时触发（需门锁支持人体感应或摄像头）。

json

{
  "duration": 60
}

字段	类型	说明
`duration`	uint32	逗留时长（秒）

遮挡报警

枚举值：OBSTRUCTION

传感器被遮挡时触发。

json

{
  "sensor": "camera"
}

字段	类型	说明
`sensor`	string	被遮挡的传感器

sensor 可选值：

camera - 摄像头
fingerprint - 指纹传感器
face - 人脸传感器

门未关好报警

枚举值：DOOR_AJAR

门磁感应开启超过设定阈值后触发。

json

{
  "duration": 30
}

字段	类型	说明
`duration`	uint32	门未关持续时长（秒）

触发逻辑

门磁感应到 DOOR_OPEN 后，若超过用户设置的时间阈值（如 30 秒）门仍未关闭，则触发 DOOR_AJAR 报警。

系统事件 (0x60-0x7F)

记录系统级别的状态变化。

值	标识	说明	detail
96	`LOW_BATTERY`	低电量警告	有
97	`POWER_OFF`	电池耗尽关机	无
98	`TIME_SYNC`	时间同步	无
99	`SETTINGS_CHANGED`	设置变更	有
100	`FACTORY_RESET`	恢复出厂设置	无
101	`FIRMWARE_UPDATED`	固件升级完成	有

低电量警告

枚举值：LOW_BATTERY

json

{
  "level": 10
}

字段	类型	说明
`level`	uint32	当前电量百分比

设置变更

枚举值：SETTINGS_CHANGED

json

{
  "key": "auto_lock_delay",
  "old": "30",
  "new": "60"
}

字段	类型	说明
`key`	string	设置项标识
`old`	string	原值
`new`	string	新值

固件升级完成

枚举值：FIRMWARE_UPDATED

json

{
  "old_version": "1.0.0",
  "new_version": "1.1.0"
}

字段	类型	说明
`old_version`	string	原固件版本
`new_version`	string	新固件版本

其他事件 (0x80-0x8F)

值	标识	说明	detail
128	`DOORBELL`	门铃	无
129	`REMOTE_UNLOCK`	远程开锁（云端下发）	无
130	`INSIDE_UNLOCK`	室内开锁（按键/把手）	无

远程开锁

枚举值：REMOTE_UNLOCK

通过云端下发指令开锁，与 UNLOCK 的区别是不经过蓝牙通道。

室内开锁

枚举值：INSIDE_UNLOCK

通过门内按键或把手开锁，无需凭证验证。

无额外参数的事件

以下事件 detail 为空字符串 ""：

事件	说明
`LOCK`	上锁
`DEADLOCK`	反锁
`DOOR_OPEN`	门已打开
`DOOR_CLOSED`	门已关闭
`PASSAGE_MODE_OFF`	常开模式关闭
`USERS_CLEARED`	清空所有用户
`DURESS`	胁迫报警（信息在 credential_id）
`TAMPER`	防撬报警
`POWER_OFF`	电池耗尽关机
`TIME_SYNC`	时间同步
`FACTORY_RESET`	恢复出厂设置
`DOORBELL`	门铃
`REMOTE_UNLOCK`	远程开锁
`INSIDE_UNLOCK`	室内开锁

事件类型 ​

事件结构 ​

事件类型总览 ​

锁状态事件 (0x00-0x0F) ​

开锁 ​

常开模式开启 ​

用户管理事件 (0x10-0x1F) ​

添加/删除/更新用户 ​

凭证管理事件 (0x20-0x2F) ​

添加/删除/更新凭证 ​

清空某类凭证 ​

报警事件 (0x40-0x5F) ​

胁迫报警 ​

防撬报警 ​

入侵报警 ​

逗留报警 ​

遮挡报警 ​

门未关好报警 ​

系统事件 (0x60-0x7F) ​

低电量警告 ​

设置变更 ​

固件升级完成 ​

其他事件 (0x80-0x8F) ​

远程开锁 ​

室内开锁 ​

无额外参数的事件 ​

事件类型

事件结构

事件类型总览

锁状态事件 (0x00-0x0F)

开锁

常开模式开启

用户管理事件 (0x10-0x1F)

添加/删除/更新用户

凭证管理事件 (0x20-0x2F)

添加/删除/更新凭证

清空某类凭证

报警事件 (0x40-0x5F)

胁迫报警

防撬报警

入侵报警

逗留报警

遮挡报警

门未关好报警

系统事件 (0x60-0x7F)

低电量警告

设置变更

固件升级完成

其他事件 (0x80-0x8F)

远程开锁

室内开锁

无额外参数的事件