共享台球室叫号预约提示场景：怎样把30W 远程控制 TTS 语音音柱对接到项目中_解决方案

CATALOG

芯步的开放接口采用统一的HTTP/MQTT指令下发机制，TTS音柱作为标准设备，只需向指定设备ID发送特定格式的JSON命令即可完成语音播报。以下是针对30W远程控制TTS语音音柱在共享台球室叫号预约场景中的完整对接方案。

一、场景需求分析

在无人值守的共享台球室中，顾客通常通过小程序预约时段。当预约时间临近或顾客到店前台确认时，需要一个声音洪亮、覆盖全场（通常多个隔间）的设备进行通知。

痛点：

即时性： 预约成功后需要马上提醒顾客开始打球或准备。
抗干扰： 环境嘈杂，普通蜂鸣器无效，需要高保真人声。
可区分： 只有涉及该订单的顾客或打扫阿姨需要听到，但音柱通常是广播，需避免过度打扰非相关顾客（通过内容区分：如“XX号桌张先生，您的订单已开始” vs “请阿姨打扫XX桌”）。

二、设计

对接方案采用 SaaS服务端直接下发指令 的轻量级架构，不依赖网关中转。

设备层： 30W TTS语音音柱（基于ESP8266或类似方案，支持Wi-Fi/4G）。
云平台层： 芯步开放API（负责设备连接状态维持与指令转发）。
业务层（管/用）： 共享台球室SaaS系统（您的业务服务器，处理订单逻辑、排队的[TTS]文本合成与指令签名）。

sequenceDiagram
    participant User as 顾客(小程序)
    participant Biz as 台球室业务服务器
    participant Yoyo as 芯步开放平台
    participant Device as 30W TTS音柱(硬件)

    User->>Biz: 1. 扫码下单/预约时段到点
    Biz->>Biz: 2. 业务逻辑判断(生成播报文本)
    Biz->>Yoyo: 3. HTTP POST (控制指令: Play 文本)
    Yoyo->>Device: 4. 长连接通道下发指令
    Device->>Device: 5. 本地TTS解析并功放播报
    Device-->>Yoyo: 6. 指令执行结果回执(ACK)
    Yoyo-->>Biz: 7. 异步消息推送(成功/失败)

三、对接前的准备工作（关键步骤）

在进行代码开发前，需在芯步控制台完成以下配置，否则接口将返回 5006（签名错误）或 5008（IP白名单错误）。

硬件配网：
- 确保30W音柱已通电。
- 使用“芯步”小程序或控制台的“网络配置”功能，将设备连接到现场的2.4G WiFi（注意：不支持5G频段）。
- 记录下控制台中生成的 设备ID (Device ID)，这是控制设备的唯一标识。
获取密钥（AppID & AppSecret）：
- 登录开放平台工作台，在“开发设置”中获取 AppID 和 AppSecret（开发者密码）。
设置IP白名单：
- 将您的共享台球室业务服务器的公网出口IP添加到控制台白名单中。如果您的服务器IP不固定，需要先固定IP或使用MQTT方式连接（MQTT无需白名单）。

四、核心技术实现：指令下发与签名

芯步接口采用双重MD5签名机制来防止接口被篡改。您的业务服务器在请求时需要动态计算sign。

1. 签名算法（Node.js 示例）

2. 下发TTS播报指令（核心逻辑）

针对30W音柱，播报指令通常封装在 order 字段中。根据芯步通用规范，文本播报的命令格式通常涉及 play 或特定文本属性。

API 请求详情：

URL:https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}
Method: POST (Content-Type: application/json)
Body (JSON):

*注：如果是中文字符，芯步后台通常处理得较好，但为了兼容性，确保HTTP Body的编码为UTF-8。有些设备支持调整音量，可附加 "volume": 80 参数。*

3. 业务场景代码逻辑（Python 示例）

以下代码模拟了“用户预约时间到点”触发语音播报的过程：

import requests
import hashlib
import time
import json

# 配置信息
APP_ID = "Your_App_Id"
APP_SECRET = "Your_App_Secret"
DEVICE_ID = "The_30W_Audio_Device_ID"

