如何接入8路智能包间集中控制模块以实现多包间批量开关控制_解决方案

CATALOG

芯步8路智能包间控制器支持通过HTTP接口进行远程集中控制，单次请求最多可同时操作100台设备，配合batch批量指令可实现对多个包间的一键全开/全关。以下方案涵盖硬件选型、接口接入、签名鉴权及多包间管理设计。

解决方案：基于芯步开放接口实现多包间批量开关控制

1. 解决概述

在共享棋牌室、茶室或剧本杀场馆等场景中，运营方通常需要在订单开始/结束时，一键开启/关闭多个包间的所有电器（如灯光、空调、麻将机等），或进行定时的巡检测试。

本方案基于 芯步 8路智能包间集中控制模块（型号：UNI-KZQ-BJ-MAX），利用其开放的 HTTP API 接口，通过调用单设备批量指令与多设备并发指令，实现对所有包间电器的集中控制、状态巡检及联动管理。

2. 硬件选型与说明

采用芯步的 智能包间控制器|Max 作为每个包间的核心控制单元。

多路输出覆盖：具备 8 路独立控制接口。
- 1-3 路（10A）：控制照明、换气扇、吸烟灯。
- 4-6 路（16A）：控制饮水机、麻将机、共享按摩椅。
- 第 7 路（10A）：门禁电磁锁接口，用于控制包间门锁。
- 第 8 路（30A）：专门用于控制 2 匹以内空调。
接口协议：支持 HTTP API 与 MQTT 协议。
网络连接：采用 2.4G WiFi 直连，无需额外网关，降低组网成本。

3. 接入准备工作

在开发之前，需要在芯步控制台完成以下配置：

获取凭证：登录芯步工作台，获取 AppID 和 AppSecret。这是所有 API 请求的鉴权基础。
设备添加：将每个包间的控制器通网通电，并在控制台中记录下每个包间对应的 Device ID（设备唯一标识）。
开发环境：确保服务器网络能与芯步 API（api.thingboot.com）互通。

4. 鉴权机制与签名生成

为防止接口被恶意篡改，所有开放接口均需进行签名校验。签名算法规则如下

参数准备AppSecret（已加密处理）、ts（当前 Unix 时间戳，秒级）。
计算公式YourSign = md5( md5(AppSecret) + ts )即：将 AppSecret 进行一次 MD5 加密，得到的字符串拼接上时间戳，再将这个新字符串整体做一次 MD5 加密。

安全性：时间戳 ts 参与签名可防止请求重放攻击，在服务端校验时间戳的有效期（如5分钟内）。

5. 技术实现：如何实现批量控制

5.1 控制单个包间的全部电器（全开/全关）

针对单个包间，如果不想逐路发送 power1 到 power8 的命令，可以利用 batch 命令。

