怎样对接30W 远程 TTS 语音壁挂音箱来实现内置铃声提示音播放_解决方案

CATALOG

30W远程TTS语音壁挂音箱是芯步智能语音产品线中的工业级设备，支持通过开放接口远程触发内置提示音。以下方案涵盖接口协议、签名机制、指令格式及多语言代码示例。

1. 概述

1.1 目的

本文档旨在指导开发者如何利用芯步开放平台 API，对 30W 远程 TTS 语音壁挂音箱（以下简称“音箱”）下发指令，以播放设备内置的铃声、提示音或警示音。

1.2 适用产品

设备名称：智能语音壁挂音箱 | 款式1 （30W）
核心功能：支持远程 TTS 文本播报、内置铃声/提示音播放、音量/音色调节。

1.3 接口特性

协议支持：HTTP/HTTPS 或 MQTT。
控制模式：支持单设备精准控制或分组同步控制。
响应速度：命令下发到执行平均延时 < 120ms。

2. 准备工作

在开始对接前，请确保已完成以下步骤：

注册开发者账号：登录芯步开放平台控制台。
获取密钥
- AppID：应用唯一标识。
- AppSecret：开发者密码（用于签名计算）。
添加设备
- 在控制台“设备列表”中获取目标音箱的 Device ID（设备唯一ID，如 1878）。
- 注意：30W 壁挂音箱通常支持 WiFi 配网，请确保设备已在线。
了解指令集：确认音箱支持 ring（铃声）、message（提示音）、alert（警示音）等指令。

3. 接口鉴权与签名机制

芯步的 API 采用动态签名验证，所有请求必须在 URL 中携带 sign 和 ts 参数。

签名算法步骤

将 AppSecret 进行一次 MD5 加密，得到字符串 S1。
拼接 S1 与当前时间戳 ts（10位秒级）。
将拼接后的字符串再次进行 MD5 加密，得到最终的 sign。

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

时间戳要求ts 必须为中国时间（CST）的实时 Unix 时间戳，误差过大会导致 5006 bad sign 错误。

4. 播放内置铃声的指令详解

30W 壁挂音箱出厂预置了 5 种铃声、5 种提示音 和 5 种警示音。开发者无需上传音频文件，只需通过 order 参数指定类型和序号即可。

4.1 指令参数表

根据接口文档 向设备下发指令 中的定义，order 结构如下

音效类型	参数 Key	取值范围	示例值	说明
铃声	`ring`	1 ~ 5	`"ring": 3`	播放第3首内置铃声（通常用于来电或提醒）
提示音	`message`	1 ~ 5	`"message": 1`	播放“叮咚”、“您有新的订单”等短促音效
警示音	`alert`	1 ~ 5	`"alert": 5`	播放警报声（适用于紧急情况）
TTS 播报	`play:gbk:16`	字符串	`"play:gbk:16":"下班了"`	将文本转为语音朗读（可与铃声组合）

4.2 组合指令

为了达到最佳提醒效果（例如“先响铃，再说话”），下发 组合指令。芯步的指令格式支持 order 内包含多个动作。

示例（播报提示音+语音内容）

注：设备将先播放序号为3的提示音，紧接着进行 TTS 语音合成播报。

5. 对接实现步骤

5.1 通过 HTTP API 下发单次指令

使用 device/control 接口。

请求地址https://api.thingboot.com/{AppID}/device/control/
请求方法：POST
Content-Typeapplication/json

5.2 通过 MQTT 对接（推荐高并发场景）

Broker Addressmapi.thingboot.com
Port1883
Publish Topicapi/{AppID}/device/control

6. 代码示例

以下示例演示如何调用 API 让 30W 音箱播放内置铃声。

6.1 Go 语言示例

package main

import (
    "bytes"
    "crypto/md5"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "strconv"
    "time"
)

func main() {
    // 1. 配置参数
    AppID := "YOUR_APP_ID"
    AppSecret := "YOUR_APP_SECRET"
    DeviceID := "1878" // 替换为你的30W音箱设备ID
    
    ts := strconv.FormatInt(time.Now().Unix(), 10)
    
    // 2. 计算签名 md5(md5(secret)+ts)
    hash1 := md5.Sum([]byte(AppSecret))
    s1 := hex.EncodeToString(hash1[:])
    hash2 := md5.Sum([]byte(s1 + ts))
    sign := hex.EncodeToString(hash2[:])
    
    // 3. 构建指令 (播放内置铃声: ring=2)
    orderMap := map[string]interface{}{
        "ring": 2,              // 播放第2首铃声
        "volume": 8,           // 可选: 设置音量为8级(0-9)
    }
    requestBody := map[string]interface{}{
        "device": DeviceID,
        "order":  orderMap,
    }
    jsonData, _ := json.Marshal(requestBody)
    
    // 4. 发起请求
    url := fmt.Sprintf("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%s", AppID, sign, ts)
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()
    
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println("Response:", string(body)) // 返回 {"code":200} 表示成功
}

代码参考自芯步通用对接教程及官方签名逻辑。

6.2 cURL 示例

适用于快速调试：

代码参考自 Shell 脚本对接实践。

6.3 HTTP 原始报文示例

7. 常见问题与排错 (FAQ)

收到 code:200 但音箱没响？
- 原因200 仅代表云端已接收指令，不代表设备执行成功。
- 排查
  - 检查音箱是否在线（控制台查看设备状态）。
  - 检查音箱音量是否被调为 0（可下发 {"volume":7} 调节）。
  - 确认 Device ID 是否准确。
报错 5006 bad sign？
- 原因：签名计算错误。
- 排查：确认 AppSecret 未包含多余空格；确认 ts 为秒级（10位数字）；确认 MD5 结果为 32 位小写字符串。
30W 音箱最多支持多少种内置音效？
- 支持 5 种铃声、5 种提示音、5 种警示音。如需自定义复杂音频，使用 TTS 播报或通过其他协议进行媒体流推送（如 RTSP，具体需查阅高级配置）。
如何实现多台音箱同步播放？
- 使用 group/control 接口。先将多个音箱加入同一分组，向 group ID 下发指令，即可实现多台 30W 音箱同步播放铃声。

8. 总结

对接芯步 30W 远程 TTS 语音壁挂音箱播放内置铃声，核心在于正确构造包含 ring/message/alert 字段的 order JSON 串，并通过标准的签名鉴权机制下发至 device/control 接口。该方案集成简单，响应迅速，可广泛应用于智慧零售、工业预警及办公通知等场景。