JF Open Pro PTZ Control

面向开发者杰峰设备云台控制工具 (Python)

支持设备状态查询、方向控制、一键遮蔽、变倍和聚焦、预置位及巡航计划管理功能。

🔒 安全说明

仅支持环境变量存储凭据

🚀 快速开始

设置环境变量

export JF_UUID="your-uuid"              # 开放平台用户唯一标识
export JF_APPKEY="your-appkey"          # 开放平台应用 Key
export JF_APPSECRET="your-appsecret"    # 开放平台应用密钥
export JF_MOVECARD=5                    # 签名算法偏移量 (0-9)
export JF_SN="your-device-sn"           # 设备序列号
export JF_USERNAME="admin"              # 设备用户名（可选，默认：admin）
export JF_PASSWORD="your-password"      # 设备密码（可选）

使用技能

# 查询设备状态
python scripts/jf_open_pro_ptz_control.py status

# 云台方向控制（向上转动）
python scripts/jf_open_pro_ptz_control.py ptz --direction up --action start
# 停止转动
python scripts/jf_open_pro_ptz_control.py ptz --direction up --action stop

# 一键遮蔽（开启）
python scripts/jf_open_pro_ptz_control.py mask --enable true

# 一键遮蔽（关闭）
python scripts/jf_open_pro_ptz_control.py mask --enable false

# 变倍控制（放大）
python scripts/jf_open_pro_ptz_control.py zoom --zoom-command ZoomTile --action start
python scripts/jf_open_pro_ptz_control.py zoom --zoom-command ZoomTile --action stop

# 设置预置点
python scripts/jf_open_pro_ptz_control.py preset --preset-command set --id 1 --name "门口"

# 转到预置点
python scripts/jf_open_pro_ptz_control.py preset --preset-command goto --id 1

# 获取预置点列表
python scripts/jf_open_pro_ptz_control.py preset --preset-command list

# 添加巡航点
python scripts/jf_open_pro_ptz_control.py tour --tour-command add --tour-id 0 --preset-id 1

# 启动巡航
python scripts/jf_open_pro_ptz_control.py tour --tour-command start --tour-id 0

# 获取巡航列表
python scripts/jf_open_pro_ptz_control.py tour --tour-command list

📋 环境变量

🛠️ 功能

1. 设备状态查询

查询设备在线状态、休眠状态、认证状态、设备 WAN IP 等。

python scripts/jf_open_pro_ptz_control.py status

返回信息：

• 设备在线状态（online/notfound）
• 低功耗设备休眠状态
• 认证状态
• 设备 WAN IP

2. 方向控制 (PTZ)

云台支持 8 个方向转动：

使用示例：

# 开始向上转动（速度 5）
python scripts/jf_open_pro_ptz_control.py ptz --direction up --action start --step 5

# 停止转动
python scripts/jf_open_pro_ptz_control.py ptz --direction up --action stop

参数说明：

• --direction: 方向（up/down/left/right/leftup/leftdown/rightup/rightdown）
• --action: 动作（start/stop）
• --step: 速度（1-8，1 最慢，8 最快，默认：5）

⚠️ 重要: 必须先发送 start 再发送 stop，建议间隔 500ms。如果不发送 stop，设备会一直转动到最大角度。

3. 一键遮蔽 (Mask)

开启后摄像头转至最下方然后转至最右侧，同时关闭视频预览和录像。

# 开启遮蔽
python scripts/jf_open_pro_ptz_control.py mask --enable true

# 关闭遮蔽
python scripts/jf_open_pro_ptz_control.py mask --enable false

4. 变倍和聚焦控制 (Zoom/Focus)

支持变倍（Zoom）和聚焦（Focus）操作：

使用示例：

# 开始变倍 +（放大）
python scripts/jf_open_pro_ptz_control.py zoom --zoom-command ZoomTile --action start --step 8

# 停止
python scripts/jf_open_pro_ptz_control.py zoom --zoom-command ZoomTile --action stop

5. 预置位管理 (Preset)

预置点编号范围：1-255（建议不使用 200 以后的编号）

特殊预置点：

• 100: 移动追踪守望位（追踪停止后自动回归）
• 128: 自检回归预置点（设备重启或自检时回归）

操作类型：

使用示例：

# 设置预置点 1，名称为"门口"
python scripts/jf_open_pro_ptz_control.py preset --preset-command set --id 1 --name "门口"

# 转到预置点 1
python scripts/jf_open_pro_ptz_control.py preset --preset-command goto --id 1

# 删除预置点 1
python scripts/jf_open_pro_ptz_control.py preset --preset-command clear --id 1

