怎么对接智能 24 路分体远程线路管理控制器以实现定时任务启停控制_解决方案

CATALOG

基于芯步官方文档中UNI-KZQ-TY-24等控制器产品的开放接口，以下从签名计算、指令构造、定时任务实现到异常处理，给出完整的对接方案。

1. 核心准备：签名计算与请求结构

要实现对接，首先需要理解芯步的API安全机制。所有HTTP请求均需携带签名（sign）和时间戳（ts），以防止接口被篡改或重放攻击。

签名生成逻辑（三步计算）：

将开发者后台获取的 AppSecret 进行一次MD5加密，得到 Secret_MD5。
将 Secret_MD5 与当前Unix时间戳（秒）拼接成字符串。
将拼接后的字符串再次进行MD5加密，得到最终的 sign。

请求示例：

请求地址https://api.thingboot.com/{AppID}/device/control/
Method：POST
HeadersContent-Type: application/x-www-form-urlencoded 或 application/json（视具体命令格式）
Body/Params
- device：设备ID（如：189xxxx）
- order：JSON字符串，即具体的控制指令
- ts：时间戳（Unix秒数）
- sign：按上述规则计算出的签名

注意：若部署在纯局域网环境，该设备支持私有化部署和自建消息服务器，API调用逻辑完全一致，只需更换内网IP地址即可。

2. 单次控制：线路启停指令构造

定时任务的本质是“在特定时间自动执行单次控制指令”。因此，我们需要先掌握单条线路的控制指令格式。

针对智能通用控制器24路（UNI-KZQ-TY-24），线路编号通常从1至24。控制指令遵循以下规则

操作场景	指令内容（order参数）	说明
开启第3路	`{"power3":1}`	将第3路通道接通
关闭第7路	`{"power7":0}`	将第7路通道断开
批量开启	`{"batch":{"relay":[1,2,3],"power":"1"}}`	同时开启1、2、3路
批量关闭	`{"batch":{"relay":[3,4,5],"power":"0"}}`	同时关闭3、4、5路
点动/脉冲	`{"point":{"relay":[6],"interval":500}}`	第6路瞬间接通500ms后断开，类似按一下开关

单次控制逻辑流程系统首先根据当前时间判断需执行哪条任务 -> 构造对应的order指令及签名 -> 调用上述API -> 设备执行线路通断。此步骤通常可在100ms内完成。

3. 定时任务设计

由于定时任务需要在无人工干预下自动执行，采用 “服务端定时器轮询 + API即时下发” 的架构，而非依赖设备本地RTC（实时时钟），这样更易于维护和灵活调整。

架构流程图解：

sequenceDiagram
    participant Admin as 管理后台
    participant Server as 中央服务器/云函数
    participant API as 芯步开放API
    participant Device as 24路控制器硬件

    Admin->>Server: 1. 配置定时策略 (如:每天8:00 开启1-5路)
    Note over Server: 任务持久化存储
    
    loop 每分钟轮询/定时触发
        Server->>Server: 2. 检查当前时间匹配的任务
        alt 时间匹配成功
            Server->>Server: 3. 生成签名 & 指令
            Server->>API: 4. POST /control/ (device=xxx, order={power1:1})
            API->>Device: 5. 下发MQTT/HTTP指令
            Device->>Device: 6. 执行继电器吸合
            Device-->>API: 7. 返回执行成功
            API-->>Server: 8. 返回HTTP 200
            Server->>Admin: 9. 记录操作日志
        end
    end

关键组件说明：

任务存储器：数据库用于存储任务规则，如“任务ID 101：每周一至周五 09：00 开启第1-10路；18：00关闭”。
触发器：使用Linux Crontab、Windows Task Scheduler 或代码中的Quartz/Schedule库，在每分钟或每秒扫描一次任务表。
执行器：即HTTP请求客户端。当“当前时间”大于等于“任务执行时间”且“状态=待执行”时，触发API调用。

4. 代码实战：Python与Java实现案例

基于上述架构，以下是具体的代码实现逻辑。

