萤石可编程设备 Python SDK 使用指南

5. 告警与 OSD 管理

• 告警配置
  • get_alarm_info()：查询已启用的告警类型（如人形检测、声音告警等）
  • set_alarm_status(cfg_str)：开启/关闭指定告警类型
  • get_alarm_events()：获取最近 200 条告警事件记录
• 画面设置
  • set_wdr(cfg_str)：设置宽动态范围（WDR）参数
  • set_mirror(cfg_str)：镜像翻转画面

三、典型使用示例

示例 1：格式化 SD 卡并查询状态

# 格式化 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")

示例 2：设置 WiFi 并获取网络信息

# 连接 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']}")

示例 3：云台巡航控制

# 设置巡航路径（预置点 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)

四、注意事项

1. 参数范围校验
   • 百分比参数（如 format_sd_card 的 percentage）需在 [0,90] 范围内。
   • 预置点索引需在 [1,12] 范围内。
2. 错误处理
   • 函数返回非 0 值表示操作失败，需检查输入参数或设备状态。
   • 状态查询函数（如 get_sd_status）返回 -1 表示查询失败。
3. 异步操作
   • 格式化 SD 卡、WiFi 连接等操作为异步，需确保设备完成操作后再执行后续步骤。
4. 云存储 ID 查询
   • 涉及云端存储的接口（如 save_video_by_time, ptz_panoramic, start_local_snapshot, start_media_record, start_mic_record）需通过 get_storage_id 或 get_and_clear_all_storages 获取云存储 ID。
5. JSON 参数格式
   • 所有 JSON 参数需严格遵循文档中的字段定义，确保键名和类型正确。

五、开发建议

1. 模块化设计：按功能模块（如存储、网络、云台）划分代码，便于维护。
2. 异常重试机制：对关键操作（如 SD 卡格式化、网络连接）增加重试逻辑。
3. 日志记录：记录关键 API 的输入、输出及错误信息，便于调试。

如需具体接口的详细用法，请参考对应函数的文档说明。

六、函数说明

1. format_sd_card(percentage)

• 描述：异步格式化 SD 卡。
• 入参：
  • percentage (int) - 格式化的百分比 [0,90]。
• 返回：0（任务已提交）；非 0（操作失败）。

2. create_directory(path)

• 描述：在 SD 卡中创建目录。
• 入参：
  • path (str) - 目录路径。
• 返回：0（创建成功）；非 0（创建失败）。

3. create_file(path)

• 描述：在 SD 卡中创建空文件。
• 入参：
  • path (str) - 文件路径。
• 返回：0（创建成功）；非 0（创建失败）。

4. delete_path(path)

• 描述：删除 SD 卡中指定目录或文件。
• 入参：
  • path (str) - 路径。
• 返回：0（删除成功）；非 0（删除失败）。

5. save_video_by_time(cfg_str)

• 描述：按时间段保存视频。
• 返回：0（成功）；非 0（失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "start_time": 1638400000, // long, 开始录像时间戳
  "end_time": 1638400000, // long, 结束录像时间戳
  "sd": 1 // int, 1=保存到 SD 卡，0=保存到云端
}

6. get_sd_status()

• 描述：获取 SD 卡状态。
• 入参：无。

返回：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=硬盘出错
}

7. get_directory_info(path)

• 描述：获取指定路径下的文件和目录信息。
• 入参：
  • path (str) - 查询路径。

返回：文件/目录信息字典或 -1（失败）：

{
  "num_files": 4, // int, 文件数量
  "num_directories": 5, // int, 目录数量
  "files": ["all.pem", "config.txt", ...], // list[str], 文件列表
  "directories": ["voice", "certs", ...] // list[str], 目录列表
}

8. get_ptz_capa()

• 描述：获取云台能力。
• 入参：无。

返回：云台能力字典或 -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, 最大速度
}

9. ptz_rotate(cfg_str)

• 描述：云台转动。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "pan_angle": 10, // int, 水平旋转角度
  "tilt_angle": 20, // int, 垂直旋转角度
  "speed": 1 // int, 转动速度
}

10. ptz_stop()

• 描述：停止云台转动。
• 入参：无。
• 返回：0（操作成功）；非 0（操作失败）。

11. position_correct()

• 描述：校准云台位置。
• 入参：无。
• 返回：0（校准成功）；非 0（校准失败）。

12. ptz_add_preset(preset_index)

• 描述：新增预置点。
• 入参：
  • preset_index (int) - 预置位索引 [1,12]。
• 返回：0（操作成功）；非 0（操作失败）。

13. ptz_del_preset(preset_index)

• 描述：删除指定预置点。
• 入参：
  • preset_index (int) - 预置位索引 [1,12]。
• 返回：0（删除成功）；非 0（操作失败）。

14. ptz_del_preset_all()

