\r \r

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

\r

概述\r

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

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

完整功能\r

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

1. 设备管理\r

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

2. 国标设备\r

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

3. SD卡管理\r

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

4. 设备配置\r

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

5. 铃音管理\r

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

6. WiFi 管理\r

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

7. 其他设备能力\r

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

8. 消息订阅\r

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

配置凭证\r

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

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

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

步骤 1: 打开系统设置\r

\r

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

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

\r

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

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

\r 在 "当前用户的变量(U)" 区域（窗口上半部分），点击 "新建(W)..."：\r \r | 变量名 | 变量值 | 说明 |\r |--------|--------|------|\r | DAHUA_CLOUD_PRODUCT_ID | 你的 AppID | 应用 ID |\r | DAHUA_CLOUD_AK | 你的 AccessKey | 访问密钥 |\r | DAHUA_CLOUD_SK | 你的 SecretKey | 保密密钥 |\r \r 示例:\r

变量名：DAHUA_CLOUD_PRODUCT_ID\r
变量值：138XXXX731\r
\r
变量名：DAHUA_CLOUD_AK  \r
变量值：196XXXXXXXXXXXXX808\r
\r
变量名：DAHUA_CLOUD_SK\r
变量值：naumXXXXXXXXXXXXXXXXyHxh\r
```\r
\r
#### 步骤 4: 确认并保存\r
\r
1. 每个变量都点击 **"确定"** 保存\r
2. 关闭所有窗口\r
3. **重要**: 重新打开命令行窗口才能生效\r
\r
#### 快速截图指引\r
\r
如需更详细的图文教程，请参考以下操作要点：\r
- 确保在"用户变量"区域添加，而非"系统变量"\r
- 变量名必须完全一致（区分大小写）\r
- 变量值不要有多余空格\r
- 添加完成后需要重启终端\r
\r
---\r
\r
### 方式 2: 命令行快速设置\r
\r
**Windows PowerShell:**\r
```powershell\r
[Environment]::SetEnvironmentVariable("DAHUA_CLOUD_PRODUCT_ID", "your_app_id", "User")\r
[Environment]::SetEnvironmentVariable("DAHUA_CLOUD_AK", "your_access_key", "User")\r
[Environment]::SetEnvironmentVariable("DAHUA_CLOUD_SK", "your_secret_key", "User")\r
```\r
\r
**Linux/Mac:**\r
```bash\r
export DAHUA_CLOUD_PRODUCT_ID='your_app_id'\r
export DAHUA_CLOUD_AK='your_access_key'\r
export DAHUA_CLOUD_SK='your_secret_key'\r
```\r
\r
---\r
\r
### 方式 3: 命令行临时设置\r
\r
**Windows PowerShell (临时):**\r
```powershell\r
$env:DAHUA_CLOUD_PRODUCT_ID='your_app_id'\r
$env:DAHUA_CLOUD_AK='your_access_key'\r
$env:DAHUA_CLOUD_SK='your_secret_key'\r
```\r
\r
**注意**: 仅在当前窗口有效，关闭后失效\r
\r
---\r
\r
### 验证环境变量是否生效\r
\r
**Linux/Mac:**\r
```bash\r
echo $DAHUA_CLOUD_PRODUCT_ID\r
echo $DAHUA_CLOUD_AK\r
# 注意：不要打印 SK，避免泄露\r
```\r
\r
**Windows PowerShell:**\r
```powershell\r
$env:DAHUA_CLOUD_PRODUCT_ID\r
$env:DAHUA_CLOUD_AK\r
```\r
\r
---\r
\r
## 快速开始\r
\r
### 基本使用\r
\r
```bash\r
# 查看帮助\r
python scripts/dahua_iot_client.py --help\r
\r
# 添加设备\r
python scripts/dahua_iot_client.py add -d \x3C设备序列号> -p admin123 -c IPC\r
\r
# 查询设备列表\r
python scripts/dahua_iot_client.py list -p 1 -s 10\r
\r
# 查询设备在线状态\r
python scripts/dahua_iot_client.py online -d \x3C设备序列号>\r
\r
# 校验设备密码（验证密码是否正确）\r
python scripts/dahua_iot_client.py verify -d \x3C设备序列号> -p admin123 -e aes256\r
\r
# 删除设备\r
python scripts/dahua_iot_client.py delete -d \x3C设备序列号>\r
```\r
\r
### 完整示例\r
\r
```bash\r
# 完整设备接入流程（仅需 Cloud 凭证）\r
cd scripts\r
python dahua_iot_client.py add -d \x3C设备序列号> -p admin123 -c IPC -e aes256\r
python dahua_iot_client.py online -d \x3C设备序列号>\r
python dahua_iot_client.py list -p 1 -s 20 -d \x3C设备序列号前缀>\r
```\r
\r
### Python SDK 调用\r
\r
> **导入说明**：在 `scripts/` 目录下运行，或将 `scripts/` 加入 `PYTHONPATH` 后使用。\r
\r
```python\r
from dahua_iot_client import DahuaIoTClient, create_client_from_env\r
\r
# 方式1: 从环境变量创建客户端（verbose=True 打印API日志）\r
client = create_client_from_env()\r
\r
# SDK 集成时建议关闭日志：create_client_from_env(verbose=False)\r
\r
# 方式2: 手动创建客户端\r
client = DahuaIoTClient(\r
    app_id='your_product_id',\r
    access_key='your_access_key',\r
    secret_key='your_secret_key'\r
)\r
\r
# 添加设备\r
result = client.add_device(\r
    device_id='\x3C设备序列号>',\r
    device_password='admin123',\r
    category_code='IPC',\r
    encrypt_method='aes256'  # 推荐\r
)\r
\r
print(f"Add device result: {result}")\r
\r
# 校验设备密码（验证密码是否正确）\r
verify_result = client.verify_device_password('\x3C设备序列号>', 'admin123', encrypt_method='aes256')\r
print(f"Password verify: {verify_result.get('success', False)}")\r
\r
# 查询设备在线状态\r
status = client.get_device_online('\x3C设备序列号>')\r
print(f"Online status: {status}")\r
\r
# 查询设备列表\r
devices = client.get_device_list(page_num=1, page_size=10)\r
print(f"Device list: {devices}")\r
\r
# 获取SD卡状态\r
sd_status = client.get_sd_card_status('\x3C设备序列号>')\r
print(f"SD card status: {sd_status}")\r
\r
# 设置设备使能开关\r
result = client.set_ability_status(\r
    device_id='\x3C设备序列号>',\r
    ability_type='localRecord',\r
    status='on',\r
    channel_id='0'\r
)\r
```\r
\r
---\r
\r
## 工作流程\r
\r
```\r
┌─────────────────────┐\r
│ 1. 初始化客户端      │\r
│   (配置凭证)         │\r
└──────────┬──────────┘\r
           ▼\r
