怎么对接12路智能照明控制终端以实现照明设备电源开关控制_解决方案

CATALOG

芯步的12路智能照明控制器采用标准HTTP接口，签名机制简单，无需网关即可直连Wi-Fi。以下方案涵盖接口鉴权、单路/批量控制、定时任务等核心对接场景，也整理了内网部署和常见排错要点。

1. 产品概述与准备

12路智能照明控制器 (型号：UNI-KQZ-ZM-12-16A) 是芯步推出的一款高性能工业/商业级照明控制设备。该设备支持直接接入12路独立的照明回路，单路最大负载可达16A，适用于大型办公区、商场、学校、工厂等多回路集中控制场景。

1.1 核心特性

接口开放性：提供全开放的HTTP API接口，任何支持HTTP请求的编程语言（Java, Python, PHP, Node.js, Go等）均可快速集成。
网络连接：支持Wi-Fi 2.4G直连，无需额外网关，支持局域网纯内网环境运行。
响应速度：指令下发到执行端延迟约为80-120ms。

1.2 对接准备

在开始开发前，请准备以下参数：

AppID（应用ID） ：在芯步IoT控制台的“开发设置”中获取。
AppSecret（开发者密码）：同样在“开发设置”中获取，用于生成签名。
Device ID（设备ID）：设备配网成功后，在控制台设备详情页获取（例如：820720）。
设备配网：给控制器通电，根据产品手册引导将设备接入本地Wi-Fi网络。

2. 接口鉴权机制

芯步的API采用动态签名签名验证，确保接口调用安全。所有控制请求必须携带有效的sign和ts。

2.1 请求地址结构

2.2 签名生成算法

签名的生成规则如下，通过两层MD5加密确保请求合法性：

将AppSecret进行一次MD5加密，得到字符串 encode_secret = md5(AppSecret)。
获取当前Unix时间戳（秒级） ts。
拼接字符串：将 encode_secret 与 ts 直接拼接（无连接符）。
将拼接后的字符串再次进行MD5加密，即为签名sign。

签名计算公式

sign = md5( md5(AppSecret) + ts )

注意：如果在对接测试阶段，可以在“开发设置”中开启“调试模式”。在调试模式下，系统将不校验sign和ts，方便快速验证指令格式。

3. 核心控制对接方案

对接的核心在于构造order参数。针对12路控制器，以下是指令的结构详解。

3.1 请求头与请求体（示例）

Content-Type: application/json
请求体格式:

3.2 单路独立控制

需求：单独打开第1路，单独关闭第12路。字段命名：线路编号对应字段从 power1 到 power12。值为 1（开）或 0（关）。

Order构造示例

3.3 多路批量控制

需求：一键全开或全关。Order构造示例

(提示：使用编程语言中的循环来动态构造此JSON对象，避免手写出错)

3.4 场景模式：脉冲控制（先通后断）

适用场景：控制电铃、卷帘门电机或需要触发信号的设备。指令会使继电器闭合（通电），持续指定毫秒数后自动断开。

命令字段point1 到 point12，值为毫秒（ms）。示例：使第3路通电2秒后自动断开。

3.5 场景模式：状态保持与恢复

适用场景：会议室或公共卫生间，用户按下面板开关后，系统强制在设定时间后恢复指定状态。

命令字段power1 使用对象格式。示例：锁定第5路为关闭状态（保持关），即使用户手动按压开关打开灯光，5秒（revert参数）后系统会自动将其关闭。

keep0 保持关，1 保持开。
revert：恢复时间（秒）。

4. 代码开发示例

以下以 Python 和 Java 为例，演示如何封装请求。

4.1 Python 实现

import requests
import hashlib
import time
import json

class YoyoLightController:
    def __init__(self, app_id, app_secret):
        self.app_id = app_id
        self.app_secret = app_secret
        self.base_url = f"https://api.thingboot.com/{app_id}/device/control/"

def _generate_sign(self, ts):
        # 第一层MD5
        md5_secret = hashlib.md5(self.app_secret.encode()).hexdigest()
        # 拼接后再MD5
        sign_str = md5_secret + str(ts)
        return hashlib.md5(sign_str.encode()).hexdigest()

def control_device(self, device_id, order_dict):
        ts = int(time.time())
        sign = self._generate_sign(ts)

