怎么接入智能 30W 云语音壁挂音箱以实现内置铃声提示音播放_解决方案

CATALOG

芯步的智能语音设备通过开放的HTTP接口，支持直接调用内置铃声和提示音。以下是针对“智能30W云语音壁挂音箱”播放内置铃声的具体接入方案，涵盖签名计算、命令格式与代码示例。

解决方案：通过开放接口控制智能30W云语音壁挂音箱播放内置铃声/提示音

1. 准备工作

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

设备联网：确保“智能30W云语音壁挂音箱”已通过WiFi 2.4G网络成功连接至互联网（该设备支持直接联网，无需网关）。
获取凭证：登录芯步开放平台控制台，获取以下三个关键信息：
- AppID：应用唯一标识。
- AppSecret：开发者密码（用于签名计算）。
- Device ID：音箱背部的设备序列号或控制台分配的ID。
接口地址
- 请求URL：https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

2. 接口鉴权与签名计算

调用所有接口都需要在URL中携带签名（sign）和时间戳（ts）进行安全验证。

时间戳（ts）：当前Unix时间戳（秒级），例如 1715328000。
签名算法（Sign）md5( md5(AppSecret) + ts )
- 第一步：计算 AppSecret 的MD5值（32位小写），得到 secret_md5。
- 第二步：将 secret_md5 与时间戳 ts 拼接成字符串。
- 第三步：计算拼接后字符串的MD5值，得到最终的 sign。

计算示例（通用逻辑）：

AppSecret = your_app_secret
ts = 1715328000
step1_md5 = md5("your_app_secret") = 5d41402abc4b2a76b9719d911017c592
string_to_sign = 5d41402abc4b2a76b9719d911017c5921715328000
sign = md5(string_to_sign) = c484eb97ee288572db7828c6071dd88f

3. 核心指令：播放内置铃声与提示音

针对智能30W云语音壁挂音箱，播放内置铃声是通过特定的 order JSON字段实现的。该设备内置了多种铃声、提示音和警示音。

指令格式：

参数说明

参数名	类型	必填	说明
device	String	是	目标音箱的设备ID，若需控制多个可用逗号分隔（如 "id1,id2"）。
order	Object	是	命令对象。
ring	String/Int	是	核心字段：代表内置铃声的索引值。根据产品手册，支持 1-5 号铃声。

具体取值列表：

播放提示音：
- "ring": 1 ：提示音1 (通常为简短“滴”声)
- "ring": 2 ：提示音2 (通常为“叮咚”)
- "ring": 3 ：提示音3 (通常为“提示”)
- "ring": 4 ：提示音4
- "ring": 5 ：提示音5
播放警示音/铃声：
- 同理，该设备支持5种铃声（如电话铃声或警报声），通常对应索引 6-10，具体请以产品外壳标签或控制台指令集为准，常见场景下多复用 1-5 的索引进行测试。

完整请求Body示例（播放“叮咚”提示音）：

4. 代码接入示例

由于芯步接口支持任何支持HTTP请求的语言，以下是几种常见的集成方式。

方式一：使用 cURL（快速测试）

可以直接在终端中使用命令测试音箱是否响应。

方式二：Java (Unirest)

适合后端集成，如订单完成时播放提示音。

import com.konghq.unirest.http.HttpResponse;
import com.konghq.unirest.http.Unirest;
import org.apache.commons.codec.digest.DigestUtils;

public class PlayRingtone {
    public static void main(String[] args) {
        String AppID = "你的AppID";
        String AppSecret = "你的AppSecret";
        String deviceId = "音箱设备ID";
        long ts = System.currentTimeMillis() / 1000;
        // 1. 计算签名
        String sign = DigestUtils.md5Hex(DigestUtils.md5Hex(AppSecret) + ts);
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", AppID, sign, ts);
        // 2. 构建指令:播放铃声/提示音 (索引 1-5)
        String orderJson = "{\"ring\":1}"; 
        String requestBody = String.format("{\"device\":\"%s\",\"order\":%s}", deviceId, orderJson);
        try {
            HttpResponse<String> response = Unirest.post(url)
                    .header("Content-Type", "application/json")
                    .body(requestBody)
                    .asString();
            System.out.println("Status: " + response.getStatus());
            System.out.println("Response: " + response.getBody()); // 返回 {"code":200} 表示成功
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

方式三：Python (Requests)

适合轻量级脚本或自动化流程。

5. 常见问题与调试

返回值 code: 200 但音箱没响？
- 接口返回200仅代表云平台接收了指令并尝试下发给设备。如果设备离线或网络信号差，指令无法到达。
- ：检查设备是否亮灯在线，或通过控制台查看设备最后上线时间。
签名错误（code: 5006 bad sign）
- 请严格按照 md5( md5(AppSecret) + ts ) 的顺序计算。注意 ts 是直接拼接在 md5(AppSecret) 的字符串后面，不是数字相加。请一定要检查时间戳是否为秒级（10位数字）。
如何更换其他声音？
- 尝试修改 {"ring": 1} 中的数字，范围通常是1-5。根据产品描述，该设备内置5种铃声和5种提示音，具体音效对应的索引需要根据实际设备效果进行调整。
私有化部署说明
- 如果运行在局域网环境，该设备支持私有化部署。只需将请求地址中的 api.thingboot.com 替换为您自建的消息服务器地址即可，接口协议完全一致。

通过以上步骤，您可以轻松地将智能30W云语音壁挂音箱集成到现有的开单系统或报警系统中，实现即时、清晰的本地语音提醒。