如何对接智能 40W 壁挂远程控制语音音箱来实现HTTP接口文本推送_解决方案

CATALOG

芯步的40W壁挂音箱开放了标准HTTP接口，文本推送的核心是签名计算和命令结构。以下方案涵盖接口原理、签名算法、代码示例及进阶玩法，可直接复用。

一、对接概述与前置准备

1.1 适用产品确认

本文方案适用于芯步 智能语音壁挂音箱Pro 40W 型号（UNI-YY-YX-BG-PRO-40W）。该设备支持WiFi 2.4G/有线以太网连接，拥有40W大功率发声单元，适合会议室、车间、大厅等大面积室内场景。

1.2 准备关键参数

在开始对接前，请登录芯步开发者后台获取以下信息：

AppID：应用的唯一标识（在控制台的“开发设置”中获取）。
AppSecret：用于计算签名，保障接口调用安全。
Device ID：设备的唯一标识（在控制台“设备列表”或设备铭牌上查看，支持在命令中传入多个ID，用逗号隔开）。

二、接口协议详解

该设备的控制核心是一个支持POST方法的HTTP接口，请求与响应均为JSON格式。

2.1 请求地址（Endpoint）

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

{AppId}：路径参数，替换为你的应用ID。
sign：动态请求签名。
ts：Unix时间戳（秒）。

2.2 安全机制 —— 签名算法

接口采用双重MD5加密防止重放攻击，生成sign的步骤必须严格按照以下逻辑在Server端实现

将 AppSecret 进行一次MD5加密，得到 secret_md5。
将 secret_md5 拼接上当前时间戳 ts（字符串格式），得到 tmp_str。
将 tmp_str 再次进行MD5加密，得到最终的 sign（32位小写）。

公式：sign = MD5( MD5(AppSecret) + ts )

2.3 请求Body结构

device：字符串，必填。指定受控设备。
order：对象，必填。定义具体动作指令。

三、核心功能：文本语音合成推送

这是最常用的功能，即将字符串文本实时合成为语音并播放。

3.1 播报指令

在order对象中，使用 "play:gbk:16" 作为Key，待播报文本作为Value。

技术特性：该指令触发设备端芯片级TTS，支持GBK编码字符集，实测响应延迟约80-120ms。

3.2 语音参数调节

若需改变播放音色或语速，可通过辅助指令预先设置。这些指令同样通过order字段发送，一般在播报前调用。

功能	指令Key	取值范围	示例
音量	`volume`	0-9 (9为最大)	`{"volume": 7}`
音色	`voice`	`0`(女声，默认)，`1`(男声)	`{"voice": 1}`
语速	`speed`	0-9 (5为正常)	`{"speed": 6}`
语调	`tone`	0-9 (5为正常)	`{"tone": 5}`
停止播报	`stop`	`""` (空或任意值)	`{"stop": ""}`

数据格式：数据均为 Key:Value 对。

四、实战代码示例（HTTP文本推送）

以下示例展示如何通过代码构建合法的签名请求，并推送文本。

4.1 Python 3 实现

import hashlib
import time
import json
import requests

# 配置信息
APP_ID = "YOUR_APP_ID"          # 替换为后台AppID
APP_SECRET = "YOUR_APP_SECRET"  # 替换为后台AppSecret
DEVICE_ID = "YOUR_DEVICE_ID"    # 替换为目标设备ID

def generate_sign(secret, ts):
    # 1. MD5(AppSecret)
    step1 = hashlib.md5(secret.encode()).hexdigest()
    # 2. MD5(step1 + ts)
    step2 = hashlib.md5((step1 + ts).encode()).hexdigest()
    return step2

def send_tts(text):
    ts = str(int(time.time()))
    sign = generate_sign(APP_SECRET, ts)
    
    url = f"https://api.thingboot.com/{APP_ID}/device/control/?sign={sign}&ts={ts}"
    
    # 构造命令:先设置音量为8（可选），再播报文本
    payload = {
        "device": DEVICE_ID,
        "order": {
            "volume": 7,
            "play:gbk:16": text
        }
    }
    
    headers = {'Content-Type': 'application/json'}
    
    try:
        response = requests.post(url, data=json.dumps(payload), headers=headers, timeout=5)
        print(f"状态码: {response.status_code}")
        print(f"响应内容: {response.text}")
    except Exception as e:
        print(f"推送失败: {e}")

if __name__ == "__main__":
    send_tts("设备巡查提醒，发现温度异常，请工作人员注意。")

4.2 Java (Unirest) 实现

import kong.unirest.HttpResponse;
import kong.unirest.Unirest;
import kong.unirest.json.JSONObject;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class VoiceBroadcast {
    public static void main(String[] args) throws NoSuchAlgorithmException {
        String appId = "YOUR_APP_ID";
        String appSecret = "YOUR_APP_SECRET";
        String deviceId = "YOUR_DEVICE_ID";
        long ts = System.currentTimeMillis() / 1000L;
        
        // 生成签名
        String secretMd5 = md5(appSecret);
        String sign = md5(secretMd5 + ts);
        
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%s", 
                                    appId, sign, ts);
        
        // 构建命令
        JSONObject order = new JSONObject();
        order.put("volume", 9);
        order.put("play:gbk:16", "您的订单已打包完成，请取货。");
        
        JSONObject body = new JSONObject();
        body.put("device", deviceId);
        body.put("order", order);
        
        HttpResponse<String> response = Unirest.post(url)
                .header("Content-Type", "application/json")
                .body(body.toString())
                .asString();
        
        System.out.println(response.getBody());
    }
    
    private static String md5(String input) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] digest = md.digest(input.getBytes());
        StringBuilder sb = new StringBuilder();
        for (byte b : digest) {
            sb.append(String.format("x", b));
        }
        return sb.toString();
    }
}

五、高级特性与场景优化

5.1 多播控制与分组广播

芯步接口支持一次性向多个设备推送相同消息，只需在device字段中用英文逗号拼接设备ID。

5.2 多音字与数字读法优化

针对中文多音字和数字格式，系统内置了智能处理引擎

数字读法：金额（100元 → 一百元）、手机号（138... → 幺三八...）自动识别。
自定义停顿：在文本中加入或特定标点符号调节语速节奏。

5.3 混合提示音播报

在实际业务中，往往希望先播放一声“叮咚”或“警报”再播报内容。采用分步调用或一次性构建复杂命令（具体视固件支持），或者代码中先发送ring指令，间隔200ms再发送play指令。

六、常见问题排查

HTTP 401/403 签名错误
- 检查时间戳ts是否为Unix秒级时间戳，且与服务器时间误差不宜超过5分钟。
- 确认ts在计算签名和拼接URL时使用的是同一个字符串值。
- 确认签名经过两次MD5，且第一次MD5后的字符串拼接ts时无任何分隔符。
设备不在线
- 确保设备供电正常并连接了2.4G WiFi（注意不支持5G WiFi频段）。
- 设备后台可能开启了“离线休眠”，尝试先发送一条stop或volume唤醒设备。
文本播报乱码或无声音
- 确认play:gbk:16中的编码标注与文本编码一致，一般中文环境使用GBK或UTF-8兼容模式。
- 检查volume音量值是否设置为0。

总结

要完成“HTTP接口文本推送”，核心在于 签名的正确计算 和 order字段的灵活运用。芯步的开放接口屏蔽了底层硬件细节，开发者只需按照上述RESTful规范集成，通常1小时内即可完成从注册到第一个“Hello World”语音的推送全流程。