如何二次开发10W HTTP 接口语音壁挂音箱以实现语音提醒发送_解决方案

CATALOG

芯步的智能语音壁挂音箱开放了标准HTTP接口，通过“设备控制”API即可实现文本转语音的远程推送。以下方案涵盖签名计算、指令构造、多设备管理等关键环节，可快速接入现有业务系统。

1. 解决概述

1.1 适用场景

本方案适用于需要将语音提醒功能集成到现有业务系统中的开发者或企业。典型应用场景包括：

订单提醒：电商、外卖平台有新订单时自动播报
异常告警：监控系统检测到异常时触发语音警报
工位呼叫：产线或服务区工人呼叫特定岗位
排队叫号：医院、银行等场所的叫号系统
智能播报：停车场余位、天气预报、定时提醒等

1.2 技术方案架构

整个二次开发的核心架构包含以下四个层次：

核心交互流程：

业务系统触发事件（如新订单创建）
业务系统构造语音播报指令
携带签名调用芯步开放API
平台验证后将指令推送到目标音箱
音箱实时播报语音内容

2. 前置准备

2.1 账号注册与凭证获取

在进行二次开发前，需要先完成以下准备工作：

步骤	操作	说明
1	访问芯步开放平台	注册开发者账号
2	创建应用	在控制台中创建新应用
3	获取AppID和AppSecret	应用的唯一标识和密钥
4	添加设备	将10W语音壁挂音箱绑定到账号下
5	获取设备ID	在设备列表或设备外壳上找到唯一ID

2.2 设备参数确认

产品名称：智能语音壁挂音箱|款式1
产品型号：10W规格
连接方式：WiFi IEEE 802.11 b/g/n 2.4GHz
工作电压：DC 12V 2A
外观尺寸：175mm(长) × 175mm(宽) × 90mm(厚)
外壳材质：防火V0级PC材质

3. 核心API详解

3.1 接口基本信息

10W语音壁挂音箱的核心控制接口为/device/control/，用于向指定设备下发播报指令。

项目	说明
请求地址	`https://api.thingboot.com/{AppID}/device/control/`
请求方式	POST（推荐）或GET
签名位置	URL参数：`?sign={sign}&ts={ts}`
Content-Type	`application/json`

3.2 签名算法

芯步的API采用双重MD5加密方式进行身份验证：

参数说明：

AppSecret：开发者密码，在控制台获取
ts：Unix时间戳（秒级），如 1747212640
+：字符串拼接操作

计算示例（以Python为例）：

3.3 请求参数详解

URL路径参数

参数	必填	说明
AppID	是	应用ID，拼接到URL路径中
sign	是	计算得到的签名
ts	是	当前Unix时间戳（秒）

Body参数（JSON格式）

参数	类型	必填	说明
device	string	是	设备唯一ID，多个用逗号或竖线分隔，最多100台
gateway	string	否	网关设备ID，用于需要网关转发的场景
order	object/string	是	命令内容，JSON对象格式

3.4 语音播报核心指令

基础播报指令

语音播报使用play:gbk:16作为命令键，值为要播报的文本内容：

完整控制指令集

功能	命令键	值范围	示例
播报文本	play:gbk:16	任意文本	`{"play:gbk:16":"有新订单啦"}`
音量调节	volume	0-9（0静音，9最大）	`{"volume":"5"}`
音色切换	voice	0(女声)，1(男声)	`{"voice":"1"}`
语速调节	speed	0-9	`{"speed":"5"}`
语调调节	tone	0-9	`{"tone":"5"}`
内置铃声	ring	1-5	`{"ring":"3"}`
提示音	message	1-5	`{"message":"2"}`
警示音	alert	1-5	`{"alert":"1"}`
停止播报	stop	0(停止当前)，1(全部停止)	`{"stop":"1"}`

组合控制示例

可以同时下发多个控制指令：

4. 代码实现示例

4.1 Java实现（使用Unirest）

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

public class VoiceBroadcastService {
    
