灯光控制：怎么把8 路智能远程电源控制器接入到项目中_解决方案

CATALOG

芯步的8路控制器通过标准HTTP API开放控制能力，接入流程清晰：先在控制台获取凭证，再按签名规则调用接口即可实现单路/多路/批量控制。以下是完整的工程化接入方案。

1. 产品理解与适用场景分析

芯步的 8路智能远程电源控制器（以 UNI-KZQ-TY-8 / UNI-KZQ-AC-8 为代表）是一款支持远程网络控制的继电模块设备。其核心价值在于提供了 8 个相互隔离的通道，允许开发者通过 HTTP 请求独立控制每个端口的通断。

工业级负载能力：该设备支持最高 4400W 阻性负载（或 700W 感性负载）。这意味着它不仅仅是控制灯泡，还能直接驱动电机、电磁阀、服务器电源等工业设备。
双电压版本选择
- DC 12V 版：通常用于沙盘模型、自动售货柜、低电压信号控制场景。
- AC 85-265V 版：直接接入市电，适用于共享自习室（控制插座）、老旧厂房照明改造。
接入优势：该产品采用 WiFi 2.4G 直连，无需网关（Hub），简化了网络拓扑，降低了项目硬件成本。

2. 核心接口协议深度解析

该设备的核心竞争力在于其开放的 HTTP API 接口。这意味着无论你的后台是用 Java、Python、PHP 还是 Node.js 编写，只要支持 HTTP 协议，都能轻松集成。

2.1 鉴权机制

为了防止接口被恶意调用，协议采用了动态签名（Sign）机制。这是一个标准的 MD5 嵌套加密流程：

签名生成规则（Sign）：

将 AppSecret 进行一次 MD5 加密得到 encoded_sec。
将 encoded_sec 与当前 Unix 时间戳 ts 直接拼接成字符串。
将拼接后的字符串再进行一次 MD5 加密，得到最终的 Sign。
公式Sign = md5( md5(AppSecret) + ts )

时间戳有效期：服务器会校验 ts 参数，通常允许一定的误差范围（如 5 分钟），这能有效防止网络抓包后的“重放攻击”。

2.2 设备指令集

该设备通过 JSON 格式的命令字进行控制，核心参数映射如下表所示：

控制对象	命令字段 (JSON Key)	数值/格式	功能描述
第1路	`power1`	`1` (通) / `0` (断)	控制端口1的通断
第2路	`power2`	`1` / `0`	控制端口2的通断
...	...	...	以此类推至第8路
全控	`batch`	`255`(全开)/`0`(全断)	一次性控制所有端口
互锁	`point`	`"1,4"`	先断开1再接通4（电机正反转切换）

3. 实战对接流程

3.1 环境准备与配置

在编写代码前，需要进行设备的物理入网配置：

上电：给控制器供电（AC版接220V，DC版接12V适配器）。
配网：使用芯步提供的“设备配置”工具或小程序，将设备连接至项目所在的局域网 Wi-Fi（注意：仅支持 2.4GHz）。
获取凭证：登录芯步控制台，获取 AppID 和 AppSecret，并记下设备列表中生成的 DeviceID（通常是一串数字）。

3.2 核心代码实现（Python 示例）

以下是一个工程化的 Python 函数，用于对接该控制器。你可以将其封装在项目的任何业务逻辑层中。

import hashlib
import time
import requests
import json

class YoYoLightController:
    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):
        """生成动态安全签名"""
        # 第一步:md5(AppSecret)
        step1 = hashlib.md5(self.app_secret.encode()).hexdigest()
        # 第二步:拼接 ts
        step2 = step1 + str(ts)
        # 第三步:md5(step2)
        sign = hashlib.md5(step2.encode()).hexdigest()
        return sign

def control_channel(self, channel, status):
        """
        控制指定通道
        :param channel: 1-8
        :param status: True(开) / False(关)
        """
        ts = int(time.time())
        sign = self._generate_sign(ts)
        
        # 构建请求参数
        params = {
            'sign': sign,
            'ts': ts
        }
        
        # 构建命令体，例如 {"power1": 1}
        command_key = f"power{channel}"
        command_value = 1 if status else 0
        payload = {
            "device": self.device_id,
            "order": {command_key: command_value}
        }
        
        # 发起POST请求
        response = requests.post(self.api_url, params=params, json=payload)
        return response.json()

def batch_control(self, status):
        """一键全开或全关"""
        ts = int(time.time())
        sign = self._generate_sign(ts)
        
        payload = {
            "device": self.device_id,
            "order": {"batch": 255 if status else 0}
        }
        
        response = requests.post(self.api_url, params={'sign': sign, 'ts': ts}, json=payload)
        return response.json()

# ---------- 项目调用示例 ----------
if __name__ == "__main__":
    # 1. 初始化控制器（填入后台获取的密钥）
    ctrl = YoYoLightController(
        app_id="你的AppID", 
        app_secret="你的AppSecret", 
        device_id="你的设备ID"
    )
    
    # 2. 业务场景:打开第3路灯光
    result = ctrl.control_channel(3, True)
    print(f"灯光控制结果: {result}")
    
    # 3. 业务场景:关闭所有灯光（下班模式）
    # result = ctrl.batch_control(False)

3.3 局域网高可用方案（低延迟场景）

如果你的项目运行在同一个局域网内（如工厂车间、展览馆），可以考虑使用 局域网直连 模式。

原理：通过芯步的接口查询设备的局域网 IP 地址，直接向该 IP 发送 HTTP 命令。
优势响应速度极快（<50ms），且不依赖外网宽带，断网情况下也能在局域网内稳定控制。
实现：在获取设备详情接口中，通常包含 local_ip 字段，将请求域名替换为该 IP 地址即可（需确认设备支持直接IP调用）。

4. 高级联动策略

在真实的项目场景中，灯光通常不是独立存在的，需要与传感器联动。

推荐架构模式将这 8 路控制器视为“执行器”，结合芯步生态内的 传感器类产品（如人体存在雷达、光照度传感器）。

联动逻辑流程

数据上行：光照传感器检测到环境照度低于 10 lux，且雷达传感器探测到“有人”。
业务处理：你的后端服务器接收到传感器的 Webhook 推送。
指令下发：触发上述 control_channel 函数，向 8 路控制器的第 1 路发送 {"power1": 1}。

安全由于该控制器直接控制强电，在项目中增加 二次确认机制。例如：在远程控制开启大功率设备前，先通过前置传感器（如震动、电流检测）判断设备是否处于可运行状态，确保安全。

5. 常见问题排查

设备掉线怎么办？
- 产品支持自动重连。在项目中增加“心跳检测”功能，若 ping 不通设备，通过接口重新配置 WiFi 或触发设备重启。
命令下发成功但继电器没反应？
- 检查负载类型。如果是 LED 节能灯（感性负载），实际负载值需控制在额定值的 70% 以内，否则可能产生冲击导致继电器粘连。
- 确认 JSON 格式是否正确。例如 power10 是无效命令，命令必须是 power1 的格式，注意不要写错数字。
如何实现定时任务（如路灯定时开关）？
- 方式一：在芯步控制台直接设置设备的“定时任务”，即使服务器宕机，设备本体也会执行。
- 方式二：在你的业务系统中增加 Cron 定时任务，定时调用上述 API。

通过以上步骤，你可以将芯步的 8 路控制器无缝集成至现有的楼宇自控、智慧农业或工业自动化项目中。