怎么二次开发20W 智能云播报音柱以实现云平台语音推送_解决方案

CATALOG

一、概述

1.1 产品简介

芯步20W智能云播报音柱（型号：UNI-YY-YZ-20W-LAN）是一款支持网络接入的智能语音播报设备，具备以下核心特性

远程语音播报：通过HTTP接口推送文本，即可实时触发语音播报，无需预先上传录音文件
TTS文本转语音：支持文本转语音，发音自然流畅
可调节参数：支持远程设置音量、音色、语速、语调
灵活接入：开放HTTP接口，兼容任何支持HTTP请求的编程语言
私有化部署：支持纯局域网环境部署

1.2 适用场景

订单提醒、工单播报（餐饮、零售、仓储）
生产看板语音报警（工业制造）
智慧停车语音提示
会议室、教室定时播报
任何需要“云端下发语音”的业务系统

1.3 技术架构图解

┌─────────────┐      HTTP/HTTPS       ┌─────────────┐      MQTT/长连接      ┌─────────────┐
│  业务系统   │  ──────────────────>  │ 芯步云  │  ──────────────────>  │  20W音柱    │
│  (ERP/小程序 │  POST /device/control │   平台      │                      │  (设备端)    │
│   /SaaS)    │  <──────────────────  │             │  <──────────────────  │             │
└─────────────┘      返回结果          └─────────────┘       状态上报         └─────────────┘

二、准备工作

2.1 注册与获取凭证

访问芯步开放平台（）注册账号
登录控制台，进入“开发设置”页面
获取以下关键凭证
- AppID：应用唯一标识
- AppSecret：开发者密钥（用于签名计算，请妥善保管）

2.2 获取设备ID

在控制台添加设备（通过设备MAC地址或SN码）
记录设备的Device ID（通常为数字字符串，如1878）
确认设备在线状态（设备联网后会有“在线”标识）

2.3 接口基础信息

项目	说明
请求地址	`https://api.thingboot.com/{AppID}/device/control/`
请求方法	POST
Content-Type	`application/json`
必传参数	`device`（设备ID）、`order`（命令JSON）
鉴权方式	URL参数签名（sign + ts）

三、接口鉴权机制

3.1 签名算法

芯步平台采用双重MD5加密方式防止请求伪造，签名生成规则如下

sign = MD5( MD5(AppSecret) + ts )

其中：

AppSecret：开发者密钥
ts：当前Unix时间戳（秒级）
+：字符串拼接操作

3.2 签名计算流程

flowchart LR
    A[AppSecret] --> B[MD5加密]
    B --> C[MD5_AppSecret]
    D[ts时间戳] --> E[字符串拼接]
    C --> E
    E --> F[MD5加密]
    F --> G[最终sign]

3.3 完整请求URL格式

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

四、语音推送核心接口

4.1 播报命令格式

向设备下发语音播报请求时，order参数格式为

参数说明

参数	说明
`play`	播报指令标识
`gbk`	文本编码格式（中文使用gbk）
`16`	音量级别（范围0-100，数字越大音量越高）

示例

4.2 请求示例

请求体（POST Body）

注意：order参数需以JSON字符串形式传递，而非直接嵌套对象。

五、多语言代码实现

5.1 Java实现（使用Unirest）

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

public class VoiceBroadcastService {
    
    private static final String APP_ID = "你的AppID";
    private static final String APP_SECRET = "你的AppSecret";
    
    public static void main(String[] args) {
        // 获取时间戳（秒）
        long ts = System.currentTimeMillis() / 1000;
        
        // 计算签名: MD5(MD5(AppSecret) + ts)
        String sign = DigestUtils.md5Hex(DigestUtils.md5Hex(APP_SECRET) + ts);
        
        // 构建请求URL
        String url = String.format(
            "https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d",
            APP_ID, sign, ts
        );
        
        // 准备请求体
        String deviceId = "1878";  // 替换为实际设备ID
        String orderJson = "{\"play:gbk:80\":\"订单号A001已准备就绪\"}";
        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("响应结果:" + response.getBody());
        } catch (Exception e) {
            System.err.println("请求失败:" + e.getMessage());
        }
    }
}

