怎么对接30W 自动语音通知音箱以实现内置铃声提示音播放_解决方案

CATALOG

解决方案：对接芯步30W自动语音通知音箱实现内置铃声提示音播放

一、概述

芯步30W智能语音壁挂音箱（型号：UNI-YY-YX-BG-30W）是一款支持HTTP接口控制的智能语音设备，内置5种铃声、5种提示音和5种警示音。本方案的目标是指导开发者如何通过开放接口对接该设备，实现远程触发内置铃声/提示音的播放功能。

适用场景

订单提醒、工单通知
设备故障告警、安防警示
定时任务提醒（如考勤、会议、作息）
生产流水线节拍提示

核心技术优势

即插即用，无需网关（WiFi 2.4G直连）
开放标准HTTP接口，支持任何编程语言
支持私有化部署和纯局域网环境

二、前置准备

2.1 硬件准备

项目	说明
设备型号	芯步智能语音壁挂音箱30W (UNI-YY-YX-BG-30W)
网络环境	2.4GHz WiFi，信号稳定
供电	100-250V AC市电

2.2 软件凭证

登录芯步控制台获取以下信息：

参数	说明	获取位置
AppID	应用唯一标识	控制台 → 开发设置
AppSecret	开发者密钥（用于签名）	控制台 → 开发设置
Device ID	设备唯一ID	控制台 → 设备列表

2.3 设备配网

长按设备按钮6秒进入配网模式
使用芯步官方App/小程序完成WiFi配置
支持预设5组WiFi，设备自动选择信号最强的连接

三、接口对接方案

3.1 核心接口说明

请求地址

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

签名算法

sign = MD5( MD5(AppSecret) + ts )

其中ts为Unix时间戳（秒），+表示字符串拼接

请求头

Content-Type: application/json

请求体结构

3.2 内置铃声/提示音命令速查表

音效类型	命令Key	值范围	说明	示例
铃声	`ring`	1 ~ 5	内置5种铃声（如门铃、电话铃等）	`{"ring":"1"}`
提示音	`message`	1 ~ 5	内置5种提示音（如通知滴声、确认音等）	`{"message":"3"}`
警示音	`alert`	1 ~ 5	内置5种警示音（如警报、蜂鸣等）	`{"alert":"2"}`

命令参考来源：

3.3 辅助命令（可选）

命令	Key	值范围	说明
音量	`volume`	0 ~ 9	0=静音，9=最大
停止播放	`stop`	0 或 1	0=停止当前，1=全部停止
音频音量	`audio_volume`	0 ~ 9	独立控制音频音量（如适用）

四、代码实现示例

4.1 Python实现（推荐）

import hashlib
import time
import json
import requests

class YoyoiotDevice:
    def __init__(self, app_id, app_secret, device_id):
        self.app_id = app_id
        self.app_secret = app_secret
        self.device_id = device_id
        self.api_url = f"https://api.thingboot.com/{app_id}/device/control/"
    
    def _generate_sign(self, ts):
        # 签名计算: MD5(MD5(AppSecret) + ts)
        step1 = hashlib.md5(self.app_secret.encode()).hexdigest()
        step2 = hashlib.md5((step1 + str(ts)).encode()).hexdigest()
        return step2
    
    def _send_command(self, order):
        ts = int(time.time())
        sign = self._generate_sign(ts)
        url = f"{self.api_url}?sign={sign}&ts={ts}"
        payload = {
            "device": self.device_id,
            "order": order
        }
        response = requests.post(url, json=payload, timeout=5)
        return response.json()
    
    # ========== 音效播放方法 ==========
    def play_ring(self, ring_id: int):
        """播放内置铃声 (1~5)"""
        return self._send_command({"ring": str(ring_id)})
    
    def play_message(self, msg_id: int):
        """播放内置提示音 (1~5)"""
        return self._send_command({"message": str(msg_id)})
    
    def play_alert(self, alert_id: int):
        """播放内置警示音 (1~5)"""
        return self._send_command({"alert": str(alert_id)})
    
    def set_volume(self, level: int):
        """设置音量 (0~9)"""
        return self._send_command({"volume": str(level)})
    
    def stop(self, all_stop: bool = False):
        """停止播放"""
        return self._send_command({"stop": "1" if all_stop else "0"})