# 编辑预置点名称
python scripts/jf_open_pro_ptz_control.py preset --preset-command name --id 1 --name "新名称"

# 获取预置点列表
python scripts/jf_open_pro_ptz_control.py preset --preset-command list

6. 巡航计划管理 (Tour)

巡航功能让设备在多个预置点之间自动循环巡视。

操作类型：

使用示例：

# 添加预置点 1 到巡航线路 0
python scripts/jf_open_pro_ptz_control.py tour --tour-command add --tour-id 0 --preset-id 1 --step 5

# 添加预置点 2 到巡航线路 0
python scripts/jf_open_pro_ptz_control.py tour --tour-command add --tour-id 0 --preset-id 2

# 启动巡航线路 0
python scripts/jf_open_pro_ptz_control.py tour --tour-command start --tour-id 0

# 停止巡航
python scripts/jf_open_pro_ptz_control.py tour --tour-command stop --tour-id 0

# 获取巡航配置
python scripts/jf_open_pro_ptz_control.py tour --tour-command list

📖 使用场景示例

场景 1: 基础云台控制

# 1. 检查设备状态
python scripts/jf_open_pro_ptz_control.py status

# 2. 向上转动
python scripts/jf_open_pro_ptz_control.py ptz --direction up --action start
sleep 1
python scripts/jf_open_pro_ptz_control.py ptz --direction up --action stop

# 3. 向右转动
python scripts/jf_open_pro_ptz_control.py ptz --direction right --action start
sleep 1
python scripts/jf_open_pro_ptz_control.py ptz --direction right --action stop

场景 2: 设置并使用预置位

# 1. 转动到目标位置
python scripts/jf_open_pro_ptz_control.py ptz --direction up --action start
sleep 1
python scripts/jf_open_pro_ptz_control.py ptz --direction up --action stop

# 2. 保存为预置点 1
python scripts/jf_open_pro_ptz_control.py preset --preset-command set --id 1 --name "门口"

# 3. 转动到其他位置...

# 4. 回到预置点 1
python scripts/jf_open_pro_ptz_control.py preset --preset-command goto --id 1

场景 3: 设置自动巡航

# 1. 设置多个预置点
python scripts/jf_open_pro_ptz_control.py preset --preset-command set --id 1 --name "位置 1"
python scripts/jf_open_pro_ptz_control.py preset --preset-command set --id 2 --name "位置 2"
python scripts/jf_open_pro_ptz_control.py preset --preset-command set --id 3 --name "位置 3"

# 2. 添加到巡航线路
python scripts/jf_open_pro_ptz_control.py tour --tour-command add --tour-id 0 --preset-id 1
python scripts/jf_open_pro_ptz_control.py tour --tour-command add --tour-id 0 --preset-id 2
python scripts/jf_open_pro_ptz_control.py tour --tour-command add --tour-id 0 --preset-id 3

# 3. 启动巡航
python scripts/jf_open_pro_ptz_control.py tour --tour-command start --tour-id 0

⚠️ 错误处理

错误码 526 说明

含义： 设备支持云台，但电量过低无法执行

解决方案：

1. 给设备充电
2. 等待电量恢复至 20% 以上
3. 使用电源供电模式

⚠️ 注意事项

1. 设备需在线 - 操作前确保设备在线
2. 设备需登录 - 脚本会自动处理设备登录
3. PTZ 控制 - start/stop 指令需串行发送（间隔 500ms）
4. 预置点范围 - 建议使用 1-199 编号
5. 电量检查 - 低电量时云台功能可能被禁用

📚 官方参考资料

• 杰峰开放平台: https://open.jftech.com/
• API 文档: https://docs.jftech.com/
• API 端点: api.jftechws.com (国际) / api-cn.jftech.com (中国大陆)

📁 脚本工具

# 获取帮助
python scripts/jf_open_pro_ptz_control.py --help

# 查询设备状态
python scripts/jf_open_pro_ptz_control.py status

# PTZ 方向控制
python scripts/jf_open_pro_ptz_control.py ptz --direction <方向> --action <start|stop>

# 一键遮蔽
python scripts/jf_open_pro_ptz_control.py mask --enable <true|false>

# 变倍聚焦
python scripts/jf_open_pro_ptz_control.py zoom --zoom-command <命令> --action <start|stop>

# 预置点管理
python scripts/jf_open_pro_ptz_control.py preset --preset-command <set|clear|goto|name|list> [选项]

# 巡航管理
python scripts/jf_open_pro_ptz_control.py tour --tour-command <add|delete|start|stop|clear|list> [选项]

脚本路径：scripts/jf_open_pro_ptz_control.py

技能版本： v1.0.0
语言： Python
最后更新： 2026-04-07