url = f"{self.base_url}?sign={sign}&ts={ts}"
        payload = {
            "device": device_id,
            "order": order_dict
        }
        headers = {'Content-Type': 'application/json'}

response = requests.post(url, headers=headers, data=json.dumps(payload))
        return response.json()

# 使用示例
if __name__ == "__main__":
    # 初始化 (从后台获取)
    app_id = "YOUR_APP_ID"
    app_secret = "YOUR_APP_SECRET"
    device_id = 820720  # 你的12路控制器ID

controller = YoyoLightController(app_id, app_secret)

# 1. 关闭第2路
    res1 = controller.control_device(device_id, {"power2": 0})
    print("关闭第2路:", res1)

# 2. 打开第1、3、5路
    res2 = controller.control_device(device_id, {"power1": 1, "power3": 1, "power5": 1})
    print("批量打开:", res2)

4.2 Java 实现 (使用 OkHttp)

import okhttp3.*;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class YoyoControl {
    private String appId;
    private String appSecret;
    private OkHttpClient client = new OkHttpClient();

public YoyoControl(String appId, String appSecret) {
        this.appId = appId;
        this.appSecret = appSecret;
    }

private String md5(String s) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] digest = md.digest(s.getBytes());
            StringBuilder sb = new StringBuilder();
            for (byte b : digest) sb.append(String.format("x", b));
            return sb.toString();
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException(e);
        }
    }

public void control(String deviceId, String orderJson) throws Exception {
        long ts = System.currentTimeMillis() / 1000L;
        String encodeSecret = md5(this.appSecret);
        String sign = md5(encodeSecret + ts);
        
        String url = "http://api.thingboot.com/" + this.appId + "/device/control/?sign=" + sign + "&ts=" + ts;
        
        String bodyJson = "{\"device\":" + deviceId + ",\"order\":" + orderJson + "}";
        RequestBody body = RequestBody.create(MediaType.parse("application/json"), bodyJson);
        Request request = new Request.Builder().url(url).post(body).build();
        
        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }

// 调用示例
    public static void main(String[] args) throws Exception {
        YoyoControl ctrl = new YoyoControl("YourAppId", "YourAppSecret");
        // 控制第1路开
        ctrl.control("820720", "{\"power1\":1}");
    }
}

5. 私有化部署与网络容灾

在部分对公网依赖较低或安全要求比较高的用户场景中，芯步支持私有化部署方案。

5.1 局域网直连

由于设备直接通过Wi-Fi连接路由器，如果你的控制系统（如本地服务器、工控机）与12路控制器处于同一个局域网段，可以将API请求域名api.thingboot.com替换为设备的本地IP地址（需在路由器中固定设备IP）。

注意：局域网模式下，可能会由于Windows或防火墙策略导致通信失败，先关闭防防火墙测试；同时，如果设备分配的IP发生变化，需要系统重新检测更新，通过ARP绑定或在应用层维护设备IP映射表。

5.2 多Wi-Fi容灾

该控制器支持设定5组Wi-Fi网络。在部署时，可将主路由和备用路由的SSID均配置进设备。当主网络故障时，设备会自动扫描并切换至信号强度最佳的可用网络，极大提高了酒店、场馆等场景下的网络容灾能力。

6. 常见问题排查

问题现象	可能原因	解决方案
返回签名错误	时间戳不对或加密逻辑有误	1. 检查服务器时间是否标准（误差不能太大）。 2. 核对MD5结果是32位小写。
指令下发成功但灯未灭	1. 继电器粘连 2. 线路接成了常闭	1. 听设备内部是否有“哒”的一声；若无，检查设备是否掉线。 2. 检查external wiring（外部接线）是否错误接到了常闭触点。
设备离线	Wi-Fi信号弱	由于设备仅支持2.4G频段，请确认连接的不是5G Wi-Fi。检查现场信号强度，必要时增补AP。
批量控制延迟高	循环单次调用接口导致阻塞	采用“单次请求携带多命令”的方式，而非循环12次调用接口。该设备单次请求即可处理所有12路状态，网络开销仅为一次。

通过上述步骤，开发者可以在数小时内完成“12路智能照明控制终端”与现有业务系统（如楼宇自控系统、能源管理系统）的对接，实现对大型照明场景的智能化控制。