    private String appId;
    private String appSecret;
    
    public VoiceBroadcastService(String appId, String appSecret) {
        this.appId = appId;
        this.appSecret = appSecret;
    }
    
    /**
     * 发送语音播报
     * @param deviceId 设备ID
     * @param message 播报内容
     * @return 是否发送成功
     */
    public boolean sendVoiceBroadcast(String deviceId, String message) {
        // 1. 获取时间戳
        long ts = System.currentTimeMillis() / 1000;
        
        // 2. 计算签名:md5(md5(AppSecret) + ts)
        String sign = DigestUtils.md5Hex(DigestUtils.md5Hex(appSecret) + ts);
        
        // 3. 构造请求URL
        String url = "https://api.thingboot.com/" + appId + "/device/control/?sign=" + sign + "&ts=" + ts;
        
        // 4. 构造播报指令
        Map<String, Object> order = new HashMap<>();
        order.put("play:gbk:16", message);
        
        Map<String, Object> requestBody = new HashMap<>();
        requestBody.put("device", deviceId);
        requestBody.put("order", order);
        
        // 5. 发送请求
        HttpResponse<String> response = Unirest.post(url)
            .header("Content-Type", "application/json")
            .body(JSON.toJSONString(requestBody))
            .asString();
        
        // 6. 处理响应（code=200表示平台接收成功）
        return response.getStatus() == 200;
    }
    
    /**
     * 带播报前设置的语音播报
     * @param deviceId 设备ID
     * @param message 播报内容
     * @param volume 音量(0-9)
     * @param voice 音色(0女声/1男声)
     */
    public boolean sendAdvancedBroadcast(String deviceId, String message, int volume, int voice) {
        long ts = System.currentTimeMillis() / 1000;
        String sign = DigestUtils.md5Hex(DigestUtils.md5Hex(appSecret) + ts);
        String url = "https://api.thingboot.com/" + appId + "/device/control/?sign=" + sign + "&ts=" + ts;
        
        Map<String, Object> order = new HashMap<>();
        order.put("volume", String.valueOf(volume));
        order.put("voice", String.valueOf(voice));
        order.put("play:gbk:16", message);
        
        Map<String, Object> requestBody = new HashMap<>();
        requestBody.put("device", deviceId);
        requestBody.put("order", order);
        
        HttpResponse<String> response = Unirest.post(url)
            .header("Content-Type", "application/json")
            .body(JSON.toJSONString(requestBody))
            .asString();
        
        return response.getStatus() == 200;
    }
}

4.2 Python实现

import hashlib
import time
import requests

class YoyoVoiceSpeaker:
    def __init__(self, app_id, app_secret):
        self.app_id = app_id
        self.app_secret = app_secret
        self.base_url = f"https://api.thingboot.com/{app_id}/device/control/"
    
    def _calculate_sign(self, ts):
        """计算签名"""
        md5_once = hashlib.md5(self.app_secret.encode()).hexdigest()
        combined = md5_once + str(ts)
        sign = hashlib.md5(combined.encode()).hexdigest()
        return sign
    
    def send_broadcast(self, device_id, message, volume=None, voice=None, speed=None):
        """
        发送语音播报
        :param device_id: 设备ID
        :param message: 播报内容
        :param volume: 音量(0-9)
        :param voice: 音色(0女/1男)
        :param speed: 语速(0-9)
        :return: 是否成功
        """
        ts = int(time.time())
        sign = self._calculate_sign(ts)
        
        # 构造order对象
        order = {"play:gbk:16": message}
        if volume is not None:
            order["volume"] = str(volume)
        if voice is not None:
            order["voice"] = str(voice)
        if speed is not None:
            order["speed"] = str(speed)
        
        # 构造请求
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        payload = {
            "device": device_id,
            "order": order
        }
        
        try:
            response = requests.post(
                url,
                json=payload,
                headers={"Content-Type": "application/json"},
                timeout=5
            )
            result = response.json()
            # code=200表示平台接收成功
            return result.get("code") == 200
        except Exception as e:
            print(f"发送失败: {e}")
            return False
    
    def multi_device_broadcast(self, device_ids, message):
        """向多个设备同时发送播报"""
        if isinstance(device_ids, list):
            device_id_str = ",".join(device_ids)
        else:
            device_id_str = device_ids
        return self.send_broadcast(device_id_str, message)
    
    def stop_broadcast(self, device_id, stop_all=True):
        """停止播报"""
        ts = int(time.time())
        sign = self._calculate_sign(ts)
        
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        payload = {
            "device": device_id,
            "order": {"stop": "1" if stop_all else "0"}
        }
        
        response = requests.post(url, json=payload, timeout=5)
        return response.json().get("code") == 200

