萤石可编程设备 Python SDK 使用说明

2.5 告警与 OSD 管理

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

3. 典型使用示例

示例 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 并获取网络信息

import json

# 连接 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)

4. 注意事项

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 参数需严格遵循文档中的字段定义，确保键名和类型正确。

5. 开发建议

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

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

6. 函数说明

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,
  "end_time": 1638400000,
  "sd": 1
}

6. get_sd_status()

• 描述：获取 SD 卡状态。
• 入参：无。
• 返回：SD 卡状态字典或 -1（失败）：

{
  "used": 1,
  "total_mmc01": 102.41,
  "free_mmc01": 65.31,
  "total_mmc02": 256.00,
  "free_mmc02": 180.50,
  "diskStatus": 0
}

7. get_directory_info(path)

• 描述：获取指定路径下的文件和目录信息。
• 入参：
  • path (str) - 查询路径。
• 返回：文件/目录信息字典或 -1（失败）：

{
  "num_files": 4,
  "num_directories": 5,
  "files": ["all.pem", "config.txt"],
  "directories": ["voice", "certs"]
}

8. get_ptz_capa()

• 描述：获取云台能力。
• 入参：无。
• 返回：云台能力字典或 -1（失败）：

{
  "pan_angle_min": -340,
  "pan_angle_max": 340,
  "tilt_angle_min": -60,
  "tilt_angle_max": 60,
  "speed_min": 1,
  "speed_max": 3
}

9. ptz_rotate(cfg_str)

• 描述：云台转动。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

{
  "pan_angle": 10,
  "tilt_angle": 20,
  "speed": 1
}

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,
  "preset_index": [1]
}

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",
  "pic_name": "pano",
  "type": 0
}

18. ptz_set_cruise(cfg_str)

• 描述：新增/修改巡航路径。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

{
  "preset_num": 2,
  "preset_no": [1, 2]
}

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,
  "preset_no": [1, 3],
  "enable": 1
}

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",
    "mode": 0,
    "security": 4,
    "channel": 161,
    "signal_strength": 100,
    "rssi": -35
  }
]

24. connect_wifi_async(cfg_str)

• 描述：设置 WiFi 配置。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

{
  "ssid": "TP-LINK_35EB",
  "password": "12345678",
  "security": 4
}

25. disconnect_wifi()

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

26. get_network_param()

• 描述：获取当前连接网络信息。
• 入参：无。
• 返回：网络信息字典或 -1（失败）：

{
  "ip_addr": "XXX.XXX.3.1",
  "gateway": "XXX.XXX.3.1",
  "pri_dns": "XXX.XXX.3.1",
  "ssid": "EZVIZ-11-11"
}

27. set_network_parameters(cfg_str)

• 描述：设置网络参数。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

{
  "ip_addr": "XXX.XXX.3.1",
  "gateway": "XXX.XXX.3.1",
  "pri_dns": "XXX.XXX.3.1"
}

28. start_local_snapshot(cfg_str)

• 描述：摄像头抓图。
• 补充说明：
  • type=1 时可用 get_storage_id 查询云存储 ID。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

{
  "type": 0,
  "dest_addr": "/mnt/mmc02/.../xxx.jpg",
  "resolution": 0
}

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,
  "type": 0,
  "pack_type": 1,
  "dest_addr": "/mnt/mmc02/.../xxx.mp4"
}

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,
  "enable": 0,
  "url": "rtmp://xxx.xxx.xxx.xxx/live/xxx"
}

35. start_mic_record(cfg_str)

• 描述：开始录音。
• 补充说明：
  • type=1 时可用 get_storage_id 查询云存储 ID。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

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

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"
}

39. set_wdr(cfg_str)

• 描述：设置宽动态使能和等级。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

{
  "enable": 0,
  "level": 10
}

40. get_wdr()

• 描述：获取宽动态使能和等级。
• 入参：无。
• 返回：宽动态配置字典或 -1（失败）：

{
  "enable": 1,
  "level": 10
}

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",
  "enable": 1
}

43. get_alarm_status(cfg_str)

• 描述：告警状态查询。
• 返回：告警状态字典或空字典：

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

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

{
  "appid": "app_db_detect"
}

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,
  "mode": "CENTER",
  "enable": 1
}

46. get_osd_param()

• 描述：获取 OSD 配置参数。
• 入参：无。
• 返回：OSD 参数字典或空字典：

{
  "attribute": 4,
  "datetime_overlay": {
    "enabled": 1,
    "clock_type": 0,
    "positionx": 576,
    "positiony": 8732
  },
  "channame_overlay": {
    "enabled": 0,
    "positionx": 608,
    "positiony": 514,
    "name": "Camera_BF4904736"
  }
}

47. set_osd_param(cfg_str)

• 描述：设置 OSD 参数。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

{
  "attribute": 4,
  "bDateTimeOverlay": 1,
  "bchannelNameOverlay": 1,
  "datetime_overlay": {},
  "channame_overlay": {}
}

48. set_audio_volume(cfg_str)

• 描述：设置音频参数。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

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

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
}

51. get_image_style()

• 描述：获取画面风格模式。
• 入参：无。
• 返回：风格模式字典或 -1（失败）：

{
  "mode": 1
}

52. set_media_resolution(cfg_str)

• 描述：设置分辨率（仅主码流）。
• 返回：0（操作成功）；非 0（操作失败）。
• 入参：
  • cfg_str (str) - JSON 字符串：

{
  "resolution": 1
}

53. get_media_resolution()

• 描述：获取分辨率。
• 入参：无。
• 返回：分辨率字典或 -1（失败）：

{
  "resolution": 1
}

54. start_play_file_speaker(path)

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

55. stop_play_speaker()

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