第一种场景：Python脚本（适用于Flask/Django后端或独立脚本）

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.api_url = f"https://api.thingboot.com/{app_id}/device/control/"

def _generate_sign(self, ts):
        # 实现前面提到的 签名三步计算
        step1 = hashlib.md5(self.app_secret.encode()).hexdigest()
        step2 = step1 + str(ts)
        final_sign = hashlib.md5(step2.encode()).hexdigest()
        return final_sign

def send_command(self, command_dict):
        ts = int(time.time())
        sign = self._generate_sign(ts)
        
        payload = {
            "device": self.device_id,
            "order": command_dict  # 这里传入 {"power1": 1}
        }
        params = {
            "sign": sign,
            "ts": ts
        }
        
        response = requests.post(self.api_url, params=params, data=payload)
        return response.json()

# ---------- 定时任务逻辑 ----------
def scheduled_job_for_lighting():
    controller = YoYoController("YourAppID", "YourSecret", "Device_24R_001")
    
    # 早上8点开灯:开启 1-5 路
    # 构造批量控制指令[citation:5]
    result = controller.send_command({"batch": {"relay": [1,2,3,4,5], "power": "1"}})
    
    if result['code'] == 0:
        print(f"[SUCCESS] {time.ctime()} 定时开灯成功")
    else:
        print(f"[ERROR] 控制失败: {result['msg']}")

# 假设这是一个Cron触发器
# scheduled_job_for_lighting()

第二种场景：Java（SpringBoot）

import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;
import java.security.MessageDigest;
import java.util.HashMap;
import java.util.Map;

public class DeviceService {
    private String appId = "YourAppID";
    private String secret = "YourSecret";
    private String deviceId = "Device_24R_001";

private String genSign(String secret, long ts) throws Exception {
        MessageDigest md = MessageDigest.getInstance("MD5");
        String md5Secret = bytesToHex(md.digest(secret.getBytes()));
        String raw = md5Secret + ts;
        return bytesToHex(md.digest(raw.getBytes()));
    }

public void controlDevice(Map<String, Object> order) throws Exception {
        long ts = System.currentTimeMillis() / 1000L;
        String sign = genSign(secret, ts);

RestTemplate rest = new RestTemplate();
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", appId, sign, ts);
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
        
        // 构建请求体: device=123&order={"power1":"1"}
        String body = String.format("device=%s&order=%s", deviceId, order.toString());
        HttpEntity<String> entity = new HttpEntity<>(body, headers);
        
        ResponseEntity<String> resp = rest.postForEntity(url, entity, String.class);
        System.out.println("控制结果: " + resp.getBody());
    }

// 定时任务方法 (配合@Scheduled)
    // @Scheduled(cron = "0 0 8 * * ?") // 每天8点执行
    public void morningTask() throws Exception {
        Map<String, Object> cmd = new HashMap<>();
        cmd.put("power1", 0); // 假设只控制某一线路断电
        controlDevice(cmd);
    }
}

5. 高级功能与异常处理

5.1 状态反馈与确认

为了确保定时任务执行确实生效，在发送控制命令后，查询一次设备状态进行校验。调用/device/status/接口获取当前线路的通断情况。

5.2 队列与重试机制

在网络不稳定的情况下：

策略：若API调用超时或返回网络错误，应实现随机间隔（或逐次增大间隔）重试（如延迟1秒、2秒、4秒后重试，最多3次）。
防抖：定时任务触发时，先查询数据库该任务上一次执行时间，避免因系统重启或时钟偏移导致的短时间内重复执行。

5.3 私有化部署适配

若在局域网使用（无外网），需在初始化客户端时将api.thingboot.com替换为您配置的自建消息服务器IP。设备在局域网内响应速度更快，延迟可降至毫秒级。

总结

通过以上方案，您可以利用“24路控制器”的HTTP接口，采用标准API签名机制构建稳定的定时控制系统。核心点在于正确生成sign签名以及针对多路设备构造精准的order指令（如powerX、batch等）。先使用Postman等工具验证单次控制指令，再集成到定时任务框架中。