怎么对接12路HTTP接口照明控制器以实现HTTP接口远程通断控制_解决方案

CATALOG

一、12路照明控制器：多路场景的核心控制设备

在实际的物联网项目中，照明或用电设备的控制往往不止一路两路——智能楼宇需要分层分区控制，景观亮化需要多路独立开关，共享棋牌室需要同时管控多个包间。芯步12路照明控制器正是为这类多路场景设计的核心设备。

1.1 产品核心规格

参数项	规格说明
产品型号	UNI-KZQ-ZM-12-16A
控制路数	12路独立继电器输出
额定电流	MAX 16A / 路
负载功率	阻性负载≤3520W/路，感性负载≤550W/路
工作电压	AC 100-250V（市电直连）
待机功耗	0.4-1W
通讯方式	WiFi 2.4GHz（支持5组WiFi自动切换）
开放接口	HTTP API（任何编程语言可调用）
私有化部署	支持纯局域网运行
产品尺寸	适合装入标准配电箱

1.2 适用场景全景

应用场景	典型需求	本方案的适配价值
智能楼宇照明	分层、分区域独立控制	12路覆盖整层办公区
景观亮化工程	多组灯带、投光灯分别控制	单设备控12路景观灯
共享棋牌室/台球室	多包间集中管理	覆盖6-12个包间
工厂车间照明	不同工位/区域独立开关	灵活分区控制
仓库货架照明	按巷道/货架分组控制	节能与便利兼顾

1.3 为什么选择HTTP接口对接

芯步设备的最大优势在于完全开放的HTTP API——无需专用SDK、无需特定编程语言、无需额外网关，任何能发起HTTP请求的系统都能对接。这意味着：

语言无关：用Python、Java、JavaScript、C#、Go等任意语言均可调用
平台无关：Web、小程序、APP、后台服务均可接入
部署灵活：支持公有云或私有化局域网部署

1.4 12路与4路/8路的对比

维度	4路控制器	8路控制器	12路控制器（本方案）
控制路数	4路	8路	12路
单路电流	10A	10A	16A
适合场景	小型项目、单包间	中型项目、多包间	大型项目、集中管理
扩展能力	有限	中等	强，单设备覆盖更多路

二、HTTP API对接详解

2.1 接口基础信息

芯步提供统一的RESTful API，请求地址格式为

项目	说明
请求地址	`POST https://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}`
Content-Type	`application/json`
认证方式	签名认证
设备ID	在控制台配网后获取

参数获取

{AppId}：应用ID，登录芯步控制台 → 开发设置中获取
AppSecret：开发者密码，开发设置中获取或设置
device：设备ID，设备配网成功后可在控制台查看

2.2 签名算法

重要：生产环境下必须计算签名，测试阶段可在控制台开启“调试模式”暂时跳过签名校验。

签名计算公式：

sign = md5( md5(AppSecret) + ts )

计算步骤

对 AppSecret 进行一次MD5加密
将加密结果与 ts（当前Unix时间戳，秒）拼接
对拼接后的字符串再次MD5加密

2.3 12路控制器命令速查表

芯步12路控制器支持以下HTTP命令格式

控制方式	命令格式	示例
单路控制	`{"power1":"1"}`, `{"power1":"0"}`	`{"power1":"1"}` 开启第1路
多路独立控制	多个power字段	`{"power1":"1","power3":"0","power5":"1"}`
批量控制	`{"batch":{"relay":[1,3,5],"power":1}}`	同时开启1、3、5路
全开/全关	`{"batch":{"power":1}}` / `{"batch":{"power":0}}`	一键全开或全关

使用说明

power1 ~ power12：分别对应12路输出，"1"为接通，"0"为断开
batch.relay：指定需要控制的回路数组，取值范围1-12
batch.power：批量操作的状态值，1开 0关

三、多语言对接代码示例

3.1 Python实现

"""
12路照明控制器对接示例
支持单路、批量、全开全关控制
"""

import hashlib
import time
import requests
from typing import List, Dict, Optional

