大厅语音播报：怎样将30W 远程控制 HTTP 接口壁挂音箱对接到自己的项目中_解决方案

CATALOG

大厅场景中，壁挂音箱通常用于排队叫号、工单播报、迎宾提示等场景，核心需求是低延迟和高稳定性。芯步的开放接口采用标准HTTP协议，无需网关中转，设备直连Wi-Fi即可工作。下面从设计到代码实现，完整说明对接流程。

一、解决方案架构与核心准备

在您的大厅项目中，逻辑架构非常简单：您的业务系统 ↔ 芯步云平台 ↔ 壁挂音箱。

通信方式：设备使用 Wi-Fi 2.4G 网络，只需配网即可在线，无需购买额外网关。
对接协议：全系支持 HTTP API，这意味着无论您的后端是 Java、Python、PHP 还是前端直接调用（需注意跨域和安全），都可以轻松集成。
核心优势：支持 TTS（文字转语音） 功能。您不需要提前录音，只要发送文字，音箱就会自动用合成的语音播报出来。

在开始对接前，请准备以下3项关键信息（在芯步控制台获取）：

AppID：您的应用唯一标识。
AppSecret：用于加密的密钥，严禁直接暴露在前端代码中。
Device ID：您购买的30W壁挂音箱的设备ID（通常贴在设备背面或包装上）。

二、详细对接流程

整个对接过程分为三个步骤：设备配网、签名计算、接口调用。

步骤1：设备初始化与配网

芯步的音箱支持多种联网方式。对于30W壁挂音箱，通常支持有线（LAN）和无线（Wi-Fi）。在大厅环境中，推荐使用Wi-Fi以降低布线成本。

操作方式：设备通电后，通常会自动开启一个热点或通过扫码进行配网。
配置策略：设备支持配置5组Wi-Fi网络，当信号不稳时会自动切换，这对于大厅等人员密集、信号复杂的场景至关重要。

步骤2：接口签名算法

芯步的API采用动态签名鉴权，确保接口安全。签名规则定义如下

参数组合md5( md5(AppSecret) + ts )
逻辑说明
1. 先将您的 AppSecret 进行一次MD5加密，得到字符串 S1。
2. 获取当前的Unix时间戳（秒级）ts。
3. 将 S1 与 ts 拼接成新字符串 S2。
4. 再将 S2 进行一次MD5加密，得到最终的 sign。

注：时间戳 ts 用于防止请求被恶意重放，服务器会校验时间戳的有效性。

步骤3：核心API调用

接口地址（POST方式）：https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

请求体参数（JSON格式）：

device: 填写您的设备ID（如 "1878"）。
order: 这是核心指令区。针对30W壁挂音箱，主要使用以下指令

功能分类	指令示例 (order字段)	说明
文本播报	`{"play:gbk:16":"你好，欢迎光临"}`	最常用指令。音箱会TTS播报中文内容。
音量调节	`{"volume":"5"}`	范围 `0-9`。
音色切换	`{"voice":"1"}`	`0`：女声（推荐），`1`：男声。
停止播报	`{"stop":"1"}`	立即停止当前播放内容。
内置提示音	`{"ring":"3"}`	内置铃声索引 `1-5`。

三、代码实战：如何对接您的项目

以下提供 Python 和 Java SpringBoot 两种常见后端语言的对接示例，直接复制到您的项目中修改参数即可。

示例 1：Python 接入（适用于Django/Flask后端）

此脚本模拟了当大厅有新订单时，自动触发语音播报。

import hashlib
import time
import json
import requests

# 1. 配置参数（请从后台替换为真实值）
APP_ID = "YOUR_APP_ID"
APP_SECRET = "YOUR_APP_SECRET"
DEVICE_ID = "YOUR_DEVICE_ID"  # 30W 音箱的设备ID

