大华云开放平台 - 基础通用套件

概述

本技能提供大华云开放平台基础通用套件的统一客户端实现，采用单文件设计：

• ✅ 统一客户端 - 封装所有设备管理API
• ✅ 零冗余配置 - 仅需 Cloud 凭证（ProductId、AK、SK）即可
• ✅ 单文件实现 - 易于维护和部署
• ✅ 环境变量支持 - 支持GUI/命令行配置
• ✅ 命令行工具 - 快速操作无需编写代码
• ✅ Python SDK - 可集成到其他应用
• ✅ 自动Token管理 - Token自动刷新，无需手动处理

完整功能

共 43 个接口 全部支持，详见 API_COVERAGE.md。

1. 设备管理

• 添加设备 add_device() / add
• 校验设备密码 verify_device_password() / verify
• 删除设备 delete_device() / delete
• 查询设备列表 get_device_list() / list
• 查询设备在线状态 get_device_online() / online
• 批量查询设备详细信息 list_device_details() / details
• 查询设备绑定状态 check_device_bind() / bind
• 查询设备品类 get_category() / category
• 获取设备通道信息 get_device_channel_info() / channels
• 修改设备/通道名称 modify_device_name()
• 修改设备密码 modify_dev_code()

2. 国标设备

• 获取国标设备注册信息 get_sip_info() / sip-info
• 获取国标码列表 list_gb_code() / gb-code
• 添加国标设备 add_gb_device() / add-gb
• 修改国标设备信息 modify_gb_device() / modify-gb
• 国标设备查询详细信息 list_gb_device_details() / gb-details

3. SD卡管理

• 查询SD卡状态 get_sd_card_status()
• 查询SD卡容量 get_sd_card_storage()
• 获取SD卡列表 list_sd_card_storage()
• 格式化SD卡 format_sd_card()

4. 设备配置

• 获取设备使能开关状态 get_ability_status() / ability
• 设置设备使能开关 set_ability_status()
• 设备校时 set_current_utc()

5. 铃音管理

• 获取铃声列表 list_custom_ring()
• 新增自定义铃声 add_custom_ring()
• 删除自定义铃声 delete_custom_ring()
• 设置铃声 set_custom_ring()

6. WiFi 管理

• 获取设备当前连接的热点信息 current_device_wifi()
• 获取设备周边热点信息 wifi_around()
• 修改设备连接热点 control_device_wifi()

7. 其他设备能力

• 获取 SIM 信号强度 get_sim_signal_strength()
• 图片解密 image_decrypt()

8. 消息订阅

• 添加回调配置 add_callback_config()
• 按设备ID列表订阅消息 message_subscribe()
• 分页获取回调配置 get_all_callback_config()
• 根据回调配置ID更新设备订阅 update_subscribe_by_callback_config()
• 根据回调配置ID更新回调配置 update_callback_config()
• 删除回调配置及相关订阅 delete_callback_config()
• 根据回调配置ID搜索回调配置信息 get_callback_config_info()
• 根据回调配置ID搜索已订阅的设备消息 get_subscribe_info_by_callback_config()
• 根据设备ID查询消息订阅信息 get_subscribe_info_by_device()
• 按设备类别获取支持的消息类型 get_message_type_page()

配置凭证

需要设置 Cloud 凭证（ProductId、AK、SK）！

方式 1: 图形界面设置 (Windows GUI)

最适合初学者和不想用命令行的用户！

步骤 1: 打开系统设置

1. 按下 Win + R 键，输入 sysdm.cpl 并回车
2. 或者右键点击"此电脑" → "属性" → "高级系统设置"

步骤 2: 进入环境变量设置

1. 在弹出的"系统属性"窗口中，切换到 "高级" 选项卡
2. 点击底部的 "环境变量(N)..." 按钮

步骤 3: 创建用户环境变量

在 "当前用户的变量(U)" 区域（窗口上半部分），点击 "新建(W)..."：

示例:

变量名：DAHUA_CLOUD_PRODUCT_ID
变量值：138XXXX731

变量名：DAHUA_CLOUD_AK  
变量值：196XXXXXXXXXXXXX808

变量名：DAHUA_CLOUD_SK
变量值：naumXXXXXXXXXXXXXXXXyHxh

