芯步的4路包间控制器MINI 采用WiFi直连+HTTP API架构，单台设备就能独立控制照明、插座、门锁和空调四路电源。以下方案涵盖硬件接线、接口鉴权、核心代码实现以及私有化部署选项，可快速集成到各类管理系统中。
1. 产品概述与适用场景
智能包间控制器Mini 是一款专为服务型门店设计的物联网控制设备。它采用 WiFi 无线通信（支持2.4GHz），无需额外的网关，通过开放的 HTTP API 接口，即可将传统电器快速升级为智能设备。
核心价值：
高度集成：一台设备整合了照明、插座、门禁和空调控制，减少硬件投入。
部署灵活：Mini 尺寸（72mm*90mm），适合空间有限的配电环境。
接口开放：支持 HTTP API 和 MQTT 协议，可无缝对接现有的小程序、PC 管理系统或 SaaS 平台。
适用场景：共享棋牌室、自助茶室、无人健身房、琴房、剧本杀包间等。
2. 硬件接口定义
在开始开发前，请确认硬件接线，以便在软件中准确控制对应设备。该控制器提供 4路 独立继电器输出：
| 线路编号 | 额定电流 | 推荐接入设备 | 说明 |
|---|---|---|---|
| 第1路 | 16A | 照明、换气扇、吸烟灯 | 阻性负载最大 3500W |
| 第2路 | 16A | 麻将机、饮水机、按摩仪 | 感性负载最大 500W |
| 第3路 | 10A | 门禁电磁锁 / 电插锁 | 直流专用接口 |
| 第4路 | 30A | 2匹空调 / 取暖设备 | 阻性负载最大 6600W |
特别注意
第3路专门用于门禁控制，接线时注意区分直流正负极。
控制空调时，命令下发的是通断电。对于需要断电后延时开机的空调（压缩机保护），配合软件的“先断后通”指令使用。
3. API 接入流程
3.1 准备工作
注册账号：登录芯步开放平台，进入控制台。
获取密钥：在“开发设置”中获取 AppID 和 AppSecret。
设备配网：给控制器通电，通过官方手册指引将其连接至现场 2.4G WiFi 网络。
获取设备ID：在控制台设备列表页面，查看已激活的 Device ID（如
1878）。
3.2 接口鉴权（Sign 签名算法）
为了防止接口被恶意调用，所有 API 请求均需携带动态签名。算法规则如下：
将
AppSecret进行 MD5 加密得到SignKey。将
SignKey与当前时间戳ts（秒级）拼接。对拼接后的字符串再次进行 MD5 加密。
代码生成示例 (Python):
3.3 核心控制指令
向设备下发命令的 URL 结构如下：POST https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}
头部信息需包含 Content-Type: application/json。
A. 单路独立控制
这是最常用的场景，针对包间内的单个设备进行开关。
| 动作 | 请求 Body (JSON) | 说明 |
|---|---|---|
| 开灯 | {"device": "设备ID", "order": {"power1": 1}} | 开启第1路（照明） |
| 关灯 | {"device": "设备ID", "order": {"power1": 0}} | 关闭第1路 |
| 解锁 | {"device": "设备ID", "order": {"power3": 1}} | 给电磁锁通电，通常需在3-5秒后自动断电 |
| 开空调 | {"device": "设备ID", "order": {"power4": 1}} | 开启第4路（空调电源） |
B. 批量控制（一键结账/打扫）
用于包间退场时的场景化控制，例如一键关闭所有电器，并短暂通电开门。
| 命令类型 | 请求 Body (JSON) | 业务场景 |
|---|---|---|
| 全关 | {"device": "ID", "order": {"power": 0}} | 用户退单后，关闭所有灯光、空调 |
| 先通后断 | {"device": "ID", "order": {"point": {"relay": [3], "interval": 3000}}} | 开门：电磁锁通电3秒后自动断开（默认是通电开锁） |
| 先断后通 | {"device": "ID", "order": {"reset": {"relay": [4], "interval": 180000}}} | 重启空调：先断电路，3分钟（180秒）后重新通电 |
3.4 高级功能：TTS 语音播报
若采购的是 TTS版本 控制器，可以在控制设备的同时，让包间内的喇叭发出语音提醒。
命令示例：
注：命令中的 16 代表音量或语速等级，具体请参考产品手册 UNI-KZQ-BJ-MINI-TTS。
4. 开发实战：场景化集成
假设您正在开发一个 棋牌室管理系统，用户在小程序端点击“开包间”，您需要执行以下逻辑：
第一步：配网激活
通常由商家通过特定配网模式（如长按设备按键）将控制器连上Wi-Fi，此处略过。
第二步：用户自助开单（API联动）
当用户支付成功后，系统后端需依次调用两件事：
开门：发送
point指令给 第3路，让电磁锁通电开锁。上电：发送
power指令将所有继电器置为1，打开灯光和空调。
后端调用逻辑示意（伪代码）：
第三步：无人化自动断电
当用户点击“退单”或预定时间结束，触发回调：
全关：下发
{"power": 0}切断所有电源。释放门锁：如果使用的是通电开锁，直接断电即可上锁；如果是断电开锁的特殊门禁，请勿切断第3路电源。
5. 网络部署架构
根据项目需求，提供两种网络接入方案：
方案一：公有云标准模式（推荐入门）
架构：设备 <-> 芯步云 <-> 您的业务服务器。
优点：开发简单，无需维护MQTT Broker，支持远程管理和OTA升级。
适用：连锁门店、需要远程查看设备状态的管理系统。
方案二：局域网/私有化模式（高安全/低延迟）
架构：设备通过 HTTP 直连您的本地服务器 IP。
实施：在设备配网时，将
api.thingboot.com域名解析指向您的私有服务器地址，或在路由器层面做拦截转发。优点：数据不出局域网，断外网也能用，响应速度可达毫秒级。
适用：军工、金融级保密场景，或对云端延迟敏感的全自动产线。
6. 故障排查和需要注意的点
感性负载问题：第1、2路接电机或麻将机时，注意功率限制（最大 500W），超过可能导致继电器触点粘连。
命令返回 200 但设备不动
平台返回 200 仅代表指令已收到且格式正确。
请检查设备是否在线（离线状态下云端会缓存指令，上线后执行）。
请确认 WiFi 信号强度，该设备仅支持 2.4G WiFi。
签名错误
请注意 MD5 结果是 32 位小写 hex 字符串。
时间戳
ts是秒级，单位是秒，不是毫秒。
调试模式：在开发测试阶段，可以在控制台开启“调试模式”，此时系统会忽略 Sign 校验，方便直接用 Postman 测试接口连通性。
7. 总结
通过本文档，您可以在 30 分钟内完成 4路包间控制器Mini 的接口对接。该设备的 API 设计非常简洁，核心在于签名计算和指令封装。无论是接入 1 个包间还是 1000 个包间，代码逻辑均可复用，这得益于其清晰的 HTTP 接口设计和稳定的 WiFi 直连能力。