如何接入三路照明智能开关以实现定时自动启停控制_解决方案

CATALOG

一、概述

本文档旨在为开发者提供一套完整的、基于芯步（YoyoIOT）智能硬件开放接口的技术解决方案，用于接入三路照明智能开关，并实现定时自动启停控制。方案适用于智能楼宇、节能办公、家居自动化等场景，允许开发者通过标准的HTTP接口，对三路照明设备进行独立或协同的定时控制。

芯步提供的智能墙壁开关（3路）支持零火/单火安装，可无缝替代传统86型开关。其核心优势在于开放了全面且简单的HTTP API接口，无论您使用哪种编程语言（Python、Java、PHP、Go等）或开发环境（云端SaaS、本地软件、微信小程序），均可快速完成对接。

二、接口基础与鉴权机制

在实现定时控制逻辑前，需先掌握芯步接口的鉴权方式。相比复杂的SDK接入，HTTP接口极大降低了集成成本。

2.1 核心参数准备

每次API调用需携带以下信息以验证权限：

AppId：应用唯一标识，在平台控制台创建应用后获取。
AppSecret：开发者密钥，用于生成动态签名，请妥善保管。
设备ID (Device ID)：目标三路开关的唯一标识，可在控制台设备列表查看。

2.2 签名算法（Authentication）

为防止接口被恶意篡改，所有控制指令需携带动态签名。算法逻辑如下

对 AppSecret 进行一次MD5加密，得到字符串 S1。
获取当前Unix时间戳（秒级），记为 ts。
将 S1 与 ts 拼接，得到字符串 S1 + ts。
对上一步结果再次进行MD5加密，得到最终签名 sign。

注：时间戳 ts 用于防止请求重放攻击，平台会校验时间戳的有效性（通常为5分钟内）。

2.3 请求结构

