如何二次开发20W 物联网语音广播音柱来实现语音播放暂停控制_解决方案

CATALOG

芯步20W语音广播音柱开放HTTP接口，通过stop命令即可实现播放/暂停控制。以下是完整的二次开发方案，涵盖认证签名、接口调用和代码示例。

解决方案：基于芯步开放接口二次开发实现语音播报暂停控制

1. 引言

芯步的 20W 物联网语音广播音柱（以 UNI-YY-YZ-20W-LAN 为例）支持标准的 HTTP 接口控制，允许开发者将其集成到现有的软件系统（如ERP、SaaS、餐饮叫号系统、智慧工地看板）中。本方案将指导您如何通过二次开发，调用其开放接口实现核心的“语音播放与暂停”功能。

2. 准备与前提

在开始开发前，请确认您已具备以下条件：

硬件设备：已联网的芯步 20W 智能语音音柱（确保设备ID已知）。
开发者凭证：登录芯步官网，进入“工作台” -> “物联网控制台” -> “开发设置”，获取 AppID 和 AppSecret（开发者密码）。
网络环境：确保您的应用服务器能访问 api.thingboot.com（公有云模式），或已部署私有化环境。

3. 核心控制原理：如何实现“暂停”

音柱的核心功能通常包括“文本播报（TTS）”和“媒体播放”。要实现“暂停”当前播放的语音，系统需要通过 HTTP 向设备下发特定的控制指令。

根据设备指令集，暂停功能通过 order 参数中的 stop 指令实现

命令对象order
控制参数{"stop":"0"} 或 {"stop":"1"}，通常 0 代表停止当前任务，1 代表全部停止。

工作流程图如下：

sequenceDiagram
    participant App as 您的应用系统
    participant API as 芯步开放API
    participant Device as 20W 语音音柱

    Note over App,Device: 1. 播放流程
    App->>API: POST /device/control (order: play TTS)
    API->>Device: 下发播报指令
    Device-->>App: 返回播放成功状态

    Note over App,Device: 2. 暂停/停止流程
    App->>API: POST /device/control (order: stop)
    API->>Device: 下发停止指令
    Device-->>App: 返回停止成功状态
    Device-->>Device: 硬件停止音频输出

4. 接口签名与认证机制

芯步采用动态签名验证，所有 HTTP 请求必须携带 sign 和 ts（时间戳）。签名生成规则如下，切勿直接在代码中硬编码拼接字符串：

签名生成步骤：

将 AppSecret 进行 MD5 加密得到 secret_md5。
获取当前 Unix 时间戳（秒级）ts。
拼接字符串：string = secret_md5 + ts。
对上述字符串再次进行 MD5 加密，得到最终的 sign。

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

注：时间戳 ts 的有效期通常较短，如果服务器时间与标准时间误差过大，可能会报 5003 错误。

5. 详细开发步骤与API调用示例

以下是实现“播放”与“暂停”的具体接口调用逻辑。假设您的 AppID 为 YOUR_APP_ID，设备 ID 为 DEVICE_001。

5.1 发送语音播报

发起一次文本转语音播报，让音柱响起来。

请求地址POST https://api.thingboot.com/YOUR_APP_ID/device/control/
Query参数sign={计算值}&ts={当前时间戳}
请求Body (JSON)

注：play:gbk:16 中的数字代表编码格式或音量档位，具体请参考产品手册。

5.2 实现暂停/停止（核心功能）

当需要停止当前正在播放的刺耳提示音或长篇通知时，调用此接口。

请求Body (JSON)

设置 stop 为 0 通常意味着“立即停止当前播放任务”。

6. 代码实战（以 Java 为例）

以下代码演示了如何封装签名逻辑并发送 HTTP 请求来控制音柱。

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

public class YoyoAudioController {

private static final String APP_ID = "YOUR_APP_ID";
    private static final String APP_SECRET = "YOUR_APP_SECRET";
    private static final String DEVICE_ID = "DEVICE_001";
    private static final String API_URL = "https://api.thingboot.com/" + APP_ID + "/device/control/";

public static void main(String[] args) {
        // 1. 让设备播放一段语音
        sendCommand("{\"play:gbk:16\":\"系统通知，设备即将进行重启测试\"}");
        
        // 模拟播放2秒后
        try { Thread.sleep(2000); } catch (InterruptedException e) { e.printStackTrace(); }
        
        // 2. 强制暂停播放 (核心控制)
        sendCommand("{\"stop\":\"0\"}");
        System.out.println("指令已发送，音柱停止播放。");
    }

/**
     * 发送控制指令
     * @param orderJson 命令JSON字符串，如 {"stop":"0"}
     */
    public static void sendCommand(String orderJson) {
        long ts = System.currentTimeMillis() / 1000; // 获取秒级时间戳
        // 计算签名:md5( md5(Secret) + ts )
        String md5Secret = DigestUtils.md5Hex(APP_SECRET);
        String sign = DigestUtils.md5Hex(md5Secret + ts);

// 构建请求体
        String requestBody = String.format("{\"device\":\"%s\",\"order\":%s}", DEVICE_ID, orderJson);
        
        // 发送POST请求
        HttpResponse<String> response = Unirest.post(API_URL)
                .queryString("sign", sign)
                .queryString("ts", ts)
                .header("Content-Type", "application/json")
                .body(requestBody)
                .asString();

System.out.println("Response: " + response.getBody());
        // 在这里解析返回的 code，判断是否为 200
    }
}

7. 扩展控制能力

除了“暂停”，您还可以通过修改 order 参数实现更多管理功能，方便集成到后台管理界面：

音量调节{"volume":"5"} （范围 0-9）
切换音色{"voice":"1"} （0 女声，1 男声）
播放提示音{"message":"3"} （内置提示音编号）

8. 常见问题与优化

设备离线：调用接口返回错误时，请先检查音柱的物理网络连接。音柱支持断网重连机制。
签名失败 (5006)：确保 ts 是秒级（10位数字），不是毫秒级（13位），并且服务器时间与北京时间相差不超过几分钟。
高并发场景：如果是大量订单触发播报（如外卖接单），请注意接口频率限制（单个设备 1次/秒）。在您的应用服务层做请求队列或限流处理。
私有化部署：如果您的项目在纯内网环境运行，可以联系芯步技术人员将设备切换至私有化 MQTT 模式，此时 API 地址将变更为您自己的服务器地址。

通过以上方案，您可以快速实现对 20W 物联网音柱的播放暂停精细化管理，而无须依赖芯步的官方后台页面。