class LightingController12:
    """12路照明控制器API封装"""
    
    def __init__(self, app_id: str, app_secret: str, device_id: str,
                 private_host: str = None):
        self.app_id = app_id
        self.app_secret = app_secret
        self.device_id = device_id
        self.api_base = private_host or "https://api.thingboot.com"
    
    def _generate_sign(self, ts: int) -> str:
        """生成API请求签名 sign = md5(md5(AppSecret) + ts)"""
        first_md5 = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign_input = first_md5 + str(ts)
        return hashlib.md5(sign_input.encode()).hexdigest()
    
    def _send_command(self, order: Dict) -> Dict:
        """向12路控制器发送命令"""
        ts = int(time.time())
        sign = self._generate_sign(ts)
        url = f"{self.api_base}/{self.app_id}/device/control/?sign={sign}&ts={ts}"
        
        payload = {
            "device": self.device_id,
            "order": order
        }
        
        response = requests.post(url, json=payload, timeout=5)
        return response.json()
    
    # ========== 单路控制 ==========
    
    def set_channel(self, channel: int, state: bool):
        """控制单路开关（1-12）"""
        power_key = f"power{channel}"
        value = "1" if state else "0"
        return self._send_command({power_key: value})
    
    def on(self, channel: int):
        """开启指定回路"""
        return self.set_channel(channel, True)
    
    def off(self, channel: int):
        """关闭指定回路"""
        return self.set_channel(channel, False)
    
    # ========== 批量控制 ==========
    
    def batch_on(self, channels: List[int]):
        """批量开启指定回路"""
        return self._send_command({
            "batch": {
                "relay": channels,
                "power": 1
            }
        })
    
    def batch_off(self, channels: List[int]):
        """批量关闭指定回路"""
        return self._send_command({
            "batch": {
                "relay": channels,
                "power": 0
            }
        })
    
    def all_on(self):
        """全开（12路全部开启）"""
        return self._send_command({"batch": {"power": 1}})
    
    def all_off(self):
        """全关（12路全部关闭）"""
        return self._send_command({"batch": {"power": 0}})
    
    # ========== 多路独立控制 ==========
    
    def set_multi(self, states: Dict[int, bool]):
        """
        多路独立控制
        states: {1: True, 3: False, 5: True} 表示开启1、5路，关闭3路
        """
        order = {}
        for channel, state in states.items():
            order[f"power{channel}"] = "1" if state else "0"
        return self._send_command(order)

# 使用示例
if __name__ == "__main__":
    controller = LightingController12(
        app_id="YOUR_APP_ID",
        app_secret="YOUR_APP_SECRET",
        device_id="YOUR_DEVICE_ID"
    )
    
    # 单路控制:开启第1路
    controller.on(1)
    
    # 批量控制:同时开启1、3、5路
    controller.batch_on([1, 3, 5])
    
    # 全关所有回路
    controller.all_off()
    
    # 多路独立控制:1路开、2路关、3路开
    controller.set_multi({1: True, 2: False, 3: True})

3.2 JavaScript/Node.js实现

const crypto = require('crypto');
const axios = require('axios');

class LightingController12 {
    constructor(appId, appSecret, deviceId) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.deviceId = deviceId;
        this.apiBase = 'https://api.thingboot.com';
    }
    
    generateSign(ts) {
        const firstMd5 = crypto.createHash('md5').update(this.appSecret).digest('hex');
        const signInput = firstMd5 + ts;
        return crypto.createHash('md5').update(signInput).digest('hex');
    }
    
    async sendCommand(order) {
        const ts = Math.floor(Date.now() / 1000);
        const sign = this.generateSign(ts);
        const url = `${this.apiBase}/${this.appId}/device/control/?sign=${sign}&ts=${ts}`;
        
        const response = await axios.post(url, {
            device: this.deviceId,
            order: order
        });
        return response.data;
    }
    
    // 单路控制
    async setChannel(channel, state) {
        const order = { [`power${channel}`]: state ? '1' : '0' };
        return this.sendCommand(order);
    }
    
    // 批量控制
    async batchControl(channels, state) {
        return this.sendCommand({
            batch: {
                relay: channels,
                power: state ? 1 : 0
            }
        });
    }
    
    // 全开/全关
    async allOn() { return this.sendCommand({ batch: { power: 1 } }); }
    async allOff() { return this.sendCommand({ batch: { power: 0 } }); }
}

// 使用示例
const controller = new LightingController12('APP_ID', 'APP_SECRET', 'DEVICE_ID');
await controller.setChannel(1, true);   // 开启第1路
await controller.batchControl([1,3,5], true);  // 开启1,3,5路
await controller.allOff();              // 全关

3.3 微信小程序实现

