怎么二次开发8 路智能包间集中控制模块来实现8 路独立线路通断控制_解决方案

CATALOG

芯步的8路智能包间控制器提供了完整的HTTP API接口，支持每路线路的独立通断控制。以下方案涵盖签名认证、单路/批量控制、状态查询等核心环节，可直接用于棋牌室、茶室等场景的二次开发。

一、硬件概述与二次开发基础

本方案基于芯步智能包间控制器（型号：UNI-KZQ-BJ-MAX） 进行二次开发。该硬件提供8路独立的继电器输出接口，是共享棋牌室、茶室、自习室等场景实现设备自动化的核心设备。

在进行二次开发前，需要了解该硬件的几个关键特性：

接口丰富性：8路输出各有不同负载能力（1-3路10A照明、4-6路16A插座、7路10A门禁、8路30A空调）。
网络连接：设备通过WiFi 2.4GHz连接互联网，无需网关。
控制协议：完全基于HTTP API，支持局域网或云端控制。

本方案的核心目标是通过编程调用开放接口，实现对8路线路的独立通断控制，并将其集成到现有的SaaS系统、小程序或PC管理后台中。

二、接口鉴权与请求流程

要实现对硬件的控制，首先必须通过芯步开放平台的鉴权机制。任何二次开发都需要遵循以下签名算法。

2.1 签名算法规则

接口安全基于 AppID（应用ID）和 AppSecret（应用密钥）。签名计算方式如下：

将 AppSecret 进行 MD5 加密，得到字符串 S1。
获取当前的 Unix 时间戳（秒级，例如 1700000000），记为 Ts。
将 S1 与 Ts 拼接，得到字符串 S1Ts。
将 S1Ts 再次进行 MD5 加密，得到最终的 Sign。

计算公式Sign = MD5( MD5(AppSecret) + Ts )

2.2 请求地址与头部

请求地址https://api.thingboot.com/{AppID}/device/control/
请求方法POST
参数传递方式
- URL参数：sign（签名）、ts（时间戳）
- Body参数（JSON格式）：device（设备ID）、order（控制指令）

三、 8路独立线路通断控制实现

针对UNI-KZQ-BJ-MAX型号，定义了标准的order指令格式。我们可以通过修改order中的参数来实现对第1路到第8路的精准控制。

3.1 单路独立控制指令集

你可以通过发送包含具体线路编号的JSON字符串来控制特定设备。

控制动作	请求Body中的order值	说明
打开第1路	`{“power1”：1}`	控制1号接口（照明/换气扇）吸合通电
关闭第1路	`{“power1”：0}`	断开1号接口
打开第2路	`{“power2”：1}`	独立控制，不影响其他路
关闭第2路	`{“power2”：0}`	独立断开
...	`{“powerX”：1/0}`	X范围 1-8，代表第1路至第8路
打开第8路	`{“power8”：1}`	控制8号接口（空调/高功率设备）

3.2 批量控制与场景联动

在实际应用场景（如打扫卫生、上下钟）中，往往需要同时操作多个开关。

控制场景	请求Body中的order值	适用场景
一键全开	`{“power”：1}`	有客人新开包间，开启所有设备
一键全关	`{“power”：0}`	客人离开现场时，切段总电源，清除待机功耗
指定多路开启	`{“batch”：{“relay”：[1，3，5]，“power”：1}}`	开启排风扇、照明、窗帘，但不开启麻将机
指定多路关闭	`{“batch”：{“relay”：[2，4，6]，“power”：0}}`	单独关闭部分娱乐设备

3.3 特殊功能：先断后通

对于一些插拔会产生火花的设备，或需要复位的电器，使用 reset 指令。

代码示例{“reset”：{“relay”：[8]，“interval”：2000}}
- 解析：先断开第8路，等待2000毫秒（2秒）后，再次接通第8路。这通常用于空调的强制重启或门禁的电锁复位。

四、代码实现示例

以下提供通用的HTTP请求示例，无论你是使用哪种后端语言，均可参考以下结构。

4.1 请求构造逻辑

获取凭证：AppID， AppSecret， Device ID。
生成签名：按上述规则计算Sign。
构建请求
- Header：Content-Type： application/json
- Body：{“device”： “设备ID”，“order”： “控制指令”}

4.2 cURL 命令行示例

假设要关闭3号房间的第4路插座（如饮水机断电）。

4.3 Python 快速集成示例

针对该硬件的二次开发，封装一个独立的控制函数是非常清晰的实现方式。

import hashlib
import time
import requests

def control_8ch_relay(app_id, app_secret, device_id, command_json):
    """
    芯步8路控制器二次开发核心函数
    :param command_json: 例如 {"power1": 1} 或 {"batch":{"relay":[1，2]，"power":0}}
    """
    # 1. 生成签名 (遵循官方最新签名逻辑)
    md5_secret = hashlib.md5(app_secret.encode()).hexdigest()
    ts = str(int(time.time()))
    sign_str = md5_secret + ts
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 2. 拼接 URL
    url = f"https://api.thingboot.com/{app_id}/device/control/"
    params = {"sign": sign, "ts": ts}
    
    # 3. 拼接 Body
    payload = {"device": device_id, "order": command_json}
    
    # 4. 发起请求
    response = requests.post(url, params=params, json=payload)
    return response.json()

# 调用示例1: 单独关闭第7路门禁
result = control_8ch_relay("你的AppID", "你的Secret", "设备序列号", {"power7": 0})

# 调用示例2: 打扫场景 - 开启排风扇(3路)和照明(1路)，关闭麻将机(4路)
result = control_8ch_relay("你的AppID", "你的Secret", "设备序列号", {"batch":{"relay":[1，3]，"power":1}})
result = control_8ch_relay("你的AppID", "你的Secret", "设备序列号", {"power4": 0})

五、方案落地核心要点

在将接口集成到实际业务系统（如微信公众号、SaaS后台）时，以下几点直接影响用户体验和设备安全：

状态同步机制该模块支持通过接口查询状态。在用户扫码开门时，调用一次设备状态查询接口，将power1到power8的状态同步到本地数据库，确保App显示的开关状态与实际物理状态一致。
超时与断电保护利用第8路（30A）的特性，在软件逻辑中设置“最低余额阈值”。当余额不足时，自动调用{“power8”： 0}关闭空调，但保留照明（power1），避免因直接全断导致客诉。
局域网直连模式上述示例走的是云端API（外网）。如果您的管理后台与包间处于同一局域网（如吧台服务器），解析设备API域名，或使用芯步支持的局域网API进行控制。局域网控制延迟更低（<10ms），且不依赖外网宽带，适合对响应速度要求高的门禁开锁场景。
定时任务叠加硬件支持云端定时。例如，设置每天凌晨2：00自动执行{“reset”：{“relay”：[4，5，6]，“interval”：3000}}，自动重启麻将机和饮水机，清除缓存故障，无需人工夜间巡检。

六、总结

通过芯步提供的开放接口，实现对8路智能包间模块的二次开发技术门槛较低，核心工作集中在签名的生成和业务逻辑的映射上。开发者只需关注如何将power1到power8这8个布尔值变量与自身的包厢预定系统、计费系统进行挂钩，即可快速打造一套无人值守的智能化空间管理系统。