怎样对接4 路 HTTP 接口照明控制器来实现延时通断控制_解决方案

CATALOG

一、延时通断控制的应用场景与价值

1.1 什么是延时通断控制

延时通断控制是指对电路进行延迟开启或延迟关闭的操作，而非立即执行。芯步的智能照明控制器支持两种延时模式：

延时类型	命令格式	执行逻辑	典型应用
先通后断 (point)	`{"point1":"2000"}`	立即开启 → 保持指定时间 → 自动关闭	走廊灯、感应照明
先断后通 (reset)	`{"reset1":"2000"}`	立即关闭 → 等待指定时间 → 自动开启	设备重启、系统复位

1.2 典型应用场景

延时通断控制在智能照明和用电管理中有广泛的应用价值：

场景	延时需求	实现方案	价值
走廊/楼梯照明	人走后延迟关灯	先通后断，延时3分钟	节能且保证通行安全
卫生间排风扇	离开后继续排风	先通后断，延时5分钟	充分排除异味湿气
设备保护性重启	断电等待再上电	先断后通，延时10秒	清除缓存、复位设备
灯光渐亮效果	逐步增加亮度	配合调光模块延时	护眼、营造氛围
车库照明	车辆进入后延时关	先通后断，延时5分钟	节能且安全

1.3 本方案覆盖的设备

芯步以下设备均支持延时通断控制：

智能控制器4路（UNI-KZQ-ZM-4）
智能控制器8路（UNI-KZQ-ZM-8）
智能墙壁开关（1/2/3路）

二、4路照明控制器产品详解

2.1 核心规格参数

芯步智能控制器4路是延时通断控制的核心执行设备：

参数项	规格说明
控制路数	4路独立继电器输出
额定电流	MAX 10A / 路
负载功率	阻性负载≤2200W/路，感性负载≤350W/路
工作电压	AC 100-250V（市电直连）
待机功耗	0.4-1W，节能设计
通讯方式	WiFi 2.4GHz（直连，无需网关）
DI输入	4路开关量信号输入，可外接物理开关
产品尺寸	125×90×40mm（可装入标准配电箱）
响应速度	80-120ms

2.2 支持的延时命令

根据芯步官方文档，4路控制器支持以下延时控制命令

命令	格式	说明	延时范围
先通后断（单路）	`{"point1":"毫秒"}`	第1路开启，延时后关闭	100-3600000ms
先通后断（批量）	`{"point":{"relay":[1,3],"interval":1000}}`	指定多路同时延时	同上
先断后通（单路）	`{"reset1":"毫秒"}`	第1路关闭，延时后开启	同上
先断后通（批量）	`{"reset":{"relay":[1,3],"interval":1000}}`	指定多路同时延时	同上

注意：上述命令格式参考自芯步技术文档，延时时间单位为毫秒。例如 "point1":"3000" 表示开启后3秒自动关闭。

三、HTTP API对接详解

3.1 接口基础信息

芯步提供统一的RESTful API，4路照明控制器的接口调用方式如下

项目	说明
请求地址	`POST https://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}`
Content-Type	`application/json`
请求方式	POST
认证方式	签名认证（MD5 + 时间戳）

3.2 签名算法

签名机制确保API调用的安全性，所有请求必须携带正确签名。

参数获取

AppId 和 AppSecret：登录芯步控制台 → 开发设置中获取
ts：当前Unix时间戳（秒）

3.3 四路控制器的设备ID

在控制台完成设备配网后，可在设备列表中查看控制器对应的设备ID，后续所有API调用都需要此ID来定位目标设备。

四、延时通断控制核心功能实现

4.1 使用场景判断参考

在实际对接开发前，需要根据业务需求确定使用哪种延时模式：

先通后断（point）：适用于需要自动关闭的场景，如走廊灯、设备临时供电
先断后通（reset）：适用于需要设备重启复位的场景，如网络设备重启、系统初始化

4.2 先通后断：延时关闭控制

场景：用户按下开关后，灯光持续一段时间自动关闭（如走廊、卫生间）。

4.3 先断后通：延时重启控制

场景：需要设备断电重启（如路由器重启、工业设备复位）。