请求地址http(s)://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}
请求方式POST
数据格式Content-Type: application/json
请求体(Body)
{ "device": "设备ID", "order": { ... } // 具体命令对象 }

三、三路开关的控制指令集

三路智能开关（如智能墙壁开关3路或智能触摸墙壁开关3路）支持三个独立继电器（Channel 1/2/3）的控制。以下是核心的 order 参数构造方法

3.1 基础开关控制

直接控制某一路的开启或关闭，响应速度极快（80-120ms）。

开启第1路 & 关闭第3路
{ "power1": 1, "power3": 0 }
开启所有路
{ "power1": 1, "power2": 1, "power3": 1 }

3.2 高级保持模式（状态锁）

在某些自动化场景中，需要临时锁定用户的手动操作，例如“请勿打扰”模式。利用保持命令，可在下发指令后的一段时间内，强制维持开关状态。

场景：保持第2路为开启状态，即使用户手动关闭，3秒后也会自动重新打开
{ "power2": { "keep": "1", "revert": "3" } }

3.3 脉冲/点动模式

适用于控制门禁电机、排气扇延时关闭等场景。

场景：第1路立刻接通，2秒后自动断开（先通后断）
{ "point1": "2000" } // 数值单位为毫秒
场景：第3路立刻断开，3秒后自动接通（先断后通）
{ "reset3": "3000" }

四、定时自动启停的实现策略

芯步的设备固件本身支持简单的倒计时任务（如上述的 point 命令），但对于复杂的、循环的“定时自动启停”（例如：每天晚上18:00开灯，早上6:00关灯），通常有两种实现路径。

推荐方案：业务层定时任务 + 单次控制指令

由于芯步开放接口的轻量特性，将复杂的定时逻辑放在您的业务服务器上实现是最灵活、可控性最高的做法。以下是具体的架构与实现步骤。

4.1 系统架构图

graph LR
    用户 -> 业务系统(定时任务/规则引擎) : 配置定时策略
    业务系统(定时任务/规则引擎) -> 芯步API : 计算sign并调用接口
    芯步API -> 三路智能开关(设备) : 下发控制指令(开关)
    三路智能开关(设备) -> 照明负载: 执行动作(灯亮/灭)

4.2 定时任务代码示例（Python + APScheduler）

假设我们需要配置两个定时任务：

18:00：开启第1路和第2路。
23:00：关闭所有路。

以下是基于Python的伪代码实现，包含了完整的签名逻辑和指令下发

import hashlib
import time
import requests
from apscheduler.schedulers.background import BackgroundScheduler

# 配置常量
APP_ID = "YOUR_APP_ID"
APP_SECRET = "YOUR_APP_SECRET"
DEVICE_ID = "YOUR_DEVICE_ID"  # 3路开关的设备ID
API_URL_TEMPLATE = "https://api.thingboot.com/{}/device/control/"

def generate_sign_and_ts(secret):
    """生成鉴权所需的签名和时间戳"""
    ts = str(int(time.time()))
    # 第一次MD5
    md5_secret = hashlib.md5(secret.encode()).hexdigest()
    # 拼接并第二次MD5
    sign_str = md5_secret + ts
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    return ts, sign

def control_device(order_cmd):
    """下发控制指令给设备"""
    ts, sign = generate_sign_and_ts(APP_SECRET)
    url = API_URL_TEMPLATE.format(APP_ID)
    params = {
        "sign": sign,
        "ts": ts
    }
    payload = {
        "device": DEVICE_ID,
        "order": order_cmd
    }
    
    try:
        response = requests.post(url, params=params, json=payload, timeout=5)
        print(f"Command sent: {order_cmd}, Response: {response.text}")
    except Exception as e:
        print(f"Error: {e}")

# 业务逻辑函数
def job_evening_on():
    """晚上开灯任务"""
    print("执行晚上18:00开灯任务")
    control_device({"power1": 1, "power2": 1})  # 只开1、2路，3路保持原状

def job_night_off():
    """深夜关灯任务"""
    print("执行23:00关灯任务")
    control_device({"power1": 0, "power2": 0, "power3": 0})

if __name__ == "__main__":
    scheduler = BackgroundScheduler()
    # 设置定时器，使用cron表达式
    scheduler.add_job(job_evening_on, 'cron', hour=18, minute=0)
    scheduler.add_job(job_night_off, 'cron', hour=23, minute=0)
    
    scheduler.start()
    print("定时控制系统已启动...")
    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        scheduler.shutdown()

4.3 利用设备端“状态保持”简化逻辑

在某些场景下，您并不需要复杂的后端定时任务。例如，需要实现“走廊灯点亮5分钟后自动熄灭”。您可以直接下发带延时复位命令，无需在业务层维护定时器

指令{"point1": "300000"} （第1路打开，5分钟=300000毫秒后自动关闭）
优势：命令下发后，即使您的服务器重启，设备依然会在硬件层面完成计时并关闭，可靠性更高。

五、其它集成场景扩展

5.1 微信小程序集成

通过上述同样的API，可以在微信小程序中快速构建控制面板。只需调用 wx.request 方法，计算签名并传递给设备即可。这种方式适合用户手动控制与定时设定的前端界面交互。

5.2 局域网与私有化部署

若您的应用对公网依赖较弱，或处于无互联网环境，芯步支持局域网API和私有化部署。您可以将请求地址指向设备所在局域网内的本地服务器IP，实现更快的响应速度和更高的数据安全性。

六、总结

通过芯步开放的三路照明智能开关HTTP接口，实现“定时自动启停控制”具有以下显著优势：

低门槛：只需标准的HTTP POST请求和简单的MD5签名计算，10分钟内即可完成第一个指令调试。
高灵活性：开发者可自由选择在业务层实现复杂的循环定时（如Cron表达式），或利用设备自带的 point/reset 命令实现简单的硬件级延时。
强稳定性：单次指令响应迅速，且支持状态保持与局域网控制，确保了商业照明、办公节能等严肃场景下的稳定运行。

开发者先通过芯步官方控制台获取 AppId 和 AppSecret，并利用上述示例代码进行快速原型验证。