5.2 Python实现

5.3 JavaScript/Node.js实现

5.4 cURL命令行测试

六、高级功能扩展

6.1 批量设备推送

device参数支持同时向多个音柱推送相同内容：

6.2 音量动态调整

播报时可动态指定音量级别（0-100）：

6.3 多音字与数字读法优化

TTS引擎智能处理以下情况

数字：自动识别金额（100元 → 一百元）、手机号（13800000000 → 幺三八...）
多音字：根据上下文自动适配读音

6.4 内置提示音

设备预置多种提示音，可用于播报前的提醒

类型	适用场景
铃声1-5	订单提醒、排队叫号
提示音1-5	轻提醒、状态变更
警示音1-5	紧急报警、设备故障

具体调用方式可参考产品手册中的铃声控制命令。

七、与业务系统集成方案

7.1 对接各类业务系统

芯步开放接口设计为“语言无关”，理论上可与任何支持HTTP请求的系统对接

业务系统类型	集成方式
Web应用	后端集成HTTP客户端（Java/Go/PHP等）
微信小程序	云函数调用或后端API转发
企业ERP/OA	在业务触发点嵌入接口调用代码
低代码平台	通过HTTP请求组件配置调用
工业SCADA	使用脚本组件（Python/JS）调用

7.2 集成架构

┌─────────────────────────────────────────────────────────┐
│                     业务系统层                            │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐  │
│  │ 订单系统 │ │ 监控系统 │ │ 工单系统 │ │ 自定义SaaS │  │
│  └────┬────┘ └────┬────┘ └────┬────┘ └──────┬──────┘  │
│       │           │           │              │         │
│       └───────────┼───────────┴──────────────┘         │
│                   ▼                                      │
│         ┌─────────────────┐                            │
│         │  统一语音网关    │  <- 可选:封装调用逻辑      │
│         │ (HTTP封装层)     │                            │
│         └────────┬────────┘                            │
└──────────────────┼──────────────────────────────────────┘
                   │ HTTP + 签名
                   ▼
         ┌─────────────────┐
         │  芯步云平台   │
         └────────┬────────┘
                   │
                   ▼
         ┌─────────────────┐
         │   20W播报音柱    │
         └─────────────────┘

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

8.1 签名校验失败

现象：返回签名错误提示排查步骤

确认AppSecret与平台控制台一致
检查ts是否为秒级时间戳
确认拼接顺序：MD5(MD5(secret) + ts)，MD5结果为32位小写十六进制
注意时间戳与时区无关，只需确保设备时间误差在合理范围

8.2 设备不在线

现象：请求成功但设备无响应解决方案

检查设备网络连接状态
确认设备已成功注册到平台
检查设备ID是否正确
首次使用在控制台手动下发测试命令确认设备功能正常

8.3 中文播报乱码

问题：播报内容显示乱码或异常解决：命令中使用play:gbk编码标识，确保文本以UTF-8编码传输

8.4 安全

AppSecret保护：在后端服务中存储，不要硬编码在前端代码中
时间戳有效期：平台通常允许5-10分钟的时间误差，实时生成
私有化部署：对安全性要求高的场景，可采用纯局域网部署方案

九、总结

通过芯步的开放HTTP接口，二次开发20W智能云播报音柱实现云平台语音推送非常简单。核心步骤可概括为：

获取凭证：注册平台获取AppID和AppSecret
理解签名：双重MD5签名算法保障通信安全
构建请求：组装JSON格式的device和order参数
发起调用：向指定URL发送POST请求
接收响应：解析返回结果，完成语音推送

该方案理论上支持任何编程语言，可轻松集成到现有的ERP、小程序、SaaS等各类业务系统中，实现“即写即播”的实时语音交互能力。