def control_tts_device(text_to_speak):
    # 1. 准备签名参数
    ts = str(int(time.time()))
    md5_secret = hashlib.md5(APP_SECRET.encode()).hexdigest()
    sign_str = md5_secret + ts
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 2. 构建请求
    url = f"https://api.thingboot.com/{APP_ID}/device/control/"
    params = {
        "sign": sign,
        "ts": ts
    }
    # 构建负载，假设设备支持直接文本播放
    payload = {
        "device": DEVICE_ID,
        "order": {
            "play": text_to_speak,
            "volume": 100  # 30W音柱在台球室满音量
        }
    }
    
    # 3. 发送请求
    response = requests.post(url, params=params, json=payload)
    result = response.json()
    
    if result.get('code') == 200:
        print("指令已成功下发给云端，正在推送给音柱")
    else:
        print(f"下发失败: {result.get('msg')}")

# 场景触发函数
def on_customer_check_in(room_number, customer_name):
    # 生成包含具体信息的语音文本，解决"谁、哪桌"的问题
    msg = f"温馨提示，{room_number}号球桌的{customer_name}，您的订单已生效，计时开始，祝您打球愉快。"
    control_tts_device(msg)

# 模拟预约到点
# on_customer_check_in("06", "张先生")

五、共享台球室“叫号预约”专项场景设计

仅仅能发声是不够的，我们需要利用30W音柱的特性设计完美的业务流程：

场景1：预约时段到点 / 临时开台（面向顾客）

触发条件： 顾客通过小程序下单支付成功，或预约的起始时间到达。
播报内容： “叮咚~ 欢迎光临【XX台球】，A08号球桌已为您解锁，请前往开打。请注意场地卫生，祝您玩的开心！”
技术细节： 调用接口时无需等待硬件响应（异步），音柱收到指令会在1秒内发声。

场景2：服务呼叫（面向服务员/老板）

触发条件： 顾客在小程序点击“呼叫服务”或“需要摆球”。
逻辑分配： 业务系统判断此时上班的服务员是谁，或者广播给所有员工区音柱。
播报内容： （仅员工区音柱响）“收到A08桌服务呼叫，请服务员尽快处理。”

场景3：超时与打扫提醒（面向保洁/超时顾客）

触发条件： 订单结束前5分钟，或订单已结束但顾客未离开。
播报内容： “尊敬的顾客，您的订单剩余时间不足5分钟，如需续费请扫码，以免断电影响您的体验。”
联动控制： 配合芯步的智能插座，在音柱提示后1分钟，切断球桌供电。利用30W音柱的大功率，确保在打球噪音中也能听到。

六、常见问题与排错（FAQ）

为什么调用了接口，设备没声音？
- 检查code： 接口返回200仅代表平台收到了指令，不代表设备执行。需订阅平台的消息推送查看设备是否回复了“执行失败”。
- 设备在线状态： 芯步控制台查看设备状态是否为“在线”。如果离线，检查WiFi密码是否正确（尤其注意路由器重启后）。
- 命令格式： 确认 order 里的JSON Key是否严格匹配产品手册。如果手册要求 {"play_text":"你好"}，你发了 {"play":"你好"}，设备会忽略。
30W音柱音量大但延迟高怎么办？
- 芯步采用MQTT长连接，延迟通常在毫秒级。如果延迟高，请检查业务服务器的公网带宽或是否跨地域（选择云服务器地域时，尽量靠近芯步API服务器）。
私有化部署（LAN模式）
- 如果台球室网络不稳定或担心外网中断，30W音柱支持局域网（LAN）私有化。如果您的SaaS系统部署在门店本地服务器，可以直接使用设备内网IP发送HTTP指令，完全不依赖外网。

七、总结

将30W远程控制TTS语音音柱接入共享台球室项目，技术核心在于利用芯步封装好的 HTTP API 进行签名调用。只需处理好设备ID管理和业务文本的TTS动态拼接，即可实现无人值守场景下的高效语音交互。

借助该方案，不仅可以实现叫号，还能联动门禁、插座实现“一码开台、自动断电”的全自动化管理，大大降低人工成本。