怎么对接4 路交流输出控制器来实现远程定时任务_解决方案

CATALOG

这是一份针对芯步 4路交流输出控制器（型号：UNI-KZQ-AC-4） 的对接方案。该方案的目标是指导开发者如何利用设备开放的 HTTP 接口，快速集成远程定时控制功能，适用于自习室电源管理、广告牌定时开关、工厂设备自动化等场景。

1. 背景与概述

在许多商业和工业场景中，经常需要对多路交流用电设备（如灯光、广告牌、自助售货机、灌溉水泵）进行精准的定时控制。传统的定时插座往往功能单一，难以联网管理和批量操作。

芯步推出的 4路交流输出控制器 提供了一种低成本、高效率的解决方案。它不仅支持4路独立大功率（10A）继电器控制，更重要的是开放了标准的 HTTP 接口。通过对接这些接口，开发者可以将其无缝集成到现有的 Web 端、移动端或 SaaS 平台中，无需网关，仅通过 Wi-Fi 即可实现远程单控、批控以及本文重点讲解的 定时任务 功能。

2. 准备工作

在开始对接前，请确保具备以下条件：

硬件设备：芯步“4路智能交流控制器”（型号：UNI-KZQ-AC-4）一台，并已通过官方小程序或控制台完成 Wi-Fi 配网。
平台账号：注册芯步官方平台账号，登录控制台获取以下必要参数：
- AppID：应用的唯一标识。
- AppSecret：接口调用的密钥（用于生成签名）。
- Device ID：目标设备的唯一ID（可在控制台查看）。
开发环境：任意支持 HTTP 协议的开发语言环境（如 Python、Node.js、Java、Go 或纯命令行 cURL）。

3. 接口鉴权与基础通信机制

芯步接口采用标准的 HTTP POST 请求，通信过程均需携带签名以确保安全。

3.1 核心参数说明

请求地址https://api.thingboot.com/{AppID}/device/control/
鉴权方式：URL 参数签名（Query String）。
数据格式multipart/form-data 或 application/json（依命令格式而定）。

3.2 签名生成规则

为了安全，所有请求必须包含 sign 和 ts（时间戳）参数。签名算法如下：

将 AppSecret 进行一次 MD5 加密：secret_md5 = md5(AppSecret)
拼接字符串并计算最终签名：sign = md5( secret_md5 + ts )
注意：此处为字符串拼接，非哈希直接拼接，实际开发请请一定要参考官方 SDK 或最新文档（如官方开放平台即 ThingBoot Open 所示）。典型逻辑是双重 MD5 加盐。

4. 实现“定时任务”的设计

由于该 4 路控制器硬件本身主要执行即时指令，实现“远程定时任务”的核心逻辑应在您的云端服务器或应用后端完成。架构流程如下：

任务存储：在您的业务数据库中，存储用户设定的定时规则（例如：每周一至周五 8:00 开启第1路，18:00 关闭第1路）。
定时触发：您的后端服务需运行一个定时任务（如 Linux Crontab、Quartz 或 SchedulerX），每分钟或每秒扫描一次数据库，找出“当前时间点需要执行”的任务。
指令下发：当触发条件满足时，后端服务调用芯步的 设备控制接口，向指定的 4 路控制器发送继电器通断指令。

5. 关键 API 调用详解

以下将结合代码示例，详解如何通过接口控制该控制器。

5.1 单路独立控制

场景需求：上午 9:00 准时开启 1 号灯，下午 18:00 准时关闭 1 号灯。控制指令：通过修改 power1 的键值实现。

开启第1路order 参数为 {"power1":1}
关闭第1路order 参数为 {"power1":0}

以此类推，power2、power3、power4 分别控制其余三路。

5.2 批量与组合控制

场景需求：午休时间（12:00-13:00）自动关闭所有设备（1-4路），以节约能源。

