怎么对接HTTP接口12路照明控制器以实现12路独立线路控制_解决方案

CATALOG

芯步12路照明控制器提供标准的HTTP API接口，可通过向指定URL发送POST请求实现每路独立开关控制。以下是完整的对接方案，涵盖接口协议、签名算法和各类控制指令。

背景

芯步 12路智能照明控制器（UNI-KZQ-ZM-12-16A） 是一款支持WiFi直连的工业级设备，无需网关即可接入局域网或互联网。其核心优势在于开放了标准的 HTTP API 接口，允许用户通过任何支持HTTP请求的编程语言（如Java、Python、PHP、Go或前端JavaScript）进行二次开发，实现对12路继电器（或16A负载）的独立通断控制。

对接准备

在开始调用接口之前，请确保完成以下准备工作：

设备联网：使用手机APP或Web控制台将设备配置到本地2.4G WiFi网络中，确保设备在控制台显示为“在线”状态。
获取凭证：登录芯步开放平台，在“开发设置”中获取以下三个关键参数：
- AppID：应用的唯一标识。
- AppSecret：用于生成签名，验证身份。
- Device ID：目标12路控制器的设备ID（通常贴于设备外壳或通过控制台获取）。
开发工具：准备好Postman（用于测试）或任意IDE（如VS Code、IDEA）。

接口对接方案

1. 核心接口地址

所有控制命令均通过向以下URL发送 POST 请求实现：

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

参数	位置	说明
`{AppID}`	URL Path	您的应用ID
`{sign}`	URL Query	接口签名，用于防盗用和防篡改
`{ts}`	URL Query	Unix时间戳（秒），用于防重放攻击

2. 签名算法（必读）

为了防止接口被恶意调用，系统开启了签名校验。生成 sign 的步骤如下：

将请求参数（如 device 和 order 的值）拼接成字符串。
拼接时间戳 ts 和 AppSecret。
进行MD5加密。

简易示例（PHP）：

具体生成规则请严格参照芯步官方文档中的“签名生成”章节。

3. 请求头与数据格式

Method: POST
Content-Type: application/x-www-form-urlencoded 或 application/json（推荐前者，简单明了）
Body 参数:

字段	类型	必填	描述
`device`	String	是	12路控制器的设备ID
`order`	String	是	JSON字符串，包含具体的控制指令

注意order 传入的是 字符串化的JSON对象，而非直接传JSON。

“12路独立控制”命令详解

为了实现12路互不干扰的独立控制，需在 order 字段中传入不同的 powerX 参数。

1. 单路独立控制（最常用）

通过指定 power1 到 power12 的值来控制对应继电器吸合或断开。

动作	order 内容 (JSON字符串)	作用对象
打开第1路	`{"power1":"1"}`	第1路照明
关闭第1路	`{"power1":"0"}`	第1路照明
打开第6路	`{"power6":"1"}`	第6路照明
打开第12路	`{"power12":"1"}`	第12路照明

请求示例 (原始HTTP Body):

device=123456789&order={"power3":"1"}

（该请求将独立控制第3路开启）

2. 批量组合控制

若需同时操作多条线路（例如一键关闭所有灯光），请使用 batch 命令。

全开/全关:
- 全开: {"batch":"{\"power\":1}"}
- 全关: {"batch":"{\"power\":0}"}
指定线路操作:
- 打开奇数线路(1,3,5,7,9,11): {"batch":"{\"relay\":[1,3,5,7,9,11],\"power\":1}"}
- 关闭偶数线路(2,4,6,8,10,12): {"batch":"{\"relay\":[2,4,6,8,10,12],\"power\":0}"}

3. 高级场景控制（脉冲/点动）

该控制器还支持“先通后断”功能，非常适合用于脉冲控制或测试线路。

闪烁一次 (所有线路接通500ms后断开):{"point":"{\"interval\":500}"}

代码调用示例：Python

以下是一个使用Python实现第1路和第2路独立开关的完整示例：

import requests
import time
import hashlib
import json

# 配置参数
APP_ID = "YOUR_APP_ID"
APP_SECRET = "YOUR_APP_SECRET"
DEVICE_ID = "YOUR_DEVICE_ID"  # 12路控制器的ID

def control_device(order_cmd):
    """通用控制函数"""
    ts = str(int(time.time()))
    
    # 准备Body参数
    body_data = {
        "device": DEVICE_ID,
        "order": json.dumps(order_cmd)  # 将命令转为JSON字符串
    }
    
    # 生成签名 (签名规则需与官方文档严格对齐，此处为逻辑示例)
    # 具体请查阅官方文档:通常为 body_string + ts + secret 后MD5
    sign_str = f"device={DEVICE_ID}&order={json.dumps(order_cmd)}" + ts + APP_SECRET
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 发起请求
    url = f"https://api.thingboot.com/{APP_ID}/device/control/"
    params = {
        "sign": sign,
        "ts": ts
    }
    
    response = requests.post(url, params=params, data=body_data)
    print(f"状态码: {response.status_code}, 响应: {response.text}")
    return response.json()

# 业务逻辑调用
if __name__ == "__main__":
    # 1. 独立打开第1路灯光
    control_device({"power1": "1"})
    time.sleep(2)
    # 2. 独立关闭第1路灯光
    control_device({"power1": "0"})
    
    # 3. 独立打开第12路灯光
    control_device({"power12": "1"})
    
    # 4. 全关所有灯光
    # control_device({"batch": {"power": 0}})

常见问题和需要注意的点

返回值 code 200 不等于执行成功接口返回 {"code":200} 仅代表平台已收到指令并下发给设备。若设备处于离线状态，命令不会生效。如果需要确信设备已执行（如灯具确实变亮），配置 消息推送 回调，监听设备上报的状态变化。
局域网内网直连该设备支持私有化部署。如果您的服务器与控制器在同一局域网内，且不需要云端中转，可以通过在控制台开启“局域网”模式，直接 POST 请求设备的本地IP地址（如 http://192.168.1.100/control），响应速度更快且不依赖外网。
线路索引编号本设备共12路，物理端口编号通常与 power1 至 power12 严格对应，接线时请核对设备外壳丝印。
异步处理在高并发或自动化场景（如传感器联动）中，使用 extra 字段携带业务ID（如 {"power1":"1","extra":"order_9527"}），平台在消息推送中原样返回，便于您关联业务状态。

通过以上方案，您可以轻松地将芯步12路控制器集成到现有的楼宇自动化系统、智慧工厂或智能家居中枢中，实现稳定、高效的独立线路控制。