一、背景与需求分析
随着共享经济模式的普及，共享沐浴房、洗浴中心VIP包间等场景对智能化管理的需求日益增长。经营者需要远程控制包间内的各类电器设备，实现计时计费、节能管理、用户体验优化等目标。
芯步推出的智能包间集中控制模块MINI（型号：UNI-KZQ-BJ-MINI）正是针对这类场景设计的专用硬件。本文档旨在指导开发者如何将该产品的开放HTTP API接口集成到现有项目中，实现沐浴房场景的智能化控制。
典型需求场景
用户下单后自动通电、开灯
使用时长耗尽前提醒用户
使用结束后自动断电、关空调
远程协助用户处理突发问题（如忘记关灯）
门禁电磁锁与订单状态联动
二、产品核心能力概览
2.1 硬件规格
智能包间控制器MINI提供4路独立控制输出，每路均可通过HTTP接口远程控制通断
| 线路 | 接口类型 | 额定负载 | 沐浴房场景典型应用 |
|---|---|---|---|
| 第1路 | 16A开关 | 3500W（阻性）/500W（感性） | 照明灯、换气扇、吸烟灯 |
| 第2路 | 16A插座 | 3500W（阻性）/500W（感性） | 饮水机、按摩仪、吹风机 |
| 第3路 | 10A门禁 | 2200W（阻性）/350W（感性） | 电磁锁、电插锁 |
| 第4路 | 30A插座 | 6600W（阻性）/1100W（感性） | 2匹空调 |
2.2 关键特性
WiFi连接：支持2.4GHz IEEE 802.11 b/g/n，无需网关直连路由
开放接口：提供完整的HTTP API，支持公网/局域网调用
实时响应：命令下发到设备响应约80-120ms
TTS版本可选：支持远程语音播报，可用于订单提醒、服务说明
私有化部署：支持自建消息服务器，可运行在纯局域网环境
2.3 支持的API命令类型
| 命令类型 | 说明 | 示例 |
|---|---|---|
| 单路控制 | 独立控制某一路开关 | {"power1":1} |
| 批量控制 | 同时控制多路 | {"batch":{"relay":[1,3],"power":1}} |
| 先通后断 | 先接通延时后断开 | {"point":{"relay":[1],"interval":1000}} |
| 先断后通 | 先断开延时后接通 | {"reset":{"relay":[2],"interval":2000}} |
| TTS播报 | 语音播报（仅TTS版） | {"play:gbk:16":"欢迎光临"} |
三、系统设计
3.1 整体架构图（文字描述）
┌─────────────────────────────────────────────────────────────┐
│ 用户终端层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 用户小程序 │ │ 商家管理端│ │ 后台管理 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼─────────────┼─────────────┼─────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ 业务服务层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 订单服务 │ │ 设备管理服务 │ │ 定时任务服务 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼─────────────────┼─────────────────┼───────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ API网关 & 控制系统 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 芯步开放平台 API │ │
│ │ 接口地址:https://api.thingboot.com/{AppId}/device/... │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────┬───────────────────────────────┘
│ WiFi/HTTP
▼
┌─────────────────────────────────────────────────────────────┐
│ 设备层 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 智能包间控制器MINI（沐浴房包间） │ │
│ │ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ │
│ │ │照明│ │换气│ │门锁│ │空调│ │ │
│ │ └────┘ └────┘ └────┘ └────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘3.2 接口调用流程
业务系统 芯步API MINI设备
│ │ │
│ 1.生成签名sign │ │
│ sign = MD5(MD5(Secret)+ts) │
│ │ │
│ 2.POST /device/control/ │ │
│ ────────────────────────►│ │
│ │ │
│ │ 3.转发控制命令 │
│ │ ────────────────────────►│
│ │ │
│ │ 4.设备执行并返回结果 │
│ │ ◄────────────────────────│
│ │ │
│ 5.返回执行结果 │ │
│ ◄────────────────────────│ │四、接口集成详细方案
4.1 前期准备
在开始集成前，需要完成以下准备工作
注册芯步开放平台账号：获取AppID和AppSecret
添加设备：在控制台中添加MINI设备，获取设备唯一ID
配置网络：确保设备连接2.4GHz WiFi，并能访问API服务器
选择版本：根据是否需要语音播报功能选择TTS版或普通版
4.2 签名生成机制
芯步的HTTP API采用双重MD5加密方式进行身份验证
sign = MD5( MD5(AppSecret) + ts )
参数说明
AppSecret：开发者密钥，在控制台获取ts：当前Unix时间戳（秒）拼接顺序：先将AppSecret进行MD5加密，得到32位字符串，再拼接ts，最后对拼接结果整体MD5
示例代码（签名生成）
4.3 API调用示例
4.3.1 单路控制
场景：用户下单成功后，自动打开照明灯（第1路）
其他单路命令
关闭第1路：
{"power1": 0}打开第2路：
{"power2": 1}关闭第3路：
{"power3": 0}打开第4路：
{"power4": 1}
4.3.2 批量控制
场景：用户开始使用，一键开启“使用模式”（照明+换气扇，关闭门锁）
命令说明
{"batch": {"relay": [1,3], "power": 1}}：同时打开第1、3路{"batch": {"relay": [2,4], "power": 0}}：同时关闭第2、4路{"batch": {"power": 1}}：全开所有线路{"batch": {"power": 0}}：全关所有线路
4.3.3 先通后断（点动模式）
场景：换气扇定时运行5分钟后自动关闭，或门禁控制（通电开锁，延时后自动断电以保护电磁锁）
命令说明interval单位为毫秒，300000毫秒=5分钟。
4.3.4 先断后通（复位模式）
场景：门禁控制中的远程开门（断电开锁型门禁），先断开门禁锁（第3路），用户进入后延时自动复位锁门。
4.3.5 TTS语音播报（仅TTS版）
场景：用户使用剩余时间不足时，通过语音提醒用户续费
编码说明:gbk:表示使用GBK编码，:16:表示音量等级（0-16）。
4.4 完整集成代码示例（Python）
五、沐浴房场景典型应用流程
5.1 完整使用流程
┌─────────────────────────────────────────────────────────────┐ │ 1. 用户下单 │ │ ├─ 业务系统判断订单有效 │ │ ├─ 调用API打开照明(第1路) + 换气扇(第2路) │ │ └─ 可选:发送TTS欢迎语 │ ├─────────────────────────────────────────────────────────────┤ │ 2. 门禁控制 │ │ ├─ 调用API执行先断后通（第3路，interval=5000） │ │ └─ 电磁锁断电5秒，用户推门进入 │ ├─────────────────────────────────────────────────────────────┤ │ 3. 使用中 │ │ ├─ 空调保持运行（第4路） │ │ ├─ 时间剩余预警:TTS播报提醒 │ │ └─ 用户可小程序自助续费 │ ├─────────────────────────────────────────────────────────────┤ │ 4. 使用结束 │ │ ├─ 时间耗尽或用户手动结束 │ │ ├─ 调用API关闭所有设备（全关） │ │ └─ 门禁自动上锁（第3路默认闭合状态） │ ├─────────────────────────────────────────────────────────────┤ │ 5. 清洁模式（可选） │ │ ├─ 保洁人员扫码进入 │ │ ├─ 只打开照明和换气扇 │ │ └─ 工作结束后关闭 │ └─────────────────────────────────────────────────────────────┘
5.2 定时任务配置
芯步平台支持在控制台设置远程定时任务，可用于：
每日定时消毒：凌晨2:00-2:30开启紫外线灯（需接入第1/2路）
定时换气：每小时开启换气扇10分钟，保持空气清新
空调预冷/预热：根据预约时间提前开启空调
六、高级集成场景
6.1 传感器联动（扩展方案）
芯步提供多种传感器产品，可通过服务端实现设备联动
场景：人体存在传感器 + MINI控制器 = 智能节能
传感器检测到包间无人超过15分钟 → 业务系统自动关闭空调和照明
传感器检测到有人进入 → 自动开启照明
实现的方式是：传感器状态变化时会实时推送消息到开发者服务器，业务系统根据消息内容触发MINI控制器的相应指令。
6.2 功率监测与异常告警
虽然MINI基础版不带电能计量功能，但业务系统可通过以下方式实现监测：
记录设备开关状态与时间
结合空调运行时长计算能耗
设置异常规则：如关门状态但照明持续开启超过30分钟 → 自动关闭
6.3 多设备批量管理
同一AppId下的所有设备可通过同一API管理
七、注意事项与最佳实践
7.1 电气安全
感性负载注意：电机类设备（换气扇、空调压缩机）启动电流较大，按感性负载额定值降额使用
接线规范：必须由专业电工按产品手册接线，确保断电操作
过载保护：虽然MINI支持较大功率，前端加装相应规格的空气开关
7.2 网络稳定性
确保WiFi信号强度，避免设备位于信号死角
支持配置5组WiFi网络，设备会自动选择信号最强的连接
开启静态IP或DHCP保留地址，避免IP变化影响局域网调用
7.3 接口调用优化
签名缓存：ts过大会导致签名失效，应在请求时实时生成
超时处理：网络波动可能导致请求超时，设置重试机制（3次，间隔递增）
异步处理：涉及多个包间的批量操作使用消息队列异步执行
7.4 故障预案
断网情况：设备断网后保持最后一次指令状态，重新联网后可恢复正常控制
本地备用：MINI设备保留物理按键（需外接轻触开关），可在网络异常时手动操作
状态同步：定期（如每5分钟）查询设备状态，确保数据库记录与实际一致
八、方案总结
通过集成芯步智能包间控制器MINI的开放HTTP接口，共享沐浴房项目可以实现：
| 维度 | 效果 |
|---|---|
| 运营效率 | 远程自动化控制，无需现场人员值守 |
| 用户体验 | 扫码即用，自动开门、开灯、开空调 |
| 节能降耗 | 使用结束后自动断电，杜绝浪费 |
| 系统扩展 | 标准化API，易于与现有订单系统集成 |
该方案适用于共享洗浴、酒店桑拿、健身房淋浴间等多种场景。如需进一步集成传感器实现更精细的联动控制，或需要私有化部署方案，可参考芯步开放平台的高级功能文档。
相关产品手册参考
《智能包间控制器Mini产品手册》
《智能包间控制器Mini[TTS版]产品手册》