jf-open-pro-smart-doorlock-control

杰峰智能门锁设备控制技能（开发版）。支持查询设备是否支持门锁能力、登录设备、获取设备接口访问令牌，以及远程一键开锁。

jf-open-pro-smart-doorlock-control - 杰峰智能门锁设备控制技能（开发版）

技能描述

支持杰峰智能门锁设备的远程控制功能：

• 查询设备是否支持开锁 - 查询设备能力集，确认是否支持门锁功能
• 登录设备 - 对门锁设备进行登录认证
• 获取设备接口访问令牌 - 获取 deviceToken 用于后续操作
• 远程一键开锁 - 远程发送开锁指令，控制门锁开启

适用场景：

• 远程给家人或访客开锁
• 确认设备是否支持门锁功能
• 设备登录与令牌管理

触发词

• 查询设备是否支持开锁 / 设备支持门锁吗
• 查询门锁配置 / 获取门锁配置
• 远程开锁 / 一键开锁 / 开锁
• 登录设备 / 设备登录
• 获取设备 Token

前置条件

硬件要求

1. 智能门锁 - 设备需为杰峰智能门锁设备

必需配置

1. 签名算法 - 使用杰峰官方移位加密算法生成 signature
2. 时间戳算法 - counter(7 位) + timeMillis(13 位)，实时生成
3. 设备绑定 - 设备需先绑定到开放平台账号

环境变量

变量名	说明	默认值	必需
JF_UUID	开放平台用户 uuid	-	✅
JF_APP_KEY	开放平台应用 appKey	-	✅
JF_APP_SECRET	开放平台应用密钥	-	✅
JF_MOVE_CARD	移动卡标识（用于签名）	2	✅
JF_DEVICE_SN	设备序列号	-	✅
JF_DEVICE_TOKEN	设备接口访问令牌	-	✅
JF_ENDPOINT	API 接入地址	api-cn.jftechws.com	❌

API 接口

功能	地址	方法	需要 Token	需要在线
查询设备能力	POST /gwp/v3/rtc/device/getability/{token}	POST	✅	✅
获取门锁配置	POST /gwp/v3/rtc/device/doorLockTransparent/{token}	POST	✅	✅
登录设备	POST /gwp/v3/rtc/device/login/{token}	POST	✅	✅
获取设备 Token	POST /gwp/v3/rtc/device/token	POST	❌	❌
远程开锁	POST /gwp/v3/rtc/device/doorLockRemoteUnlock/{token}	POST	✅	✅

核心功能

1. 查询设备是否支持开锁

API: POST /gwp/v3/rtc/device/getability/{deviceToken}

Name: DoorFunction

说明： 查询设备能力集，确认设备是否支持门锁功能及相关特性。

响应参数：

字段	类型	说明
DoorFunction.DoorAbilityMask	int	门锁能力掩码（按位标识各类门锁能力）
DoorFunction.LocalAbilityMask	int	本地能力掩码（按位标识本地支持的能力）
DoorFunction.UserManage	object	用户管理能力信息
DoorFunction.UserManage.TypeMsk	int	用户类型掩码
DoorFunction.AdminAbility	int	管理员能力值
DoorFunction.TmpPwdRange	object	临时密码范围配置
DoorFunction.TmpPwdRange.Start	int	临时密码起始值
DoorFunction.TmpPwdRange.End	int	临时密码结束值
DoorFunction.TmpPwdRange.UsrTypeMask	int	临时密码适用的用户类型掩码
DoorFunction.TipVolume	int	提示音量档位
DoorFunction.RebootMachine	int	重启设备支持标识
DoorFunction.OPTrans	int	透明传输能力标识
DoorFunction.IOTFaceModuleOta	object	人脸识别模块 OTA 信息
DoorFunction.IOTFaceModuleOta.Enable	bool	人脸识别模块 OTA 使能状态
DoorFunction.IOTFaceModuleOta.Pid	int	人脸识别模块产品 ID
DoorFunction.IOTFaceModuleOta.ModuleName	string	人脸识别模块名称
DoorFunction.IOTFaceModuleOta.NavVersion	string	人脸识别模块导航版本
DoorFunction.QsCapMask	int	快速启动能力掩码
DoorFunction.QsPid	int	快速启动产品 ID
DoorFunction.NavVersion	string	导航版本号

2. 获取门锁配置

API: POST /gwp/v3/rtc/device/doorLockTransparent/{deviceToken}

请求参数：

参数	类型	必需	说明	取值
Name	string	✅	方法名称	OPDoorLockProCmd
OPDoorLockProCmd.Cmd	string	✅	命令码	GetDoorConfig

请求示例：

json

{
  "Name": "OPDoorLockProCmd",
  "OPDoorLockProCmd": {
    "Cmd": "GetDoorConfig"
  }
}

响应参数：