def send_voice(text):
    # 2. 计算签名
    ts = int(time.time())
    # 第一步:md5(AppSecret)
    md5_app_secret = hashlib.md5(APP_SECRET.encode()).hexdigest()
    # 第二步:md5(md5(AppSecret) + ts)
    sign_str = md5_app_secret + str(ts)
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 3. 构造URL和Header
    url = f"https://api.thingboot.com/{APP_ID}/device/control/"
    params = {
        "sign": sign,
        "ts": ts
    }
    headers = {
        "Content-Type": "application/json",
        "User-Agent": "Your-App-Name"
    }
    
    # 4. 构造Body:包含播报指令
    payload = {
        "device": DEVICE_ID,
        "order": {
            "play:gbk:16": text   # 推送给音箱的文字内容
        }
    }
    
    # 5. 发送请求
    response = requests.post(url, params=params, headers=headers, data=json.dumps(payload))
    return response.json()

# 模拟调用:大厅叫号
if __name__ == "__main__":
    result = send_voice("请 8888 号顾客到 3 号窗口办理业务")
    print(result)

示例 2：Java 接入（SpringBoot风格）

在您的 Service 层中，可以直接注入此逻辑。

import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;
import org.springframework.http.*;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

@Service
public class VoiceService {
    
    public String notifyHall(String message) {
        String appId = "YOUR_APP_ID";
        String appSecret = "YOUR_APP_SECRET";
        String deviceId = "YOUR_DEVICE_ID";
        
        // 1. 生成签名
        long ts = System.currentTimeMillis() / 1000L;
        String md5Secret = md5(appSecret);
        String signRaw = md5Secret + ts;
        String sign = md5(signRaw);
        
        // 2. 构建请求
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", 
                                   appId, sign, ts);
        
        // 3. 封装指令
        VoiceOrder order = new VoiceOrder();
        order.setPlay_gbk_16(message); // 对应 {"play:gbk:16":"内容"}
        
        RequestBody body = new RequestBody();
        body.setDevice(deviceId);
        body.setOrder(order);
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        HttpEntity<RequestBody> entity = new HttpEntity<>(body, headers);
        
        // 4. 发送（使用RestTemplate）
        RestTemplate restTemplate = new RestTemplate();
        ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, entity, String.class);
        return response.getBody();
    }
    
    // MD5加密工具方法
    private static String md5(String input) {
        // 实现MD5加密逻辑，此处省略具体代码
        // 可使用 org.apache.commons.codec.digest.DigestUtils
        return org.apache.commons.codec.digest.DigestUtils.md5Hex(input);
    }
    
    // 内部类定义
    static class VoiceOrder { public String play_gbk_16; 
                              public void setPlay_gbk_16(String v) { this.play_gbk_16 = v; } }
    static class RequestBody { public String device; public VoiceOrder order; 
                               public void setDevice(String d) { this.device = d; }
                               public void setOrder(VoiceOrder o) { this.order = o; } }
}

四、大厅场景下的高级优化

为了让30W音箱在您的大厅项目中更专业、更稳定，您在调试时关注以下三点：

网络环境适配（支持局域网）芯步的设备支持私有化部署和局域网通信。如果您的业务系统与音箱处于同一个局域网（且音箱获取到了局域网IP），您可以不经过公网云平台，直接向音箱的局域网IP发送HTTP请求。这可以极大降低公网延迟，保障网络断开时核心播报功能依然可用。
多设备分区播控在大厅场景中，您可能安装了多个30W音箱（如大厅前排、后排、VIP室）。只需在请求的 device 字段中用逗号拼接多个ID（例如 "1878,1879,1880"），即可实现一键全区域广播。若需单独控制，分别调用不同设备的API即可。
利用“数字与多音字”优化播报体验直接发送 “请 185 号到 3 号窗口”，音箱可能会将 185 读成 一八五。根据官方文档，您可以利用指令优化：
- 金额/数值[n2]1888 会读成 一千八百八十八。
- 手机号[n3]13800000000 会读成 幺三八零零零...。
- 多音字：使用 [=diao4] 来强制读音，如 请把空调调[=diao4]转一下。

总结

通过芯步的HTTP接口，将30W壁挂音箱集成到您的大厅项目中，本质上是调用一次HTTPS请求。您不需要关心底层的音频解码或硬件驱动，只需关注业务逻辑：“什么事件触发，播报什么文字”。无论是排队叫号系统对接，还是安防警报联动，均可通过上述代码规范快速实现。