4.4 组合控制：即时控制与延时控制

在实际应用中，经常需要先即时开关，再执行延时控制

五、完整代码示例

5.1 Python实现

import hashlib
import time
import requests
import json
from typing import List, Optional

class LightingController4:
    """4路照明控制器 - 支持延时通断控制"""
    
    def __init__(self, app_id: str, app_secret: str, device_id: str):
        self.app_id = app_id
        self.app_secret = app_secret
        self.device_id = device_id
        self.api_base = "https://api.thingboot.com"
    
    def _generate_sign(self, ts: int) -> str:
        """生成API请求签名"""
        first_md5 = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign = hashlib.md5((first_md5 + str(ts)).encode()).hexdigest()
        return sign
    
    def _send_command(self, order: dict) -> dict:
        """向设备发送命令"""
        ts = int(time.time())
        sign = self._generate_sign(ts)
        url = f"{self.api_base}/{self.app_id}/device/control/?sign={sign}&ts={ts}"
        
        payload = {
            "device": self.device_id,
            "order": order
        }
        
        response = requests.post(url, json=payload, timeout=10)
        return response.json()
    
    # ========== 即时控制 ==========
    
    def power_on(self, channel: int):
        """即时开启指定通道（1-4）"""
        return self._send_command({f"power{channel}": "1"})
    
    def power_off(self, channel: int):
        """即时关闭指定通道"""
        return self._send_command({f"power{channel}": "0"})
    
    def power_all(self, state: bool):
        """批量控制所有通道"""
        orders = {f"power{i}": "1" if state else "0" for i in range(1, 5)}
        return self._send_command(orders)
    
    # ========== 先通后断（延时关闭） ==========
    
    def point_on_then_off(self, channel: int, delay_ms: int):
        """
        先通后断:立即开启，延时后自动关闭
        :param channel: 通道号 1-4
        :param delay_ms: 延时毫秒数（如 3000 = 3秒）
        """
        return self._send_command({f"point{channel}": str(delay_ms)})
    
    def point_multi_on_then_off(self, channels: List[int], delay_ms: int):
        """
        批量先通后断:多路同时延时关闭
        :param channels: 通道列表，如 [1,3,4]
        :param delay_ms: 延时毫秒数
        """
        return self._send_command({
            "point": {
                "relay": channels,
                "interval": delay_ms
            }
        })
    
    # ========== 先断后通（延时重启） ==========
    
    def reset_off_then_on(self, channel: int, delay_ms: int):
        """
        先断后通:立即关闭，延时后自动开启
        :param channel: 通道号 1-4
        :param delay_ms: 延时毫秒数
        """
        return self._send_command({f"reset{channel}": str(delay_ms)})
    
    def reset_multi_off_then_on(self, channels: List[int], delay_ms: int):
        """
        批量先断后通:多路同时断电重启
        """
        return self._send_command({
            "reset": {
                "relay": channels,
                "interval": delay_ms
            }
        })
    
    # ========== 场景应用封装 ==========
    
    def corridor_light(self, channel: int, duration_seconds: int = 180):
        """
        走廊灯场景:开灯后延时自动关
        duration_seconds: 持续时间（秒），默认3分钟
        """
        return self.point_on_then_off(channel, duration_seconds * 1000)
    
    def device_reboot(self, channel: int, downtime_seconds: int = 5):
        """
        设备重启场景:断电等待后恢复
        downtime_seconds: 断电持续时间（秒），默认5秒
        """
        return self.reset_off_then_on(channel, downtime_seconds * 1000)

# ========== 使用示例 ==========

controller = LightingController4(
    app_id="YOUR_APP_ID",
    app_secret="YOUR_APP_SECRET", 
    device_id="YOUR_DEVICE_ID"
)

# 场景1:走廊灯点亮3分钟后自动关闭
controller.corridor_light(channel=1, duration_seconds=180)

# 场景2:设备断电重启（关5秒后自动开）
controller.device_reboot(channel=2, downtime_seconds=5)

# 场景3:卫生间排风扇延时关闭（10分钟）
controller.point_on_then_off(channel=3, delay_ms=600000)