步骤 4: 确认并保存

1. 每个变量都点击 "确定" 保存
2. 关闭所有窗口
3. 重要: 重新打开命令行窗口才能生效

快速截图指引

如需更详细的图文教程，请参考以下操作要点：

• 确保在"用户变量"区域添加，而非"系统变量"
• 变量名必须完全一致（区分大小写）
• 变量值不要有多余空格
• 添加完成后需要重启终端

方式 2: 命令行快速设置

Windows PowerShell:

[Environment]::SetEnvironmentVariable("DAHUA_CLOUD_PRODUCT_ID", "your_app_id", "User")
[Environment]::SetEnvironmentVariable("DAHUA_CLOUD_AK", "your_access_key", "User")
[Environment]::SetEnvironmentVariable("DAHUA_CLOUD_SK", "your_secret_key", "User")

Linux/Mac:

export DAHUA_CLOUD_PRODUCT_ID='your_app_id'
export DAHUA_CLOUD_AK='your_access_key'
export DAHUA_CLOUD_SK='your_secret_key'

方式 3: 命令行临时设置

Windows PowerShell (临时):

$env:DAHUA_CLOUD_PRODUCT_ID='your_app_id'
$env:DAHUA_CLOUD_AK='your_access_key'
$env:DAHUA_CLOUD_SK='your_secret_key'

注意: 仅在当前窗口有效，关闭后失效

验证环境变量是否生效

Linux/Mac:

echo $DAHUA_CLOUD_PRODUCT_ID
echo $DAHUA_CLOUD_AK
# 注意：不要打印 SK，避免泄露

Windows PowerShell:

$env:DAHUA_CLOUD_PRODUCT_ID
$env:DAHUA_CLOUD_AK

快速开始

基本使用

# 查看帮助
python scripts/dahua_iot_client.py --help

# 添加设备
python scripts/dahua_iot_client.py add -d <设备序列号> -p admin123 -c IPC

# 查询设备列表
python scripts/dahua_iot_client.py list -p 1 -s 10

# 查询设备在线状态
python scripts/dahua_iot_client.py online -d <设备序列号>

# 校验设备密码（验证密码是否正确）
python scripts/dahua_iot_client.py verify -d <设备序列号> -p admin123 -e aes256

# 删除设备
python scripts/dahua_iot_client.py delete -d <设备序列号>

完整示例

# 完整设备接入流程（仅需 Cloud 凭证）
cd scripts
python dahua_iot_client.py add -d <设备序列号> -p admin123 -c IPC -e aes256
python dahua_iot_client.py online -d <设备序列号>
python dahua_iot_client.py list -p 1 -s 20 -d <设备序列号前缀>

Python SDK 调用

导入说明：在 scripts/ 目录下运行，或将 scripts/ 加入 PYTHONPATH 后使用。

from dahua_iot_client import DahuaIoTClient, create_client_from_env

# 方式1: 从环境变量创建客户端（verbose=True 打印API日志）
client = create_client_from_env()

# SDK 集成时建议关闭日志：create_client_from_env(verbose=False)

# 方式2: 手动创建客户端
client = DahuaIoTClient(
    app_id='your_product_id',
    access_key='your_access_key',
    secret_key='your_secret_key'
)

# 添加设备
result = client.add_device(
    device_id='<设备序列号>',
    device_password='admin123',
    category_code='IPC',
    encrypt_method='aes256'  # 推荐
)

print(f"Add device result: {result}")

# 校验设备密码（验证密码是否正确）
verify_result = client.verify_device_password('<设备序列号>', 'admin123', encrypt_method='aes256')
print(f"Password verify: {verify_result.get('success', False)}")

# 查询设备在线状态
status = client.get_device_online('<设备序列号>')
print(f"Online status: {status}")

# 查询设备列表
devices = client.get_device_list(page_num=1, page_size=10)
print(f"Device list: {devices}")

# 获取SD卡状态
sd_status = client.get_sd_card_status('<设备序列号>')
print(f"SD card status: {sd_status}")

# 设置设备使能开关
result = client.set_ability_status(
    device_id='<设备序列号>',
    ability_type='localRecord',
    status='on',
    channel_id='0'
)

工作流程

