如何对接DC-10A 智能开关来实现单路直流负载控制_解决方案

CATALOG

DC-10A 是一款支持 HTTP 接口控制的智能通断器，适用于直流负载控制场景。以下方案涵盖签名计算、接口调用和对接流程，可直接参考实施。

1. 产品概述与核心能力

DC-10A 智能通断器（型号：UNI-TDQ-DC-10A）是芯步推出的一款支持直流负载控制的智能硬件。在进行对接开发前，需明确其技术特性

通信方式：支持 2.4G WiFi，直连路由器，无需额外网关。
控制原理：通过控制内部继电器的通断，来管理直流电路的“开/关”状态。
接口协议：全开放 HTTP API，支持任何支持 HTTP 请求的编程语言或开发工具（如 Postman、Python、Java、Node-RED 等）。
网络环境：支持公有云控制，也支持私有化部署和纯局域网内的本地控制。

2. 接口对接前的准备工作

在编写代码之前，需要先获取必要的身份凭证和设备唯一标识：

注册/登录开发者账号：访问芯步开放平台。
获取凭证：在控制台的“开发设置”中，获取 AppID（应用ID）和 AppSecret（开发者密码）。这是调用接口的“账号”和“密码”。
获取设备ID：将 DC-10A 通电并配置网络连接到云端后，在控制台设备列表中查看对应的 Device ID（设备ID，通常为数字）。
查阅命令集：根据产品手册，DC-10A 的控制命令格式为 JSON 字符串。

3. 核心接口与签名机制解析

DC-10A 的对接核心在于 下行控制，即由您的业务系统发起 HTTPS 请求，经由芯步云平台转发至设备，实现远程控制。

3.1 请求地址与参数

URLhttps://api.thingboot.com/{AppID}/device/control/
MethodPOST
HeaderContent-Type: application/json
Query String
- sign：接口签名（安全校验）。
- ts：当前 Unix 时间戳（秒）。
Body 参数（JSON）：
- device：设备 ID（字符串形式）。
- order：控制命令（JSON 字符串）。

3.2 签名算法

为了确保接口安全，需按照以下步骤计算 sign 值

将 AppSecret 进行一次 MD5 加密，得到 Secret_MD5。
- 示例：Secret_MD5 = md5(AppSecret)
将 Secret_MD5 拼接上当前时间戳 ts。
- 示例：Str = Secret_MD5 + ts
将拼接后的字符串再次进行一次 MD5 加密，得到最终的 Sign。
- 示例：Sign = md5(Str)

4. 直流负载控制命令详解

针对 DC-10A 的单路直流负载控制，主要通过 order 字段中的 power 或 power1 参数实现。

控制动作	Order 命令 (JSON String)	功能描述
开启负载	`{"power1":1}` 或 `{"power":1}`	闭合继电器，电路导通，负载开始工作
关闭负载	`{"power1":0}` 或 `{"power":0}`	断开继电器，电路切断，负载停止工作
查询状态	`{"get":"power"}`	查询当前开关的通断状态

注：不同的固件版本可能支持 power（单路通用）或 power1（多路扩展），查阅具体设备的产品手册确认。

5. 实战对接流程与代码示例

5.1 业务逻辑流程图（Mermaid）

下图展示了从业务系统发起请求到设备执行的全链路流程：

sequenceDiagram
    participant App as 业务系统/服务器
    participant API as 芯步云API
    participant Device as DC-10A设备
    App->>App: 1.生成时间戳ts，计算签名sign
    App->>API: 2.POST /device/control/ (携带sign, ts, device, order)
    API->>API: 3.校验签名与设备归属
    API->>Device: 4.转发指令 (MQTT/HTTP)
    Device->>Device: 5.执行继电器动作 (通/断)
    Device-->>API: 6.返回执行结果 (成功/失败)
    API-->>App: 7.返回JSON响应

5.2 具体对接步骤

第一步：计算签名这是最容易出错的一步，请一定要严格按照以下逻辑进行字符串拼接与加密。