字段	类型	说明
DoorConfig.PirConfig.Enable	bool	逗留侦测是否使能
DoorConfig.PirConfig.sensitivity	int	灵敏度：低/中/高（0/1/2）
DoorConfig.UnlockDirection.Direction	int	方向：左/右（0/1）
DoorConfig.AutoLock.LockMode	int	手动上锁/自动上锁（0/1）
DoorConfig.AutoLock.AutoLockInterval	int	自动锁定时间：10~99 秒
DoorConfig.UnlockMode.mode	int	单开模式/组合模式（0/1）
DoorConfig.VolumeControl.Volume	int	音量：静音/小/中/大（0/1/2/3）
DoorConfig.FaceAlarmTone.Enable	bool	人脸声音开关是否使能
DoorConfig.MotorTorque.Torque	int	扭矩：小/中/大（0/1/2）
DoorConfig.NormalOpenMode.Mode	int	常开模式：关闭/开启（0/1）
DoorConfig.DeployDefense.Enable	int	布防状态：撤防/布防（0/1）

3. 登录设备

API: POST /gwp/v3/rtc/device/login/{deviceToken}

请求参数：

参数	类型	必需	说明	示例
UserName	string	✅	设备用户名，恢复出厂后部分设备默认为 admin	admin
PassWord	string	❌	设备登录密码	123456
KeepaliveTime	int	❌	保活时长，单位秒（默认 5 分钟，最长 24 小时）	300

响应参数：

字段	类型	说明
Ret	int	设备登录状态码（100=成功）
DeviceType	string	设备类型（IOT/IPC/DVR 等）
AliveInterval	int	客户端与设备保活时间周期，单位秒
ChannelNum	int	设备通道数
SessionID	string	会话 ID

说明： 设备默认 1 分钟无操作自动断开连接，若需保持长时间连接可设置 KeepaliveTime 进行保活。

3. 获取设备接口访问令牌

API: POST /gwp/v3/rtc/device/token

说明： 获取 deviceToken，用于后续的门锁操作。Token 有效期 24 小时。

4. 远程一键开锁

API: POST /gwp/v3/rtc/device/doorLockRemoteUnlock/{deviceToken}

请求参数：

参数	类型	必需	说明	取值
sn	string	✅	设备序列号	-
props.doorLock.remoteUnlock.password	string	❌	锁端密码（密码开锁时必填）	-
props.doorLock.remoteOneKeyUnlock	int	❌	无密码一键开锁标记，填 1	-
props.doorLock.userType	int	❌	远程开锁为 5	5
props.doorLock.memberID	int	❌	成员 ID，1 表示主账号	1

说明： 支持两种开锁方式。提供密码时使用密码开锁，不提供密码时使用无密码一键开锁。

使用示例

环境准备

bash

# 设置环境变量（使用占位符，请替换为实际值）
export JF_UUID="uuidxxxx"
export JF_APP_KEY="appkeyxxxx"
export JF_APP_SECRET="appsecretxxxx"
export JF_MOVE_CARD="2"
export JF_DEVICE_SN="snxxx1"
export JF_DEVICE_TOKEN="NTQ0NzQ3YmE3MXwyYzFk..."
export JF_ENDPOINT="api-cn.jftechws.com"

1. 查询设备是否支持开锁

bash

cd ~/.qoderwork/skills/jf-open-pro-smart-doorlock-control/scripts

python3 doorlock_control.py --action check-support

2. 获取门锁配置

bash

python3 doorlock_control.py --action get-config

3. 登录设备

bash

# 使用默认用户名 admin 登录
python3 doorlock_control.py --action login --username "admin" --password "123456"

# 设置保活时长为 10 分钟
python3 doorlock_control.py --action login --username "admin" --password "123456" --keepalive-time 600

4. 获取设备 Token

bash

python3 doorlock_control.py --action get-token --device-sn "snxxx1"

5. 远程一键开锁

bash

# 无密码一键开锁
python3 doorlock_control.py --action unlock

# 使用密码开锁
python3 doorlock_control.py --action unlock --password "123456"

状态码

平台状态码

code	说明	处理建议
2000	成功	-
28007	Header 参数错误	检查 uuid、appKey、timeMillis、signature
40103	无效 Token	deviceToken 过期，重新获取
50000	服务器内部错误	联系杰峰技术支持

设备状态码（Ret）

Ret	说明
100	成功
103	非法请求（设备不支持该功能）
106	用户名或密码错误

注意事项

1. 设备要求 - 仅智能门锁设备支持此功能
2. deviceToken 有效期 - 24 小时，过期需重新获取
3. 设备在线要求 - 远程开锁需要设备在线
4. 安全性 - 远程开锁涉及物理安全，请谨慎操作
5. 登录要求 - 部分设备可能需要先登录才能执行开锁操作

相关文件

文件	说明
SKILL.md	技能文档
scripts/doorlock_control.py	Python 执行脚本
scripts/crypto.py	签名/时间戳加密工具（复用）

参考文档

• 杰峰开放平台