批量关闭所有：使用 batch 参数可以一次性控制多个继电器，减少网络请求次数。
{ "batch": { "relay": [1, 2, 3, 4], "power": 0 } }
点控（先通后断）：对于需要复位或临时触发的设备（如门禁、警铃），可以使用 point（先接通后再自动断开）。
{ "point": { "relay": [1], "interval": 2000 // 单位:毫秒，即打开2秒后自动关闭 } }

参考其他控制指令如 reset（先断后通）等，参见产品手册。

5.3 Node.js 后端定时任务示例

假设您使用 Node.js 编写后端，需要实现“每天 8:00 打开第2路”。

// 使用 node-cron 作为定时触发器
const cron = require(‘node-cron‘);
const crypto = require(‘crypto‘);
const axios = require(‘axios‘);

// 配置参数
const APP_ID = ‘Your_App_ID‘;
const APP_SECRET = ‘Your_App_Secret‘;
const DEVICE_ID = ‘Your_Device_ID‘;

// 生成签名
function generateSign(ts) {
    const md5Secret = crypto.createHash(‘md5‘).update(APP_SECRET).digest(‘hex‘);
    const signStr = md5Secret + ts;
    return crypto.createHash(‘md5‘).update(signStr).digest(‘hex‘);
}

// 下发命令函数
async function controlDevice(orderJson) {
    const ts = Math.floor(Date.now() / 1000);
    const sign = generateSign(ts);
    
    const url = `https://api.thingboot.com/${APP_ID}/device/control/?sign=${sign}&ts=${ts}`;
    
    // 注意:根据芯步接口规范，通常使用 Form Data 格式
    const params = new URLSearchParams();
    params.append(‘device‘, DEVICE_ID);
    params.append(‘order‘, JSON.stringify(orderJson));

try {
        const response = await axios.post(url, params);
        console.log(‘控制成功:‘, response.data);
    } catch (error) {
        console.error(‘控制失败:‘, error.response.data);
    }
}

// 定时任务配置:每天早上 8:00:00 执行
cron.schedule(‘0 8 * * *‘, () => {
    console.log(‘执行定时任务: 开启第2路‘);
    // 发送开启命令
    controlDevice({ "power2": "1" });
});

// 若需在晚上 18:00 关闭，同理可再配置一个定时任务:
cron.schedule(‘0 18 * * *‘, () => {
    console.log(‘执行定时任务: 关闭第2路‘);
    controlDevice({ "power2": "0" });
});

5.4 利用设备输入实现“本地联动定时”

除了云端轮询，该设备硬件支持 4路开关量信号输入。这意味着您可以外接物理按钮或传感器。虽然这不是纯粹的远程定时，但可以借助服务器做中间转换：传感器触发 -> 上报状态给您的服务器 -> 服务器计算延时/条件 -> 服务器下发指令关断。这种机制可以作为云端定时方案的本地补充。

6. 高级应用场景与优化

6.1 跨设备联动

如果您购买了芯步的传感器（如温湿度传感器），逻辑可以更丰富。当传感器检测到温度过高时，您的服务器可以自动触发该4路控制器接通散热风扇。

6.2 状态同步与可靠性

由于 HTTP 是无状态的，在处理重要定时任务（如工厂断电）时：

查询状态：在发送命令前后，可调用查询接口确认设备当前在线状态和继电器状态。
重试机制：如果接口调用超时或返回错误，代码中需实现重试逻辑（最多3次），以确保命令确实送达。

6.3 局域网直连模式（私有化部署）

对于对公网依赖性低或安全性要求比较高的内网环境，该控制器支持私有化部署。您可以将服务器部署在本地局域网，设备直接通过内网 IP 调用接口，实现极低延时的控制。

7. 总结

通过对接芯步 4 路交流控制器的 HTTP 开放接口，您可以构建一个稳定、灵活的远程定时控制系统。核心方案归纳为三点

接管时序：将“定时”逻辑部署在您的业务服务器上，而非设备固件。
封装 API：通过签名鉴权后，发送标准的 {"powerX":0/1} 或 batch 指令。
业务闭环：结合实际业务场景（收银、打烊、预热），配置对应的 Cron 表达式或日历调度。

该方案无需网关，开发接入门槛低，是目前实现远程工业级交流设备定时控制的高效路径。如需具体的接口签名代码示例，请参考开放平台的 C 语言或 Node.js Demo。