芯步24路智能线路控制主机（UNI-KZQ-TY-24）提供完整的HTTP API接口，支持24路独立通断控制和批量操作。以下方案涵盖接口鉴权、单路/批量控制实现、私有化部署配置，以及沙盘模型、智能配电等典型应用场景的接入示例。

一、 解决概述

在现代智能化项目中，需要对大量离散设备（如灯光、水阀、电机、沙盘模型指示灯）进行集中管理时，传统的人工操作效率低下且布线复杂。芯步 24路智能线路控制主机 通过提供标准、开放的HTTP API接口，允许开发者通过任何支持HTTP协议的编程语言（如Python、Java、Go、PHP、PHP、C#）或物联网平台，实现对24路继电器的远程独立控制、状态查询以及场景联动。

本方案的目标是指导开发者如何在30分钟内完成从环境准备到代码集成的全过程，实现毫秒级响应的线路控制。

二、 硬件与接口能力

在开始接入前，请确认硬件参数符合项目预期：

• 核心功能：提供24路继电器输出，支持独立控制每一路的“通”与“断”。

• 接口协议：标准HTTP/HTTPS协议，支持JSON数据格式。

• 网络模式：支持公网远程控制（通过云平台转发）和局域网直连控制（私有化部署，无需外网）。

• 负载能力：单路最大支持2200W（阻性负载），总功率不超过4400W，支持交直流小负载，外接触发器可控制大功率设备。

三、 接入流程与API调用详解

本方案采用云平台API接入方式，这是最通用且安全的模式。

1. 准备工作：获取凭证

在芯步开发者控制台完成以下操作：

1. 注册企业/开发者账号。

2. 创建设备实例，获取目标控制器的唯一标识 Device ID （如 820720）。

3. 在“开发设置”中获取 AppID 和 AppSecret，用于生成接口访问签名。

2. 签名机制（鉴权）

为防止接口被恶意调用，所有API请求需携带动态签名。签名生成算法逻辑如下：

• 参数AppSecret（密钥）、ts（当前Unix时间戳，单位秒）。

• 计算公式Sign = md5( md5(AppSecret) + ts)

注：先将AppSecret进行一次MD5加密得到字符串A，再将字符串A与时间戳拼接，最后对拼接串进行MD5加密得到最终签名。

3. 单路独立控制（核心指令）

要实现24路中的任意一路单独开关，需调用设备控制接口。

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

• 请求方式： POST

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

• 请求Body示例

场景1：控制第8路打开

场景2：控制第13路关闭

依据命令集，power1 至 power24 分别对应第1至第24路输出。

4. 批量与联动控制

为提高效率，避免频繁请求，接口支持批量操作命令。

• 场景：一键全开 / 全关使用 batch 命令可以同时控制所有回路。

• 场景：点动模式如果需要实现类似“门铃”或“脉冲触发”（接通2秒后自动断开），可使用 point 命令。以下指令将第6路接通，持续3000毫秒（3秒）后自动断开：

四、 私有化部署与局域网控制

对于不允许数据出园区的项目（如军工、保密会议室、工业产线），该设备支持纯局域网运行。

1. 配置网络：确保控制主机与PC/服务器处于同一局域网网段，设备通过WiFi（2.4GHz）连接路由器。

2. 消息服务器自建：芯步支持私有化部署，可将消息推送目标地址配置为本地服务器的IP。

3. 接口调用：在网络通畅的情况下，局域网内的API调用延迟极低（约10-30ms），且完全与外网隔离，保障数据安全。

五、 典型应用场景案例分析

第一种场景：沙盘模型灯光控制

• 需求：通过一个iPad控制整个城市沙盘模型上24栋建筑的独立灯光。

• 实施方案

  1. 将24路输出分别连接24栋建筑的LED灯带。

  2. 开发简单的Web控制面板，生成24个开关按钮。

  3. 点击按钮时，触发Ajax请求调用 powerX 指令。

  4. 效果：实现单栋点亮、分区点亮或全盘流光效果，替代了传统复杂的PLC编程。

第二种场景：智能配电与能耗管理

• 需求：远程重启机房服务器或控制远端设备电源。

• 实施方案

  1. 将控制器接入机柜PDU或设备电源前端。

  2. 集成API到现有的巡检系统中。

  3. 当系统探测到设备死机时，自动发送指令：{"power5": 0}（断电），等待5秒后发送 {"power5": 1}（通电重启），实现自动化运维。

六、 注意事项与最佳实践

1. 电源容量限制：设备总功率限制为4400W（阻性负载）。若控制大型电机或空调，必须通过交流接触器进行“小控大”，严禁直接带载大功率感性负载，以免烧毁触点。

2. WiFi信号强度：该设备仅支持 2.4GHz WiFi 。若项目环境中2.4G信号干扰严重，采用有线局域网方案或设置AP中继，确保设备在线率。

3. 错误处理：开发时应捕获HTTP返回状态码（如200成功，401签名错误，404设备不在线）。

4. 定时任务：若不想自行编写定时脚本，可直接在芯步控制台为设备设置“定时任务”和“联动任务”，云端会自动按策略下发指令。

通过以上步骤，用户可以快速打通从“应用层”到“物理层”的链路，将24路智能线路控制主机无缝集成到各类商业或工业自动化系统中。