如何二次开发智能 30W 语音音柱以实现远程音量调节控制_解决方案

CATALOG

芯步智能语音音柱支持通过HTTP接口进行二次开发，远程调节音量、音色、语速等参数只需向指定API发送JSON指令即可。以下是完整的实现方案。

一、背景与技术原理

芯步的智能30W语音音柱（型号：UNI-YY-YZ-30W）区别于传统的蓝牙或AUX音频音箱，它是一款物联网（IoT）设备。它直接连接WiFi（2.4GHz）或网线，拥有独立的IP地址，并开放了HTTP API接口。

核心逻辑：开发者无需操作物理按键，只需通过后端系统（Java, PHP, Python, Go等）向芯步云平台发送特定的HTTP请求，云端即时将该指令推送至音柱，从而实现远程音量调节。

二、准备工作

在开始编码之前，需要准备以下三项关键信息：

硬件就绪：确保音柱已接通电源并成功连接至互联网（WiFi或有线）。
获取凭证
- AppID：应用唯一标识。
- AppSecret：应用密钥（用于签名加密）。
- Device ID：音柱底部的设备唯一ID（或从控制台查看）。
开发环境：支持HTTP协议的任何语言（本文方案通用）。

三、 API接口详解

1. 请求地址

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

注：{AppID}直接拼接在URL路径中，不要使用问号传参。

2. 签名机制（鉴权）

为了防止接口被恶意调用，芯步使用了动态签名机制。签名计算规则如下：

将 AppSecret 进行第一次MD5加密，得到 secret_md5。
获取当前Unix时间戳（秒级） ts。
将 secret_md5 与 ts 字符串直接拼接，再进行一次MD5加密，得到最终的 sign。

公式：

sign = md5( md5(AppSecret) + ts )

3. 核心指令：调节音量

根据产品手册，30W音柱的音量调节指令如下

参数名volume
取值范围0 (静音) 至 9 (最大音量)。
类型：字符串或数字。

四、代码实现示例

以下示例展示如何通过代码将音柱音量调整至“5”（中等音量）。

示例 1：使用 Java (Unirest)

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

public class VolumeController {
    public static void main(String[] args) {
        String AppID = "YOUR_APP_ID";
        String AppSecret = "YOUR_APP_SECRET";
        String DeviceID = "YOUR_DEVICE_ID";
        
        // 1. 构建签名
        long ts = System.currentTimeMillis() / 1000; // 秒级时间戳
        String secretMd5 = DigestUtils.md5Hex(AppSecret);
        String signRaw = secretMd5 + ts;
        String sign = DigestUtils.md5Hex(signRaw);
        
        // 2. 构建URL
        String url = "https://api.thingboot.com/" + AppID + "/device/control/?sign=" + sign + "&ts=" + ts;
        
        // 3. 构建JSON Body (设定音量为5)
        // order = {"volume":5}
        String orderJson = "{\"volume\":5}";
        
        // 4. 发送请求
        HttpResponse<String> response = Unirest.post(url)
                .header("Content-Type", "application/json")
                .body("{\"device\":\"" + DeviceID + "\", \"order\":" + orderJson + "}")
                .asString();
        
        System.out.println("Response: " + response.getBody());
        // 输出 {"code":200} 代表指令已送达云端
    }
}

示例 2：使用 PHP (cURL)

示例 3：使用命令行 cURL (调试用)

如果你只想通过命令行快速测试，可以直接用 curl 命令：

五、进阶扩展：完整的远程控制体系

除了单纯的音量调节，利用此接口还可以构建一个完整的智能音频管理系统：

1. 动态场景切换（音量与时段的结合）

场景A（白天/嘈杂环境）：通过程序调用 {"volume":8}，并播报{"play:gbk:16":"[message_1]请XXX到3号窗口"}，确保音量足够覆盖噪音。
场景B（夜晚/安静环境）：通过定时任务（Cron Job）自动调用 {"volume":2}，避免扰民。

2. 多设备分组控制（广播系统）

接口的 device 参数支持批量控制，格式为 "device":"ID1,ID2,ID3"。

此特性可用于商场消防联动、工厂车间分区广播等场景。

六、注意事项

返回值200不等于设备已执行API返回 {"code":200} 仅代表云端接收到了指令。如果音柱此时离线（断网），指令将不会生效。对于必须生效的场景，监听芯步的消息推送（设备状态回调）来获取执行反馈。
参数类型兼容性虽然示例中使用的是 {"volume":5}（整数），在某些旧版固件中可能需要使用字符串 {"volume":"5"}。如果遇到指令下发成功但音量未变的情况，两种类型都尝试一下。
私有化部署如果你的系统运行在纯内网环境，芯步支持私有化部署。此时API地址将变更为你自建服务器的地址，而非api.thingboot.com，通信将完全不经过公网。

通过上述方案，你可以轻松将芯步30W智能音柱集成到现有的ERP、餐饮叫号系统或工业自动化报警系统中，实现远程无人化音量控制。