输入：AppSecret="abc123", ts="1704067200"
计算
1. md5("abc123") -> "e99a18c428cb38d5f260853678922e03"
2. 拼接 -> "e99a18c428cb38d5f260853678922e031704067200"
3. md5(上述字符串) -> "f25a2fc72690b780b2a14e1ef5a46d89"
结果：sign="f25a2fc72690b780b2a14e1ef5a46d89"

第二步：发起 HTTP 请求以下提供一个通用的 cURL 示例，您可以将其复制到命令行中直接测试（请替换其中的 AppID、Device ID 等参数）：

第三步：编程语言集成 (Python 示例)使用 Python 可以方便地集成该逻辑，适用于 Web 后端或自动化脚本：

import hashlib
import time
import requests
import json

def control_dc10a_power(app_id, app_secret, device_id, power_status):
    """
    控制DC-10A的通断
    :param power_status: 1 开启, 0 关闭
    """
    # 1. 准备时间戳
    ts = int(time.time())
    
    # 2. 计算签名:md5(md5(AppSecret) + ts)
    secret_md5 = hashlib.md5(app_secret.encode()).hexdigest()
    sign_str = secret_md5 + str(ts)
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 3. 构造URL与Body
    url = f"https://api.thingboot.com/{app_id}/device/control/"
    params = {
        "sign": sign,
        "ts": ts
    }
    # 构建控制命令:打开或关闭直流输出
    order = {"power1": power_status}
    payload = {
        "device": str(device_id),
        "order": json.dumps(order)  # 注意:order需要是JSON字符串格式
    }
    
    # 4. 发送请求
    headers = {"Content-Type": "application/json"}
    response = requests.post(url, params=params, json=payload, headers=headers, timeout=5)
    
    # 5. 返回结果
    if response.status_code == 200:
        print(f"指令下发成功，设备 {device_id} 状态已变更: {order}")
        return response.json()
    else:
        print(f"指令下发失败: {response.text}")
        return None

# 使用示例
if __name__ == "__main__":
    APP_ID = "你的AppID"
    APP_SECRET = "你的AppSecret"
    DEVICE_ID = "你的设备ID"
    
    # 开启直流负载
    control_dc10a_power(APP_ID, APP_SECRET, DEVICE_ID, 1)
    time.sleep(5)
    # 关闭直流负载
    control_dc10a_power(APP_ID, APP_SECRET, DEVICE_ID, 0)

6. 最佳实践与常见问题

6.1 网络稳定性与重试

离线重试：DC-10A 依靠 WiFi 通信。如果信号不稳定，接口调用可能返回成功但设备未动作。在业务逻辑中加入“查询状态”接口进行二次确认，或实现定时重试机制。
心跳维持：设备默认有保活机制，如果网络环境极差，重启设备或检查路由器 2.4G 信道干扰。

6.2 安全

签名时效：时间戳 ts 取当前实时时间。服务端通常会校验时间戳的有效期（例如 5 分钟内有效），防止过期请求重放攻击。
HTTPS 加密：请一定要使用 https:// 地址进行 API 调用，防止在网络传输中明文抓包导致 AppSecret 泄露。

6.3 私有化部署对接

如果您的项目需要运行在纯内网环境，DC-10A 支持私有化部署。此时，API 地址需变更为：

本地 API 地址http://{内网服务器IP:端口}/{AppID}/device/control/
其余签名逻辑与公有云完全一致，且无需经过外网，延迟更低。

7. 总结

对接芯步 DC-10A 智能开关实现直流负载控制，在技术上是一个标准的 RESTful API 调用 过程。开发者只需要处理好 MD5 嵌套签名 的安全校验，以及理解 {"power1":1/0} 的命令格式，即可在 30 分钟内完成核心功能的开发和联调。

通过上述方案，业务系统可以轻松地将 DC-10A 集成到各类直流供电场景中，如安防供电切换、路灯定时控制、工业设备联动等。