┌─────────────────────┐\r
│ 2. 自动获取 Token    │\r
│   (AppAccessToken)   │\r
└──────────┬──────────┘\r
           ▼\r
┌─────────────────────┐\r
│ 3. 调用业务API       │\r
│   (设备管理/配置)    │\r
└──────────┬──────────┘\r
           ▼\r
┌─────────────────────┐\r
│ 4. 返回结果          │\r
│   (JSON格式)         │\r
└─────────────────────┘\r
```\r
\r
---\r
\r
## API 端点\r
\r
| 模块 | 路径前缀 | 说明 |\r
|------|----------|------|\r
| 认证 | `/open-api/api-base/auth/getAppAccessToken` | 获取 AppAccessToken |\r
| 设备管理 | `/open-api/api-iot/device/*` | addDevice、deleteDevice、verifyDevCode、getDeviceList、deviceOnline、listDeviceDetailsByIds、checkDeviceBindInfo、getCategory、modifyDeviceName、modifyDevCode、getDeviceChannelInfo |\r
| 国标设备 | `/open-api/api-iot/device/*` | getSipInfo、listGbCode、addGbDevice、modifyGbDevice、deviceInfoDetailAll |\r
| SD卡/铃音/WiFi | `/open-api/api-aiot/device/*` | getSDCardStatus、getSDCardStorage、listSDCardStorage、formatSDCard、listCustomRing、addCustomRing、deleteCustomRing、setCustomRing、wifiAround、currentDeviceWifi、controlDeviceWifi |\r
| 设备配置 | `/open-api/api-aiot/device/*` | getAbilityStatus、setAbilityStatus、setCurrentUTC |\r
| 其他 | `/open-api/api-aiot/device/getSimSignalStrength` | 获取 SIM 信号强度 |\r
| 图片解密 | `/open-api/api-decrypto/image/decrypto` | 图片解密 |\r
| 消息订阅 | `/open-api/api-message/*` | addCallbackConfig、getAllCallbackConfigId、messageSubscribeByDeviceIds、getMessageTypePage、getMessageSubscribeInfoByDeviceId、updateSubscribeByCallbackConfigId、updateByCallbackConfigId、deleteCallbackId、getInfoByCallbackConfigId、getSubscribeInfoByCallbackConfigId |\r
\r
完整 API 参考见 [references/api_reference.md](./references/api_reference.md)。\r
\r
---\r
\r
## 认证机制\r
\r
### 签名算法\r
\r
**SHA512 HMAC 签名** - 两种签名方式：\r
\r
1. **get_token_sign()** - 获取 Token 签名\r
   ```\r
   签名因子: access_key + timestamp + nonce\r
   ```\r
\r
2. **business_api_sign()** - 业务 API 签名\r
   ```\r
   签名因子: access_key + app_access_token + timestamp + nonce\r
   ```\r
\r
### 请求头结构\r
\r
**认证请求头** (获取 Token):\r
```python\r
{\r
    "Content-Type": "application/json",\r
    "AccessKey": access_key,\r
    "Timestamp": timestamp,\r
    "Nonce": nonce,\r
    "X-TraceId-Header": trace_id,\r
    "Sign": signature,           # get_token_sign() 生成\r
    "ProductId": app_id,\r
    "Version": "V1",\r
    "Sign-Type": "simple"\r
}\r
```\r
\r
**业务请求头** (所有设备管理API):\r
```python\r
{\r
    "Content-Type": "application/json",\r
    "AccessKey": access_key,\r
    "Timestamp": timestamp,\r
    "Nonce": nonce,\r
    "X-TraceId-Header": trace_id,\r
    "Sign": signature,           # business_api_sign() 生成\r
    "Version": "V1",\r
    "Sign-Type": "simple",\r
    "AppAccessToken": app_token,\r
    "ProductId": app_id\r
}\r
```\r
\r
---\r
\r
## 代码架构\r
\r
```\r
┌──────────────────────────────────────────────────────────────────┐\r
│                    常量配置层 (Constants)                         │\r
│  - API 端点、超时时间、环境变量名                               │\r
└──────────────────────────────────────────────────────────────────┘\r
                              │\r
┌──────────────────────────────────────────────────────────────────┐\r
│                    工具函数层 (Utilities)                         │\r
│  - get_token_sign()          获取 Token 签名                  │\r
│  - business_api_sign()       业务 API 签名                    │\r
│  - DeviceCodeEncryptor       设备密码加密（Base64/AES256）        │\r
└──────────────────────────────────────────────────────────────────┘\r
                              │\r
┌──────────────────────────────────────────────────────────────────┐\r
│                     DahuaIoTClient 类 (43个接口)                   │\r
│  设备: add/verify/delete/list/details/online/bind/category/channel │\r
│  国标: get_sip_info/add_gb/list_gb_code/modify_gb/gb_details      │\r
│  SD卡: get_status/storage/list/format  铃音: list/add/delete/set  │\r
│  配置: get/set_ability_status/set_current_utc                     │\r
│  WiFi: wifi_around/current/control  SIM: get_sim_signal_strength  │\r
│  消息: callback/message_subscribe/update/delete/query             │\r
│  其他: image_decrypt 图片解密                                      │\r
└──────────────────────────────────────────────────────────────────┘\r
                              │\r
┌──────────────────────────────────────────────────────────────────┐\r
│                    辅助函数层                                     │\r
│  - create_client_from_env()  从环境变量创建客户端                 │\r
└──────────────────────────────────────────────────────────────────┘\r
```\r
\r
---\r
\r
## 设备密码加密\r
\r
### 方式一：Base64加密\r
\r
```python\r
格式："Dolynk_" + Base64(设备密码)\r
例如：若设备密码为 admin123\r
Base64(admin123) = YWRtaW4xMjM=\r
加密后字符串 = Dolynk_YWRtaW4xMjM=\r
```\r
\r
### 方式二：AES256加密（推荐）\r
\r
```python\r
格式：Base64(Aes256(待加密内容, AesKey, IV初始向量))\r
加密算法：Aes256/CBC/PKCS7\r
初始化向量IV：86E2DB6D77B5E9CD\r
AesKey：Cut32(UpperCase(MD5-32位(UpperCase(sk))))\r
```\r
\r
**示例代码**:\r
```python\r
from dahua_iot_client import DeviceCodeEncryptor\r
\r
encryptor = DeviceCodeEncryptor(\r
    secret_access_key="your_sk",\r
    device_id="your_device_id"\r
)\r
\r
# AES256加密（推荐）\r
dev_code = encryptor.encrypt_aes256("admin123")\r
\r
# Base64加密\r
dev_code = encryptor.encrypt_base64("admin123")\r
```\r
\r
---\r
\r
## 核心类和函数\r
\r
### `DahuaIoTClient` 类\r
\r
统一客户端类，封装所有设备管理API。\r
\r
#### 初始化参数\r
\r
| 参数 | 类型 | 必填 | 说明 |\r
|------|------|------|------|\r
| `app_id` | `str` | ✅ | 产品ID (ProductId) |\r
| `access_key` | `str` | ✅ | 访问密钥 (AccessKey) |\r
| `secret_key` | `str` | ✅ | 密钥 (SecretKey) |\r
| `api_base_url` | `str` | ❌ | API基础地址（默认：https://open.cloud-dahua.com/） |\r
| `verbose` | `bool` | ❌ | 是否打印API调用日志（默认：True，SDK集成时建议False） |\r
\r
#### 主要方法（43 个接口）\r
\r
| 分类 | 方法 | 说明 | CLI |\r
|------|------|------|-----|\r
| 设备 | `add_device()` | 添加设备 | `add` |\r
| 设备 | `verify_device_password()` | 校验设备密码 | `verify` |\r
| 设备 | `delete_device()` | 删除设备 | `delete` |\r
| 设备 | `get_device_list()` | 查询设备列表 | `list` |\r
| 设备 | `get_device_online()` | 查询设备在线状态 | `online` |\r
| 设备 | `list_device_details()` | 批量查询设备详细信息 | `details` |\r
| 设备 | `check_device_bind()` | 查询设备绑定状态 | `bind` |\r
| 设备 | `get_category()` | 查询设备品类 | `category` |\r
| 设备 | `get_device_channel_info()` | 获取设备通道信息 | `channels` |\r
| 设备 | `modify_device_name()` | 修改设备/通道名称 | - |\r
| 设备 | `modify_dev_code()` | 修改设备密码 | - |\r
| 国标 | `get_sip_info()` | 获取国标设备注册信息 | `sip-info` |\r
| 国标 | `list_gb_code()` | 获取国标码列表 | `gb-code` |\r
| 国标 | `add_gb_device()` | 添加国标设备 | `add-gb` |\r
| 国标 | `modify_gb_device()` | 修改国标设备信息 | `modify-gb` |\r
| 国标 | `list_gb_device_details()` | 国标设备查询详细信息 | `gb-details` |\r
| SD卡 | `get_sd_card_status()` | 获取SD卡状态 | - |\r
| SD卡 | `get_sd_card_storage()` | 查询SD卡容量 | - |\r
| SD卡 | `list_sd_card_storage()` | 获取SD卡列表 | - |\r
| SD卡 | `format_sd_card()` | 格式化SD卡 | - |\r
| 配置 | `get_ability_status()` | 获取设备使能状态 | `ability` |\r
| 配置 | `set_ability_status()` | 设置设备使能状态 | - |\r
| 配置 | `set_current_utc()` | 设备校时 | - |\r
| 铃音 | `list_custom_ring()` | 获取铃声列表 | - |\r
| 铃音 | `add_custom_ring()` | 新增自定义铃声 | - |\r
| 铃音 | `delete_custom_ring()` | 删除自定义铃声 | - |\r
| 铃音 | `set_custom_ring()` | 设置铃声 | - |\r
| WiFi | `current_device_wifi()` | 获取设备当前连接热点 | - |\r
| WiFi | `wifi_around()` | 获取设备周边热点 | - |\r
| WiFi | `control_device_wifi()` | 修改设备连接热点 | - |\r
| 其他 | `get_sim_signal_strength()` | 获取SIM信号强度 | - |\r
| 其他 | `image_decrypt()` | 图片解密 | - |\r
| 消息 | `add_callback_config()` | 添加回调配置 | - |\r
| 消息 | `message_subscribe()` | 按设备ID订阅消息 | - |\r
| 消息 | `get_all_callback_config()` | 分页获取回调配置 | - |\r
| 消息 | `update_subscribe_by_callback_config()` | 根据回调配置更新订阅 | - |\r
| 消息 | `update_callback_config()` | 更新回调配置 | - |\r
| 消息 | `delete_callback_config()` | 删除回调配置 | - |\r
| 消息 | `get_callback_config_info()` | 搜索回调配置信息 | - |\r
| 消息 | `get_subscribe_info_by_callback_config()` | 搜索已订阅设备消息 | - |\r
| 消息 | `get_subscribe_info_by_device()` | 按设备ID查询订阅信息 | - |\r
| 消息 | `get_message_type_page()` | 按设备类别获取消息类型 | - |\r
\r
### `DeviceCodeEncryptor` 类\r
\r
设备密码加密工具类。\r
\r
#### 方法\r
\r
| 方法 | 说明 |\r
|------|------|\r
| `encrypt_base64(password)` | Base64加密 |\r
| `encrypt_aes256(password)` | AES256加密（推荐） |\r
\r
---\r
\r
## 命令行参数\r
\r
### 通用参数\r
\r
| 参数 | 简写 | 类型 | 必填 | 说明 |\r
|------|------|------|------|------|\r
| `--help` | `-h` | - | ❌ | 显示帮助信息 |\r
\r
### 命令行子命令汇总\r
\r
| 子命令 | 说明 |\r
|--------|------|\r
| `add` | 添加设备 |\r
| `add-gb` | 添加国标设备 |\r
| `delete` | 删除设备 |\r
| `verify` | 校验设备密码 |\r
| `list` | 查询设备列表 |\r
| `details` | 查询设备详细信息 |\r
| `online` | 查询设备在线状态 |\r
| `bind` | 查询设备绑定状态 |\r
| `category` | 查询设备品类 |\r
| `channels` | 获取设备通道信息 |\r
| `ability` | 获取设备使能状态 |\r
| `gb-code` | 获取国标码列表 |\r
| `sip-info` | 获取国标设备注册信息 |\r
| `gb-details` | 查询国标设备详细信息 |\r
| `modify-gb` | 修改国标设备信息 |\r
| `encrypt` | 加密设备密码 |\r
\r
### 子命令详情\r
\r
#### `add` - 添加设备\r
\r
| 参数 | 简写 | 类型 | 必填 | 说明 |\r
|------|------|------|------|------|\r
| `--device-id` | `-d` | `str` | ✅ | 设备序列号 |\r
| `--password` | `-p` | `str` | ✅ | 设备密码 |\r
| `--category` | `-c` | `str` | ❌ | 设备品类编码（默认：IPC） |\r
| `--encrypt` | `-e` | `str` | ❌ | 加密方式（base64/aes256，默认：base64） |\r
\r
#### `delete` - 删除设备\r
\r
| 参数 | 简写 | 类型 | 必填 | 说明 |\r
|------|------|------|------|------|\r
| `--device-id` | `-d` | `str` | ✅ | 设备序列号 |\r
\r
#### `list` - 查询设备列表\r
\r
| 参数 | 简写 | 类型 | 必填 | 说明 |\r
|------|------|------|------|------|\r
| `--page` | `-p` | `int` | ❌ | 页码（默认：1） |\r
| `--size` | `-s` | `int` | ❌ | 每页条数（默认：10） |\r
| `--device-id` | `-d` | `str` | ❌ | 设备序列号（模糊查询） |\r
\r
#### `online` - 查询设备在线状态\r
\r
| 参数 | 简写 | 类型 | 必填 | 说明 |\r
|------|------|------|------|------|\r
| `--device-id` | `-d` | `str` | ✅ | 设备序列号 |\r
\r
#### `verify` - 校验设备密码\r
\r
验证指定设备的密码是否正确（调用 verifyDevCode 接口）。\r
\r
| 参数 | 简写 | 类型 | 必填 | 说明 |\r
|------|------|------|------|------|\r
| `--device-id` | `-d` | `str` | ✅ | 设备序列号 |\r
| `--password` | `-p` | `str` | ✅ | 设备密码（明文） |\r
| `--encrypt` | `-e` | `str` | ❌ | 加密方式（base64/aes256，默认：base64） |\r
\r
```bash\r
# 校验设备密码\r
python scripts/dahua_iot_client.py verify -d \x3C设备序列号> -p admin123 -e aes256\r
```\r
\r
#### `details` - 查询设备详细信息\r
\r
| 参数 | 说明 |\r
|------|------|\r
| `device_ids` | 设备序列号（可多个，位置参数） |\r
\r
```bash\r
python scripts/dahua_iot_client.py details \x3C设备序列号> \x3C设备序列号2>\r
```\r
\r
#### `category` - 查询设备品类\r
\r
| 参数 | 简写 | 说明 |\r
|------|------|------|\r
| `--primary` | `-p` | 1级设备类别代码 |\r
| `--second` | `-s` | 2级设备类别代码（如 IPC） |\r
| `--model` | `-m` | 设备型号 |\r
\r
#### `bind` - 查询设备绑定状态\r
\r
| 参数 | 简写 | 必填 | 说明 |\r
|------|------|------|------|\r
| `--device-id` | `-d` | ✅ | 设备序列号 |\r
\r
#### `channels` - 获取设备通道信息\r
\r
| 参数 | 简写 | 必填 | 说明 |\r
|------|------|------|------|\r
| `--device-id` | `-d` | ✅ | 设备序列号 |\r
\r
#### `ability` - 获取设备使能状态\r
\r
| 参数 | 简写 | 必填 | 说明 |\r
|------|------|------|------|\r
| `--device-id` | `-d` | ✅ | 设备序列号 |\r
| `--ability-type` | `-a` | ✅ | 使能类型（如 localRecord、motionDetect、faceCapture） |\r
| `--channel-id` | `-c` | ❌ | 通道号（通道级使能需传） |\r
\r
#### `add-gb` - 添加国标设备\r
\r
| 参数 | 简写 | 必填 | 说明 |\r
|------|------|------|------|\r
| `--gb-code` | `-g` | ✅ | 国标码 |\r
| `--password` | `-p` | ✅ | 设备注册密码 |\r
| `--channels` | `-c` | ✅ | 通道总数 |\r
| `--encrypt` | `-e` | ❌ | 加密方式（base64/aes256，默认 base64） |\r
| `--manufacturer` | `-m` | ❌ | 厂商（Dahua、HIKVSION、UNKNOW） |\r
| `--stream-model` | `-s` | ❌ | 拉流协议（TCP/UDP） |\r
| `--device-class` | `-d` | ❌ | 设备类型（NVR/IPC） |\r
\r
#### `gb-code` - 获取国标码列表\r
\r
| 参数 | 简写 | 说明 |\r
|------|------|------|\r
| `--count` | `-c` | 查询数量（1-10000，默认 10） |\r
| `--prefix` | `-p` | 国标码前缀（长度必须 13 位） |\r
\r
#### `sip-info` - 获取国标设备注册信息\r
\r
无需参数，返回 Sip 服务器 IP 和端口。\r
\r
#### `gb-details` - 查询国标设备详细信息\r
\r
| 参数 | 说明 |\r
|------|------|\r
| `device_ids` | 设备序列号（可多个，位置参数） |\r
\r
#### `modify-gb` - 修改国标设备信息\r
\r
| 参数 | 简写 | 必填 | 说明 |\r
|------|------|------|------|\r
| `--device-id` | `-d` | ✅ | 设备序列号 |\r
| `--password` | `-p` | ❌ | 新设备密码 |\r
| `--encrypt` | `-e` | ❌ | 密码加密方式（base64/aes256，默认：base64） |\r
| `--stream-model` | `-s` | ❌ | 拉流协议（TCP/UDP） |\r
\r
#### `encrypt` - 加密设备密码\r
\r
| 参数 | 简写 | 类型 | 必填 | 说明 |\r
|------|------|------|------|------|\r
| `--password` | `-p` | `str` | ✅ | 设备密码 |\r
| `--secret-key` | `-s` | `str` | ✅ | SecretKey |\r
| `--device-id` | `-d` | `str` | ❌ | 设备序列号 |\r
| `--method` | `-m` | `str` | ❌ | 加密方式（base64/aes256，默认：base64） |\r
\r
---\r
\r
## 响应格式\r
\r
所有 API 响应遵循统一格式：\r
\r
```python\r
{\r
    "code": "200",           # 响应状态码\r
    "success": true,         # 响应状态\r
    "data": {},             # 响应数据\r
    "msg": "操作成功"         # 响应消息\r
}\r
```\r
\r
### add_device 响应示例\r
\r
```python\r
{\r
    "success": True,\r
    "code": "200",\r
    "msg": "操作成功",\r
    "data": {\r
        "deviceId": "\x3C设备序列号>",\r
        "deviceName": "",\r
        "channelNum": 1,\r
        "status": 1\r
    }\r
}\r
```\r
\r
### get_device_online 响应示例\r
\r
```python\r
{\r
    "success": True,\r
    "code": "200",\r
    "msg": "操作成功",\r
    "data": {\r
        "deviceId": "\x3C设备序列号>",\r
        "online": True\r
    }\r
}\r
```\r
\r
**错误码说明**:\r
- `200`: 成功\r
- 其他: 失败，查看 `msg` 字段了解错误原因\r
\r
---\r
\r
## 可配置常量\r
\r
| 常量名 | 默认值 | 说明 |\r
|--------|--------|------|\r
| `DEFAULT_API_BASE_URL` | `https://open.cloud-dahua.com/` | API 基础地址 |\r
| `TOKEN_EXPIRY_SECONDS` | `604800` | Token 有效期(秒) - 7天 |\r
| `TIMEOUT_AUTH` | `60` | 认证超时(秒) |\r
| `TIMEOUT_DEVICE` | `60` | 设备管理超时(秒) |\r
| `TIMEOUT_CONFIG` | `60` | 配置超时(秒) |\r
| `TIMEOUT_SD_CARD` | `60` | SD卡管理超时(秒) |\r
| `TIMEOUT_FORMAT_SD` | `120` | SD卡格式化超时(秒) |\r
\r
---\r
\r
## 依赖要求\r
\r
- Python 3.8+\r
- requests>=2.31.0\r
- pycryptodome>=3.15.0\r
\r
安装依赖:\r
```bash\r
pip install requests pycryptodome\r
```\r
\r
---\r
\r
## 使用场景\r
\r
### 1️ 设备接入场景\r
\r
```bash\r
# 添加设备\r
python scripts/dahua_iot_client.py add -d \x3C设备序列号> -p admin123 -c IPC\r
\r
# 校验设备密码（验证密码是否正确）\r
python scripts/dahua_iot_client.py verify -d \x3C设备序列号> -p admin123 -e aes256\r
\r
# 查询设备在线状态\r
python scripts/dahua_iot_client.py online -d \x3C设备序列号>\r
\r
# 查询设备列表/详细信息\r
python scripts/dahua_iot_client.py list -d \x3C设备序列号前缀>\r
python scripts/dahua_iot_client.py details \x3C设备序列号>\r
```\r
\r
### 2️ 设备管理场景\r
\r
```python\r
# Python SDK\r
client = create_client_from_env()\r
\r
# 获取设备列表\r
devices = client.get_device_list(page_num=1, page_size=100)\r
\r
# 批量查询设备详情\r
device_ids = ['\x3C设备序列号1>', '\x3C设备序列号2>']\r
details = client.list_device_details(device_ids)\r
\r
# 删除设备\r
client.delete_device('\x3C设备序列号>')\r
```\r
\r
### 3️ SD卡管理场景\r
\r
```python\r
# 查询SD卡状态\r
status = client.get_sd_card_status('\x3C设备序列号>')\r
\r
# 查询SD卡容量\r
storage = client.get_sd_card_storage('\x3C设备序列号>')\r
\r
# 格式化SD卡\r
result = client.format_sd_card('\x3C设备序列号>')\r
```\r
\r
### 4️ 设备配置场景\r
\r
```python\r
# 修改设备名称\r
client.modify_device_name('\x3C设备序列号>', 'My Camera')\r
\r
# 启用本地录像\r
client.set_ability_status(\r
    device_id='\x3C设备序列号>',\r
    ability_type='localRecord',\r
    status='on',\r
    channel_id='0'\r
)\r
```\r
\r
### 5️ 消息订阅场景\r
\r
```python\r
# 添加回调配置（返回的 data 为回调配置ID）\r
callback = client.add_callback_config(\r
    callback_url='https://your-server.com/callback',\r
    is_push=True\r
)\r
callback_config_id = callback['data']  # API 返回的 data 即为 callbackConfigId\r
\r
# 订阅设备消息\r
client.message_subscribe(\r
    device_ids=['\x3C设备序列号>'],\r
    message_type_codes=['online', 'offline', 'videoMotion'],\r
    category_code='IPC',\r
    callback_config_id=callback_config_id\r
)\r
```\r
\r
### 6️ 国标设备场景\r
\r
```bash\r
# 获取国标码\r
python scripts/dahua_iot_client.py gb-code -c 5\r
\r
# 获取 Sip 注册信息\r
python scripts/dahua_iot_client.py sip-info\r
\r
# 添加国标设备\r
python scripts/dahua_iot_client.py add-gb -g 34020000001320000001 -p admin123 -c 4 -e aes256\r
```\r
\r
```python\r
# Python SDK\r
gb_codes = client.list_gb_code(count=10)\r
sip_info = client.get_sip_info()\r
result = client.add_gb_device(gb_code='34020000001320000001', device_password='admin123', channel_number=4)\r
```\r
\r
### 7️ 铃音 / WiFi / 图片解密\r
\r
```python\r
# 铃音管理\r
rings = client.list_custom_ring(device_id, relate_type='device')  # relate_type: device/channel\r
client.add_custom_ring(device_id, name='my_ring', url='https://...', ring_type='custom')\r
\r
# WiFi 管理\r
wifi_info = client.current_device_wifi(device_id)\r
around = client.wifi_around(device_id)\r
client.control_device_wifi(device_id, ssid='MyWiFi', password='wifi_password')\r
\r
# 图片解密（image_url 为待解密的图片地址）\r
decrypted = client.image_decrypt(device_id, image_url='https://...')\r
```\r
\r
---\r
\r
## 安全提示\r
\r
⚠️ **不要将真实的 Cloud 凭证提交到 Git!**\r
\r
本项目包含 `.gitignore` 文件，会自动忽略敏感配置文件。建议：\r
- 使用环境变量存储凭证\r
- 定期轮换密钥\r
- 限制应用权限范围\r
- Windows 用户建议使用 GUI 方式设置（更安全）\r
\r
---\r
\r
## 目录结构\r
\r
```\r
dahua-cloud-open-iot-basic-general-kit/\r
├── README.md                        # 快速说明\r
├── QUICKSTART.md                    # 5分钟快速入门\r
├── SKILL.md                         # 本文件（完整指南）\r
├── FAQ.md                           # 常见问题解答\r
├── .gitignore                       # Git 忽略规则\r
├── references/\r
│   └── api_reference.md             # 完整API参考文档（43个接口）\r
└── scripts/\r
    ├── dahua_iot_client.py          # 统一客户端（推荐使用）\r
    ├── sign_helper.py               # 签名工具（旧版，保留兼容）\r
    ├── device_code_encrypt.py       # 密码加密工具（旧版，保留兼容）\r
    └── requirements.txt             # Python依赖\r
```\r
\r
---\r
\r
## 核心优势\r
\r
✅ **极简配置** - 仅需要 3 个环境变量 (ProductId, AK, SK)  \r
✅ **单文件实现** - 所有功能集中在一个文件，易于维护  \r
✅ **统一客户端** - 封装所有API，无需关心签名细节  \r
✅ **自动Token管理** - Token自动刷新，无需手动处理  \r
✅ **命令行支持** - 快速操作无需编写代码  \r
✅ **Python SDK** - 可轻松集成到其他应用  \r
✅ **跨平台支持** - Windows/Linux/Mac 完美运行  \r
✅ **GUI 友好** - Windows 图形界面设置环境变量  \r
✅ **轻量依赖** - 仅依赖 requests 和 pycryptodome  \r
✅ **安全可靠** - 标准 API 认证，无密码泄露风险  \r
\r
---\r
\r
## 迁移指南\r
\r
### 从旧版迁移\r
\r
如果你之前使用 `sign_helper.py` 和 `device_code_encrypt.py`，可以这样迁移：\r
\r
**旧版代码**:\r
```python\r
from sign_helper import DahuaAPISigner\r
from device_code_encrypt import DeviceCodeEncryptor\r
\r
signer = DahuaAPISigner(access_key, secret_key, product_id)\r
encryptor = DeviceCodeEncryptor(secret_key, device_id)\r
\r
# 手动管理Token\r
auth_headers = signer.sign_for_auth_api()\r
# ... 手动获取Token ...\r
\r
# 手动构造请求\r
business_headers = signer.sign_for_business_api(app_token)\r
# ... 手动调用API ...\r
```\r
\r
**新版代码**:\r
```python\r
from dahua_iot_client import create_client_from_env\r
\r
# 自动从环境变量读取配置\r
client = create_client_from_env()\r
\r
# 自动管理Token，直接调用API\r
result = client.add_device(\r
    device_id='\x3C设备序列号>',\r
    device_password='admin123'\r
)\r
```\r
\r
---\r
\r
## 常见问题\r
\r
### Q1: Token过期怎么办？\r
\r
**解决方案**: 客户端会自动管理Token，在过期前自动刷新，无需手动处理。\r
\r
### Q2: 签名验证失败？\r
\r
**检查清单**:\r
- [ ] AccessKey、SecretKey、ProductID是否正确\r
- [ ] 环境变量是否正确设置\r
- [ ] 是否重新打开了命令行窗口（环境变量需重启终端生效）\r
\r
### Q3: 设备添加失败？\r
\r
**可能原因**:\r
- 设备密码加密方式不正确（推荐使用AES256）\r
- 设备序列号已存在\r
- 设备品类编码不正确\r
- 设备未初始化或未设置密码\r
\r
### Q4: 如何判断设备是否支持某个功能？\r
\r
**方法**: 调用 `list_device_details()` 接口，查看返回的 `deviceAbility` 或 `channelAbility` 字段，检查是否包含相应的能力集标识。\r
\r
### Q5: 如何验证设备密码是否正确？\r
\r
**方法**: 使用 `verify` 子命令或 `verify_device_password()` 方法调用 verifyDevCode 接口：\r
\r
```bash\r
# 命令行\r
python scripts/dahua_iot_client.py verify -d \x3C设备ID> -p \x3C密码> -e aes256\r
```\r
\r
```python\r
# Python SDK\r
result = client.verify_device_password(device_id, password, encrypt_method='aes256')\r
# result['success'] 为 True 表示密码正确\r
```\r
\r
更多常见问题请参阅 [FAQ.md](./FAQ.md)。\r
\r
---\r
\r
## License\r
\r
MIT License\r