微信小程序可直接调用芯步的HTTP接口实现远程控制

// pages/control/control.js
Page({
    data: {
        channels: Array.from({ length: 12 }, (_, i) => ({ 
            id: i + 1, 
            status: false 
        }))
    },
    
    // 生成签名（需在后端完成，或使用调试模式）
    generateSign() {
        // 重要:生产环境在后端计算签名，避免AppSecret暴露
        // 以下仅为简化示例
        const ts = Math.floor(Date.now() / 1000);
        // sign计算需要AppSecret，应在服务端完成
        return { ts, sign: 'backend_computed_sign' };
    },
    
    // 控制单路灯光
    async toggleChannel(e) {
        const channel = e.currentTarget.dataset.channel;
        const newStatus = !this.data.channels[channel-1].status;
        
        // 调用云函数或后端接口
        wx.request({
            url: 'https://your-server.com/api/light/control',
            method: 'POST',
            data: {
                deviceId: 'YOUR_DEVICE_ID',
                channel: channel,
                state: newStatus ? 1 : 0
            },
            success: (res) => {
                if (res.data.code === 200) {
                    this.setData({
                        [`channels[${channel-1}].status`]: newStatus
                    });
                }
            }
        });
    },
    
    // 全开
    allOn() {
        wx.request({
            url: 'https://your-server.com/api/light/all_on',
            method: 'POST',
            data: { deviceId: 'YOUR_DEVICE_ID' },
            success: () => {
                this.setData({
                    channels: Array.from({ length: 12 }, (_, i) => ({ 
                        id: i + 1, status: true 
                    }))
                });
            }
        });
    },
    
    // 全关
    allOff() {
        wx.request({
            url: 'https://your-server.com/api/light/all_off',
            method: 'POST',
            data: { deviceId: 'YOUR_DEVICE_ID' },
            success: () => {
                this.setData({
                    channels: Array.from({ length: 12 }, (_, i) => ({ 
                        id: i + 1, status: false 
                    }))
                });
            }
        });
    }
});

微信小程序对接说明

签名计算所需的AppSecret不应在小程序端暴露，通过后端服务中转
开发测试阶段可在控制台开启“调试模式”暂时跳过签名验证

3.4 cURL命令行测试

四、部署与集成指南

4.1 设备安装与配网

接线要点

控制器需接入AC 100-250V市电供电
12路输出分别接入对应照明回路
每路输出前加装小型断路器保护

配网流程

设备通电，等待指示灯状态
搜索WiFi热点YO-XXXX，连接
浏览器访问192.168.4.1
选择目标WiFi（2.4GHz频段）并输入密码
配网成功后，在芯步控制台获取设备ID

网络要求

仅支持2.4GHz WiFi（不支持5GHz）
支持配置5组WiFi，自动选择最强信号连接
优先推荐有线局域网版（如环境允许）

4.2 开发对接流程

芯步官方提供了清晰的对接流程

步骤	操作	说明
1	登录控制台	注册并登录芯步平台
2	获取AppId/AppSecret	在“开发设置”中设置开发者密码
3	设备配网	按照产品手册给设备配网
4	获取设备ID	在控制台设备列表中查看
5	编码对接	封装HTTP请求，计算签名
6	测试验证	使用Postman或代码测试

4.3 私有化部署说明

12路控制器支持私有化部署，可运行在纯局域网环境。实现方式：

设备与业务服务器处于同一局域网
API请求地址替换为自建服务器内网地址
所有数据不经过公网，满足数据安全要求

五、总结

对比维度	传统工控方案	芯步12路控制器本方案
控制路数	需多台继电器模块	单设备12路独立控制
编程门槛	需PLC编程知识	任意语言HTTP调用
部署方式	需布线+专用网关	WiFi直连，无需网关
远程能力	需额外模块	原生远程控制
私有化支持	一般不涉及	支持纯局域网部署
扩展能力	增加模块扩路	多台设备并联扩展

通过芯步12路照明控制器 + 开放HTTP API，开发者可以快速实现：

12路独立控制：单设备覆盖大型照明项目
️ 任意语言对接：HTTP接口，10分钟完成集成
灵活部署：支持WiFi/有线、公网/私有化
⚡ 大规模管理：可并联多台设备，扩展无限

完整的API文档、产品手册和演示环境，请访问芯步官网或联系技术支持团队。