前台语音提醒：如何将20W HTTP接口壁挂音箱接入到项目中_解决方案

CATALOG

一、概述

酒店、写字楼、企业前台场景需要及时向接待人员传达访客到达、快递送达、会议提醒等语音通知。传统方式依赖人工喊话或对讲机，效率低且容易遗漏。芯步20W智能语音壁挂音箱（型号：UNI-YY-YX-BG-PRO-20W）通过开放HTTP接口实现文本实时播报，可将语音提醒无缝集成到您的软件系统中。

核心能力

芯片级TTS：文本到语音在设备端合成，无需预录音
开放HTTP API：适用于任何支持HTTP请求的编程语言
超低延迟：命令下发到设备响应80-120ms
私有化部署：支持局域网直连，数据不出内网
无网关设计：WiFi直连，即插即用

前台典型应用场景

场景	触发条件	语音内容示例
访客到达	访客在门禁处呼叫	“前台您好，有访客到达，请接待”
快递送达	快递员扫码登记	“前台您好，有您的快递已送达”
会议提醒	会议开始前5分钟	“3号会议室会议即将开始，请参会人员就位”
外卖送达	配送员扫码登记	“您好，您的外卖已到前台，请领取”
紧急通知	管理员触发	“紧急通知，请所有人员注意”

二、产品核心特性

2.1 技术规格

芯步20W智能语音壁挂音箱具备以下技术特性

特性	参数
产品型号	UNI-YY-YX-BG-PRO-20W
功率	20W（适合前台、办公室等室内场景）
安装方式	壁挂式，可摆可挂
联网方式	WiFi 2.4GHz
网络配置	可设定5组WiFi，自动连接信号最强的网络
控制接口	HTTP API
播报方式	文本转语音（TTS），无需预录音
私有化部署	支持局域网直连
响应延迟	80-120ms

2.2 支持的命令功能

该设备支持以下核心命令，用于实现各种语音提醒场景

功能类别	支持项	命令示例
文本播报	GBK编码文本	`{"play:gbk:16":"欢迎光临"}`
前置提示音	5种内置提示音	`{"play:gbk:16":"[message_1]新订单"}`
停止播报	打断当前播报	`{"stop":"1"}`
音量调节	0-9级	`{"volume":"7"}`
音色切换	男声/女声	`{"voice":"1"}`（0=女声，1=男声）
语速调节	0-9级	`{"speed":"5"}`
语调调节	0-9级	`{"tone":"5"}`
铃声播放	5种内置铃声	`{"ring":"1"}`
提示音	5种	`{"message":"1"}`
警示音	5种	`{"alert":"1"}`

提示音说明：内置提示音配合文本播报使用，格式为 [message_1] 至 [message_5]，可增强提醒效果。

三、软件集成架构

3.1 整体架构图

┌─────────────────────────────────────────────────────────────────┐
│                    前台管理系统 / 访客系统                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │
│  │  访客管理   │  │  快递登记   │  │  会议系统   │               │
│  └─────────────┘  └─────────────┘  └─────────────┘               │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │ HTTP API调用（携带签名）
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     芯步云平台 / 私有化服务器                  │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │ WiFi 2.4GHz
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     20W壁挂语音音箱                              │
│                    （前台壁挂安装）                               │
└─────────────────────────────────────────────────────────────────┘

3.2 集成工作原理

设备开放HTTP接口，适用于任何支持HTTP请求的编程语言。接口简单、清晰、友好，仅需在接口携带签名以及设备ID，即可向设备下发命令。支持接入任何形式的软件项目：Web、APP/小程序、窗体软件以及SaaS/低代码等平台。

集成工作流程

业务触发：访客呼叫、快递登记、会议开始等事件触发
文本生成：系统根据事件类型和参数生成播报文本
签名计算：生成MD5签名，发起一个HTTP请求
指令下发：向API发送POST请求
设备播报：音箱接收命令，实时TTS合成并播放（80-120ms）

四、API接口接入详解

4.1 接口地址与签名计算

请求地址

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

参数说明

参数	说明	示例
{AppId}	应用ID（控制台获取）	`qtyVWcgeMq`
{ts}	当前Unix时间戳（秒）	`1747212640`
{sign}	签名	`c484eb97...`

签名计算公式（两次MD5加密）

sign = md5( md5(AppSecret) + ts )

将开发者密码（AppSecret）进行一次MD5
将这个结果拼接上时间戳ts
对整个拼接后的字符串再做一次MD5

