共享台球厅：怎么把智能照明控制器 4 路集成到自己的项目中_解决方案

CATALOG

共享台球厅的痛点是“人效”——无人值守时如何管理每个球台的灯和电源？芯步4路智能照明控制器正好解决这个问题，一台设备管4张台。以下方案涵盖硬件选型、接口对接、签名算法到核心代码实现，可直接落地。

解决方案：基于芯步4路控制器，打造无人值守共享台球厅

1. 概述与硬件选型

在共享台球厅场景中，痛点是人工管理成本高和电能浪费（顾客走后灯未关）。通过集成芯步的智能硬件，可以实现用户下单后自动通电、倒计时结束自动断电的完全自动化流程。

推荐硬件：芯步智能照明控制器 4路 16A （UNI-KZQ-ZM-4-16A）

为什么选它？
- 4路独立控制：正好对应台球厅的 4 张球台（或 1 个包厢里的 4 路灯光）。每路可独立控制通断，互不干扰。
- 负载能力强：16A 容量，不仅支持照明，还支持排风扇、空调、甚至自助售货机等大功率电器。
- 直连Wi-Fi：无需额外购买网关，通电后配置 Wi-Fi 即可联网，部署极其简单。
- 接口开放：提供标准的 HTTP 接口，无论你的小程序后端是用 Java、Python 还是 PHP 写的，都能无缝对接。

*示意图：将总闸接入输入端，1-4路输出分别接4张球台的顶灯或插座。*

2. 接口集成准备工作

在编写代码前，需要完成以下三步配置：

设备配网：给控制器通电，用手机 App 或微信小程序，将其连接到台球厅的 2.4G Wi-Fi 上（注意：5G Wi-Fi 不支持）。
获取凭证：登录芯步控制台，获取三个核心要素：
- AppID：你的应用唯一标识。
- AppSecret：用于生成签名的密钥（请妥善保管）。
- Device ID：这台 4 路控制器的设备编号。
理解签名机制：为了安全，每次请求都需要携带签名 sign。算法规则简单且固定，后端很容易实现：
- 公式sign = md5( md5(AppSecret) + "." + ts )
- ts 是当前 Unix 时间戳（秒级）。

3. 业务逻辑集成

这是落地的关键一步。你需要将设备指令与业务系统绑定：

场景闭环流程：

用户下单：用户在小程序支付了“1号台”1小时。
系统处理：支付回调触发 -> 后端计算当前时间戳和签名 -> 调用 API。
执行指令：向设备发送 {"power1":"1"}（开启1路）。
状态监控：设备成功开灯，返回 success。
定时结束：1小时倒计时结束 -> 后端再次调用 API 发送 {"power1":"0"}（关灯）。

4. 详细的接口调试与代码示例

你可以先在 Postman 等工具中调试，成功后写入后端代码。

API 请求详情

请求方式：POST
URLhttps://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}
HeaderContent-Type: application/json
Body (JSON)

后端代码示例（Python Flask）

以下是一个简单的下单即开灯的示例函数：

import requests
import hashlib
import time
import json

# 配置信息 (请替换为实际值)
APP_ID = "你的AppID"
SECRET = "你的AppSecret" 
DEVICE_ID = "你的设备ID"
API_URL = f"https://api.thingboot.com/{APP_ID}/device/control/"

def control_light(relay_num, action):
    """
    控制指定线路的灯
    relay_num: 线路号 (1-4)
    action: 动作 (1开 0关)
    """
    # 1. 生成时间戳和签名
    ts = str(int(time.time()))
    # 计算:md5(md5(密钥) + "." + 时间戳)
    md5_secret = hashlib.md5(SECRET.encode()).hexdigest()
    sign_str = md5_secret + "." + ts
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 2. 构造请求参数
    params = {
        "sign": sign,
        "ts": ts
    }
    
    # 3. 构造命令（以控制power1为例）
    order_key = f"power{relay_num}"
    payload = {
        "device": DEVICE_ID,
        "order": {
            order_key: str(action)  # 注意转为字符串 "1" 或 "0"
        }
    }
    
    # 4. 发起请求
    try:
        response = requests.post(API_URL, params=params, json=payload, timeout=5)
        if response.status_code == 200:
            # 解析返回结果，确认设备是否执行成功
            print(f"指令下发成功: {response.text}")
            return True
        else:
            print(f"接口异常: {response.text}")
            return False
    except Exception as e:
        print(f"网络错误: {e}")
        return False

# 示例调用:用户下单了1号球台，开启1路
if __name__ == "__main__":
    control_light(1, 1)  # 开启1号灯

其他语言参考

Java：使用 OkHttp 构造 POST 请求，逻辑同 Python 。
Node.js：使用 http 模块或 axios 库，拼接 device 和 order 参数。

5. 高级玩法：不仅仅是开关灯

芯步的控制器还支持一些高级指令，利用它们可以按时间计费或播放开场特效

先通后断模式
- 如果用户没关灯就直接离开现场时，你可以调用“先通后断”指令。例如 {"point":{"interval":1000}} 会让线路接通1秒后自动断开，起到“点动”或“复位”的效果，配合门禁逻辑非常有用。
批量控制
- 打烊时不需要一个个关，直接发送全关指令：{"batch":{"power":0}}。
状态查询与同步
- 开发后台管理页面时，记得调用设备状态查询接口。这可以帮你解决“硬件被人手工按了开关”与“软件订单状态不一致”的问题（例如订单未结束但灯被手动关了，系统可以自动检测并告警）。

6. 项目落地注意事项

网络环境：台球厅墙体较厚，确保设备安装位置 Wi-Fi 信号良好（信号强度 2 格以上）。设备支持配置 5 组 Wi-Fi，会自动选择信号最强的连接。
安全隔离：虽然设备支持 16A 大电流，但在强电箱内接线时，请请一定要由专业电工操作，并在每一路输出串联合适的空气开关，确保安全。
私有化部署：如果你对公网稳定性有顾虑（例如比赛期间必须保证网络不断），芯步支持私有化部署。你可以把平台部署在台球厅的局域网服务器上，即使外网断了，局域网内的控制指令依然有效。