• 描述：清空所有预置点。
• 入参：无。
• 返回：0（清空成功）；非 0（操作失败）。

15. ptz_call_preset(preset_index)

• 描述：调用指定预置点。
• 入参：
  • preset_index (int) - 预置位索引 [1,12]。
• 返回：0（调用成功）；非 0（操作失败）。

16. ptz_get_preset()

• 描述：查询当前配置的预置点信息。
• 入参：无。

返回：预置点信息字典或 -1（失败）：

{
  "preset_num": 1, // int, 预置点数量
  "preset_index": [1] // list[int], 预置点索引列表
}

17. ptz_panoramic(cfg_str)

• 描述：设置全景图保存路径、命名规则及存储类型。
• 补充说明：
  • 生成 12 张图：pic_name1.jpg 到 pic_name12.jpg。
  • type=1 时可用 get_storage_id 查询云存储 ID。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "path": "/mnt/mmc02/.../pano", // str, 存储路径
  "pic_name": "pano", // str, 全景图命名前缀
  "type": 0 // int, 0=本地存储，1=云端存储
}

18. ptz_set_cruise(cfg_str)

• 描述：新增/修改巡航路径。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "preset_num": 2, // int, 预置点个数 (1-4)
  "preset_no": [1, 2] // list[int], 预置点编号
}

19. ptz_del_cruise()

• 描述：删除巡航路径。
• 入参：无。
• 返回：0（操作成功）；非 0（操作失败）。

20. ptz_cruise_enable(enable)

• 描述：开启/停止巡航。
• 入参：
  • enable (int) - 1=开启，0=停止。
• 返回：0（操作成功）；非 0（操作失败）。

21. ptz_get_cruise()

• 描述：查询巡航轨迹信息。
• 入参：无。

返回：巡航信息字典或 -1（失败）：

{
  "preset_num": 2, // int, 预置点数量
  "preset_no": [1, 3], // list[int], 预置点索引
  "enable": 1 // int, 巡航状态：1=开启，0=停止
}

22. set_privacy_enable(enable)

• 描述：开启/关闭隐私遮蔽。
• 入参：
  • enable (int) - 1=开启，0=关闭。
• 返回：0（操作成功）；非 0（操作失败）。

23. get_wifi_list(count)

• 描述：获取 WiFi 列表。
• 入参：
  • count (int) - 获取列表个数 (1-10)。

返回：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, 预留字段
  }
]

24. connect_wifi_async(cfg_str)

• 描述：设置 WiFi 配置。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "ssid": "TP-LINK_35EB", // str, WiFi 名称
  "password": "12345678", // str, 密码
  "security": 4 // int, 加密方式 (0-4)
}

25. disconnect_wifi()

• 描述：断开 WiFi 连接。
• 入参：无。
• 返回：0（操作成功）；非 0（操作失败）。

26. get_network_param()

• 描述：获取当前连接网络信息。
• 入参：无。

返回：网络信息字典或 -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 物理地址
}

27. set_network_parameters(cfg_str)

• 描述：设置网络参数。
• 返回：0（操作成功）；非 0（操作失败）。

入参： 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 地址
}

28. start_local_snapshot(cfg_str)

• 描述：摄像头抓图。
• 补充说明：
  • type=1 时可用 get_storage_id 查询云存储 ID。
• 返回：0（操作成功）；非 0（操作失败）。

入参： 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
}

29. led_control(enable)

• 描述：开启/关闭 LED 指示灯。
• 入参：
  • enable (int) - 1=开启，0=关闭。
• 返回：0（操作成功）；非 0（操作失败）。

30. white_led_control(enable)

• 描述：开启/关闭白光灯。
• 入参：
  • enable (int) - 1=开启，0=关闭。
• 返回：0（操作成功）；非 0（操作失败）。

31. infrared_control(enable)

• 描述：开启/关闭红外灯。
• 入参：
  • enable (int) - 1=开启，0=关闭。
• 返回：0（操作成功）；非 0（操作失败）。

32. start_media_record(cfg_str)

• 描述：开始视频存储。
• 补充说明：
  • type=1 时可用 get_storage_id 查询云存储 ID。
• 返回：0（操作成功）；非 0（操作失败）。

入参： 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, 目标存储地址
}

33. stop_media_record(cfg_str)

• 描述：异步停止媒体录制。
• 返回：0（停止请求已受理）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串（需与开始录制参数一致）：

{
  "stream_idx": 0,
  "type": 0,
  "pack_type": 1,
  "dest_addr": "/mnt/mmc02/.../xxx.mp4"
}

34. start_media_preview(cfg_str)

• 描述：媒体预览推流。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "stream_idx": 0, // int, 码流类型 (必须为 1)
  "enable": 0, // int, 使能：0=关闭，1=开启
  "url": "rtmp://xxx.xxx.xxx.xxx/live/xxx" // str, 推流地址
}

35. start_mic_record(cfg_str)