签名计算示例（Python） ：

HTTP请求示例

4.2 核心命令详解

4.2.1 基本文本播报

4.2.2 带提示音的播报（增强提醒效果）

注：[message_1]至[message_5]为5种内置提示音

4.2.3 紧急播报（最大音量+警示音）

4.2.4 同时控制多个功能

4.2.5 停止当前播报

4.2.6 单独播报铃声

4.3 多语言代码示例

Python

import requests
import time
import hashlib

class FrontDeskSpeaker:
    """前台语音播报控制器"""
    
    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 _generate_sign(self, ts):
        """生成签名:md5(md5(AppSecret) + ts)"""
        md5_secret = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign_str = md5_secret + str(ts)
        return hashlib.md5(sign_str.encode()).hexdigest()
    
    def _send_command(self, device_id, order):
        """发送命令到设备"""
        ts = int(time.time())
        sign = self._generate_sign(ts)
        
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        payload = {"device": device_id, "order": order}
        
        response = requests.post(url, json=payload)
        return response.json()
    
    def broadcast(self, device_id, text, volume=None, voice=None):
        """语音播报"""
        order = {"play:gbk:16": text}
        if volume:
            order["volume"] = str(volume)
        if voice:
            order["voice"] = str(voice)
        return self._send_command(device_id, order)
    
    def visitor_arrival(self, device_id, visitor_name):
        """访客到达提醒"""
        text = f"[message_2]前台您好，访客{visitor_name}已到达，请接待"
        return self.broadcast(device_id, text, volume=7)
    
    def courier_arrival(self, device_id, recipient):
        """快递送达提醒"""
        text = f"[message_1]{recipient}，您的快递已送达前台，请及时领取"
        return self.broadcast(device_id, text, volume=6)
    
    def meeting_reminder(self, device_id, room, minutes=5):
        """会议提醒"""
        text = f"{room}会议将在{minutes}分钟后开始，请参会人员就位"
        return self.broadcast(device_id, text, volume=7)
    
    def emergency(self, device_id, message):
        """紧急播报"""
        text = f"[alert_5]{message}"
        return self.broadcast(device_id, text, volume=9)

# 使用示例
speaker = FrontDeskSpeaker("your_app_id", "your_app_secret")
device_id = "speaker_frontdesk_01"

# 访客到达提醒
speaker.visitor_arrival(device_id, "张先生")

# 快递送达提醒
speaker.courier_arrival(device_id, "李女士")

# 会议提醒
speaker.meeting_reminder(device_id, "3号会议室")

JavaScript/Node.js

const crypto = require('crypto');
const axios = require('axios');

class FrontDeskSpeaker {
    constructor(appId, appSecret) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.baseUrl = `https://api.thingboot.com/${appId}/device/control/`;
    }
    
    _generateSign(ts) {
        const md5Secret = crypto.createHash('md5').update(this.appSecret).digest('hex');
        const signStr = md5Secret + ts;
        return crypto.createHash('md5').update(signStr).digest('hex');
    }
    
    async sendCommand(deviceId, order) {
        const ts = Math.floor(Date.now() / 1000);
        const sign = this._generateSign(ts);
        const url = `${this.baseUrl}?sign=${sign}&ts=${ts}`;
        
        const payload = { device: deviceId, order };
        const response = await axios.post(url, payload);
        return response.data;
    }
    
    async broadcast(deviceId, text, options = {}) {
        const order = { "play:gbk:16": text };
        if (options.volume) order.volume = options.volume.toString();
        if (options.voice) order.voice = options.voice.toString();
        return this.sendCommand(deviceId, order);
    }
    
    async visitorArrival(deviceId, visitorName) {
        return this.broadcast(deviceId, `[message_2]前台您好，访客${visitorName}已到达，请接待`, { volume: 7 });
    }
}

// 使用示例
const speaker = new FrontDeskSpeaker("your_app_id", "your_app_secret");
await speaker.visitorArrival("speaker_01", "张先生");

Java

import okhttp3.*;
import java.security.MessageDigest;
import java.time.Instant;

public class FrontDeskSpeaker {
    private final String appId;
    private final String appSecret;
    private final OkHttpClient client;
    private static final MediaType JSON = MediaType.parse("application/json; charset=utf-8");
    
