PythonAI
萤石可编程设备 Python SDK 使用指南
萤石可编程设备的 Python SDK 功能，包括 SD 卡管理、云台控制、网络配置、媒体录制及告警设置等核心模块。文中提供了格式化 SD 卡、连接 WiFi、云台巡航等典型代码示例，并列举了各接口的入参、返回值及注意事项，旨在帮助开发者快速完成设备集成与功能开发。
萤石可编程设备的 Python SDK 功能，包括 SD 卡管理、云台控制、网络配置、媒体录制及告警设置等核心模块。文中提供了格式化 SD 卡、连接 WiFi、云台巡航等典型代码示例，并列举了各接口的入参、返回值及注意事项，旨在帮助开发者快速完成设备集成与功能开发。
本 SDK 提供摄像头设备的完整控制能力，涵盖 SD 卡管理、云台控制、网络配置、媒体录制、告警管理等核心功能。支持异步操作、参数配置及状态查询，适用于可编程摄像头设备的开发与维护。
format_sd_card(percentage)：异步格式化 SD 卡（百分比范围 [0,90]）get_sd_status()：获取 SD 卡状态（返回分区容量、使用率等信息）create_directory(path) / create_file(path)：创建目录/文件delete_path(path)：删除路径（支持文件或目录）get_directory_info(path)：查询目录下的文件/目录列表ptz_rotate(cfg_str)：设置云台水平/垂直角度及速度ptz_stop()：立即停止云台转动position_correct()：校准云台初始位置ptz_add_preset(preset_index) / ptz_del_preset(preset_index)：添加/删除预置点ptz_call_preset(preset_index)：调用指定预置点ptz_del_preset_all()：清空所有预置点ptz_set_cruise(cfg_str)：设置巡航路径（支持 1-4 个预置点）ptz_cruise_enable(enable)：开启/关闭巡航模式get_wifi_list(count)：获取可用 WiFi 列表（最多 10 个）connect_wifi_async(cfg_str)：异步连接指定 WiFi（需密码及加密方式）disconnect_wifi()：断开当前 WiFi 连接get_network_param()：查询当前 IP、网关等网络信息set_network_parameters(cfg_str)：手动设置 IP、DNS 等参数save_video_by_time(cfg_str)：按时间范围保存视频到 SD 或云端start_media_record(cfg_str) / stop_media_record(cfg_str)：开始/停止视频录制start_local_snapshot(cfg_str)：摄像头抓图（支持本地或云端存储）start_mic_record(cfg_str) / stop_mic_record(cfg_str)：开始/停止录音get_alarm_info()：查询已启用的告警类型（如人形检测、声音告警等）set_alarm_status(cfg_str)：开启/关闭指定告警类型get_alarm_events()：获取最近 200 条告警事件记录set_wdr(cfg_str)：设置宽动态范围（WDR）参数set_mirror(cfg_str)：镜像翻转画面# 格式化 SD 卡（保留 10% 空间）
result = format_sd_card(percentage=90)
if result == 0:
print("格式化任务已提交")
else:
print("格式化失败")
# 查询 SD 卡状态
sd_status = get_sd_status()
if sd_status != -1:
print(f"已用空间：{sd_status['used']}%, mmc01 剩余空间：{sd_status['free_mmc01']}GB")
# 连接 WiFi（假设密码为"12345678"，加密方式为 WPA2）
wifi_config = {
"ssid": "TP-LINK_35EB",
"password": "12345678",
"security": 4 # WPA2-PSK
}
result = connect_wifi_async(cfg_str=json.dumps(wifi_config))
if result == 0:
print("WiFi 连接请求已提交")
# 获取当前网络参数
network_info = get_network_param()
if network_info != -1:
print(f"IP 地址：{network_info['ip_addr']}, 信号强度：{network_info['signal_strength']}")
# 设置巡航路径（预置点 1 和 3）
cruise_config = {
"preset_num": 2,
"preset_no": [1, 3]
}
result = ptz_set_cruise(cfg_str=json.dumps(cruise_config))
if result == 0:
# 开启巡航模式
ptz_cruise_enable(enable=1)
format_sd_card 的 percentage）需在 [0,90] 范围内。get_sd_status）返回 -1 表示查询失败。save_video_by_time, ptz_panoramic, start_local_snapshot, start_media_record, start_mic_record）需通过 get_storage_id 或 get_and_clear_all_storages 获取云存储 ID。如需具体接口的详细用法，请参考对应函数的文档说明。
入参：
cfg_str (str) - JSON 字符串：
{
"start_time": 1638400000, // long, 开始录像时间戳
"end_time": 1638400000, // long, 结束录像时间戳
"sd": 1 // int, 1=保存到 SD 卡，0=保存到云端
}
返回：SD 卡状态字典或 -1（失败）：
{
"used": 1, // int, 已用空间百分比
"total_mmc01": 102.41, // double, mmc01 分区总容量 (GB)
"free_mmc01": 65.31, // double, mmc01 分区剩余容量 (GB)
"total_mmc02": 256.00, // double, mmc02 分区总容量 (GB)
"free_mmc02": 180.50, // double, mmc02 分区剩余容量 (GB)
"total_mmc03": 0.00, // double, mmc03 分区总容量 (GB)
"free_mmc03": 0.00, // double, mmc03 分区剩余容量 (GB)
"total_mmc04": 0.00, // double, mmc04 分区总容量 (GB)
"free_mmc04": 0.00, // double, mmc04 分区剩余容量 (GB)
"diskStatus": 0 // int, 磁盘状态：0=活动，1=休眠，2=不正常，3=硬盘出错
}
path (str) - 查询路径。返回：文件/目录信息字典或 -1（失败）：
{
"num_files": 4, // int, 文件数量
"num_directories": 5, // int, 目录数量
"files": ["all.pem", "config.txt", ...], // list[str], 文件列表
"directories": ["voice", "certs", ...] // list[str], 目录列表
}
返回：云台能力字典或 -1（失败）：
{
"pan_angle_min": -340, // int, 水平转动最小角度
"pan_angle_max": 340, // int, 水平转动最大角度
"tilt_angle_min": -60, // int, 垂直转动最小角度
"tilt_angle_max": 60, // int, 垂直转动最大角度
"speed_min": 1, // int, 最小速度
"speed_max": 3 // int, 最大速度
}
入参：
cfg_str (str) - JSON 字符串：
{
"pan_angle": 10, // int, 水平旋转角度
"tilt_angle": 20, // int, 垂直旋转角度
"speed": 1 // int, 转动速度
}
返回：预置点信息字典或 -1（失败）：
{
"preset_num": 1, // int, 预置点数量
"preset_index": [1] // list[int], 预置点索引列表
}
get_storage_id 查询云存储 ID。入参：
cfg_str (str) - JSON 字符串：
{
"path": "/mnt/mmc02/.../pano", // str, 存储路径
"pic_name": "pano", // str, 全景图命名前缀
"type": 0 // int, 0=本地存储，1=云端存储
}
入参：
cfg_str (str) - JSON 字符串：
{
"preset_num": 2, // int, 预置点个数 (1-4)
"preset_no": [1, 2] // list[int], 预置点编号
}
返回：巡航信息字典或 -1（失败）：
{
"preset_num": 2, // int, 预置点数量
"preset_no": [1, 3], // list[int], 预置点索引
"enable": 1 // int, 巡航状态：1=开启，0=停止
}
返回：WiFi 信息列表或 -1（失败）：
[
{
"ssid": "TP-LINK_35EB", // str, WiFi 名称
"mode": 0, // int, 模式
"security": 4, // int, 加密方式：0=不加密，1=wep,2=wpa-psk,3=wpa-Enterprise,4=wpa2-psk
"channel": 161, // int, 信道
"signal_strength": 100, // int, 信号强度
"speed": 150, // int, WiFi 速率 (Mbps)
"ap_address": "04:f9:f8:f1:35:ed", // str, AP 物理地址
"rssi": -35, // int, 真实信号强度 (0~-100, 0 最强)
"res": 0 // int, 预留字段
}
]
入参：
cfg_str (str) - JSON 字符串：
{
"ssid": "TP-LINK_35EB", // str, WiFi 名称
"password": "12345678", // str, 密码
"security": 4 // int, 加密方式 (0-4)
}
返回：网络信息字典或 -1（失败）：
{
"ip_addr": "XXX.XXX.3.1", // str, IP 地址
"gateway": "XXX.XXX.3.1", // str, 网关地址
"pri_dns": "XXX.XXX.3.1", // str, 主 DNS 地址
"sec_dns": "", // str, 备用 DNS 地址
"ssid": "EZVIZ-11-11", // str, WiFi 名称
"mode": 0, // int, 模式
"security": 4, // int, 加密方式 (0-4)
"channel": 161, // int, 信道
"signal_strength": 100, // int, 信号强度
"speed": 150, // int, WiFi 速率 (Mbps)
"ap_address": "04:f9:f8:f1:35:ed" // str, AP 物理地址
}
入参：
cfg_str (str) - JSON 字符串：
{
"ip_addr": "XXX.XXX.3.1", // str, IP 地址
"gateway": "XXX.XXX.3.1", // str, 网关地址
"pri_dns": "XXX.XXX.3.1", // str, 主 DNS 地址
"sec_dns": "XXX.XXX.3.1" // str, 备用 DNS 地址
}
get_storage_id 查询云存储 ID。入参：
cfg_str (str) - JSON 字符串：
{
"type": 0, // int, 存储类型：0=本地，1=云端
"dest_addr": "/mnt/mmc02/.../xxx.jpg", // str, 存储路径
"resolution": 0 // int, 分辨率类型：0=720p, 1=1080p, 2=2K
}
get_storage_id 查询云存储 ID。入参：
cfg_str (str) - JSON 字符串：
{
"stream_idx": 0, // int, 码流索引：0=主码流，1=子码流
"type": 0, // int, 存储类型：0=本地，1=云端
"pack_type": 1, // int, 封装类型：0=ps 流，1=mp4
"dest_addr": "/mnt/mmc02/.../xxx.mp4" // str, 目标存储地址
}
入参：
cfg_str (str) - JSON 字符串（需与开始录制参数一致）：
{
"stream_idx": 0,
"type": 0,
"pack_type": 1,
"dest_addr": "/mnt/mmc02/.../xxx.mp4"
}
入参：
cfg_str (str) - JSON 字符串：
{
"stream_idx": 0, // int, 码流类型 (必须为 1)
"enable": 0, // int, 使能：0=关闭，1=开启
"url": "rtmp://xxx.xxx.xxx.xxx/live/xxx" // str, 推流地址
}
get_storage_id 查询云存储 ID。入参：
cfg_str (str) - JSON 字符串：
{
"type": 0, // int, 存储类型：0=本地，1=云存
"dest_addr": "/mnt/mmc02/.../XXXX.aac" // str, 存储地址
}
入参：
cfg_str (str) - JSON 字符串：
{
"type": 0,
"dest_addr": "/mnt/mmc02/.../XXXX.aac"
}
save_video_by_time, ptz_panoramic, start_local_snapshot, start_media_record, start_mic_record。get_storage_id。返回：云存储 ID 字典或空字典：
{
"/XXX/XXX1.jpg": "E1$0$11$0$PY4O4B~$N1$BF4904736-1$00$0a81",
"/XXX/XXX2.jpg": "E1$0$12$0$PY4O4B~$N1$BF4904736-1$00$0a86"
}
入参：
cfg_str (str) - JSON 字符串：
{
"enable": 0, // int, 使能：0=关闭，1=开启，2=自动
"level": 10 // int, 宽动态等级 (0-100)
}
返回：宽动态配置字典或 -1（失败）：
{
"enable": 1, // int, 使能状态
"level": 10 // int, 宽动态等级
}
app_video_change（画面变化）, app_human_detect（人形告警）, app_db_detect（大噪声检测）, app_babycry_detect（哭声检测）, app_fix_gesture_recognize（手势识别）。返回：告警状态列表或空列表：
[
{ "appid": "app_human_detect", "enable": 1 },
{ "appid": "app_db_detect", "enable": 1 }
]
入参：
cfg_str (str) - JSON 字符串：
{
"appid": "app_db_detect", // str, 告警标识
"enable": 1 // int, 开关状态：1=开启
}
返回：告警状态字典或空字典：
{
"appid": "app_db_detect",
"enable": 1
}
入参：
cfg_str (str) - JSON 字符串：
{
"appid": "app_db_detect" // str, 告警标识
}
返回：告警事件列表或空列表：
[
{ "app_id": "app_db_detect", "alarm_time": 1754632006 },
{ "app_id": "app_human_detect", "alarm_time": 1754632010 }
]
入参：
cfg_str (str) - JSON 字符串：
{
"channel": 1, // int, 通道 (主码流)
"mode": "CENTER", // str, 翻转模式 (仅支持 CENTER)
"enable": 1 // int, 开关：1=开启
}
返回：OSD 参数字典或空字典：
{
"attribute": 4, // int, OSD 属性：1=透明闪烁，2=透明不闪烁，3=不透明闪烁，4=不透明不闪烁
"datetime_overlay": {
"enabled": 1, // int, 开关
"clock_type": 0, // int, 时间类型：0=24 小时制
"positionx": 576, // int, 日期横坐标
"positiony": 8732, // int, 日期纵坐标
"type": 0, // int, OSD 格式类型 (0-5)
"display_week": 0 // int, 是否显示星期：0=不显示
},
"channame_overlay": {
"enabled": 0, // int, 开关
"positionx": 608, // int, 通道名横坐标
"positiony": 514, // int, 通道名纵坐标
"name": "Camera_BF4904736" // str, 通道名称
}
}
入参：
cfg_str (str) - JSON 字符串：
{
"attribute": 4,
"bDateTimeOverlay": 1, // int, 时间 OSD 开关 (仅设置用)
"bchannelNameOverlay": 1, // int, 通道名称 OSD 开关 (仅设置用)
"datetime_overlay": { ... }, // 同 get_osd_param
"channame_overlay": { ... } // 同 get_osd_param
}
入参：
cfg_str (str) - JSON 字符串：
{
"mic_volume": 10, // int, 麦克风音量 (0-100)
"speaker_volume": 50 // int, 扬声器音量 (0-100)
}
返回：音频配置字典或 -1（失败）：
{
"mic_volume": 10,
"speaker_volume": 50
}
入参：
cfg_str (str) - JSON 字符串：
{
"mode": 1 // int, 模式：1=标准，2=写实，3=艳丽，4=明亮
}
返回：风格模式字典或 -1（失败）：
{
"mode": 1
}
入参：
cfg_str (str) - JSON 字符串：
{
"resolution": 1 // int, 分辨率：0=1080P, 1=2304*1296, 2=2592*1944, 3=4064*3040
}
返回：分辨率字典或 -1（失败）：
{
"resolution": 1
}
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online