共享茶室包间控制：如何将4路智能包间控制器MINI对接到自己的项目中_解决方案

CATALOG

芯步Mini控制器通过HTTP API开放接口，支持设备控制、状态查询和语音播报，可快速集成到小程序、App或管理后台中。以下是具体的对接方案：

1. 硬件选型与场景定义

首先明确Mini控制器的4路输出分别控制包间内的哪些设备。根据官方手册，标准的接法如下：

线路编号	负载类型	对接设备	备注
第1路	16A 开关	照明灯、换气扇、吸烟灯	阻性负载最大3500W
第2路	16A 插座	麻将机、饮水机、按摩椅	感性负载不超过500W
第3路	10A 门禁	电磁锁、电插锁	配合门磁使用，实现门禁控制
第4路	30A 插座	2匹空调（重要）	空调专用回路，负载功率较高
TTS模块	音频	语音播报	仅TTS版本支持，用于订单提醒

关键点：若项目中包含空调控制，必须将空调插头接在第4路，因为只有这一路支持30A大电流继电器，直接控制照明或普通插座可能导致触点粘连。

2. 接口对接设计

芯步的API支持公网SaaS模式和私有化部署模式。对于商用项目，搭建自己的后端服务进行中转，而不是在前端直接暴露AppSecret。

推荐架构：

flowchart LR
    subgraph 用户端
        A[用户手机/小程序]
    end
    
    subgraph 业务服务器
        B[你的后端服务
签名计算/业务逻辑]
    end
    
    subgraph 芯步云
        C[API网关
api.thingboot.com]
    end
    
    subgraph 门店现场
        D[WiFi路由器]
        E[4路智能控制器Mini]
        F[包间电器]
    end
    
    A -- 业务请求 --> B
    B -- 携带签名调用 --> C
    C -- 指令下发 --> D
    D -- 无线指令 --> E
    E -- 继电器通断 --> F

数据流向说明

设备配网：设备通电后，通过配网模式将其连接至门店WiFi（设备仅支持2.4GHz）。
设备注册：设备连网后自动注册到芯步平台，你可以在后台获取唯一的设备ID（Device ID）。
业务触发：用户在微信小程序点击“开灯”。
业务请求：小程序调用你自己的后端接口。
签名与下发：你的后端服务器计算sign，携带Device ID向 api.thingboot.com 发起 POST 请求。
执行：云平台通过WiFi将指令推送给Mini控制器，继电器吸合，灯亮。

3. API 核心调用逻辑

芯步的接口安全性依赖于动态 sign 计算。将所有API调用封装在后端服务中。

3.1 签名算法

接口地址：https://api.thingboot.com/{AppID}/device/control/

请求参数必须在 URL 中携带 sign 和 ts，在 Body 中携带 device 和 order。

签名生成步骤：

获取当前时间戳（秒） ts。
对 AppSecret 进行一次 MD5 加密：secret_md5 = md5(AppSecret)。
将 secret_md5 与 ts 拼接成字符串。
对拼接后的字符串再次进行 MD5 加密得到 signsign = md5( secret_md5 + ts )

3.2 接口调用示例

请求格式：

Method: POST
Content-Type: application/json
URL: /api.thingboot.com/{你的AppID}/device/control/?sign={计算的值}&ts={当前时间戳}

Body 示例（开灯/关灯）：

语音播报示例（TTS版本）：当用户下单成功或时间快结束时，通过接口让包间喇叭播报提醒。

4. 关键业务场景实现

在共享茶室项目中，有几个核心逻辑必须在对接代码中处理：

4.1 订单开始（通电）

动作：用户支付成功后。
逻辑
1. 调用 API 下发 order: {"power1": 1} （照明）。
2. 调用 API 下发 order: {"power2": 1} （麻将机/饮水机）。
3. 调用 API 下发 order: {"power4": 1} （空调）。
4. 注意：门禁（第3路）通常在订单开始后不开锁，而是保持关闭状态，允许用户通过小程序点击“开门”或刷脸触发短暂开锁，防止外人进入。

4.2 临时开门（防钓鱼）

场景：用户中途出去上厕所/抽烟，需防止门关上后进不去。
逻辑：小程序提供“开门”按钮 -> 后端调用 {"power3": 1} -> 电磁锁断电 -> 门拉开（延时3-5秒）-> 后端自动/手动调用 {"power3": 0} 恢复上锁。 切忌一直给第3路通电，否则电磁锁线圈会烧毁。

4.3 订单结束（全断与复位）

动作：用户点击退场或时间耗尽。
逻辑：使用批量控制命令，一次性关闭所有继电器。
// 全关命令 "order": {"power": 0}

4.4 定时器与联动（本地执行）

为了减少服务器轮询压力，可以在设备端设置定时任务（通过后台设置）：

空调保护：设置设备逻辑为关门断电后，延时3分钟再切断空调电源，保护压缩机。
深夜静音：设置定时任务，23:00后如果检测到无人移动，自动关闭换气扇。

5. 对接注意事项与排错

根据实际项目对接经验，以下几点容易出错：

局域网直连 vs 云端控制
- Mini控制器支持局域网HTTP控制。如果收银系统与Mini控制器在同一路由器下（且路由器未隔离），可以直接通过 http://{设备IP}/control 发送指令，延迟极低且不依赖外网。但考虑到远程运维和商业保险，通常还是走云端API，利用其自动重连机制。
感性负载限制
- 第1、2路如果接的是麻将机电机（感性负载），标称3500W，实际安全使用控制在500W以内，否则多次开关产生的反向电动势极易损坏继电器。如果必须接大功率风扇/马达，外接交流接触器，用Mini控制器控制接触器的线圈。
设备ID的获取
- 千万不要手动输入错误。编写一个 getDeviceList 接口查询功能，自动拉取设备列表并同步到本地数据库，防止设备更换或复位后ID变更。
签名失败排查
- 80%的对接失败是因为时间戳（ts）时区不一致。请一定要确保服务器时间是正确的北京时间（UTC+8） 戳。
- md5 的结果通常为32位小写字符串。