线下服务场景语音播报：怎样将5W 壁挂远程控制 HTTP 接口音箱接入到项目中_解决方案

CATALOG

芯步的5W壁挂音箱通过HTTP接口开放了TTS播报能力，核心对接流程其实很简单：获取凭证→计算签名→构造请求→下发文本。以下方案涵盖设备配网、接口调用、场景集成（订单/告警/定时播报）及局域网部署要点。

线下服务场景语音播报解决方案：5W壁挂远程控制 HTTP 接口音箱接入指南

一、项目概述与设备选型

在“线下服务场景”中，语音播报是连接线上业务与线下执行的关键环节。无论是餐饮门店的新订单提醒、工厂车间的设备告警，还是办公区域的人员通知，5W 壁挂远程控制音箱（型号：UNI-YY-YX-BG-5W） 提供了一个低成本、高实时的解决方案。

该设备的核心优势在于：

接口开放：提供标准的 HTTP API 接口，可无缝集成到现有的 ERP、OA、SaaS 或自研系统中。
硬件级 TTS：无需预先录音，直接推送文本，设备端毫秒级合成语音并播报。
部署灵活：支持 2.4G WiFi，无需额外网关，只要有网络覆盖即可通电使用。
私有化支持：支持纯局域网运行（自建消息服务器），保障数据安全。

二、硬件部署与网络配置

在开始代码接入前，需完成硬件的物理安装和联网。

安装位置
- 该设备为壁挂式设计（5W功率），适合覆盖 10-30 平米的房间（如：厨房出餐口、收银台、小型办公室、包间）。
- 安装高度在 2-2.5 米，确保声音传播无遮挡。
配网流程
- 设备通电后，会发出特定提示音，并进入 AP（热点）模式。
- 使用手机连接该音箱发射的 WiFi 热点，在浏览器弹出的配置页面中，输入目标场景的 WiFi 密码（仅支持 2.4G）。
- 设备支持设置多组备用 WiFi，当主网络信号不稳时自动切换。
- 联网成功后，在芯步后台的控制台会发现该设备，记录下唯一的 设备ID (Device ID)。

三、接口对接技术方案

这是项目集成的核心。音箱提供了一个“简单粗暴”的 HTTP 请求方式，无需复杂的 SDK，任何能发起网络请求的语言均可实现。

1. 接口协议概览

请求地址： http(s)://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}
请求方式： POST
数据格式： JSON
核心命令字段： {"play:gbk:16":"要播报的文本内容"}

2. 签名安全机制

为了防止接口被恶意调用，接口采用了动态签名验证，规则如下：sign = md5( md5(AppSecret) + ts )其中 ts 为当前 Unix 时间戳（秒）。

3. 代码实现示例

以下以 Python 和 Java 为例，展示如何在业务代码中触发播报：

Python 示例（推荐用于脚本、后端服务）

Java 示例（使用 OkHttp 或 Unirest）

import com.konghq.unirest.http.HttpResponse;
import com.konghq.unirest.http.Unirest;
import org.apache.commons.codec.digest.DigestUtils;

public class VoiceService {
    public static void main(String[] args) {
        String AppID = "YOUR_APP_ID";
        String AppSecret = "YOUR_APP_SECRET";
        String DeviceId = "820720";
        
        long ts = System.currentTimeMillis() / 1000L;
        // 计算签名
        String md5Secret = DigestUtils.md5Hex(AppSecret);
        String sign = DigestUtils.md5Hex(md5Secret + ts);
        
        String url = "https://api.thingboot.com/" + AppID + "/device/control/?sign=" + sign + "&ts=" + ts;
        
        String jsonBody = "{\"device\":\"" + DeviceId + "\",\"order\":{\"play:gbk:16\":\"工单异常，请检查流水线A\"}}";
        
        HttpResponse<String> response = Unirest.post(url)
                .header("Content-Type", "application/json")
                .body(jsonBody)
                .asString();
        
        System.out.println(response.getBody());
    }
}

4. 高级播报控制

除了单纯的文字播报，该接口还支持实时控制播报行为，在 order 字段中切换命令即可：

功能	Order JSON 示例	场景说明
紧急打断	`{"play":"紧急通知：全体集合"}`	原有的长播报未结束时，强制插入高优先级通知
音量调节	`{"volume":9}`	白天调至 7-9 级，夜晚调至 2-3 级避免扰民
清空/停止	`{"stop":""}`	立即停止当前所有播报任务
铃声提示	`{"ring":1}`	播报前先响铃，吸引注意力
音色切换	`{"voice":"1"}`	0-女声，1-男声

四、业务场景集成方案

根据“线下服务场景”的特点，我们可以在不同环节进行嵌入：

第一种场景：餐饮/零售 —— 多渠道订单语音流转

痛点：美团、饿了么、小程序、收银台POS机订单分散，容易漏单。
方案
1. 编写一个中间件服务，聚合各大平台的 Webhook 订单数据。
2. 解析订单内容，格式化为字符串（例如："XX平台，您有一个新的订单，请准备：XX商品 x 2份"）。
3. 调用上述 send_voice 方法，向厨房的 5W 壁挂音箱推送语音。
4. 优化点：如果订单暴增（如高峰期），程序可自动降低播报语速，或合并播报避免连续轰炸。

第二种场景：智慧办公/车间 —— 异常告警联动

痛点：监控大屏无人值守，异常事件无法实时通知到现场人员。
方案
1. 将音箱接入局域网（支持有线网版更佳）。
2. 通过 Modbus 或 API 轮询设备状态，当检测到温度过高、设备停机等异常数值时。
3. 触发告警逻辑，发送 {"play":"警告：3号车间温度异常，请立即检查"}。
4. 循环播报直到人工确认复位。

第三种场景：SaaS/低代码平台 —— 无需后端

痛点：不想搭建服务器，只想快速测试或使用 Excel 触发。
方案
- 使用 低代码平台 中的 HTTP 插件，直接填入 URL、Header 和 Body 即可实现点击按钮播报。

五、私有化部署与特殊配置

对于金融、政务或对数据安全敏感的企业：

自建消息服务器：该音箱支持纯局域网工作。你需要在本地服务器部署一个轻量级的 HTTP Server（如 Flask、Nginx）。
配置修改：在音箱配网时，将 API 请求地址从官方的 api.thingboot.com 修改为你内网服务器的 IP 地址。
隔离运行：音箱、业务服务器均在局域网内闭环，数据完全不经过公网，延迟可降低至 10ms 以内。

六、总结

将芯步 5W 壁挂音箱接入项目，本质上是一次 “软件定义硬件” 的过程。开发者只需关注 签名生成 和 HTTP 请求构造 这两个环节，无需关心音频驱动的底层实现。

实施清单

设备通电、配网，记录 Device ID。
后台获取 AppID 和 AppSecret。
编写 Demo 脚本，验证 play:gbk:16 指令。
封装公共语音服务层，应用到订单/告警逻辑中。
（可选）配置局域网私有化服务器。