4路智能包间集中控制模块MINI：如何将4路共享空间智能控制器MINI集成到自己的项目中_解决方案

CATALOG

这份方案面向技术决策者和开发人员，从硬件选型、接口协议到核心场景代码实现，提供了完整的集成路径。

1. 背景与概述

在共享经济与无人值守服务模式快速普及的背景下，棋牌室、茶室、影咖、舞蹈教室等“共享空间”对远程管控的需求日益迫切。如何实现对包间内的灯光、空调、麻将机、门禁等设备的统一远程管理，成为运营方的痛点。

芯步4路智能包间集中控制模块MINI（型号：UNI-KZQ-BJ-MINI）正是为解决此场景而设计的硬件设备。该模块体积小巧（仅名片大小），支持4路独立电路控制，并开放标准的HTTP API接口。

本方案的目标是指导开发者如何利用该模块的开放接口，快速将其集成到现有的SaaS系统、小程序或APP中，构建从“下单-通电-计费-断电”的完整商业闭环。

2. 硬件选型与电气参数

在进行软件集成前，需明确硬件的物理规格，以确保与现场强电环境匹配。

硬件规格	参数详情	集成指导意义
产品型号	UNI-KZQ-BJ-MINI（可选TTS语音版）	选择TTS版本可实现语音播报提醒（如“欢迎光临”）
工作电压	DC 5V1A（Micro USB供电）	设备独立供电，不可接强电，需预留USB口或适配器
网络连接	Wi-Fi 2.4GHz	注意：不支持5G WiFi，部署时需确保信号覆盖
控制路数	4路继电器输出	对应控制代码为 power1, power2, power3, power4
接线端口	L/N 输入，每路独立输出	每路为干接点信号，控制火线通断
负载功率	1、2路：3500W；3路（门禁）：2200W；4路（空调）：6600W	这是关键参数：空调需接第4路（30A继电器）

适用场景

第1/2路：灯光、换气扇、饮水机、麻将机（16A继电器）。
第3路：电磁锁/门禁（配合12V电源）。
第4路：2匹以内空调（若空调电流过大，需加交流接触器）。

3. API接口集成方案

该模块的一大优势是接口协议轻量级，采用通用的HTTP POST请求，无论您的后端是Java、Python、PHP还是前端JavaScript，均可轻松调用。

3.1 接口鉴权与签名机制

为了防止接口被恶意调用，所有请求需携带动态签名（Sign）。签名生成规则如下：

获取开发者凭证（在芯步控制台获取）：
- AppID：应用唯一标识
- AppSecret：开发者密钥
获取当前Unix时间戳（秒级）：ts
计算签名：Sign = md5( md5(AppSecret) + ts )

安全提示：时间戳ts与服务器时间误差不可超过5分钟，实时获取。

3.2 API 端点说明

请求地址https://api.thingboot.com/{AppID}/device/control/
请求方式：POST
HeaderContent-Type: application/json
URL参数?sign={计算出的签名}&ts={时间戳}

3.3 核心指令集

针对本模块，order参数支持以下指令：

功能描述	JSON指令示例	业务逻辑说明
单路开启	`{"power1":1}`	开启第一路（如照明）
单路关闭	`{"power2":0}`	关闭第二路（如麻将机）
全开/全关	`{"power":1}` 或 `{"power":0}`	批量控制所有继电器
空调/麻将机复位	`{"reset":{"relay":[4],"interval":3000}}`	先断开第4路，3秒后重新闭合（用于空调压缩机保护或麻将机故障复位）
语音播报(TTS版)	`{"play:gbk:16":"欢迎光临，您的包间已准备就绪"}`	设备喇叭播报文本

4. 集成到自有项目的实战步骤

4.1 设备初始化与配网

在代码开发前，需完成硬件初始化：

通过USB给模块供电。
微信搜索“芯步”小程序或登录控制台。
选择“添加设备”，输入设备底部的唯一UID。
配置Wi-Fi SSID和密码（仅支持2.4G）。
：在场所内为每个包间分配静态DHCP或固定IP，以降低网络波动带来的离线风险。

4.2 后端服务集成（示例伪代码）

以下以订单系统为例，展示“用户下单成功 -> 自动通电”的逻辑。

# 示例:订单支付成功回调中的设备控制逻辑
import requests
import hashlib
import time
import json

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

def _generate_sign(self, ts):
        # 1. 先加密 AppSecret
        step1 = hashlib.md5(self.app_secret.encode()).hexdigest()
        # 2. 拼接 ts 再加密
        step2 = step1 + str(ts)
        return hashlib.md5(step2.encode()).hexdigest()

def control_device(self, device_id, command):
        ts = int(time.time())
        sign = self._generate_sign(ts)
        
        params = {
            "sign": sign,
            "ts": ts
        }
        payload = {
            "device": device_id,
            "order": command
        }
        
        # 发起请求
        response = requests.post(self.api_url, params=params, json=payload)
        return response.json()

# 集成应用场景:用户购买2小时包间
def on_room_order_paid(room_id, device_serial):
    controller = YoyoiotController("Your_AppID", "Your_AppSecret")
    
    # 1. 开启照明和麻将机 (power1和power2)
    controller.control_device(device_serial, {"power1": 1, "power2": 1})
    
    # 2. 开启空调 (第4路)
    controller.control_device(device_serial, {"power4": 1})
    
    # 3. 如果是TTS版本，通知用户
    controller.control_device(device_serial, {"play:gbk:16": f"包间{room_id}已通电，祝您愉快"})
    
    # 4. 写入数据库，记录订单开始时间，用于定时任务检查结束
    # ...

# 应用场景:时间到，断电
def on_room_order_end(device_serial):
    # 全关
    controller.control_device(device_serial, {"power": 0})
    
    # 关门的特殊处理:如果门禁是通电开锁型，这里需注意逻辑。通常门禁是断电开锁，所以关门时可能需要给门禁通电。
    # 具体需根据电磁锁类型调整，常见电插锁为断电开门，这里假设开门后需锁门则给power3通电。

4.3 私有化部署与局域网控制

对于注重隐私或网络环境不佳的客户，该模块支持 纯局域网控制。

自建MQTT/HTTP服务器：在配置设备时，将平台地址指向本地服务器IP。
优势：即使外网断开，内网系统依然可以控制设备开关。
适用场景：大型连锁门店内部管理系统，数据不出场。

5. 常见问题排查

设备频繁掉线怎么办？
- 原因：Wi-Fi信号弱或供电不足。
- 解决：该设备仅支持2.4G频段，若双频合一请关闭。确保使用正规5V1A电源适配器，供电不稳会导致继电器吸合时电压骤降重启。
空调无法通过断电复位？
- 原因：空调压缩机有3分钟保护延迟。
- 解决：使用reset命令时，interval间隔设置大于180秒（如"interval":200000），让压缩机压力平衡后再启动。
接口返回签名错误（Sign Error）
- 解决：严格遵循 md5(md5(AppSecret) + ts) 格式。注意 md5() 的结果通常是32位小写Hex字符串，拼接时不要加任何符号。

6. 总结

通过集成芯步4路智能包间集中控制模块MINI，开发者可以在短时间内为自有的SaaS系统赋予“物联网肢体”。

核心集成价值：

成本低：无需开发固件，4路控制覆盖一个包间的全部刚需电器。
开发快：仅需封装HTTP POST调用，无需复杂的物联网协议栈。
控制精：支持单路控制和空调专用大功率继电器，保障设备稳定运行。

开发者首先在芯步官方控制台完成单设备测试，确认网络与接线无误后，再参考本方案的代码示例进行业务系统对接。