4路HTTP接口包间控制器MINI：如何将4路远程包间管理控制器MINI接入到软件项目中_解决方案

CATALOG

这款MINI控制器的亮点在于：接口统一、签名机制简单、支持局域网私有化部署。以下方案会从硬件准备、签名算法、接口调用、业务场景代码示例到架构，帮你快速完成接入。

解决方案：4路HTTP接口包间控制器MINI接入软件项目

1. 背景与概述

芯步4路远程包间管理控制器MINI是一款专为共享棋牌室、茶室、琴房等服务型门店设计的智能硬件。它提供4路继电器输出，可独立控制包间内的照明、麻将机、空调、门锁等设备。

本方案的目标是指导开发者如何利用该设备开放的HTTP API接口，将其快速集成到现有的Web应用、小程序或SaaS系统中，实现远程控制、状态同步和自动化管理。

2. 准备工作

在开始编码前，请确认具备以下条件：

硬件就绪：已购买“智能包间控制器MINI”（型号：UNI-KZQ-BJ-MINI），并通电使其连接至2.4G WiFi网络。
平台账号：在芯步开放平台注册开发者账号，登录控制台。
获取凭证：在控制台的“开发设置”中获取 AppID 和 AppSecret。
设备ID：在控制台设备列表或设备外壳标签上获取目标设备的 Device ID。

3. API接入核心：签名机制

所有HTTP请求都需要进行签名鉴权，这是接入过程中最关键的一步。签名算法采用双层MD5加密，公式如下Sign = md5( md5(AppSecret) + ts )

参数说明：

AppSecret：开发者密钥。
ts：当前Unix时间戳（秒）。
+：字符串拼接。

计算步骤示例（伪代码）：假设 AppSecret = "abc123"，当前时间戳 ts = 1714876800。

计算第一层MD5：md5_1 = md5("abc123") -> 结果为 e99a18c428cb38d5f260853678922e03。
拼接时间戳：str = md5_1 + ts -> 结果为 e99a18c428cb38d5f260853678922e031714876800。
计算最终签名：Sign = md5(str)。

注意： 时间戳 ts 在请求中作为参数传递，用于服务端校验请求的有效期，防止重放攻击。

4. 接口集成实战：从单路到4路控制

接口地址统一为：https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

请求方式：POSTContent-Typeapplication/json

4.1 基础命令格式

请求Body包含两个必须字段

4.2 单路独立控制

MINI控制器支持 power1 至 power4 的参数，对应4路输出。1代表开启，0代表关闭。

关灯（第1路关闭） ：
{ "device": "123456"， "order": { "power1": 0 } }
开空调（第4路开启） ：
{ "device": "123456"， "order": { "power4": 1 } }

4.3 场景化批量控制

当需要开门（第3路）并开灯时，无需发送两次请求，可使用 batch 命令

同时开启第1路和第3路
{ "device": "123456"， "order": { "batch": { "relay": [1, 3], "power": 1 } } }
一键全关（结束营业） ：
{ "device": "123456"， "order": { "power": 0 } }
注：直接使用 power 字段（不带数字）控制所有线路通断。

4.4 门禁联动与语音播报（TTS版）

如果你的设备是TTS版本，还可以进行语音控制。

开门延时：门禁通常需要先通电几秒再关才能让电磁锁动作。使用 reset（先断后通）模拟“出门开关”动作。
{ "device": "123456"， "order": { "reset": { "relay": [3], "interval": 5000 } } }
*逻辑：第3路关闭 -> 等待5秒 -> 第3路开启。*
语音播报当用户下单或超时时，控制台播报提醒。
{ "device": "123456"， "order": { "play:gbk:16": "您好，欢迎光临，请到B区消费" } }

5. 代码实现示例

以下是一个通用的调用函数（以Python为例），展示了如何动态生成签名并发起请求。

import requests
import hashlib
import time
import json

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

def _generate_sign(self, ts):
        # 实现签名算法:md5(md5(AppSecret) + ts)
        md5_first = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign_str = md5_first + str(ts)
        sign = hashlib.md5(sign_str.encode()).hexdigest()
        return sign

def control_device(self, device_id, order_cmd):
        ts = int(time.time())
        sign = self._generate_sign(ts)
        
        # 拼接最终URL
        url = f"{self.base_url}{self.app_id}/device/control/？sign={sign}&ts={ts}"
        
        # 构建请求体
        payload = {
            "device": device_id,
            "order": order_cmd
        }
        
        headers = {"Content-Type": "application/json"}
        
        # 发起POST请求
        response = requests.post(url, json=payload, headers=headers)
        return response.json()

# 使用示例
if __name__ == "__main__":
    # 初始化
    ctrl = YoYoController("你的AppID"， "你的AppSecret")
    
    # 场景1:关闭包间1的照明（假设设备ID为10086，照明在第1路）
    res1 = ctrl.control_device("10086"， {"power1": 0})
    
    # 场景2:TTS语音播报通知
    res2 = ctrl.control_device("10086"， {"play:gbk:16": "您的剩余时间还有15分钟"})
    
    print(res1, res2)

其他语言参考

CURL示例：可参考官方提供的命令行格式，方便在Shell脚本中调试。
PHP/Java：签名逻辑完全一致，只需注意不同语言对MD5和JSON处理的语法差异即可。官方文档提供了PHP的详细示例。

6. 高级集成：状态同步与私有化部署

6.1 异步消息推送（推荐）

单纯的HTTP请求只能下发命令，无法知道设备是否真正执行了命令（例如设备当时离线或断网）。为了完善业务逻辑，配置消息推送回调URL。

在芯步控制台设置你的服务器接收地址（URL）。
当设备状态变化（如用户按了物理按键、设备上下线、命令执行结果）时，平台会主动推送数据到你的服务器。
应用：收到“设备执行成功”的推送后，才更新数据库中“灯已打开”的状态。

6.2 局域网私有化部署

对于注重隐私或网络稳定的场景（如高端棋牌室），MINI控制器支持局域网控制。

原理：设备通过WiFi连接，如果软件项目部署在同一局域网内，可以绕过云端API，直接向设备的本地IP发请求。
优势：无延迟（瞬间响应）、断外网仍可使用、无需消耗云流量。

7. 电气接线注意事项

在软件集成的同时，请请一定要注意硬件接线的正确性，否则软件无法生效

第1路（16A）：适用于照明灯、排风扇。
第2路（16A）：适用于普通插座（麻将机、饮水机）。
第3路（10A）门禁专用，接电磁锁或电插锁。必须配合 reset 或 point 命令使用（通电时长控制在5-10秒），切勿长期通电，否则会烧毁锁具线圈。
第4路（30A）空调专用，可直接接2匹空调，无需额外交流接触器。

8. 总结

通过遵循上述方案，开发者仅需 2 步即可完成集成：

封装签名函数：复用 md5(md5(Secret)+ts) 逻辑。
构造命令：利用 powerX、batch 和 reset 映射业务动作（如“开灯”、“开门”、“断电”）。

该接口设计轻量，不论你是开发棋牌室SaaS系统的后端，还是编写自动化脚本，都能在半小时内跑通第一个控制流程。