自动化设备交流电源管理：怎样把AC1-10A线路控制器接入到软件项目中_解决方案

CATALOG

芯步AC1-10A线路控制器提供了完整的HTTP API接口，通过签名认证和标准RESTful调用，可以快速接入各类软件项目。以下方案涵盖接口协议、签名算法、代码实现和状态回调机制。

1. 概述

在当前的智能化转型浪潮中，将传统的交流电源设备（如灯具、电机、自动化仪表）纳入软件管理系统是提升效率的关键。针对芯步 智能通断器AC1-10A（型号：UNI-TDQ-AC1-10A），本方案的目标是指导开发者如何利用其开放的API接口，快速将该硬件集成到现有的Web平台、移动应用（APP/小程序）或企业级SaaS系统中。

该硬件支持10A交流负载，具备一路通断控制能力，额定功率支持2200W，满足绝大多数家电及工业自动化设备的供电管理需求。

2. 硬件与接口特性

在接入前，需明确该设备的通信机制：

控制方式HTTP API 和 WebSocket。其中HTTP API适用于绝大多数一次性指令下发场景（如开关灯、重启设备），WebSocket适用于需要低延迟、高频次控制的实时场景。
状态反馈：设备支持状态主动推送。当设备物理按键被触发或由于过载保护自动断电时，设备会通过回调机制将最新状态推送给指定的服务器URL，保证软件端状态与物理设备实时同步。
核心资源
- AppID：开发者身份标识。
- AppSecret：开发者密钥（用于签名）。
- Device ID：目标设备唯一ID，可在芯步控制台获取。

3. 接入认证与协议详解

为了实现安全的远程控制，系统采用动态MD5签名鉴权机制，绝不允许在代码中明文传输AppSecret。

3.1 签名算法规则

根据芯步开放接口规范，请求必须携带 sign 和 ts（时间戳）参数。签名生成逻辑如下

对 AppSecret 进行一次MD5加密，得到 Secret_MD5。
将 Secret_MD5 与当前Unix时间戳（秒级）ts 拼接成字符串 Secret_MD5 + ts。
对拼接后的字符串再次进行MD5加密，得到最终的 sign。

公式Sign = md5( md5(AppSecret) + ts )

3.2 接口地址与请求结构

请求URLhttps://api.thingboot.com/{AppID}/device/control/
Method：POST
HeaderContent-Type: application/json

Body参数示例

注：对于单路控制器，power1 代表控制第一路线路；对于多路设备，可使用 power2, power3 等。

4. 软件集成实施步骤

4.1 准备工作

在芯步执行以下操作：

创建设备：给AC1-10A设备通电并配网，确认其在控制台显示为“在线”。
获取凭证：在“开发设置”中获取 AppID 和 AppSecret（开发者密码）。
设置回调URL：在控制台配置“状态推送”地址，用于接收设备状态变更通知。

4.2 核心代码实现（以Python/Node.js为例）

在后端服务中封装设备控制函数，由于签名涉及密钥，所有控制请求必须经由后端发起，前端仅调用后端接口。

第一种场景：单次通断控制

*需求：用户点击“开启电源”，软件发送指令让AC1-10A接通电路。*

Python (Flask) 后端示例

import hashlib
import time
import requests
import json

class YoYoController:
    def __init__(self, app_id, app_secret):
        self.app_id = app_id
        self.app_secret = app_secret
        self.api_url = f"https://api.thingboot.com/{app_id}/device/control/"

def _generate_sign(self, ts):
        # 1. MD5(AppSecret)
        step1 = hashlib.md5(self.app_secret.encode()).hexdigest()
        # 2. md5(step1 + ts)
        step2 = step1 + str(ts)
        sign = hashlib.md5(step2.encode()).hexdigest()
        return sign

def control_device(self, device_id, power_status):
        ts = int(time.time())
        sign = self._generate_sign(ts)
        
        params = {
            'sign': sign,
            'ts': ts
        }
        
        # 指令构建:{"power1": 1} 开启; {"power1": 0} 关闭
        payload = {
            'device': str(device_id),
            'order': {"power1": power_status}
        }
        
        response = requests.post(self.api_url, params=params, json=payload)
        return response.json()

# 调用示例
ctrl = YoYoController("Your_AppID", "Your_AppSecret")
# power_status = 1 开启，0 关闭
result = ctrl.control_device("1878", 1) 
print(result)

代码参考自芯步官方开发手册。

第二种场景：自定义动作（脉冲/点动模式）

需求：控制设备短暂通电1秒后自动断开（如控制门禁或电机）。AC1-10A支持自定义动作，通过order字段传递更复杂的JSON结构：

此模式适用于需要“点动”或“触发”的自动化场景。

4.3 实时状态同步机制

为了避免界面显示滞后，不应单纯依赖控制接口的返回结果来判断设备状态。采用被动接收回调的方式：

机制：当设备状态因任何原因（软件控制、手动按键、过载保护）发生变化时，芯步服务器会立即向开发者预设的 Callback URL 发送POST请求。
数据格式
{ "device_id": "1878", "status": {"power1": 0}, // 当前状态，0代表断开 "event": "manual" // 触发原因如manual/auto }
集成策略
- 在项目中新建一个无需鉴权的API路由（如 /yoyo/callback），用于接收物联平台的POST数据。
- 收到数据后，更新数据库中该设备的状态字段，并可通过WebSocket主动推送给前端页面，实现页面实时刷新。

5. 前端/小程序集成方案

对于微信小程序或Web前端，严禁直接调用设备控制API，因为会暴露AppSecret导致安全问题。正确的项目架构如下：

架构流程

用户操作 -> 2. 前端页面 -> 3. 开发者后端服务器 -> 4. 芯步云API -> 5. AC1-10A设备

5.1 微信小程序代码片段

在前端，只需请求自己的后端接口，示例中使用的API路由类似 /api/control_device，由后端代为签名和请求

6. 调试与排错

使用调试模式：在开发阶段，可在芯步控制台的“开发设置”中开启调试模式。该模式下系统不检查签名和时间戳，可先用Postman测试指令连通性，排除签名错误干扰。
常见错误码排查
- sign invalid：检查时间戳ts是否与服务器时间相差过大（通常不超过5分钟），或MD5生成时的字符串拼接顺序有误。
- device offline：设备未联网或断电，请检查设备电源及网络状态。
利用控制台日志：芯步提供设备详情的“日志”卡片，可在此查看每次下发的指令记录和设备回应，是定位问题的有效手段。

7. 总结

通过本方案，开发者可在不关心底层硬件通信细节的情况下，仅通过标准的HTTP协议将AC1-10A线路控制器集成至各类软件项目中。关键在于：

安全第一：后端签名，严禁前端存储密钥。
状态同步：利用回调机制保障数据一致性。
指令复用：同一套控制代码适用于芯步生态内的多种智能硬件。