# 使用示例
if __name__ == "__main__":
    # 替换为实际凭证
    device = YoyoiotDevice(
        app_id="你的AppID",
        app_secret="你的AppSecret",
        device_id="你的设备ID"
    )
    
    # 设置音量为5（适中）
    device.set_volume(5)
    
    # 播放铃声2号
    device.play_ring(2)
    
    # 播放提示音3号
    device.play_message(3)
    
    # 播放警示音1号
    device.play_alert(1)

4.2 curl命令行示例

4.3 Java实现（Spring Boot）

import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;
import java.security.MessageDigest;

public class YoyoiotService {
    private static final String API_BASE = "https://api.thingboot.com/";
    
    public void playRing(String appId, String appSecret, String deviceId, int ringId) {
        long ts = System.currentTimeMillis() / 1000;
        String sign = generateSign(appSecret, ts);
        String url = API_BASE + appId + "/device/control/?sign=" + sign + "&ts=" + ts;
        
        RestTemplate rest = new RestTemplate();
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        String body = String.format("{\"device\":\"%s\",\"order\":{\"ring\":\"%d\"}}", deviceId, ringId);
        HttpEntity<String> entity = new HttpEntity<>(body, headers);
        
        ResponseEntity<String> response = rest.postForEntity(url, entity, String.class);
        System.out.println("Response: " + response.getBody());
    }
    
    private String generateSign(String appSecret, long ts) {
        String step1 = md5(appSecret);
        String step2 = md5(step1 + ts);
        return step2;
    }
    
    private String md5(String input) {
        try {
            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();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

五、音效选择参考

编号	铃声类型	提示音类型	警示音类型	推荐用途
1	柔和门铃	短促“滴”	温和提示	普通通知、访客
2	清脆电话	双短“滴滴”	中速蜂鸣	订单提醒、工单
3	悠扬旋律	三连音	急促警报	重要提醒
4	轻快节奏	电子提示	连续警报	定时任务、节拍
5	古典风格	长提示音	紧急警报	紧急情况、撤离

具体音效请实际测试确认，不同批次可能存在差异。

六、常见问题和需要注意的点

6.1 网络相关

问题	解决方案
设备离线	检查WiFi信号强度，确保2.4GHz频段；设备支持5组WiFi自动切换
局域网内网不通	可私有化部署自建消息服务器，参考官方文档配置

6.2 命令执行

问题	解决方案
签名错误	确认AppSecret无额外空格，ts为秒级时间戳，MD5结果为32位小写十六进制
设备无响应	先调用`{"volume":"5"}`设置音量，确认设备在线后再发播放命令
同时播放冲突	可使用队列机制，待上一个播报完成后再下发新命令；或先发送`{"stop":"1"}`停止当前播放

6.3 音效播放要点

播放铃声/提示音时可配合TTS语音播报（play:gbk:16）实现“提示音+语音内容”组合效果
示例：{"play:gbk:16":"[message_3]欢迎光临"} 可实现先播提示音3再播报文字
若需连续播放多个音效，间隔500ms以上，避免设备处理冲突

七、快速验证流程

flowchart LR
    A[获取AppID/Secret/DeviceID] --> B[设备配网接入WiFi]
    B --> C[测试签名接口连通性]
    C --> D[设置音量: volume]
    D --> E[测试单个铃声: ring=1]
    E --> F[测试多个音效编号]
    F --> G[集成到业务系统]

验证命令示例（逐一执行）：

{"volume":"5"} — 设置音量
{"ring":"1"} — 播放铃声1
{"message":"2"} — 播放提示音2
{"alert":"3"} — 播放警示音3

八、总结

通过芯步的标准HTTP接口，对接30W自动语音通知音箱实现内置铃声播放非常简单：

核心命令：使用ring、message、alert三个命令，传入1~5的数值即可触发对应音效
签名机制：采用双层MD5加密，确保接口调用安全
扩展性：可配合volume、stop等命令实现完整控制，还可结合TTS语音播报实现更丰富的通知场景
部署灵活：支持公有云和私有化两种模式，满足不同网络环境需求

该方案已在芯步全系列智能语音设备（智能语音喇叭、智能语音音柱等）上验证通过，可直接用于生产环境。