4路智能包间集中控制模块MINI：如何把带语音播报迷你包间控制器接入到自己的项目中_解决方案

CATALOG

4路智能包间集中控制模块MINI是一款集四路电器控制与语音播报于一体的嵌入式设备，开放HTTP API接口，支持局域网和公网两种接入模式。以下方案涵盖硬件选型、接口对接流程、核心代码实现及典型场景应用。

一、核心产品特性与选型

在接入项目之前，首先需要明确硬件的能力边界。该设备（型号：UNI-KZQ-BJ-MINI-TTS）具备以下核心技术指标，是方案设计的基础：

四路独立控制
- 第1/2路：16A继电器，适用于照明、换气扇、饮水机、麻将机。
- 第3路：10A门禁专用，接电磁锁/电插锁（直流）。
- 第4路：30A大功率继电器，专用于2匹空调或取暖设备。
语音交互能力：TTS版本内置语音播报功能，支持通过接口推送文本进行实时朗读，用于订单提醒、操作指引或警报。
网络与接口
- 通信方式：Wi-Fi 2.4GHz，无需网关。
- 接口协议：开放 HTTP API，支持 JSON 格式指令。
- 部署模式：支持公有云调用，也支持纯局域网私有化部署，保障数据安全。

二、两种接入模式选型

根据你的项目架构，芯步提供两种截然不同的接入路径：

特性	模式一：公有云 HTTP API	模式二：局域网私有化 SDK
适用场景	连锁门店、需要远程查看状态、跨地域管理	单门店、高安全内网、无外网环境、极低延迟
设备寻址	通过设备ID（Device ID）寻址	通过设备IP地址寻址
鉴权方式	AppID + AppSecret + MD5签名	设备预设Secret + MD5签名
语音编码	标准UTF-8（云端自动处理）	需手动转码为 GBK/GB2312 十六进制
优势	免网络配置，穿透内网，维护简单	无云端依赖，响应速度毫秒级

三、接口对接详细步骤

1. 环境准备与设备配网

获取凭证：在芯步开发者后台创建项目，获取 AppID 和 AppSecret。
设备配网：设备通电后，通过提供的配网工具将设备连接到现场Wi-Fi。记录下平台分配的唯一 Device ID（设备ID，在外壳标签或后台均可找到）。
（私有化模式）获取IP：在路由器后台查看设备被分配的IP地址，并设为静态IP以防变动。

2. 接口鉴权机制

无论是云模式还是本地模式，核心逻辑都是构造一个带有签名的HTTP请求。公有云模式的签名算法逻辑为：

sign = \text{MD5}(\text{MD5}(\text{AppSecret}) + \text{timestamp})

即：将AppSecret进行MD5加密，结果拼接上当前时间戳，再进行一次MD5加密。

3. 核心功能开发：指令下发

命令格式：请求体为JSON格式，核心参数为 device 和 order。

单路控制：通过 power1 ~ power4 字段控制对应线路的通断。
- 开启第1路（照明）：{"power1": 1}
- 关闭第2路（麻将机）：{"power2": 0}。
语音播报开发（TTS核心）
- 公有云模式：直接下发中文字符串。
  - 命令示例：{"play":"欢迎光临，请上座"}
- 私有化模式\局域网：由于设备底层芯片限制，需将中文转GBK编码的十六进制。
  - “你好”转为 c4e3bac3。
  - 命令示例：{"play:gbk:16":"c4e3bac3"}。
场景联动\批量控制
- 若需一键执行“离店模式”（关空调、关灯、关门锁、播报），可使用批量指令：
  { "batch": { "relay": [1, 2, 4], "power": 0 }, "play":"感谢光临，欢迎下次再来" }

4. 私有化部署的特殊处理

如果你完全不需要外网，仅在内网运行：

请求地址：不再是 api.thingboot.com，而是 http://[设备IP地址]/control。
签名：如果设置了密码，需计算 md5(密码) 作为sign参数。
优势：数据完全不经过云端，响应速度极快（实测80-120ms）。

四、典型场景应用实战

以“共享棋牌室”的完整业务流程为例，展示如何将MINI控制器融入你的系统：

场景：用户下单 -> 自动通电 -> 到点提醒 -> 断电

用户下单（小程序端）
- 用户支付成功后，你的后端服务收到支付回调。
设备控制（服务端逻辑）
- 调用接口开启第4路（空调）：{"power4":1}
- 调用接口开启第1路（照明）：{"power1":1}
- 调用接口开启第2路（麻将机）：{"power2":1}
- 调用接口控制第3路（门锁）：{"power3":0} （断电开锁/根据锁类型调整逻辑）。
语音播报（现场交互）
- 控制器自动播报：“设备已通电，欢迎光临，祝您娱乐愉快”。
- 在包间时间剩余15分钟时，后端定时任务触发：
- {"play":"您的包间时间还剩15分钟，请注意续费"}。
超时断电（结束流程）
- 订单结束时间到，调用接口关闭所有继电器：
- {"power1":0, "power2":0, "power4":0} （关灯、关麻将机、关空调）。
- 同时控制电磁锁上电锁门（{"power3":1}）。

五、核心代码集成示例（Python/Java）

以下是基于公有云的Python集成示例，展示了如何构造请求控制设备。

Python 示例

import requests
import hashlib
import time
import json

# 配置信息
APP_ID = "YOUR_APP_ID"
APP_SECRET = "YOUR_APP_SECRET"
DEVICE_ID = "12345678"  # 设备标签上的ID

def control_device(device_id, order_dict):
    # 1. 生成时间戳和签名
    ts = str(int(time.time()))
    # md5(md5(AppSecret) + ts)
    step1 = hashlib.md5(APP_SECRET.encode()).hexdigest()
    sign_str = step1 + ts
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 2. 构造URL
    url = f"https://api.thingboot.com/{APP_ID}/device/control/?sign={sign}&ts={ts}"
    
    # 3. 构造Body
    payload = {
        "device": device_id,
        "order": order_dict
    }
    
    # 4. 发送请求
    headers = {'Content-Type': 'application/json'}
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

# 场景:开门 + 播报欢迎词
if __name__ == "__main__":
    # 1. 电插锁断电（开门）
    result_lock = control_device(DEVICE_ID, {"power3": 0})
    # 2. 语音播报
    result_voice = control_device(DEVICE_ID, {"play": "欢迎光临，请将空调温度设定在26度"})
    print(result_voice)

Java 示例对于Java项目，推荐使用Unirest库，核心逻辑同样是拼接签名和发送JSON Body。需注意私有化部署时的GBK转码处理。

六、常见问题与解决方案

指令下发成功但设备无反应
- 检查返回码：code 200 仅代表云端收到指令，不代表设备执行。
- 解决方案：检查设备Wi-Fi信号强度，或开启“消息推送”功能，接收设备执行结果的异步回调。
私有化模式中文播报乱码
- 原因：直接发送UTF-8中文。
- 解决方案：必须将中文转为GBK编码的十六进制字符串。例如“测试” -> b2e2cad4。
空调接入不工作
- 原因：空调为感性负载，启动电流大。
- 解决方案：确保空调（2匹内）接入第4路，该路支持30A大电流，不宜接入前3路。
语音播报不清晰或无声
- 检查音量设置。可下发命令调整音量，范围通常0-10：{"vol": 7}。

通过上述方案，你可以将“4路智能包间集中控制模块MINI”无缝对接到现有项目中，显著提升包间管理的自动化水平和用户体验。