设备管理
设备管理模块负责门锁的初始化、密钥生成、状态查询等核心功能。这些操作是使用门锁前的必要步骤。
概述
设备管理主要包括以下功能：
- 密钥管理：获取公钥、私钥和签名密钥，建立安全通信
- 设备信息查询：读取锁的详细状态和配置信息
- 设备诊断数据读取：读取工厂测试所需的功耗等诊断数据
- 超级管理员设置：初始化门锁的首个管理员
- 领锁状态管理：控制门锁的初始化状态
获取公钥
指令码
0x3090
请求参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID (0x3090) |
| LockID | 字符串 | 40 | 锁 ID |
响应参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID (0x3090) |
| Status | 整型 | 1 | 处理状态 |
| PublicKey | 二进制 | 16 | 公钥 |
说明
- 加密类型: 0 (明文)
- 公钥由锁端随机生成
- 锁里写入钥匙数据后不允许再获取
- 密钥体系和用途详见 加密与签名
获取私钥和签名密钥
密钥命名混乱历史
由于历史原因，代码中存在多种命名（如CommKey、通信密钥等），详见 密钥命名混乱历史。
指令码
0x3091
请求参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID (0x3091) |
| LockID | 字符串 | 40 | 锁 ID |
| KeyID | 字符串 | 40 | 钥匙 ID |
| AuthUserID | 字符串 | 20 | 钥匙授权人 ID |
| Timestamp | 整型 | 4 | 当前时间戳(UNIX格式) |
| AuthCodeLen | 整型 | 1 | AuthCode 数据长度(固定为16) |
| AuthCode | 二进制 | 16 | 鉴权码 |
响应参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID (0x3091) |
| Status | 整型 | 1 | 处理状态 |
| PrivateKey | 二进制 | 16 | 私钥 |
| SignKey | 二进制 | 16 | 签名密钥 |
| RandPassTick | 整型 | 4 | 随机密码时间戳 |
说明
- 加密类型: 2 (SM4公钥模式，密钥=LockID[0:16])
- AuthCode计算: 使用加密与签名 - AuthCode签名计算中的
场景1计算方式 - 返回的密钥用途详见 加密与签名
读取设备状态信息
获取门锁的详细状态信息，包括硬件版本、软件版本、功能特征值等。
指令码
0x3040
请求参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID |
| LockID | 字符串 | 40 | 锁 ID |
| UserID | 字符串 | 20 | 用户 ID |
| TimeStamp | 整型 | 4 | 时间戳（UTC+0） |
| LocalUnix | 整型 | 4 | 当地时间（UNIX 格式） 无网络情况传 0，锁板不校验 中国传 UTC+8： 8*3600 + timestamp |
响应参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID |
| Status | 整型 | 1 | 处理状态 |
| Vendor | 字符串 | 20 | 厂商名称 例如： 万达集团 → WDJT |
| Product | 整型 | 1 | 锁设备类型1: 普通门锁2: 视频门锁3: 人脸识别门锁4: 挂锁等 |
| Model | 字符串 | 20 | 产品型号 例如： 一握开家用版v2 → singlegrip2外观不同或功能有差异的产品必须使用不同型号 |
| FwVersion | 字符串 | 20 | 软件版本 例如： 1.0.0.230828 |
| HwVersion | 字符串 | 20 | 硬件版本 例如： 1.0.0.230828 |
| SerialNum0 | 字符串 | 16 | 厂商序列号 同一把锁必须保证唯一，重置不变 SerialNum0 相同的设备会覆盖现有设备 |
| SerialNum1 | 字符串 | 16 | 成品商序列号（可选） 等同于产品外包装上的 SN 号 |
| BtDeviceName | 字符串 | 16 | 蓝牙名称 例如： TMH_c3570480da8d |
| ElectricQuantity | 整型 | 1 | 电池剩余电量 |
| ElectricQuantityStandby | 整型 | 1 | 备用电池剩余电量 |
| RestoreCounter | 整型 | 2 | 重置次数 |
| RestoreDate | 整型 | 4 | 重置时间（UNIX 时间格式） |
| IcPartNo | 字符串 | 10 | 主控芯片型号 |
| Indate | 整型 | 4 | 有效时间（UNIX 时间格式） |
| Mac | 字符串 | 20 | 蓝牙 MAC 地址 |
| FeatureValueLength | 整型 | 1 | 特征值字符串长度 |
| FeatureValue | 字符串 | 变长 | 锁特征值说明（设备支持的功能） |
| FeatureEnValLength | 整型 | 1 | 使能特征值字符串长度 |
| FeatureEnVal | 字符串 | 变长 | 使能锁特征值说明（设备已启用的功能） |
| FeatureParaTotal | 整型 | 1 | 支持的带参数特征值的总条目数 |
| FeatureParaBit | 整型 | 1 | 对应特征值的位 |
| FeatureParaLength | 整型 | 1 | 对应特征值的参数长度 |
| FeatureParaData | 变长 | - | 对应特征值的参数 若 FeatureParaTotal > 1 则重复上述 3 个字段 |
锁特征值说明
特征值概述
特征值是一个 16 进制字符串，用于说明门锁支持的功能。
- 如果使用官方 APP SDK，SDK 提供了相应的方法来判断特征值是否支持某项功能
- 如果需要在后端或 Web 前端进行判断，请参考以下规则自行实现
解析规则
特征值是一个 16 进制字符串，表示门锁支持的功能。
解析步骤：
- 将 16 进制字符串转换为二进制
- 每个字节的每一位代表一个功能
- 值为
1表示支持，值为0表示不支持
示例：
假设某把锁的特征值为：C2F44354CF1F3
转换为二进制后：
1100 0010 1111 0100 0100 0011 0101 0100 1100 1111 0001 1111 0011高低位转换后的二进制：
11001111 10001111 00110010 10101100 00100010 11110100 0011功能位定义
高低位转换后，每个字节位（从 0 开始计算）对应的功能如下：
| 位 | 变量名 | 功能说明 | 是否带参数 |
|---|---|---|---|
| 0 | password | 支持密码 | 否 |
| 1 | icCard | 支持IC卡 | 否 |
| 2 | fingerprint | 支持指纹 | 否 |
| 3 | fingerVein | 支持指静脉 | 否 |
| 4 | palmVein | 支持掌静脉 | 否 |
| 5 | d3Face | 支持3D人脸 | 否 |
| 6 | qrCode | 支持二维码 | 否 |
| 7 | bluetoothRemoteControl | 支持蓝牙遥控器 | 否 |
| 8 | wirelessKey | 支持无线钥匙 | 否 |
| 9 | gatewayUnlock | 支持网关开锁 | 否 |
| 10 | isSupportIris | 支持虹膜识别 | 否 |
| 11 | reserveMethod2 | 预留开锁方式2 | 否 |
| 12 | reserveMethod3 | 预留开锁方式3 | 否 |
| 13 | reserveMethod4 | 预留开锁方式4 | 否 |
| 14 | lockCommand | 支持闭锁指令 | 否 |
| 15 | firmwareUpgrade | 支持固件升级设置 | 否 |
| 16 | passwordIssue | 支持密码下发 | 否 |
| 17 | cardIssue | 支持卡片下发 | 否 |
| 18 | fingerprintIssue | 支持指纹下发 | 否 |
| 19 | fingerVeinIssue | 支持指静脉下发 | 否 |
| 20 | palmVeinIssue | 支持掌静脉下发 | 否 |
| 21 | d3FaceIssue | 支持3D人脸下发 | 否 |
| 22 | reserveDownload1 | 预留下发特征1 | 否 |
| 23 | reserveDownload2 | 预留下发特征2 | 否 |
| 24 | lockFreeze | 支持冻结/解冻锁 | 否 |
| 25 | readAdminPassword | 支持读取管理员密码 | 否 |
| 26 | passwordManagement | 支持密码管理功能 | 否 |
| 27 | passwordWithDelete | 支持密码带删除功能 | 否 |
| 28 | remoteUnlock | 支持配置远程开锁 | 否 |
| 29 | autoLock | 支持自动闭锁设置 | 是 |
| 30 | antiPrySwitch | 支持防撬开关配置 | 否 |
| 31 | resetSwitch | 支持重置键配置 | 否 |
| 32 | lockSwitch | 支持反锁功能配置 | 否 |
| 33 | lockSound | 支持语音提示管理 | 是 |
| 34 | languageSetting | 支持语言设置 | 是 |
| 35 | realTimeClock | 支持实时时钟 | 否 |
| 36 | wifi | 支持WIFI | 否 |
| 37 | videoIntercom | 支持可视对讲 | 否 |
| 38 | cyclePassword | 支持循环密码 | 否 |
| 39 | cycleFingerprintCard | 支持循环指纹/卡 | 否 |
| 40 | doubleAuthentication | 支持双重认证 | 否 |
| 41 | openDirection | 支持左右开门设置 | 是 |
| 42 | proximitySensing | 支持接近感应 | 是 |
| 43 | doorStatus | 支持门磁状态 | 否 |
| 44 | wiredDoorMagnet | 支持有线门磁 | 否 |
| 45 | wirelessDoorMagnet | 支持无线门磁 | 否 |
| 46 | doorNotClosedAlarm | 支持门未关报警 | 否 |
| 47 | unlockReminder | 支持开锁提醒 | 否 |
| 48 | wirelessKeyboard | 支持无线键盘 | 否 |
| 49 | lightingTime | 支持照明灯时间配置 | 是 |
| 50 | passageMode | 支持常开模式（某一天几点到几点） | 是 |
| 51 | hotelLockCardSystem | 支持常开模式自动开锁设置 | 否 |
| 52 | discardValue1 | 常开模式下是否支持关闭自动闭锁 | 否 |
| 53 | discardValue2 | 保留项（原考勤功能） | 否 |
| 54 | discardValue3 | 支持酒店锁卡系统 | 否 |
| 55 | appUnlockOnline | APP开锁时需联网 | 否 |
| 56 | bluetoothBroadcast | 支持蓝牙广播 关闭则不能使用蓝牙主动开锁 | 否 |
| 57 | isSupportPush | 支持推送设置 | 是 |
| 58 | motorTorsion | 支持电机扭力设置 | 是 |
| 59 | isSupportOpen | 支持开门器开锁 | 否 |
| 60 | isSupportAutoLight | 支持自动亮屏 | 否 |
| 61 | stayWarn | 支持逗留警告 | 否 |
| 62 | abnormalWarn | 支持异常警告 | 否 |
| 63 | isSupportForcedOpen | 支持胁迫开门 | 否 |
| 64 | isSupportCatEye | 猫眼监控功能 | 否 |
| 65 | isSupportBackupBattery | 支持备用电池 | 否 |
| 66 | offlinePasswordEncryption | 离线密码算法 用于区分方案商的不同离线密码算法 | 否 |
| 67 | offlinePasswordNumMax | 离线密码最大个数 | 否 |
| 68 | deviceEnMultiLanguage | 设备支持的多国语言 bit0=1: 支持中文 bit1=1: 支持英文 | 是 |
| 69 | isNoSupportedBlueBroadcast | 0: 默认支持蓝牙广播 1: 不支持蓝牙广播 | 否 |
| 70 | isElectronicAntiLock | 电子反锁 1: 打开 0: 关闭 | 否 |
| 71 | isVisualDoorBellCode | 是否支持可视门铃码 | 否 |
| 72 | isDoubleLockLinkage | 双锁联动 | 是 |
| 73 | wifiLockType | WiFi 类型 0: WiFi保活 1: WiFi不保活图传 2: WiFi不保活可视对讲 | 否 |
| 74 | isMJpeg | 是否支持 mJpeg | 否 |
| 75 | isH264 | 是否支持 h264 | 否 |
| 76 | isH265 | 是否支持 h265 | 否 |
| 77 | languageSpeech | 是否支持语音的语种设置 | 是 |
提示
更多功能位定义请参考最新的协议文档或联系技术支持。
获取门锁功耗数据
获取门锁在工厂测试中保存的功耗诊断数据，用于质检、追溯与导出报表。
指令码
0x3041
请求参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID (0x3041) |
| LockID | 字符串 | 40 | 锁 ID |
| UserID | 字符串 | 20 | 用户 ID |
| TimeStamp | 整型 | 4 | 当前时间戳（UTC） |
| TestSessionID | 整型 | 4 | 本次测试会话 ID，用于关联同一次产测数据；无会话时传 0 |
响应参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID (0x3041) |
| Status | 整型 | 1 | 处理状态 |
| DataVersion | 整型 | 1 | 功耗数据格式版本号，当前固定为 1 |
| SampleTime | 整型 | 4 | 功耗数据采集时间（UNIX 时间） |
| VoltageMv | 整型 | 2 | 采样时电源电压，单位 mV |
| StandbyCurrentUa | 整型 | 4 | 待机电流，单位 μA |
| ConnectCurrentMa | 整型 | 2 | 蓝牙连接状态平均电流，单位 mA |
| UnlockPeakCurrentMa | 整型 | 2 | 开锁瞬时峰值电流，单位 mA |
| MotorCurrentMa | 整型 | 2 | 电机工作平均电流，单位 mA |
| LowVoltageCurrentUa | 整型 | 4 | 低压休眠电流，单位 μA |
| BatteryLevel | 整型 | 1 | 电池剩余电量，范围 0-100 |
| ResultFlags | 整型 | 1 | 测试结果标记位 |
ResultFlags 位定义
| Bit | 名称 | 说明 |
|---|---|---|
| 0 | standbyValid | 待机电流有效 |
| 1 | connectValid | 蓝牙连接电流有效 |
| 2 | unlockPeakValid | 开锁峰值电流有效 |
| 3 | motorValid | 电机工作电流有效 |
| 4 | lowVoltageValid | 低压休眠电流有效 |
| 5 | batteryLevelValid | 电池电量有效 |
| 6-7 | Reserved | 保留 |
说明
- 本接口返回锁板当前保存的最近一次功耗测试结果
- 功耗数据由锁板采集并保存，APP 负责读取与展示
- 当某项数据未采集成功时，对应值返回
0，并将ResultFlags中对应位清零 - 数值单位以字段名为准：
Ua表示微安，Ma表示毫安，Mv表示毫伏
增加超级管理员
添加门锁的首个超级管理员用户，完成门锁的初始化。
指令码
0x3001
请求参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID |
| LockID | 字符串 | 40 | 锁 ID |
| AuthUserID | 字符串 | 20 | 授权者 ID（管理员角色） |
| KeyID | 字符串 | 40 | 钥匙 ID |
| UserID | 字符串 | 20 | 用户 ID |
| OpenMode | 整型 | 1 | 开锁方式 |
| KeyType | 整型 | 1 | 钥匙类型0: 普通1: 临时（到期自动删除）2: 蓝牙遥控器255: 测试（添加正式钥匙后自动失效） |
| StartDate | 整型 | 4 | 启用日期（UNIX 时间） |
| ExpireDate | 整型 | 4 | 停用日期（UNIX 时间） |
| UseCountLimit | 整型 | 2 | 使用次数限制0xFFFF: 不限次数 |
| IsRound | 整型 | 1 | 是否循环 |
| WeekRound | 整型 | 1 | 循环周期 Bit0-6 置位分别代表周日至周六 |
| StartHour | 整型 | 1 | 开始小时 |
| StartMin | 整型 | 1 | 开始分钟 |
| EndHour | 整型 | 1 | 结束小时 |
| EndMin | 整型 | 1 | 结束分钟 |
| Role | 整型 | 1 | 用户角色0: 普通用户1: 管理员0xff: 超级管理员 |
| Password | 字符串 | 20 | 超级管理员领锁时需验证的密码 |
| Token | 整型 | 4 | 动态口令 |
| AuthCodeLen | 整型 | 1 | 鉴权码长度 |
| AuthCode | 字符串 | 变长 | 鉴权码 首次请求可填写附加信息，用于锁验证用户合法性 |
鉴权码计算
鉴权码计算方法参考 加密与签名 文档。
响应参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID |
| LockID | 字符串 | 40 | 锁 ID（成功时返回） |
| Token | 整型 | 4 | 动态口令 |
| Status | 整型 | 1 | 处理状态 |
| No | 整型 | 2 | 在锁上的用户序号 APP 可将其替换为 KeyID |
| serialNo | 字符串 | 4 | 序列号，用于临时密码生成 |
退出领锁状态
退出门锁的领锁（初始化）状态。
指令码
0x30F3
请求参数
| 字段名称 | 类型 | 长度 | 说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID |
| LockID | 字符串 | 40 | 锁 ID |
响应参数
无