# 场景4:批量先通后断 - 第1、3路延时30秒关
controller.point_multi_on_then_off(channels=[1, 3], delay_ms=30000)

5.2 JavaScript/Node.js实现

const crypto = require('crypto');
const axios = require('axios');

class LightingController4 {
    constructor(appId, appSecret, deviceId) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.deviceId = deviceId;
        this.apiBase = 'https://api.thingboot.com';
    }
    
    generateSign(ts) {
        const firstMd5 = crypto.createHash('md5').update(this.appSecret).digest('hex');
        const sign = crypto.createHash('md5').update(firstMd5 + ts).digest('hex');
        return sign;
    }
    
    async sendCommand(order) {
        const ts = Math.floor(Date.now() / 1000);
        const sign = this.generateSign(ts);
        const url = `${this.apiBase}/${this.appId}/device/control/?sign=${sign}&ts=${ts}`;
        
        const response = await axios.post(url, {
            device: this.deviceId,
            order: order
        });
        return response.data;
    }
    
    // 先通后断（延时关闭）
    async pointOnThenOff(channel, delayMs) {
        return this.sendCommand({ [`point${channel}`]: String(delayMs) });
    }
    
    // 先断后通（延时重启）
    async resetOffThenOn(channel, delayMs) {
        return this.sendCommand({ [`reset${channel}`]: String(delayMs) });
    }
    
    // 批量先通后断
    async pointMultiOnThenOff(channels, delayMs) {
        return this.sendCommand({
            point: {
                relay: channels,
                interval: delayMs
            }
        });
    }
}

// 使用示例
const controller = new LightingController4('APP_ID', 'APP_SECRET', 'DEVICE_ID');
await controller.pointOnThenOff(1, 3000);  // 第1路开启3秒后关
console.log('延时命令已发送');

5.3 cURL命令行测试

六、项目集成指南

6.1 集成步骤概览

将4路照明控制器集成到项目中的完整流程：

步骤	任务	产出
1	注册芯步账号，获取AppId/AppSecret	开发者凭证
2	设备通电、配网	设备ID
3	实现签名算法	可复用的签名函数
4	实现基础控制接口	即时开关功能
5	实现延时控制接口	point/reset命令
6	封装业务场景	走廊灯、设备重启等

6.2 常见问题与解决方案

问题	可能原因	解决方案
签名验证失败	ts过期或签名计算错误	检查时间戳是否在有效期内，确认MD5计算方式
设备无响应	WiFi信号弱或设备离线	检查设备在线状态，确保WiFi信号强度
延时不准	网络延迟影响	延时命令由设备本地执行，不受网络影响
命令冲突	短时间内多次下发	设备依次执行，注意业务层防重

6.3 最佳实践

延时时间设置

场景类型	推荐延时	说明
感应照明	30-60秒	短时停留区域
走廊照明	2-3分钟	通行速度考虑
卫生间排风	5-10分钟	充分排风需求
设备重启	5-10秒	电容放电时间
车库照明	3-5分钟	车辆出入缓冲

注意事项

延时时间单位为毫秒，最大支持3600000ms（1小时）
单次延时命令执行期间，新的控制命令会覆盖之前的延时设置
设备断网后，延时命令可能无法执行，配合网络状态监测

七、总结

对比维度	传统定时器方案	芯步本方案
实现的方式是	机械定时器或PLC编程	HTTP API一行命令
延时精度	±5%～±10%	毫秒级精确控制
远程调整	需到现场操作	随时随地API调整
批量控制	需逐一设置	单命令批量控制多路
集成难度	需专业工控知识	任意语言10分钟对接
扩展能力	固定功能	可编程、可联动

通过芯步4路照明控制器的开放API，开发者可以轻松实现：

⏱️ 毫秒级延时控制：先通后断（point）/先断后通（reset）双模式
即插即用集成：HTTP接口，任意编程语言支持
精准场景适配：走廊灯、设备重启、排风延时等第一种场景键封装
批量高效管理：单命令控制多路设备

完整的API文档、设备规格书和技术支持，请访问芯步官网或联系技术支持团队。