芯步的智能分体控制箱（16路）提供完整的HTTP API接口，支持设备状态查询、单路/批量控制、参数配置等操作。以下方案涵盖接口对接流程、签名计算、核心命令示例及参数配置管理的最佳实践。

1. 概述

本方案的目标是指导开发者或系统集成商，利用芯步提供的标准 HTTP 开放接口，对 16路智能分体控制箱（如型号：UNI-KZQ-TY-16 或 UNI-KZQ-FT）进行二次开发。

通过本方案，用户可以实现对控制箱每一路输出的独立开关控制、批量控制、状态实时感知以及远程参数配置。该方案适用于智慧工厂设备集中控制、沙盘模型灯光管理、农业灌溉阀门控制及远程机房电源管理等场景。

2. 对接准备

在开始对接前，请确保完成以下硬件及平台准备：

3. 接口鉴权机制

芯步的开放接口采用双重 MD5 加密方式进行身份验证。每一次 API 调用都需要在 URL 中携带动态生成的签名。

签名算法 (Sign) 生成步骤：

1. 将 AppSecret 进行一次 MD5 加密，得到 Secret_MD5。

2. 获取当前的 Unix 时间戳（秒级），记为 ts。

3. 将 Secret_MD5 与 ts 进行字符串拼接，得到 String_Concat。

4. 将 String_Concat 再进行一次 MD5 加密，得到最终的 Sign。

5. 公式Sign = MD5( MD5(AppSecret) + ts )

4. 核心对接流程与命令实现

芯步的核心 API 请求地址为：https://api.thingboot.com/{AppID}/device/control/?sign={Sign}&ts={ts}。所有控制指令均通过 POST 请求发送，Content-Type 为 application/json。

4.1 单路继电器控制

需求：远程关闭第 3 路灯光设备，或开启第 8 路电机。实现：通过 order 参数传递 power{路数} 字段，值 1 代表接通/开启，0 代表断开/关闭。

• 请求示例 (JSON Body)

4.2 参数配置与读取（状态查询）

需求：获取当前 16 路中哪些路是开启的，以便在软件界面同步状态。

方案 A直接读取设备状态虽然主要控制命令是 powerX，但在完整的物联网架构中，使用 设备影子/状态查询接口 或通过控制台预设的 回调/推送机制 来获取最新状态。若需主动查询，通常调用 device/status/ 相关接口，返回的 JSON 中会包含所有 power 键值对。

方案 B远程参数配置（定时与联动）控制箱支持远程配置定时任务。可以通过调用 group/control 或设备详情设置接口，下发配置参数，例如设置某一路在每天 18：00 开启，或者在传感器触发时开启。

4.3 批量与场景控制

需求：一键关闭所有输出（急停场景），或者按特定顺序启动设备。

• 全关操作：遍历 power1 到 power16 设为 0 效率较低，使用 batch 命令。

• 顺序启动：使用 point(先通后断) 或 reset(先断后通) 命令。

  • {“point”: “5,100”} 含义：仅仅执行第5路线路，延迟100毫秒再执行后续指令。

• 批量控制利用 batch 参数可以一次性写入多个线路的状态。

4.4 编程示例（Python）

以下是一个配置完整的 Python 函数，用于控制任意线路的通断：

5. 远程参数配置管理最佳实践

为了实现对 16 路控制箱的高效运维，在应用层实施以下管理策略：

5.1 配置模板化

针对不同场景（如“夏季模式”、“冬季模式”），在您的业务服务器中预设不同的 JSON 配置模板。

• 场景 A（灌溉）power1 开 10 分钟，power5 开 20 分钟。

• 场景 B（照明）power1 至 power10 全开。

• 实现：通过调用 API 下发对应的 order JSON 字符串即可完成场景切换。

5.2 网络稳定性优化

控制箱支持存储多组 WiFi 配置。

• 配置：在设备配网阶段，除了配置当前路由器，配置相邻信号较强的备用 AP。

• 断网重连：系统设计时应考虑网络抖动。下发命令后，应配合设备的状态上报机制确认命令执行成功，而非仅依赖 HTTP 200 状态码。

5.3 分组管理

如果单个项目中使用超过 10 台 16 路控制箱（例如管理 160 台设备）。

• 策略：不要逐台发送指令，利用芯步的 分组控制接口/group/control/。

• 优势：一次 API 调用即可关闭同一组内所有控制箱的所有电源，极大降低服务器负载和响应延迟。

6. 私有化部署与局域网控制

对于数据安全要求比较高的内网环境，芯步的 16 路控制器支持 局域网直连 和 私有化部署。

• 局域网模式：设备支持 MQTT 协议，您可以在本地服务器搭建 MQTT Broker，设备上线后订阅特定 Topic，无需经过广域网即可完成指令下发，实现毫秒级响应。

• HTTP 局域网：若设备与服务器在同一网段，可直接通过设备 IP 地址调用本地 API，完全脱离外网依赖。

7. 总结

芯步的 16 路智能分体控制箱通过标准化、轻量级的 HTTP API，大幅降低了硬件集成的门槛。开发者仅需掌握简单的 AppID + AppSecret 鉴权机制，即可通过 power1 ~ power16 和 batch 等核心命令，实现对强电设备的精细化远程运维与参数配置管理。