back
loading skill details...
杰峰智能门锁设备控制技能（开发版）。支持查询设备是否支持门锁能力、登录设备、获取设备接口访问令牌，以及远程一键开锁。
---
name: jf-open-pro-smart-doorlock-control
description: 杰峰智能门锁设备控制技能（开发版）。支持查询设备是否支持门锁能力、登录设备、获取设备接口访问令牌，以及远程一键开锁。
metadata:
version: 1.0.0
author: JFTech
category: device
tags:
- 杰峰
- 智能门锁
- 远程开锁
- 设备登录
- 设备能力
triggers:
- 查询设备是否支持开锁
- 设备支持门锁吗
- 远程开锁
- 一键开锁
- 登录设备
- 获取设备Token
prerequisites:
- 配置必需的环境变量
- 设备需已完成配网和绑定
- 设备需在线
region:
- CN: api-cn.jftechws.com (中国大陆)
- AS: api-as.jftechws.com (亚洲)
- EU: api-eu.jftechws.com (欧洲)
- NA: api-na.jftechws.com (北美洲)
---
# 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` | 签名/时间戳加密工具（复用） |
## 参考文档
- [杰峰开放平台](https://docs.jftech.com)
don't have the plugin yet? install it then click "run inline in claude" again.