如何接入60W语音播报音柱来实现语音通知推送_解决方案

CATALOG

芯步60W语音播报音柱基于标准HTTP接口，采用MD5双重签名验证，可快速集成到各类业务系统中。以下是完整的接入方案。

1. 产品概述与技术特性

芯步智能语音音柱Pro 60W（型号：UNI-YY-YZ-PRO-60W）是一款支持远程文本转语音（TTS）播报的物联网设备。它具备以下核心特性，使其成为工业级语音通知的理想选择：

开放接口：设备开放标准HTTP接口，这意味着任何支持HTTP请求的编程语言（Java、Python、Node.js、PHP、C#等）或开发平台（小程序、SaaS、低代码平台）都能轻松集成。
高音质与高音量：60W大功率输出，配备2寸高音+4寸中低音发声单元，灵敏度达89db，适用于车间、停车场、加油站、场馆等嘈杂的户外或工业环境。
部署灵活：支持2.4G WiFi无线连接，无需网关，即插即用。同时支持私有化部署，可运行在纯局域网环境，满足数据安全要求。
音频格式：支持文本直接播报，无需预先录制MP3文件。

2. 接口鉴权与请求机制

接入芯步生态的核心是调用其设备控制API。所有接口调用均需通过签名进行身份验证，确保通信安全。

2.1 请求地址

POST https://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}

{AppId}：应用ID，在芯步开发者控制台创建应用时获取。
{sign}：接口签名，用于验证请求合法性。
{ts}：Unix时间戳（秒），用于防止请求重放。

2.2 签名算法

签名生成规则如下：

将AppSecret进行MD5加密，得到 secret_md5 = md5(AppSecret)。
拼接时间戳：tmp_str = secret_md5 + ts。
将tmp_str再次进行MD5加密，得到最终签名：sign = md5(tmp_str)。

2.3 请求Header与Body

HeaderContent-Type: application/json
Body：包含目标设备ID和具体的控制指令。

参数名	类型	必填	描述
`device`	String	是	设备唯一ID，可在控制台查看，支持批量下发（用逗号分隔）
`order`	JSON	是	控制指令，详见下文命令列表

3. 核心语音播报指令集

针对60W音柱，主要通过order字段中的不同命令来实现音量控制、内容播报等功能。以下是常用的JSON指令示例：

功能	指令JSON示例	参数说明
文本播报	`{"play:gbk:16":"通知内容"}`	核心播报指令。`play:gbk:16`表示以GBK编码播报中文文本
音量调节	`{"volume":"7"}`	范围0-9，数值越大音量越高
音色切换	`{"voice":"1"}`	`0`：女声（默认），`1`：男声
语速调节	`{"speed":"5"}`	范围0-9，数值越大语速越快
语调调节	`{"tone":"5"}`	范围0-9，影响声音的抑扬顿挫
播放提示音	`{"message":"3"}`	内置1-5种提示音，可用于播报前的提醒
停止播报	`{"stop":"0"}`	`0`：停止当前播报；`1`：停止全部

多指令组合使用说明在实际应用开发中，若需在播报前调节音量并播放提示音，在应用层进行逻辑组合，或者连续调用API下发配置指令。例如先下发{"volume":"7"}，再下发{"message":"1"}和{"play:gbk:16":"8号车间发生告警"}。

4. 代码接入示例

以下是一个较为接近生产环境的Java接入示例，使用了OKHttp3库，模拟了通常的对接流程：

import okhttp3.*;
import org.apache.commons.codec.digest.DigestUtils;
import java.io.IOException;

public class YoyoVoiceBroadcaster {

// 配置参数（从控制台获取）
    private static final String APP_ID = "YOUR_APP_ID";
    private static final String APP_SECRET = "YOUR_APP_SECRET";
    private static final String DEVICE_ID = "YOUR_DEVICE_ID";

// API 地址模板
    private static final String API_URL = "https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d";

public static void main(String[] args) throws IOException {
        // 1. 生成时间戳和签名
        long ts = System.currentTimeMillis() / 1000;
        String sign = generateSign(APP_SECRET, ts);

// 2. 构建请求URL
        String url = String.format(API_URL, APP_ID, sign, ts);

// 3. 构建业务指令 (以调节音量至7，并播报指定文本为例)
        String orderJson = "{\"volume\":\"7\"}";
        // String broadcastOrder = "{\"play:gbk:16\":\"请注意，仓库入库区有新车辆到达。\"}";
        
        // 构建请求Body，此例演示先调节音量
        String requestBody = String.format("{\"device\":\"%s\",\"order\":%s}", DEVICE_ID, orderJson);

// 4. 发送请求
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
                .url(url)
                .post(RequestBody.create(requestBody, MediaType.parse("application/json")))
                .build();

try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
            System.out.println(response.body().string());
        }
    }

/**
     * 签名生成规则:md5(md5(secret) + ts)
     */
    private static String generateSign(String secret, long ts) {
        String firstMd5 = DigestUtils.md5Hex(secret);
        String combined = firstMd5 + ts;
        return DigestUtils.md5Hex(combined);
    }
}

关键点说明

示例中使用了commons-codec进行MD5加密。
实际业务中，若需连续下发不同指令（如先设音量再播报），在两次请求间加入适当延时（如100ms），或处理服务端返回的并发限制。

5. 业务系统集成架构

在将60W音柱集成到现有的业务系统（如MES、WMS、停车场系统）时，采用以下架构模式：

5.1 直接调用模式

适用于低并发、单系统场景。例如，在仓库管理系统中，当PDA扫描入库单时，业务代码直接调用上述API接口触发音柱播报“入库单已创建”。

5.2 消息队列中间件模式

适用于高并发、多系统场景。由于音柱属于硬件设备，瞬时高并发请求可能导致设备响应延迟或IP被封禁。

组件	作用	说明
业务系统A/B/C	生产语音通知任务	产生通知但不直接调用API，而是发送到MQ队列
消息队列	削峰填谷	如RocketMQ/RabbitMQ，作为缓冲区
通知服务	消费队列，调用API	单线程或控制线程池大小，优雅调用API
60W音柱	执行播报	最终执行端

6. 常见故障排除指南

签名错误（401 Unauthorized）
- 原因：时间戳ts与服务器时间相差超过5分钟，或MD5计算错误。
- 解决：同步服务器时间（安装NTP服务）；检查字符串拼接是否无空格、无换行，严格按照md5(md5(secret) + ts)顺序。
设备离线（Device Offline）
- 原因：音柱未连接WiFi或信号差。
- 解决：检查音柱配置页面的网络连接状态；确认设备支持2.4G WiFi（不支持5G频段）。
播报内容乱码
- 原因：文本包含特殊字符或编码格式不匹配。
- 解决：确保play:gbk:16指令下的文本使用GBK编码；发送前对JSON字符串进行转义处理。
无声音输出
- 检查音柱音量指令是否设置不为0；检查音柱电源及功放模块是否正常，音频线是否连接正确。
响应超时
- 检查防火墙或安全组是否开放了对外访问api.thingboot.com的权限；检查DNS配置是否正确。