┌─────────────────────┐
│ 1. 初始化客户端      │
│   (配置凭证)         │
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│ 2. 自动获取 Token    │
│   (AppAccessToken)   │
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│ 3. 调用业务API       │
│   (设备管理/配置)    │
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│ 4. 返回结果          │
│   (JSON格式)         │
└─────────────────────┘

API 端点

完整 API 参考见 references/api_reference.md。

认证机制

签名算法

SHA512 HMAC 签名 - 两种签名方式：

1. get_token_sign() - 获取 Token 签名

   签名因子: access_key + timestamp + nonce
   

2. business_api_sign() - 业务 API 签名

   签名因子: access_key + app_access_token + timestamp + nonce
   

请求头结构

认证请求头 (获取 Token):

{
    "Content-Type": "application/json",
    "AccessKey": access_key,
    "Timestamp": timestamp,
    "Nonce": nonce,
    "X-TraceId-Header": trace_id,
    "Sign": signature,           # get_token_sign() 生成
    "ProductId": app_id,
    "Version": "V1",
    "Sign-Type": "simple"
}

业务请求头 (所有设备管理API):

{
    "Content-Type": "application/json",
    "AccessKey": access_key,
    "Timestamp": timestamp,
    "Nonce": nonce,
    "X-TraceId-Header": trace_id,
    "Sign": signature,           # business_api_sign() 生成
    "Version": "V1",
    "Sign-Type": "simple",
    "AppAccessToken": app_token,
    "ProductId": app_id
}

代码架构

┌──────────────────────────────────────────────────────────────────┐
│                    常量配置层 (Constants)                         │
│  - API 端点、超时时间、环境变量名                               │
└──────────────────────────────────────────────────────────────────┘
                              │
┌──────────────────────────────────────────────────────────────────┐
│                    工具函数层 (Utilities)                         │
│  - get_token_sign()          获取 Token 签名                  │
│  - business_api_sign()       业务 API 签名                    │
│  - DeviceCodeEncryptor       设备密码加密（Base64/AES256）        │
└──────────────────────────────────────────────────────────────────┘
                              │
┌──────────────────────────────────────────────────────────────────┐
│                     DahuaIoTClient 类 (43个接口)                   │
│  设备: add/verify/delete/list/details/online/bind/category/channel │
│  国标: get_sip_info/add_gb/list_gb_code/modify_gb/gb_details      │
│  SD卡: get_status/storage/list/format  铃音: list/add/delete/set  │
│  配置: get/set_ability_status/set_current_utc                     │
│  WiFi: wifi_around/current/control  SIM: get_sim_signal_strength  │
│  消息: callback/message_subscribe/update/delete/query             │
│  其他: image_decrypt 图片解密                                      │
└──────────────────────────────────────────────────────────────────┘
                              │
┌──────────────────────────────────────────────────────────────────┐
│                    辅助函数层                                     │
│  - create_client_from_env()  从环境变量创建客户端                 │
└──────────────────────────────────────────────────────────────────┘

设备密码加密

方式一：Base64加密

格式："Dolynk_" + Base64(设备密码)
例如：若设备密码为 admin123
Base64(admin123) = YWRtaW4xMjM=
加密后字符串 = Dolynk_YWRtaW4xMjM=

方式二：AES256加密（推荐）

格式：Base64(Aes256(待加密内容, AesKey, IV初始向量))
加密算法：Aes256/CBC/PKCS7
初始化向量IV：86E2DB6D77B5E9CD
AesKey：Cut32(UpperCase(MD5-32位(UpperCase(sk))))

示例代码:

from dahua_iot_client import DeviceCodeEncryptor

encryptor = DeviceCodeEncryptor(
    secret_access_key="your_sk",
    device_id="your_device_id"
)

# AES256加密（推荐）
dev_code = encryptor.encrypt_aes256("admin123")

# Base64加密
dev_code = encryptor.encrypt_base64("admin123")

核心类和函数

DahuaIoTClient 类

统一客户端类，封装所有设备管理API。

初始化参数

主要方法（43 个接口）

DeviceCodeEncryptor 类

设备密码加密工具类。

方法

命令行参数

通用参数

命令行子命令汇总

子命令详情

add - 添加设备

delete - 删除设备

list - 查询设备列表

online - 查询设备在线状态

verify - 校验设备密码

