如何二次开发智能包间控制器Max来实现包间清洁模式一键切换_解决方案

CATALOG

芯步智能包间控制器Max提供了完整的HTTP API接口，支持8路独立继电器控制。清洁模式一键切换的本质，是将“关门、开换气、关空调/麻将机”等系列操作打包成一个原子指令。以下方案涵盖接口协议、签名算法、前端集成到语音反馈的完整链路。

解决方案：基于芯步开放接口的包间清洁模式一键切换二次开发

1. 背景与需求

在棋牌室、茶室、剧本杀等共享包间场景中，上一轮客人离开现场时到下一轮客人入场之间的“清洁模式”转换至关重要。传统的操作需要服务员逐一手动关闭麻将机、空调，打开排风扇和灯光，效率低下且容易遗漏。

本方案的目标是利用智能包间控制器Max的开放API，通过二次开发，将“清洁模式”封装为一个原子化操作。服务员只需在小程序或PDA上点击一次 “一键清洁” ，控制器将自动执行预设的时序逻辑，并在清洁完成后自动复位。

2. 技术架构与接口基础

核心设备：芯步智能包间控制器Max (型号：UNI-KZQ-BJ-MAX-TTS)通信协议：HTTP API (支持任何支持HTTP协议的开发语言)关键能力

8路独立控制：第1-3路（照明/换气）、第4-6路（插座/麻将机/饮水机）、第8路（空调）。
批量指令：支持batch指令一次性切换多路状态。
时序控制：支持point（先通后断）和reset（先断后通）指令，用于实现断电重启或电磁锁控制。
语音播报：TTS版本支持在动作执行时播放语音提示。

二次开发对接流程

在芯步控制台获取 AppID 和 AppSecret。
设备配网后获取 Device ID。
后端服务器组装签名，调用 https://api.thingboot.com/{AppID}/device/control/ 接口。

3. 清洁模式逻辑设计

场景设定

正常营业模式：麻将机(第4路)通电、空调(第8路)运行、照明(第1路)开启、排风扇(第2路)关闭。
点击“一键清洁”后
1. 断电：立即切断麻将机、空调、饮水机电源。
2. 换气：打开排风扇。
3. 照明：切换为明亮清洁模式灯光（或保持全亮）。
4. 语音：播报“清洁模式已启动，正在排气...”。
5. 复位：保洁完成后，一键切换回待客模式。

线路规划

线路编号	用途	清洁模式动作
第1路	照明（主灯）	开启 (照亮环境以便清洁)
第2路	排风扇/新风机	开启 (排烟、去异味)
第4路	麻将机插座	关闭 (防止清洁时误触安全隐患)
第6路	饮水机	关闭 (节能)
第8路	空调	关闭 (清洁时无需制冷)

4. 核心二次开发代码实现

后端开发（以Java/Spring Boot为例）需要封装一个专门的清洁模式服务。

步骤一：签名生成工具类参考芯步的鉴权规则：Sign = md5( md5(AppSecret) + ts )

步骤二：清洁模式业务逻辑封装关键在于构建order JSON字符串。这里我们利用batch（批量）指令实现瞬间状态切换。

@Service
public class RoomCleanService {

@Value("${yoyo.appId}")
    private String appId;
    @Value("${yoyo.api.url}")
    private String apiUrl; // https://api.thingboot.com

/**
     * 切换到清洁模式
     * @param deviceId 控制器设备ID
     */
    public void switchToCleanMode(String deviceId) {
        // 组装命令:
        // 1. 关闭麻将机(4)、空调(8)、饮水机(6)
        // 2. 开启照明(1)、排风(2)
        // 注意:其他线路(3,5,7)若未使用，保持原状或关闭，这里默认维持现状，仅下发变化部分
        
        // 方案A:使用通用开关 (powerX)
        // Map<String, Object> order = new HashMap<>();
        // order.put("power1", "1"); // 照明开
        // order.put("power2", "1"); // 排风开
        // order.put("power4", "0"); // 麻将机关
        // order.put("power8", "0"); // 空调关
        
        // 方案B:推荐使用Batch批量模式（性能更优，代码更简洁）
        // 构建batch指令: 指定线路开启 -> [1,2], 指定线路关闭 -> [4,6,8]
        Map<String, Object> batchCommand = new HashMap<>();
        // 需要开启的线路: 1(照明),2(换气)
        batchCommand.put("on", new int[]{1, 2});
        // 需要关闭的线路: 4(麻将),6(饮水),8(空调)
        batchCommand.put("off", new int[]{4, 6, 8});
        
        Map<String, Object> order = new HashMap<>();
        order.put("batch", batchCommand);
        
        // 发送请求
        executeCommand(deviceId, order);
        
        // 可选:如果是TTS版本，发送语音播报指令
        // order = new HashMap<>();
        // order.put("play:gbk:16", "欢迎光临，清洁模式已启动，正在为您通风换气");
        // executeCommand(deviceId, order);
    }
    
    /**
     * 切换到正常营业模式 (退出清洁)
     */
    public void switchToNormalMode(String deviceId) {
        // 关闭排风(2)，开启空调(8)和麻将机(4)
        Map<String, Object> batchCommand = new HashMap<>();
        batchCommand.put("on", new int[]{4, 8});   // 开麻将机、空调
        batchCommand.put("off", new int[]{2});     // 关排风
        // 照明保持开启
        
        Map<String, Object> order = new HashMap<>();
        order.put("batch", batchCommand);
        
        executeCommand(deviceId, order);
    }
    
    private void executeCommand(String deviceId, Map<String, Object> order) {
        // 实际HTTP请求发送逻辑
        // 请求体构建: {"device":"xxx", "order": {上述JSON}}
        // 具体RestTemplate调用略
    }
}

5. 高级交互：时序控制与电磁锁联动

为了提高安全性，如果清洁模式涉及电磁门锁（第7路） 的自动控制，可以利用reset（先断后通）指令。

场景：保洁人员进入包间后，按下“清洁按钮”，门锁断电几秒自动复位，防止反锁。

如果需要实现一键全关（除了换气扇），可以直接下发：

6. Web前端 / 小程序集成示例

在前端界面上，增加一个“清洁模式”的开关按钮。通过Axios调用你自己的后端服务，再转发给芯步API（避免在前端暴露AppSecret）。

7. 部署与联动策略

硬件安装
- 将控制器安装在包间配电箱附近。
- 线路4（麻将机）：设置为常闭继电器逻辑，上电默认导通，避免因服务器故障导致设备无法启动。
私有化部署芯步设备支持私有化部署。如果客户对数据安全要求比较高，可以将API服务器部署在门店局域网内，控制器通过WiFi直接连接本地服务器，实现断网内网控制，保障清洁模式的低延迟与高可用。
定时任务结合如果包间有固定时段的强制保洁需求，可以利用控制器的“远程定时任务”功能，设置在凌晨2：00自动触发上述清洁指令，实现无人化管理。

8. 总结

通过上述二次开发，原本需要多步操作的控制流程被简化为 “一键切换” 。利用智能包间控制器Max的Batch批量指令，我们确保了照明、排风与高功率电器（麻将机、空调）状态的快速协同变更；结合TTS语音播报，保洁人员能实时获得操作反馈。该方案显著提升了共享包间营地的翻台效率，降低了人力沟通成本。