芯步的8路控制箱支持通过HTTP接口进行独立控制和批量操作。以下是分组控制的完整实现方案。

怎样对接8路成品控制箱以实现分组控制模式设置

一、 概述与需求分析

在复杂的物联网控制场景中（如沙盘模型、多功能展厅、智能家居系统），用户往往不希望逐个控制8路继电器，而是需要将不同线路定义为“区域组”（如“灯光组”、“电机组”），实现一键全开/全关或场景联动。

芯步8路成品控制箱（型号：UNI-KZQ-TY-8）提供了开放HTTP API接口，支持JSON格式的命令交互。

本解决方案的目标是指导开发者如何通过对接其开放接口，利用“批量控制”及“分组接口”功能，实现自定义分组控制。

二、 技术准备与鉴权机制

在开始编码对接前，请确认具备以下条件：

1. 硬件设备：已激活并联网的芯步8路控制器。

2. 平台凭证：登录芯步控制台，获取您的 AppID 和 AppSecret。

3. 核心签名算法：所有API请求均需携带动态签名以确保安全。算法规则如下

   • 步骤1：对 AppSecret 进行MD5加密：secret_md5 = md5(AppSecret)

   • 步骤2：拼接时间戳：str = secret_md5 + ts （ts为Unix时间戳，秒级）

   • 步骤3：最终签名：sign = md5(str)

   • API地址https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

注意：若在局域网环境，可支持私有化部署，将API地址替换为本地服务器地址。

三、 对接模式一：基于“批量命令”的软分组（推荐）

这是最直接的方式。如果你需要在一个请求中同时控制第1、3、5路开启，而不影响其他路，可以使用 batch 命令。

1. 接口调用示例

假设我们需要实现“演示模式”：开启奇数线路（1,3,5,7），关闭偶数线路（2,4,6,8）。

请求方式：POSTURLhttps://api.thingboot.com/YourAppID/device/control/?sign=xxxx&ts=xxxx

请求Body (JSON)

逻辑解释

• batch 指令允许你自定义一个继电器数组 relay。

• power:1 代表开启该数组内的线路；power:0 代表关闭。

• 优势：该模式下无需在后端维护分组逻辑，前端直接传参即可，API响应速度极快，适合定时任务或场景面板控制。

2. 自定义分组的逻辑存储

由于 batch 接口本身不存储“组名”，你需要在自己的业务系统中建立“虚拟分组”。

数据表设计参考（JSON格式存储）：

当用户点击“左侧灯光组开启”时，调用业务后端接口，查询该组包含的继电器列表 [1,2,3]，动态构建上述 batch 指令下发。

四、 对接模式二：基于“分组接口”的原生控制

芯步开放平台提供了专门的分组控制接口。该模式需要在物联网控制台预先将设备加入某个分组，通过 group ID 进行控制，无需关心内部继电器数量。

1. 预先设置分组

登录芯步控制台：

1. 进入“设备管理” -> “分组列表”。

2. 创建新分组（例如 “Group_A”）。

3. 将目标8路控制器添加到该分组，系统会返回一个唯一的 Group ID。

2. 执行分组控制

通过API向该分组下发指令，组内的所有设备将同步执行。

请求Body (JSON)

• 场景适配：此模式适合多设备的联动。例如，一键开启“回家模式”：打开控制箱的第1路（大灯），同时打开另一个智能插座的第2路（饮水机）。

• 注意事项：需确保分组内设备指令兼容，若对不支持 power1 的设备下发该指令可能会报错。

五、 特殊模式应用：实现“一键轮流控制”

在某些工业场景（如生产线测试或灯光秀），需要让一组线路按顺序逐个通断，而非同时改变。

利用8路控制箱支持的 point（先通后断）或 reset（先断后通）指令，可以轻松实现流水灯效果或设备轮询。

业务场景：设置分组循环启动模式，每组电机启动间隔1秒。

下发命令

*效果：继电器1先接通 -> 等待1秒 -> 继电器2接通（此时1可能仍为通或断，取决于固件逻辑，通常此模式用于轮流测试）。*

六、 完整对接流程总结

1. 环境搭建

   • 使用小程序或PC控制台为设备配置2.4G WiFi。

   • 获取设备的唯一ID（可在控制台直接查看）。

2. 代码封装

   • 按照签名算法封装HTTP请求库。

   • 确保请求头包含 Content-Type: application/json。

3. 逻辑实现

   • 前端直连：适用于微信小程序或APP，直接携带签名调用API控制单路或批量。

   • 后端中转：适用于SaaS系统，由前端触发 -> 业务后端查询分组关系 -> 拼接 batch 指令 -> 调用芯步API。

4. 测试验证

   • 使用工具（如Postman或Burp Suite）模拟请求。

   • 观察8路控制箱上的指示灯是否按预期亮灭。

七、 常见问题与排错

• 签名错误（sign）芯步的签名机制是 md5(md5(密钥) + ts)。特别注意，是对 AppSecret 做MD5后，拼接字符串 再做MD5，而不是对数值进行相加。

• WiFi配网失败目前仅支持2.4GHz频段。如果在配网模式，需确保手机热点或现场WiFi是2.4G频段。

• 指令报错（Batch 命令无效）请检查JSON格式，relay 必须是一个数组，数字间用逗号分隔，不能是字符串 "[1,2,3]"。

通过上述对接方案，你可以灵活地将芯步的8路控制箱集成到现有的任何软件系统中，实现灵活、高效的分组管理模式。