验证指定设备的密码是否正确（调用 verifyDevCode 接口）。

# 校验设备密码
python scripts/dahua_iot_client.py verify -d <设备序列号> -p admin123 -e aes256

details - 查询设备详细信息

python scripts/dahua_iot_client.py details <设备序列号> <设备序列号2>

category - 查询设备品类

bind - 查询设备绑定状态

channels - 获取设备通道信息

ability - 获取设备使能状态

add-gb - 添加国标设备

gb-code - 获取国标码列表

sip-info - 获取国标设备注册信息

无需参数，返回 Sip 服务器 IP 和端口。

gb-details - 查询国标设备详细信息

modify-gb - 修改国标设备信息

encrypt - 加密设备密码

响应格式

所有 API 响应遵循统一格式：

{
    "code": "200",           # 响应状态码
    "success": true,         # 响应状态
    "data": {},             # 响应数据
    "msg": "操作成功"         # 响应消息
}

add_device 响应示例

{
    "success": True,
    "code": "200",
    "msg": "操作成功",
    "data": {
        "deviceId": "<设备序列号>",
        "deviceName": "",
        "channelNum": 1,
        "status": 1
    }
}

get_device_online 响应示例

{
    "success": True,
    "code": "200",
    "msg": "操作成功",
    "data": {
        "deviceId": "<设备序列号>",
        "online": True
    }
}

错误码说明:

• 200: 成功
• 其他: 失败，查看 msg 字段了解错误原因

可配置常量

依赖要求

• Python 3.8+
• requests>=2.31.0
• pycryptodome>=3.15.0

安装依赖:

pip install requests pycryptodome

使用场景

1️ 设备接入场景

# 添加设备
python scripts/dahua_iot_client.py add -d <设备序列号> -p admin123 -c IPC

# 校验设备密码（验证密码是否正确）
python scripts/dahua_iot_client.py verify -d <设备序列号> -p admin123 -e aes256

# 查询设备在线状态
python scripts/dahua_iot_client.py online -d <设备序列号>

# 查询设备列表/详细信息
python scripts/dahua_iot_client.py list -d <设备序列号前缀>
python scripts/dahua_iot_client.py details <设备序列号>

2️ 设备管理场景

# Python SDK
client = create_client_from_env()

# 获取设备列表
devices = client.get_device_list(page_num=1, page_size=100)

# 批量查询设备详情
device_ids = ['<设备序列号1>', '<设备序列号2>']
details = client.list_device_details(device_ids)

# 删除设备
client.delete_device('<设备序列号>')

3️ SD卡管理场景

# 查询SD卡状态
status = client.get_sd_card_status('<设备序列号>')

# 查询SD卡容量
storage = client.get_sd_card_storage('<设备序列号>')

# 格式化SD卡
result = client.format_sd_card('<设备序列号>')

4️ 设备配置场景

# 修改设备名称
client.modify_device_name('<设备序列号>', 'My Camera')

# 启用本地录像
client.set_ability_status(
    device_id='<设备序列号>',
    ability_type='localRecord',
    status='on',
    channel_id='0'
)

5️ 消息订阅场景

# 添加回调配置（返回的 data 为回调配置ID）
callback = client.add_callback_config(
    callback_url='https://your-server.com/callback',
    is_push=True
)
callback_config_id = callback['data']  # API 返回的 data 即为 callbackConfigId

# 订阅设备消息
client.message_subscribe(
    device_ids=['<设备序列号>'],
    message_type_codes=['online', 'offline', 'videoMotion'],
    category_code='IPC',
    callback_config_id=callback_config_id
)

6️ 国标设备场景

# 获取国标码
python scripts/dahua_iot_client.py gb-code -c 5

# 获取 Sip 注册信息
python scripts/dahua_iot_client.py sip-info

# 添加国标设备
python scripts/dahua_iot_client.py add-gb -g 34020000001320000001 -p admin123 -c 4 -e aes256

# Python SDK
gb_codes = client.list_gb_code(count=10)
sip_info = client.get_sip_info()
result = client.add_gb_device(gb_code='34020000001320000001', device_password='admin123', channel_number=4)

7️ 铃音 / WiFi / 图片解密

