怎样二次开发智能照明控制器 4 路以实现自定义联动操作_解决方案

CATALOG

芯步智能照明控制器4路（UNI-KZQ-ZM-4-16A）的核心价值在于其完全开放的HTTP接口——这意味着你可以摆脱厂商App的限制，将照明控制深度集成到自己的业务系统中。以下方案将从接口协议、签名机制、指令构造到联动逻辑落地，提供一个完整的技术实现路径。

1. 技术与接口概述

芯步智能照明控制器4路（型号：UNI-KZQ-ZM-4-16A）是一款支持WiFi直连的工业级智能控制设备，提供了完全开放的API（应用程序接口）供开发者进行二次开发。

在开始二次开发之前，理解其开放接口的架构至关重要：

通信协议：设备使用标准HTTP/HTTPS协议进行通信。这意味着开发者可以使用任何支持HTTP请求的编程语言（如Python、Java、Node.js、PHP、Go）或工具（如Postman）进行调用。
核心优势：支持私有化部署和纯局域网（LAN，Local Area Network）环境运行，数据安全可控，无需经过厂商云中转（如果配置为直连模式）。
实时性：官方数据显示，命令下发到设备响应的延迟约为80-120毫秒。

开发前置条件：

在芯步开发者平台注册账号，获取 AppID 和 AppSecret（用于身份认证）。
将设备上电并配置WiFi（2.4GHz），获取设备唯一ID（Device ID）。

2. API认证机制与签名生成详解

为了保证控制指令的安全性，API使用了动态签名机制。每一次请求都需要计算一个特定的签名（Sign）。

请求地址结构：http(s)://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}

参数说明：

{AppId}：平台生成的唯一应用ID。
{ts}： Unix时间戳（秒级）。用于防止重放攻击，通常服务器会校验时间戳的有效范围（如5分钟内有效）。
{sign}：消息签名。

签名算法（核心逻辑）：根据官方文档及示例，签名规则如下

将 AppSecret 进行一次MD5加密，得到 Secret_MD5 = MD5(AppSecret)。
拼接字符串：将 Secret_MD5 与时间戳 ts 直接拼接（无连接符，视具体SDK而定，通常为直接拼接或使用:，示例代码多为直接拼接）。
再次MD5：将拼接后的字符串再次进行MD5加密。
最终得到签名：Sign = MD5( Secret_MD5 + ts )

代码示例（Python实现）：

3. 核心控制指令集：实现“自定义联动”的基础

要实现自定义联动，必须熟练掌握order参数的构造。该设备支持单路、批量以及时序控制。

数据格式Content-Type: application/json请求Body结构{"device": "设备ID", "order": {...}}

以下是实现联动的几种关键指令模式：

3.1 单路独立控制（基础模式）

适用于最基本的联动逻辑，如传感器触发特定灯亮。

3.2 批量同步控制（组合模式）

适用于场景联动，如“观影模式”下关闭所有灯光。

场景类型	执行逻辑	示例命令（线路 1 与 3）
单路控制	改变单一线路状态	`{"power1":1}`
全开/全关	多路批量控制	`{"batch":{"relay":[1,3],"power":0}}`
脉冲/点动	先通后断（模拟按键）	`{"point":{"relay":[1],"interval":500}}`
复位/重启	先断后通	`{"reset":{"relay":[2],"interval":1000}}`

3.3 时序脉冲控制（高级联动模式）

这是实现自定义联动的核心。如果你希望灯光与门禁、传感器或安防系统联动，往往需要模拟“点动”或“脉冲”信号。

模式一：先通后断 (Point)
- 场景：按一下门铃，楼道灯亮起30秒后自动关闭。
- 命令
  { "device": "xxx", "order": {"point": {"relay": [1], "interval": 30000}} }
- 解析：继电器先闭合（通电），持续30秒（30000毫秒）后自动断开。
模式二：先断后通 (Reset)
- 场景：远程重启挂载在控制器上的网络设备（如路由器）。
- 命令
  { "device": "xxx", "order": {"reset": {"relay": [2], "interval": 5000}} }
- 解析：继电器先断开（断电），5秒后重新闭合（通电）。

4. 实战：二次开发设计与代码实现

为了构建“自定义联动操作”，通常需要一个 “业务逻辑层” （Middleware/Server）来监听各类触发源（如温湿度传感器、人体红外、闹钟时间）并通过API调用控制器。

4.1 Node.js 实现示例（兼容性与通用性强）

Node.js 的非阻塞 I/O 特性非常适合作为设备联动中枢。本示例展示如何封装一个通用的设备控制函数。

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

class YoYoController {
    constructor(appId, appSecret) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.hostname = 'api.thingboot.com';
    }

// 生成签名
    _generateSign(ts) {
        const md5Once = crypto.createHash('md5').update(this.appSecret).digest('hex');
        const rawSign = md5Once + ts;
        return crypto.createHash('md5').update(rawSign).digest('hex');
    }