• 描述：开始录音。
• 补充说明：
  • type=1 时可用 get_storage_id 查询云存储 ID。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "type": 0, // int, 存储类型：0=本地，1=云存
  "dest_addr": "/mnt/mmc02/.../XXXX.aac" // str, 存储地址
}

36. stop_mic_record(cfg_str)

• 描述：异步停止录音。
• 返回：0（停止请求已受理）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "type": 0,
  "dest_addr": "/mnt/mmc02/.../XXXX.aac"
}

37. get_storage_id(dest_addr)

• 描述：根据存储地址查询云存储 ID。
• 入参：
  • dest_addr (str) - 文件存储地址。
• 返回：
  • storage_id (str) - 文件存储 ID（查询不到时返回空字符串）。
• 数据来源：
  • save_video_by_time, ptz_panoramic, start_local_snapshot, start_media_record, start_mic_record。

38. get_and_clear_all_storages()

• 描述：查询所有云存储 ID。
• 入参：无。
• 数据来源：同 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"
}

39. set_wdr(cfg_str)

• 描述：设置宽动态使能和等级。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "enable": 0, // int, 使能：0=关闭，1=开启，2=自动
  "level": 10 // int, 宽动态等级 (0-100)
}

40. get_wdr()

• 描述：获取宽动态使能和等级。
• 入参：无。

返回：宽动态配置字典或 -1（失败）：

{
  "enable": 1, // int, 使能状态
  "level": 10 // int, 宽动态等级
}

41. get_alarm_info()

• 描述：获取告警状态列表。
• 入参：无。
• 告警标识说明：
  • 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 }
]

42. set_alarm_status(cfg_str)

• 描述：告警状态设置。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "appid": "app_db_detect", // str, 告警标识
  "enable": 1 // int, 开关状态：1=开启
}

43. get_alarm_status(cfg_str)

• 描述：告警状态查询。

返回：告警状态字典或空字典：

{
  "appid": "app_db_detect",
  "enable": 1
}

入参： cfg_str (str) - JSON 字符串：

{
  "appid": "app_db_detect" // str, 告警标识
}

44. get_alarm_events()

• 描述：获取告警事件（最多 200 条）。
• 入参：无。

返回：告警事件列表或空列表：

[
  { "app_id": "app_db_detect", "alarm_time": 1754632006 },
  { "app_id": "app_human_detect", "alarm_time": 1754632010 }
]

45. set_mirror(cfg_str)

• 描述：镜像翻转画面。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "channel": 1, // int, 通道 (主码流)
  "mode": "CENTER", // str, 翻转模式 (仅支持 CENTER)
  "enable": 1 // int, 开关：1=开启
}

46. get_osd_param()

• 描述：获取 OSD 配置参数。
• 入参：无。

返回：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, 通道名称
  }
}

47. set_osd_param(cfg_str)

• 描述：设置 OSD 参数。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "attribute": 4,
  "bDateTimeOverlay": 1, // int, 时间 OSD 开关 (仅设置用)
  "bchannelNameOverlay": 1, // int, 通道名称 OSD 开关 (仅设置用)
  "datetime_overlay": { ... }, // 同 get_osd_param
  "channame_overlay": { ... } // 同 get_osd_param
}

48. set_audio_volume(cfg_str)

• 描述：设置音频参数。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "mic_volume": 10, // int, 麦克风音量 (0-100)
  "speaker_volume": 50 // int, 扬声器音量 (0-100)
}

49. get_audio_volume()

• 描述：获取音频参数。
• 入参：无。

返回：音频配置字典或 -1（失败）：

{
  "mic_volume": 10,
  "speaker_volume": 50
}

50. set_image_style(cfg_str)

• 描述：设置画面风格模式。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "mode": 1 // int, 模式：1=标准，2=写实，3=艳丽，4=明亮
}

51. get_image_style()

• 描述：获取画面风格模式。
• 入参：无。

返回：风格模式字典或 -1（失败）：

{
  "mode": 1
}

52. set_media_resolution(cfg_str)

• 描述：设置分辨率（仅主码流）。
• 返回：0（操作成功）；非 0（操作失败）。

入参： cfg_str (str) - JSON 字符串：

{
  "resolution": 1 // int, 分辨率：0=1080P, 1=2304*1296, 2=2592*1944, 3=4064*3040
}

53. get_media_resolution()

• 描述：获取分辨率。
• 入参：无。

返回：分辨率字典或 -1（失败）：

{
  "resolution": 1
}

54. start_play_file_speaker(path)

• 描述：播放音频文件（仅支持 AAC 格式）。
• 入参：
  • path (str) - 音频文件绝对路径。
• 返回：0（操作成功）；非 0（操作失败）。

55. stop_play_speaker()

• 描述：停止语音或文件播报。
• 入参：无。
• 返回：0（操作成功）；非 0（操作失败）。