# 铃音管理
rings = client.list_custom_ring(device_id, relate_type='device')  # relate_type: device/channel
client.add_custom_ring(device_id, name='my_ring', url='https://...', ring_type='custom')

# WiFi 管理
wifi_info = client.current_device_wifi(device_id)
around = client.wifi_around(device_id)
client.control_device_wifi(device_id, ssid='MyWiFi', password='wifi_password')

# 图片解密（image_url 为待解密的图片地址）
decrypted = client.image_decrypt(device_id, image_url='https://...')

安全提示

⚠️ 不要将真实的 Cloud 凭证提交到 Git!

本项目包含 .gitignore 文件，会自动忽略敏感配置文件。建议：

• 使用环境变量存储凭证
• 定期轮换密钥
• 限制应用权限范围
• Windows 用户建议使用 GUI 方式设置（更安全）

目录结构

dahua-cloud-open-iot-basic-general-kit/
├── README.md                        # 快速说明
├── QUICKSTART.md                    # 5分钟快速入门
├── SKILL.md                         # 本文件（完整指南）
├── FAQ.md                           # 常见问题解答
├── .gitignore                       # Git 忽略规则
├── references/
│   └── api_reference.md             # 完整API参考文档（43个接口）
└── scripts/
    ├── dahua_iot_client.py          # 统一客户端（推荐使用）
    ├── sign_helper.py               # 签名工具（旧版，保留兼容）
    ├── device_code_encrypt.py       # 密码加密工具（旧版，保留兼容）
    └── requirements.txt             # Python依赖

核心优势

✅ 极简配置 - 仅需要 3 个环境变量 (ProductId, AK, SK)
✅ 单文件实现 - 所有功能集中在一个文件，易于维护
✅ 统一客户端 - 封装所有API，无需关心签名细节
✅ 自动Token管理 - Token自动刷新，无需手动处理
✅ 命令行支持 - 快速操作无需编写代码
✅ Python SDK - 可轻松集成到其他应用
✅ 跨平台支持 - Windows/Linux/Mac 完美运行
✅ GUI 友好 - Windows 图形界面设置环境变量
✅ 轻量依赖 - 仅依赖 requests 和 pycryptodome
✅ 安全可靠 - 标准 API 认证，无密码泄露风险

迁移指南

从旧版迁移

如果你之前使用 sign_helper.py 和 device_code_encrypt.py，可以这样迁移：

旧版代码:

from sign_helper import DahuaAPISigner
from device_code_encrypt import DeviceCodeEncryptor

signer = DahuaAPISigner(access_key, secret_key, product_id)
encryptor = DeviceCodeEncryptor(secret_key, device_id)

# 手动管理Token
auth_headers = signer.sign_for_auth_api()
# ... 手动获取Token ...

# 手动构造请求
business_headers = signer.sign_for_business_api(app_token)
# ... 手动调用API ...

新版代码:

from dahua_iot_client import create_client_from_env

# 自动从环境变量读取配置
client = create_client_from_env()

# 自动管理Token，直接调用API
result = client.add_device(
    device_id='<设备序列号>',
    device_password='admin123'
)

常见问题

Q1: Token过期怎么办？

解决方案: 客户端会自动管理Token，在过期前自动刷新，无需手动处理。

Q2: 签名验证失败？

检查清单:

• AccessKey、SecretKey、ProductID是否正确
• 环境变量是否正确设置
• 是否重新打开了命令行窗口（环境变量需重启终端生效）

Q3: 设备添加失败？

可能原因:

• 设备密码加密方式不正确（推荐使用AES256）
• 设备序列号已存在
• 设备品类编码不正确
• 设备未初始化或未设置密码

Q4: 如何判断设备是否支持某个功能？

方法: 调用 list_device_details() 接口，查看返回的 deviceAbility 或 channelAbility 字段，检查是否包含相应的能力集标识。

Q5: 如何验证设备密码是否正确？

方法: 使用 verify 子命令或 verify_device_password() 方法调用 verifyDevCode 接口：

# 命令行
python scripts/dahua_iot_client.py verify -d <设备ID> -p <密码> -e aes256

# Python SDK
result = client.verify_device_password(device_id, password, encrypt_method='aes256')
# result['success'] 为 True 表示密码正确

更多常见问题请参阅 FAQ.md。

License

MIT License