如何对接60W 云远程语音音柱以实现HTTP 接口文本推送_解决方案

CATALOG

芯步60W语音音柱的HTTP接口采用“双重MD5签名”验证机制，调用流程清晰。以下方案涵盖签名算法、文本推送指令、多语种/数字读法优化，以及Java/Python/Node.js等主流语言的代码实现。

1. 概述与准备

芯步60W智能语音音柱（型号：UNI-YY-YZ-60W）是一款支持WiFi 2.4G联网的户外大音量设备，具备IP防护等级，适用于车间、停车场、加油站等嘈杂环境。其核心优势在于开放了标准的HTTP接口，允许开发者通过文本推送即时触发语音合成播报，无需预录音频。

在开始对接前，请完成以下准备工作：

硬件激活：确保60W音柱通电并连接至WiFi（仅支持2.4G网络）。
获取凭证：登录芯步控制台，在“开发设置”中获取 AppId（应用ID）和 AppSecret（开发者密码）。
设备标识：在控制台设备列表页面获取目标音柱的 Device ID（设备编号）。

2. 接口鉴权机制

芯步的开放接口采用动态签名验证，所有HTTP请求需携带 sign 和 ts 参数。

2.1 签名生成算法

签名生成逻辑如下：

将 AppSecret 进行第一次MD5加密，得到 encoded_secret = md5(AppSecret)。
拼接字符串：encoded_secret + 当前时间戳 ts（秒级）。
取拼接后的字符串进行第二次MD5加密，得到最终签名。

公式sign = md5( md5(AppSecret) + ts )

注意：时间戳ts需与计算签名时使用的保持一致，服务器会校验时间戳的有效性（通常为5分钟内）。

2.2 请求地址

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

3. 文本推送核心指令

60W音柱的核心播报命令参数为 order 对象中的 "play:gbk:16" 字段。

3.1 基础播报

若要音柱播报“托盘已到位，请开始装载”，请求Body如下

3.2 参数化控制（播报优化）

在实际工业场景中，往往需要调节音量或改变音色。芯步接口支持在播报前或播报时下发控制指令。

语音参数调节范围

参数指令	功能描述	取值范围	示例
`volume`	音量大小	0-9 (9级最大)	`{"volume":7}`
`voice`	音色选择	男声/女声	`{"voice":"女声"}`
`speed`	语速调节	0-9	`{"speed":5}`
`tone`	语调调节	0-9	`{"tone":5}`

流程：设备刚上线时下发一次音量设置指令，后续仅推送文本，以减少网络开销。

4. 关键功能与容错设计

为提升播报的自然度和系统的健壮性，芯步接口支持以下高级特性：

4.1 多音字与数字读法优化

TTS引擎支持特定标记来控制发音，避免如“五四路”读成“五四”或金额读错：

多音字：可使用同音字替换或依赖引擎自动识别，若需强制，可尝试在文本前后添加符号。
数字读法
- 金额：直接输入数字+元，如 100.5元。
- 手机号：按位读，输入 138****0000。
- 连续数字：可用短横线分隔或直接连续输入。

4.2 打断与紧急播报

如果当前音柱正在播报一条长文本，系统需要立即插入一条紧急通知（如“设备故障”）。

机制：新请求下发时，默认行为是立即打断当前播放，开始播报新推送的文本。
最佳实践：无需额外设置打断标志，直接推送最高优先级内容即可。

4.3 心跳与状态检查

若音柱长时间未在线（如WiFi信号弱），业务系统增加状态预检逻辑：

可调用设备信息接口查询设备在线状态。
若设备离线，业务系统应将待推送文本存入本地队列或数据库，待设备上线后补推。

5. 多语言代码实现示例

由于接口基于HTTP，任何语言均可对接。以下提供三种场景的代码片段。

5.1 Java (Spring Boot 环境)

利用 HttpClient 或 Unirest 实现，其中签名逻辑使用了 DigestUtils。

import org.apache.commons.codec.digest.DigestUtils;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class YoyoVoiceService {
    public static void main(String[] args) throws IOException, InterruptedException {
        String appId = "YOUR_APP_ID";
        String secret = "YOUR_APP_SECRET";
        String deviceId = "YOUR_DEVICE_ID";
        long ts = System.currentTimeMillis() / 1000;
        
        // 签名计算:md5(md5(secret) + ts)
        String md5Secret = DigestUtils.md5Hex(secret);
        String sign = DigestUtils.md5Hex(md5Secret + ts);
        
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", appId, sign, ts);
        
        // 构建请求体
        String jsonBody = String.format("{\"device\":\"%s\", \"order\":{\"play:gbk:16\":\"请注意，一号生产线出现异常\"}}", deviceId);
        
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                .build();
                
        HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    }
}

5.2 Python (Flask/Django 集成)

适合数据分析或爬虫脚本快速集成。

5.3 Node.js (适合服务端事件触发)

适合基于Express的Web应用处理订单或报警推送。

6. 联调与故障排查

如果接口返回错误或音柱不发声，可按以下清单排查：

签名错误 (401)
- 检查 AppSecret 是否正确（注意大小写）。
- 检查服务器时间是否准确，时间戳偏差过大会被拒绝。
设备离线 (1002)
- 音柱是否供电且WiFi信号覆盖正常。该设备仅支持2.4G WiFi，请勿连接5G信号。
- 检查设备是否绑定到了其他账户或被移除。
播报无声
- 检查 order 中的 volume 参数是否误设为0。
- 确认音频线（若外接音箱）连接正常，主板功放指示灯是否亮起。

7. 总结

芯步60W音柱的HTTP接口设计符合RESTful规范，通过计算双重MD5签名保障了设备控制的安全性。开发者只需关注业务逻辑中的文本拼接，并将该接口集成到现有的MES、WMS或报警系统中，即可在3秒内（网络RTT约80-120ms）实现工业现场的远程语音调度。