芯步的智能分体控制器24路开放了标准HTTP接口，单路控制、批量操作、签名验证都有明确的规范。以下从硬件准备、接口协议、命令示例到落地注意事项，给出完整方案。

解决方案：基于芯步开放接口接入智能分体控制器24路

1. 背景与概述

在许多工业自动化和商业管理场景中（如机房监控、智能灌溉、楼宇照明、售货柜），需要对多达24个独立线路的设备进行远程通断控制。传统的人工操作效率低且难以集成。

芯步提供的 智能分体控制器24路 是一款支持 HTTP API 接口的硬件设备。本方案的目标是指导开发者如何利用芯步的开放平台，通过编程方式实现对 24 路线路的精准、高效控制。

2. 硬件与接口准备

在开始开发对接前，需确保硬件环境就绪并获取关键的鉴权信息。

2.1 硬件清单

• 核心设备：芯步智能分体控制器24路 （型号：UNI-KZQ-FT 或 UNI-KZQ-TY-24） 。

• 连接要求

  • 设备需接通 DC 12V 电源。

  • 通过 2.4GHz WiFi 连接至互联网（支持设置5组WiFi优先连接，无需网关）。

  • 确认设备处于在线状态（可通过芯步控制台查看）。

2.2 接口鉴权准备芯步开放平台采用 AppID + Sign签名 的鉴权机制，任何 HTTP 请求都必须携带此签名以验证身份。

以下四个参数是所有 API 调用的基础：

• AppID： 开发者 ID，在控制台的“开发设置”中获取。

• AppSecret： 开发者密码，用于计算签名，请妥善保管。

• ts： 当前 Unix 时间戳（秒），用于防止请求重放攻击。

• Sign： 签名值，计算规则为：Sign = md5( md5(AppSecret) + ts )。

注：在测试阶段，可在控制台开启“调试模式”以临时绕过签名校验，方便快速测试功能。

3. 接口调用逻辑与核心功能实现

本方案主要通过向芯步的 API 服务器发送 POST 请求，服务器将指令转发至目标控制器。

3.1 API 端点

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

• 请求方式： POST

• 请求头： Content-Type: application/json

3.2 功能一：单路线路控制实现对 24 路中的任意一条线路进行独立的“通”或“断”控制。

• 命令参数详解： order 字段为 JSON 字符串，键名为 power1 到 power24，值为 1（接通）或 0（断开） 。

• 请求示例

  • 控制第3路接通

    { "device": "1878", // 替换为实际的设备序列号 "order": {"power3": 1} }

  • 控制第8路断开

    { "device": "1878", "order": {"power8": 0} }

3.3 功能二：批量控制在实际业务中常需一键开启或关闭所有线路（如设备断电维护），通过循环调用单路接口存在网络延迟且效率低。

• 专用命令： 使用 batch 命令配合 power 数组 。

• 请求示例

  • 关闭所有线路

    { "device": "1878", "order": {"batch": {"power": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}} }

    *(数组中按顺序对应 1-24 路的状态值)*

3.4 功能三：场景联动与分组控制如果项目涉及多个控制器（假设有10个机房，每个机房1个控制器），直接控制单个设备管理较为繁琐。

• 高级方案： 利用芯步平台，在控制台将多个控制器或线路组合成一个“分组” 。

• 调用方式： 调用 /group/control/ 接口，传入 group ID 和指令，即可同时控制多个设备的线路状态，实现“一键全关”或“一键布防”。

4. 代码实战：15分钟完成接入

以下提供 Python 和 Bash 两种语言的示例，演示如何封装签名与发送指令。

4.1 签名生成逻辑无论哪种语言，核心逻辑是：

1. 将 AppSecret 进行 MD5 加密，得到 str1。

2. 将 str1 与时间戳 ts 拼接，得到 str2。

3. 将 str2 进行 MD5 加密，得到最终的 Sign。

4.2 Python 接入示例

5. 关键注意事项与排障指南

为了确保方案顺利落地，对接过程中请特别关注以下几个关键点：

• 设备ID准确性： 请请一定要核对设备外壳上的标签或控制台显示的 ID。API 返回 502 错误通常意味着设备 ID 不存在或设备已离线。

• 返回值不等于执行结果： API 返回 {"code":200} 仅代表云端成功接收指令。如果设备处于断网状态，指令将无法执行。对于要求反馈结果的场景，需监听平台的异步消息推送来确认设备实际状态。

• 负载安全限制： 控制器虽有 24 路，但 总负载功率有限制。例如 UNI-KZQ-TY-24 型号，总阻性负载不超过 4400W。控制大功率设备（如电机、空调）时，必须外接交流接触器，严禁直接接入大功率负载，以免烧毁电路板。

• 透传字段 Extra： 业务中若需关联订单号，可在命令中增加 extra 字段（如 {"power1":1,"extra":"ORDER_001"}），平台推送结果时会原样返回，便于业务逻辑闭环。