# 使用示例
speaker = YoyoVoiceSpeaker("your_app_id", "your_app_secret")
speaker.send_broadcast("123456789", "您有一个新的订单，请及时处理")

4.3 Go语言实现

package main

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

type VoiceSpeaker struct {
    AppID     string
    AppSecret string
}

type BroadcastRequest struct {
    Device string                 `json:"device"`
    Order  map[string]interface{} `json:"order"`
}

func (v *VoiceSpeaker) calculateSign(ts int64) string {
    // 第一次MD5
    md5Once := md5.Sum([]byte(v.AppSecret))
    md5OnceStr := hex.EncodeToString(md5Once[:])
    // 拼接时间戳
    combined := md5OnceStr + strconv.FormatInt(ts, 10)
    // 第二次MD5
    finalSign := md5.Sum([]byte(combined))
    return hex.EncodeToString(finalSign[:])
}

func (v *VoiceSpeaker) SendBroadcast(deviceID, message string) error {
    ts := time.Now().Unix()
    sign := v.calculateSign(ts)
    
    // 构造URL
    url := fmt.Sprintf("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d",
        v.AppID, sign, ts)
    
    // 构造请求体
    order := map[string]interface{}{
        "play:gbk:16": message,
    }
    reqBody := BroadcastRequest{
        Device: deviceID,
        Order:  order,
    }
    
    jsonData, _ := json.Marshal(reqBody)
    
    // 发送请求
    resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    
    // 检查响应
    if resp.StatusCode == 200 {
        return nil
    }
    return fmt.Errorf("send failed, status: %d", resp.StatusCode)
}

5. 高级功能开发

5.1 批量播报管理

对于需要向多个设备同时发送播报的场景，芯步API支持批量操作：

批量操作限制：

最多可同时指定100台设备
所有设备必须属于同一产品类型
指令必须对所有设备有效

5.2 播报队列与优先级

对于高并发场景，在业务层实现播报队列管理：

5.3 消息回执处理

API返回的200状态码仅表示平台成功接收到指令，如需确认设备是否真正播报，需要监听平台的异步消息推送：

5.4 场景化播报模板

6. 集成到业务系统

6.1 订单系统集成示例

6.2 监控告警集成

7. 注意事项

7.1 响应码说明

Code	说明	处理
200	指令下发成功	正常
501	未指定设备ID	检查device参数
502	设备不存在	确认设备ID正确且已绑定
503	指定设备过多	单次不超过100台
504	部分设备不可用	检查无效设备ID

7.2 最佳实践

签名时效性：时间戳有效期一般为5分钟，每次请求重新生成
频率控制：避免过于频繁的播报请求，同设备间隔至少1秒
文本长度：单次播报内容不超过200字符
网络环境：设备需要稳定连接2.4GHz WiFi
异步确认：对于关键播报，监听异步推送确认设备执行状态

7.3 设备安装

安装高度：2-3米
供电要求：DC 12V 2A稳定电源
WiFi信号：确保音箱所在位置WiFi信号强度良好

通过上述方案，开发者可以将10W HTTP接口语音壁挂音箱快速集成到各类业务系统中，实现灵活、实时的语音提醒功能。