怎么对接4路交流负载控制器来实现交流负载通断控制_解决方案

CATALOG

芯步的4路交流负载控制器支持通过HTTP接口进行远程通断控制，单路最大承载10A电流，适用于共享设备、智能照明等场景。以下方案涵盖接口协议、签名规则及单路/批量/定时等控制模式的代码示例。

1. 解决概述

本方案的目标是指导开发者如何通过调用芯步开放平台的 HTTP API 接口，实现对 4路交流负载控制器 的远程通断控制。该设备支持独立控制 4 路交流输出（每路最大 10A），适用于照明、插座、电机等各类交流负载。

核心流程：开发者业务系统 → 芯步 API 网关 → 设备 (4路控制器) → 控制继电器通断。

前置准备

已注册芯步开发者账号。
在控制台获取 AppID、API Token（用于生成签名）。
已添加设备并获取 设备ID（Device ID）。
设备已联网在线。

2. 接口对接详解

所有控制指令均通过 HTTP POST 方法提交，指令经云端下发给设备。

2.1 请求地址

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

参数	类型	必填	描述
`AppID`	String	是	平台分配的应用ID（直接在URL路径中替换）
`sign`	String	是	签名，用于身份验证（生成规则见下文）
`ts`	String	是	Unix 时间戳（秒），用于防止重放攻击

2.2 请求头 (Headers)

2.3 请求体 (Body)

使用表单格式提交：device 和 order 两个字段。

参数	类型	必填	描述
`device`	String	是	目标设备ID
`order`	String	是	JSON 字符串，包含具体的控制指令

3. 核心控制指令明细（`order` 格式）

根据芯步的接口定义，order 字段支持多种控制模式：

3.1 单路独立控制

通过 power1、power2、power3、power4 精准控制指定线路的通断。

功能	order 值示例	说明
断开第1路	`{"power1":"0"}`	关闭连接在继电器1上的设备
闭合第2路	`{"power2":"1"}`	开启继电器2
断开第3路	`{"power3":"0"}`	关闭继电器3
闭合第4路	`{"power4":"1"}`	开启继电器4

3.2 批量控制

同时对多个不相邻的线路执行相同的开关动作。

功能	order 值示例	说明
批量关闭	`{"batch":{"relay":[1,3,4],"power":0}}`	同时断开第1、3、4路
批量开启	`{"batch":{"relay":[2,4],"power":1}}`	同时开启第2、4路

3.3 高级时序控制

用于需要临时触发或定时通断的场景。

先通后断 (Point)：先闭合指定线路，延时一段时间后断开。常用于门禁、电磁阀或脉冲触发。
- {"point":{"relay":[1],"interval":500}}(第1路闭合，500ms后断开)
先断后通 (Reset)：先断开指定线路，延时一段时间后恢复闭合。常用于设备重启（如路由器重启）。
- {"reset":{"relay":[2,3],"interval":10000}}(第2、3路断开，10秒后重新闭合)

4. 签名机制与安全

为了防止接口被恶意篡改，芯步接口要求对请求进行签名校验。

签名生成步骤

拼接字符串：将 AppID、Token、Timestamp 按照 特定顺序（依据官方文档，通常为字典序或固定拼接）组合。注：常见格式为 AppID + Token + Timestamp 或参数排序后拼接。
MD5 加密：对拼接后的字符串进行 MD5 运算，得到 32 位小写字符串作为 sign。

代码示例 (Python)

5. 对接实现示例

以下示例演示如何控制 第1路断开 和 第2路闭合。

5.1 Python 3 示例

5.2 Go 示例

package main

import (
    "crypto/md5"
    "encoding/hex"
    "fmt"
    "io"
    "net/url"
    "strconv"
    "time"
    "strings"
)

func main() {
    appId := "your_app_id"
    token := "your_api_token"
    deviceId := "your_device_id"
    
    ts := strconv.FormatInt(time.Now().Unix(), 10)
    // 签名逻辑 (示例)
    signRaw := appId + token + ts
    hash := md5.Sum([]byte(signRaw))
    sign := hex.EncodeToString(hash[:])
    
    apiUrl := fmt.Sprintf("https://api.thingboot.com/%s/device/control?sign=%s&ts=%s", appId, sign, ts)
    
    // 控制指令:断开第1路，开启第2路
    order := `{"power1":"0","power2":"1"}`
    
    payload := url.Values{}
    payload.Set("device", deviceId)
    payload.Set("order", order)
    
    req, _ := http.NewRequest("POST", apiUrl, strings.NewReader(payload.Encode()))
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
    req.Header.Set("X-APISpace-Token", token)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    // ... error handling
}

6. 典型应用场景

共享自习室/工位：用户扫码付费后，调用接口 {"power1":"1"} 开启对应座位的电源插座；计时结束后调用 {"power1":"0"} 断电。
智慧农业/养殖：根据传感器温湿度阈值，调用 {"batch":{"relay":[1,2],"power":1}} 同时启动多台风机或水泵。
远程运维：当网络摄像头或路由器死机时，调用 {"reset":{"relay":[3],"interval":5000}} 实现远程重启。

7. 常见问题

Q: 控制指令下发成功，但设备没反应？
- A: 请检查设备是否在线（可在芯步控制台查看设备状态）。设备离线时指令会缓存，但需确认离线时长未超出缓存有效期。
Q: 单路最大负载是多少？
- A: 该交流版控制器推荐阻性负载不超过 10A，感性/容性负载需考虑浪涌电流，降额至 8A 以下使用。
Q: 能否获取设备当前的通断状态？
- A: 除了控制接口，平台通常提供设备状态查询接口（GET /device/status），可读取当前各路继电器的实际开关状态。