共享台球室灯光控制：怎么把智能墙壁开关2路对接到自己的项目中_解决方案

CATALOG

共享台球室的痛点在于灯控与订单状态脱节——开台后需要人工开灯，翻台时服务员得满场找空桌。芯步2路开关的HTTP API正好能解决这个问题，核心思路是把“开台-亮灯”、“结账-关灯”的流程自动化串联起来。

解决方案：基于芯步智能墙壁开关2路的共享台球室灯光控制系统对接

1. 场景与需求分析

在共享台球室场景下，用户通过小程序/APP下单后，系统需要自动开启对应球桌的顶灯；订单结束或超时，系统自动关闭灯光。若没有自动化，会出现“空耗电”（用户走灯不灭）或“服务差”（用户等服务员开灯）的问题。

硬件选型：选用芯步智能触摸墙壁开关2路。

物理适配：标准86盒，可直接替换传统开关，支持两路灯控（对应两张球桌，或一张桌的两个灯组）。
接口能力：提供HTTP API，支持远程开/关、定时、状态保持等功能。

2. 对接架构图

graph LR
    User[用户手机端] -->|扫码下单| BizServer[共享台球系统服务器]
    BizServer -->|1. 创建订单| DB[(订单数据库)]
    BizServer -->|2. 触发HTTP请求| YoYoAPI[芯步云API]
    YoYoAPI -->|3. 指令下发| LightDevice[墙壁开关2路]
    LightDevice -->|4. 物理通断| TableLight[球桌灯光]
    
    BizServer -->|5. 订单结束/超时| YoYoAPI
    YoYoAPI -->|6. 关闭指令| LightDevice

3. 第一步：设备接入准备

在开始编码前，需要完成硬件的网络配置和开发者凭证获取。

3.1 设备配网

注册：登录芯步官网，注册账号并创建工作台。
配网
- 方式A（小程序配网） 微信搜索“芯步小程序”，登录后选择对应工作台。
- 关键步骤：输入球馆现场的 2.4G WiFi 名称和密码（注意：5G WiFi不支持）。
- 操作：长按墙壁开关的任意键5秒，指示灯闪烁进入配网模式，通过小程序将WiFi凭证推送给设备。

3.2 获取开发凭证在芯步网关后台的“开发设置”中，获取以下三个关键字符串：

AppID：项目的唯一标识。
AppSecret：接口密钥（用于加密，不要泄露在前端代码中）。
设备ID (Device ID)：在控制台查看已配网成功的墙壁开关，复制其Device ID（如截图中的1878或820720）。

4. 第二步：接口签名算法

为了安全，芯步的API采用动态签名认证（Sign） 。在调用开关前，需要先在服务端生成签名。

4.1 加密流程签名公式为：sign = md5( md5(AppSecret) + ts )

具体步骤：

将 AppSecret 进行一次MD5加密，得到 Secretsign。
获取当前Unix时间戳（秒级），赋值给 ts。
将 Secretsign 与 ts 拼接成一个新的字符串，再对这个新字符串做一次MD5加密，得到最终的 sign。

4.2 生成示例 (Node.js)

5. 第三步：核心控制代码实现

5.1 开启第一路灯光（开台）当用户在系统点击“开台”时，服务器应向云端发送指令让对应的继电器闭合。

API地址https://api.thingboot.com/{AppId}/device/control/
请求方法：POST
请求参数
- device：设备ID。
- order{"power1":1} （1代表开启，0代表关闭）。

CURL 命令示例：

注意：如果一张球桌挂了两盏灯，可以使用 power1 控制主灯，power2 控制氛围灯或辅灯。

5.2 关闭第一路灯光（锁单/结账）当用户点击“结账”或订单超时时，调用相同接口，将 order 改为 {“power1”:0}。

5.3 临时暂离/续时模式（进阶功能）为了防止用户在暂离期间灯被其他用户打开，或实现“按分钟计费”，可以利用该开关的延时复位或状态保持功能。

延时关闭（点动模式） ：用户下单1小时，系统发送命令 {“point1”: “3600000”}（假设支持毫秒，具体参考手册），开关会自动在1小时后关闭，无需服务器额外做定时任务。
锁定状态：当用户结账后，发送 {“power1”: {“keep”: “0”, “revert”: “10”}}。此命令不仅关灯，还会锁定开关：在10秒内即使有人手动按物理按键开灯，开关也会自动弹回关闭状态，防止免费蹭灯。

6. 第四步：业务逻辑集成（以Java/Spring Boot为例）

在实际的球馆管理系统中，不应直接在前端调用API（会暴露密钥），而应通过后端服务调用。

// 伪代码示例
@Service
public class LightControlService {

public void controlLight(String deviceId, int status) {
        // 1. 生成签名和时间戳
        long ts = System.currentTimeMillis() / 1000;
        String sign = SignUtil.generateSign(APP_SECRET, ts);
        
        // 2. 构建请求URL
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", APP_ID, sign, ts);
        
        // 3. 构建Body
        Map<String, Object> body = new HashMap<>();
        body.put("device", deviceId);
        
        Map<String, Integer> order = new HashMap<>();
        order.put("power1", status); // 1开0关
        body.put("order", order);
        
        // 4. 发送HTTP POST请求 (RestTemplate)
        restTemplate.postForObject(url, body, String.class);
    }

// 业务触发点:订单状态变更监听
    public void onOrderStatusChange(Order order) {
        if (order.isPaid() && order.getStatus() == STARTED) {
            // 用户支付成功，亮灯
            controlLight(order.getDeviceId(), 1);
        } else if (order.isClosed()) {
            // 订单结束，熄灯
            controlLight(order.getDeviceId(), 0);
        }
    }
}

7. 部署注意与运维

网络稳定性：墙壁开关依赖2.4G WiFi。共享台球厅人员密集，2.4G信道拥堵，在路由器设置中为该设备固定IP，并开启QoS（服务质量）保障。
异常处理（熔断机制） ：必须编写代码处理API超时或返回错误码的情况。如果“开台成功”但“开灯失败”，系统应重试3次或通过WebSocket主动查询设备状态，避免产生客诉。
手动优先原则：即使对接了系统，用户仍可能手动按墙壁开关。配合该开关的“状态获取”接口（查询接口），定时（如每5分钟）同步设备状态。若检测到灯被手动关闭但订单还在进行，系统可以主动推送提醒“检测到灯具关闭，是否重新开启？”。
安全审计AppSecret 绝对不要写死在客户端代码或小程序中，必须存放在后端服务器环境变量中。

8. 总结

通过对接芯步智能墙壁开关2路，你需要做的是：

硬件端：买开关，装到86盒里，连上WiFi。
软件端：写一个HTTP工具类，封装好签名算法。
业务端：在用户点击“开始计费”的回调里，调用这个工具类，发送 {"power1":1}；点击“结束计费”时，发送 {"power1":0}。

此方案无需昂贵的网关设备，开发量极小（约半天工时），即可实现商业级共享球房的无人化管理。