需求场景：顾客下单成功，自动打开该包间所有设备。
请求示例（针对单个 Device_A）：
- URLhttps://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}
- POST Body (JSON)
  { "device": "Device_A_ID", "order": { "batch": { "power": 1 // 1=全开， 0=全关 } } }

5.2 痛点：多包间批量开关控制

针对“全场清场”、“批量巡检”或“定时统一关闭”的需求，芯步的 HTTP 接口支持 单次请求多设备并发控制。

实现原理device 参数支持用英文逗号 , 或竖线 | 间隔，一次最多支持 100台 设备同时控制。
需求场景：凌晨 2 点，管理员后台点击“全部清场”，所有包间自动断电、落锁。
请求示例假设需要关闭 包间1（ID: 1001） 和 包间2（ID: 1002） 的所有电源（全关）：
{ "device": "1001,1002", // 核心:用逗号连接多个包间设备ID "order": { "batch": { "power": 0 // 0=全关 } } }

5.3 特殊场景：一键“先断后通”复位

在棋牌室等场景中，顾客离开后需要复位门锁（断电几秒让电磁锁释放），同时确保空调关闭。这可以通过 reset 命令实现“先断开指定线路，延时后接通”的逻辑。

需求场景：清场时，关闭所有电器，并对门锁线路（假设接在第7路）执行断开 5 秒后自动恢复上电（以便门锁复位锁门）。
请求示例
{ "device": "1001", "order": { "reset": { "relay": [7], // 只操作门锁线路 "interval": 5000 // 断开5秒后自动吸合/接通 } } }

5.4 语音播报联动（TTS版本）

如果选择了 TTS 版本控制器，可以在批量关闭前进行语音提醒。

场景：在强制关闭包间电器前 1 分钟，调用语音接口播报“您的订单即将结束，请准备离开”。
命令{"play:gbk:16":"温馨提醒，系统将关闭电源"}。

6. 设计与实施步骤

6.1 逻辑架构图

graph LR
    Admin[管理员后台/SaaS系统] -->|HTTP API 批量命令| YoyoCloud[芯步云平台]
    YoyoCloud -->|MQTT/WiFi 指令下发| Room1[包间1 控制器]
    YoyoCloud -->|MQTT/WiFi 指令下发| Room2[包间2 控制器]
    YoyoCloud -->|MQTT/WiFi 指令下发| RoomN[包间N 控制器]
    
    subgraph 包间内电路控制
    Room1 --> Light[照明]
    Room1 --> AC[空调 第8路]
    Room1 --> Lock[门锁 第7路]
    end

6.2 实施步骤

第一步：硬件安装与配网按照产品手册，将 220V 强电线接入控制器的输入端，并根据功率将对应电器接入 1-8 路输出接口。通过控制台或配网按钮将设备连接至门店 2.4G WiFi。

第二步：封装 SDK 或工具类开发一个通用的控制服务类，封装签名生成逻辑和 HTTP 请求。核心 Python 代码如下（基于搜索结果）：

import hashlib
import time
import requests
import json

class YoYoController:
    def __init__(self, app_id, app_secret):
        self.app_id = app_id
        self.app_secret = app_secret
        self.base_url = f"https://api.thingboot.com/{app_id}/device/control/"

def _gen_sign(self):
        # 1. 对 AppSecret 进行 MD5
        md5_secret = hashlib.md5(self.app_secret.encode()).hexdigest()
        # 2. 拼接时间戳
        ts = str(int(time.time()))
        data = md5_secret + ts
        # 3. 整体再次 MD5
        sign = hashlib.md5(data.encode()).hexdigest()
        return sign, ts

def batch_control_rooms(self, device_ids, action):
        """
        批量控制多个包间
        :param device_ids: 列表，例如 ['1001', '1002']
        :param action: 1 开启， 0 关闭
        """
        sign, ts = self._gen_sign()
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        
        # device 参数用逗号连接
        payload = {
            "device": ",".join(device_ids), 
            "order": {
                "batch": {"power": action}
            }
        }
        
        response = requests.post(url, json=payload)
        return response.json()

# 调用示例
ctrl = YoYoController("Your_AppID", "Your_AppSecret")
# 批量关闭 3个包间的所有电源
ctrl.batch_control_rooms(["room_id_1", "room_id_2", "room_id_3"], 0)

第三步：集成到业务系统

订单开始：触发 batch_control_rooms([room_id], 1)，并下发门锁开门指令 {"power7": 0}（假设门锁是断电开）。
订单结束：先发送语音提醒，等待 10 秒后，发送 batch_control_rooms([room_id], 0) 关闭所有电器，并发送 reset 指令复位门锁。

7. 注意事项

异步反馈机制：API 返回 code 200 仅代表指令被平台接收，设备是否真正执行成功需通过“消息推送”或查询设备状态接口获取。
负载安全：请注意各线路的负载上限。特别是第 8 路虽然支持 30A（6600W），但仍需确保接入的空调功率不超过此限制。
局域网控制：如果你的系统部署在门店本地且不想经过公网，该设备支持私有化部署和局域网发现，可在无外网环境下使用。
Extra 字段：在进行退单或关键操作时，在 order 中传入 extra 字段（如订单号），以便在异步回调中关联业务数据。

通过以上方案，开发者可利用芯步的 8 路控制器及其批量设备控制接口，快速构建出稳定、高效的多包间集中管理系统。