    public FrontDeskSpeaker(String appId, String appSecret) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.client = new OkHttpClient();
    }
    
    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);
        }
    }
    
    private String generateSign(long ts) {
        String md5Secret = md5(appSecret);
        return md5(md5Secret + ts);
    }
    
    public String broadcast(String deviceId, String text) throws Exception {
        long ts = Instant.now().getEpochSecond();
        String sign = generateSign(ts);
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", 
            appId, sign, ts);
        
        String payload = String.format(
            "{\"device\":\"%s\",\"order\":{\"play:gbk:16\":\"%s\"}}",
            deviceId, text
        );
        
        RequestBody body = RequestBody.create(payload, JSON);
        Request request = new Request.Builder().url(url).post(body).build();
        
        Response response = client.newCall(request).execute();
        return response.body().string();
    }
}

PHP

Shell（curl）

五、前台场景实战示例

5.1 第一种场景：访客到达语音提醒

需求：当访客在门禁处呼叫时，前台音箱自动播报提醒接待人员。

设备配置：20W壁挂音箱 ×1（前台壁挂安装）+ 门禁呼叫设备

集成方式：门禁系统Webhook触发

5.2 第二种场景：快递/外卖送达提醒

需求：配送员扫码登记时，前台音箱自动播报通知收件人。

设备配置：20W壁挂音箱 ×1

5.3 第三种场景：会议系统联动提醒

需求：会议开始前5分钟，自动播报提醒参会人员。

设备配置：20W壁挂音箱 ×1 + 会议系统

5.4 场景四：与小程序/APP集成

需求：前台人员可通过移动端APP远程触发语音播报。

小程序端代码示例

5.5 场景五：定时语音广播（如午休提醒）

需求：定时播报午休开始/结束提醒。

设备配置：20W壁挂音箱 ×1

六、私有化部署方案

酒店、企业等场景对数据安全和稳定性要求较高，芯步音箱支持纯局域网运行。

部署模式对比

特性	公有云模式	私有化模式
设备联网	WiFi连接互联网	连接内网WiFi
API地址	`api.thingboot.com`	自建服务器IP
数据流向	经过芯步云端	内网直连，数据不出园区
网络依赖	需要互联网	仅需局域网
适用场景	快速接入、中小型场景	酒店、企业、安全要求高

私有化配置要点

设备支持配置5组WiFi网络，自动连接信号最强的网络
需自建HTTP服务，所有API调用在内网完成
支持自建消息服务器，接收设备状态回调

七、设备安装部署指南

7.1 安装要求

项目	要求
安装方式	壁挂式，可摆可挂
安装位置	前台区域，距地面2-2.5米
电源	220V AC电源插座
网络	WiFi 2.4GHz信号覆盖良好

7.2 部署位置

场景类型	部署数量	安装位置
酒店前台	1-2台	前台接待区
写字楼大堂	1台	前台接待台旁
企业前台	1台	前台区域
联合办公空间	2-3台	前台+各会议室

7.3 WiFi配置

设备采用WiFi直接方式，无需网关支持。可设定5组WiFi网络，优先连接信号最强的进行连接。

八、常见问题与排障

问题	可能原因	解决方案
设备不在线	WiFi信号弱	检查2.4GHz WiFi覆盖，设备支持5组WiFi自动切换
播报延迟高	网络波动	私有化部署可降至80-120ms
音量不够大	环境噪音大	调高volume至9
多音字读错	TTS引擎规则	使用同音字替代，如“重量”改“重量（第四声）”
签名验证失败	参数错误	确认ts为秒级时间戳，签名公式正确
无法同时播报	设备正在播报	使用`stop`命令停止当前播报后再发新命令

九、总结

本方案基于芯步20W智能语音壁挂音箱，实现了前台场景的语音提醒自动化与软件集成

能力	实现的方式是
访客到达提醒	门禁系统触发HTTP API播报
快递/外卖提醒	扫码登记触发播报
会议提醒	会议系统定时触发
紧急通知	管理员后台一键触发
定时广播	定时任务自动播报

集成核心步骤

获取AppID/AppSecret，实现MD5签名算法
开发HTTP调用模块，封装播报命令
根据业务需求，在访客系统、快递系统等事件中调用播报接口

方案优势

✅ 接口统一：标准HTTP API，任意编程语言10分钟对接
✅ 即插即用：WiFi直连，无需网关，可设定多组WiFi自动切换
✅ 超低延迟：80-120ms响应，实时性强
✅ 功能丰富：支持音色/语速/音量调节，内置5种提示音、5种铃声、5种警示音
✅ 数据安全：支持私有化部署，数据不出园区

如需详细的产品手册和API文档，请访问查阅或联系技术支持团队获取。