// 核心:向设备发送命令
    controlDevice(deviceId, order) {
        const ts = Math.floor(Date.now() / 1000);
        const sign = this._generateSign(ts);
        const path = `/${this.appId}/device/control/?sign=${sign}&ts=${ts}`;

const postData = JSON.stringify({
            device: deviceId,
            order: order
        });

const options = {
            hostname: this.hostname,
            path: path,
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Content-Length': Buffer.byteLength(postData)
            }
        };

req.write(postData);
        req.end();
    }
}

// ----- 自定义联动场景示例 -----
const controller = new YoYoController('YOUR_APP_ID', 'YOUR_APP_SECRET');
const deviceID = '820720';

// 场景 1:自定义模式 - 离家模式 (一键全关)
function activateAwayMode() {
    console.log('Executing Away Mode: Turning off all lights.');
    controller.controlDevice(deviceID, { "batch": { "relay": [1, 2, 3, 4], "power": 0 } });
}

// 场景 2:走廊灯延时联动 (自动关灯)
function triggerCorridorLight() {
    console.log('Motion detected. Turning on light for 30 seconds.');
    // 重点:利用 point 命令实现"开灯->延时->关灯"的自动化，无需编写定时器代码
    controller.controlDevice(deviceID, { "point": { "relay": [1], "interval": 30000 } });
}

// 场景 3:雨感联动 (雨天自动关闭窗户/晾衣架... 假设接在回路3)
function weatherTrigger(isRaining) {
    if(isRaining) {
        controller.controlDevice(deviceID, { "power3": 0 }); // 关闭
    } else {
        controller.controlDevice(deviceID, { "power3": 1 }); // 打开
    }
}

// 执行示例
activateAwayMode();

4.2 PHP 实现示例

如果你的后端是基于 PHP 的，可以利用 cURL 库进行实现。这在对接微信小程序或传统 Web 管理系统时较为常见。

<?php
function control_device($device_id, $order_data) {
    $app_id = "YOUR_APP_ID";
    $app_secret = "YOUR_APP_SECRET";
    $ts = time();

// 签名计算
    $md5_once = md5($app_secret);
    $sign = md5($md5_once . $ts);

$url = "https://api.thingboot.com/{$app_id}/device/control/?sign={$sign}&ts={$ts}";

$post_fields = array(
        'device' => $device_id,
        'order' => $order_data
    );

$ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post_fields));
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));

$response = curl_exec($ch);
    curl_close($ch);

return $response;
}

// 调用:呼吸灯或流水灯效果 (间隔1秒循环开灯，需配合外部循环调用，此处仅演示命令)
// 注意:流水灯最好在业务代码中用循环延时调用，或者利用 point 顺序触发，但 HTTP 无状态，业务层做循环。
control_device("820720", json_encode(array("power1"=>1)));
sleep(1);
control_device("820720", json_encode(array("power2"=>1)));
?>

5. 构建复杂联动逻辑的架构

为了实现更高级、去中心化的自定义联动，采用以下架构模式：

5.1 本地闭环联动（低延迟方案）

场景：环境光传感器 + 灯光自动调节。

方案：部署一个本地服务器（如树莓派、NAS或Docker容器）。
逻辑：传感器（通过MQTT或Modbus）上报光照值 -> 本地规则引擎判断是否低于阈值 -> 调用局域网API控制设备。
优势：即使外网断开，联动依然生效。

5.2 Webhook / API 集成（云联动方案）

场景：钉钉/微信直接控制或基于日历的预约。

方案：使用芯步的API配合无服务器云函数（如腾讯云SCF、阿里云FC）。
逻辑：用户在企业微信群发送“开灯” -> 机器人接收消息 -> 触发云函数 -> 调用API。

5.3 定时与场景预设

设备本身支持远程定时任务设置，但若需复杂的循环逻辑，可以在你的服务器端使用 Cron 表达式（Linux定时任务）调用上述 Node.js 或 PHP 代码块。

示例0 8 * * * node /scripts/turn_on_light.js （每天早上8点开灯）。

6. 注意事项与最佳实践

看门狗与状态反馈
- 该API主要执行下行控制。若业务需要强一致性反馈，配合芯步的设备状态查询API或开启消息推送功能（如有），避免因手动关闭开关导致系统状态不同步。
设备ID管理
- 在程序中，设备ID应以配置文件或数据库形式存储，便于批量管理。支持在一个请求中传入多个设备ID（用逗号分隔）进行群控。
负载安全
- 该设备单路最大阻性负载为16A/2200W。进行联动设计时（例如全亮模式），需确认总功率不超过负载上限，必要时在逻辑层加上“互斥锁”（如打开A回路时强制关闭B回路）来保护电路。
签名的时间同步
- 服务器时间必须与标准时间同步。如果时间戳偏移过大，sign 验证会失败。

通过以上方案，开发者可以完全绕过标准App的限制，基于Http协议将该设备深度集成到各类垂直行业应用（如智慧农业、租赁管理系统、智能展厅中控）中。