普通灯具系统交流控制：怎么把AC3-10A 计量版智能控制器集成到软件项目中_解决方案

CATALOG

针对“普通灯具系统交流控制”这一具体场景，结合 UNI-TDQ-AC3-10A-P（计量版） 设备，以下是一篇关于如何将其集成到软件项目中的详细解决方案。

1. 概述与适用场景

核心目标：将物理的普通灯具（如路灯、工厂灯、展厅射灯、广告灯箱）改造为可远程控制、状态可视、电量可统计的智能照明系统。
技术路径：采用基于 HTTP 协议的 API 集成 方式。设备直连 WiFi，无需额外网关，通过芯步开放平台或直接局域网下发指令。
适用硬件： UNI-TDQ-AC3-10A-P（10A 计量版 / 型号标识含 -P）。

2. 核心技术架构

设备层： AC3-10A 计量版控制器，串接在灯具的 220V 交流回路上。
网络层：设备连接 2.4GHz WiFi 。
云平台层：芯步开放 API 网关。
应用层：您的现有软件（Web/App/小程序/ERP）。

3. 集成前期准备

硬件安装确认
- 确认额定电流（最大 10A，对应 2200W 阻性负载）。
- 确认信号强度（-60dBm 以上为佳）。
平台账号与密钥
- 注册并登录芯步控制台。
- 在“开发设置”中获取 AppID 和 AppSecret。
设备激活
- 使用配网工具将设备绑定至平台，获取唯一标识 Device ID。

4. 接口集成详解

4.1 API 请求通用规范

请求地址： https://api.thingboot.com/{AppId}/device/control/
认证机制：动态 Sign 签名。
- 算法：sign = md5( md5(AppSecret) + ts )
- 每次请求必须携带实时时间戳 ts，防止重放攻击。

4.2 核心功能：开关控制 (Power Control)

这是最常用的功能，用于控制灯具的点亮与熄灭。

指令详情
- 参数名： power
- 取值： 1 (开启/接通) 或 0 (关闭/断开)。
JSON 示例
{ "device": "1878xxxx", // 替换为实际的设备ID "order": {"power": 1} }

注意：响应时间通常在 80-120ms 之间，可用于实时反馈界面（如开关按钮的状态同步）。

4.3 高阶功能：计量与能耗管理 (Metering Query)

充分利用该设备带“计量版”后缀的特性，实现数据可视化。

指令详情
- 查询今日用电： {"query": "today"}
- 查询总用电量： {"query": "total"}
- 查询过去 3 天日用电量： {"query": "days"}
JSON 示例
// 请求 { "device": "1878xxxx", "order": {"query": "today"} } // 响应(示例) 返回当前已使用的电量(kWh) { "today_energy": 1.23 }
应用场景
- 在软件后端定期轮询（如每小时一次）获取用电数据。
- 在前端 Dashboard 生成用电趋势图表。
- 结合电费单价，自动统计每个回路的照明成本。

4.4 安全功能：过载保护配置 (Overload Protection)

功能：当电流超过设定阈值时自动断电。
配置参数
- high_power_value：触发阈值（瓦特 W），如 2500。
- high_power_time：超过阈值持续多长时间（秒）触发动作。
应用场景：在软件中设置“最大功率限制”，防止灯具短路或线路过热。

5. 消息接收（实时状态同步）

5.1 推送机制（推荐）

设备状态变化（如本地物理按键按下、过载自动跳闸、功率波动）会主动推送至开发者服务器。

协议： HTTP POST。
数据格式
{ "device_id": "xxx", "power": 1, // 当前开关状态 "power_cur": 1.23 // 实时电流 }
开发：需实现回调接口 http://yourdomain.com/api/yoyo_callback，接收数据后实时更新数据库中的设备状态。

5.2 主动查询（轮询）

针对瞬时状态或网络穿透性要求较高的场景，可调用设备查询接口获取最新状态。

6. 软件界面设计

为普通灯具管理软件设计界面时，包含以下三个融合点：

控制卡片：每个灯具对应一个开关按钮，颜色随状态改变（绿色=亮，灰色=灭）。交互上，点击按钮即调用 4.2 节中的 {"power":x} 接口。
能耗看板：在软件后台新增“能耗中心”，利用 4.3 节数据，展示“今日空调节能”、“同比昨日用电”等维度数据。
策略联动：在软件中设置“定时任务”或“循环任务”。
- 示例：每天早上 8:00 发送 {"power":1}；晚上 10:00 发送 {"power":0}。

7. 典型代码集成片段 (Python 示例)

import hashlib
import time
import requests

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

def _generate_sign(self):
        ts = int(time.time())
        # 签名规则参考:md5(md5(app_secret) + ts)
        sign_str = hashlib.md5(self.app_secret.encode()).hexdigest() + str(ts)
        sign = hashlib.md5(sign_str.encode()).hexdigest()
        return sign, ts

def control_light(self, power_status):
        # power_status: 1=开, 0=关
        sign, ts = self._generate_sign()
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        payload = {
            "device": self.device_id,
            "order": {"power": power_status}
        }
        response = requests.post(url, json=payload)
        return response.json()

def get_today_energy(self):
        sign, ts = self._generate_sign()
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        payload = {
            "device": self.device_id,
            "order": {"query": "today"}
        }
        response = requests.post(url, json=payload)
        return response.json().get("today_energy")

# 使用实例
ctrl = YoYoController("YOUR_APP_ID", "YOUR_SECRET", "DEVICE_123")
ctrl.control_light(1)  # 开灯
print(ctrl.get_today_energy())  # 打印今日用电量

8. 风险控制与最佳实践

局域网直连模式：如果您的软件项目运行在工业局域网、无外网环境下，该设备支持私有化部署和局域网发现，可直接通过本地 IP 调用接口，降低延迟并保障数据不外流。
多设备批量控制：接口支持 device 参数传入多个 ID（用逗号分隔），如 "device":"101,102,103"，可一次性关闭所有灯具，显著提升软件响应速度。
固件升级：确保设备固件为最新版本。早期版本或非计量版（UNI-TDQ-AC3-10A 不带 P）在电量统计精度上有差异，若需精确到 0.01kWh，请核对型号是否正确。

通过以上集成，您可以将普通的灯具管理系统升级为具备 “远程控制、电量统计、过载保护” 三大核心能力的 IoT 智能照明系统。