线下服务语音提醒场景：如何把30W HTTP接口壁挂音箱接入到项目中_解决方案

CATALOG

1. 背景与需求分析

在线下服务场景中，语音提醒是高效的信息传递方式。然而，传统广播系统存在诸多痛点：需要独立布线、操作繁琐、无法与业务系统联动、内容更新困难。芯步30W HTTP接口壁挂音箱正为这些场景设计，通过标准HTTP API即可实现文字转语音播报，无需网关，直连WiFi。

典型应用场景包括：

服务网点语音提醒：银行、政务大厅、医院候诊区叫号及业务提醒
零售门店语音播报：促销活动播报、会员到店欢迎语
公共场馆语音引导：图书馆还书提醒、博物馆展品解说
企业内部语音通知：会议提醒、考勤播报、安全警示

本方案将详细阐述如何将该设备集成到软件项目中，实现灵活、可靠的线下服务语音提醒。

2. 产品选型：30W HTTP接口壁挂音箱

2.1 产品核心参数

参数项	规格说明
产品型号	UNI-YY-YX-BG-30W
额定功率	30W
覆盖范围	约80-120平方米，适用于服务大厅、门店等场景
通信方式	WiFi 2.4GHz，内置天线
控制协议	HTTP API（RESTful风格）
语音能力	TTS文字转语音，支持SSML标记
联网要求	无需网关，WiFi直连
音频接口	AUX输入（可外接音源）
安装方式	壁挂式安装
私有化部署	支持纯局域网运行

2.2 产品核心优势

直连WiFi，无需网关：设备内置WiFi模块，通电联网即可使用
HTTP接口开放：任何编程语言只需发起HTTP请求即可调用，集成门槛极低
私有化部署能力：支持自建消息服务器，可在纯局域网环境运行，满足数据安全要求
多重网络保障：支持设定5组WiFi网络，优先连接信号最强的，保证服务稳定性

2.3 命令接口说明

设备支持的核心命令如下：

命令	功能	参数说明	示例
`speak`	文字转语音	`text`: 播报内容	`{"speak":"欢迎光临"}`
`music`	播放音乐	`url`: 音乐文件URL	`{"music":"http://..."}`
`volume`	调节音量	`level`: 0-100	`{"volume":80}`
`stop`	停止播报	无	`{"stop":""}`
`status`	查询状态	无	`{"action":"status"}`

3. 集成设计

3.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                        业务应用层                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
│  │ 排队叫号 │  │ 促销系统 │  │ 会员系统 │  │ 运维管理台    │   │
│  │ 系统     │  │          │  │          │  │              │   │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬───────┘   │
└───────┼─────────────┼─────────────┼───────────────┼────────────┘
        │             │             │               │
        └─────────────┼─────────────┼───────────────┘
                      │ HTTP API调用
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                      您的软件项目                                │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    语音播报服务模块                        │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────────────┐  │  │
│  │  │ 指令生成   │  │ 队列管理   │  │ 设备状态管理        │  │  │
│  │  │ 模块       │  │ 模块       │  │（含在线/离线检测）  │  │  │
│  │  └────────────┘  └────────────┘  └────────────────────┘  │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                      │ HTTP API（公网或局域网）
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                   芯步云平台 / 本地API                        │
│        （设备接入、指令路由、签名验证、消息推送）                   │
└─────────────────────────────────────────────────────────────────┘
                      │ WiFi 2.4GHz
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│              30W HTTP接口壁挂音箱 × N                            │
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │  安装位置:服务大厅、门店、候诊区、办公区                   │  │
│   └─────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

3.2 架构特点

极简接入：设备直连WiFi，无需网关，通电即用
多语言兼容：基于HTTP API，支持Java、Python、Node.js、Go等任何编程语言
私有化可选：支持局域网纯环境运行，敏感数据可完全内网闭环
可扩展性：支持单播（单台播报）和广播（多台同时播报）

4. 详细实施步骤

4.1 准备工作：设备安装与平台配置

步骤1：硬件安装

确定安装位置（壁挂安装，距地面2-2.5米为佳，确保声音覆盖目标区域）
连接220V电源线（设备内置电源，直连市电）
确保安装位置WiFi信号强度良好（≥-65dBm）

步骤2：开发者账号配置

登录芯步工作台（）
创建应用，获取AppID和AppSecret

步骤3：设备配网

设备通电启动
使用芯步APP进行WiFi配网（支持SmartConfig一键配网）
设备仅支持2.4GHz WiFi

步骤4：记录设备信息

在控制台设备列表中获取device_id
为设备命名以标识位置（如“一楼服务大厅主音箱”）

4.2 接口基础封装

芯步API采用签名鉴权机制。

API基本信息

请求地址https://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}
请求方式：POST
数据格式：JSON

签名算法

sign = md5( md5(AppSecret) + ts )

其中ts为Unix时间戳（秒级）。

Java完整封装示例

@Component
public class VoiceBroadcastService {
    
    @Value("${yoyo.app-id}")
    private String appId;
    
    @Value("${yoyo.app-secret}")
    private String appSecret;
    
    private final RestTemplate restTemplate = new RestTemplate();
    
    private String generateSign(long ts) {
        String md5Secret = DigestUtils.md5DigestAsHex(appSecret.getBytes());
        String plain = md5Secret + ts;
        return DigestUtils.md5DigestAsHex(plain.getBytes());
    }
    
    private String buildUrl() {
        long ts = System.currentTimeMillis() / 1000;
        String sign = generateSign(ts);
        return String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d",
                           appId, sign, ts);
    }
    
    /**
     * 向设备下发命令
     */
    public Map<String, Object> sendCommand(String deviceId, Map<String, Object> order) {
        String url = buildUrl();
        Map<String, Object> requestBody = new HashMap<>();
        requestBody.put("device", deviceId);
        requestBody.put("order", order);
        
        HttpEntity<Map<String, Object>> entity = new HttpEntity<>(requestBody);
        ResponseEntity<Map> response = restTemplate.postForEntity(url, entity, Map.class);
        return response.getBody();
    }
}

4.3 核心功能一：文字转语音播报

这是设备最核心的能力——将文字内容通过TTS合成并播报。

/**
 * 文字转语音播报
 * @param deviceId 设备ID
 * @param text 播报内容（支持中英文）
 * @return 是否成功
 */
public boolean speak(String deviceId, String text) {
    Map<String, Object> order = new HashMap<>();
    order.put("speak", text);
    
    Map<String, Object> response = sendCommand(deviceId, order);
    boolean success = "200".equals(String.valueOf(response.get("code")));
    
    if (success) {
        log.info("语音播报指令已发送: device={}, text={}", deviceId, text);
    } else {
        log.error("语音播报失败: {}", response);
    }
    return success;
}

/**
 * 带音量控制的播报
 * @param deviceId 设备ID
 * @param text 播报内容
 * @param volume 音量（0-100）
 */
public boolean speakWithVolume(String deviceId, String text, int volume) {
    // 先设置音量
    setVolume(deviceId, volume);
    // 延时100ms后再播报，确保音量设置生效
    try { Thread.sleep(100); } catch (InterruptedException e) {}
    return speak(deviceId, text);
}

private boolean setVolume(String deviceId, int volume) {
    Map<String, Object> order = new HashMap<>();
    order.put("volume", volume);
    Map<String, Object> response = sendCommand(deviceId, order);
    return "200".equals(String.valueOf(response.get("code")));
}

4.4 核心功能二：业务场景语音模板

在实际使用中，播报内容通常是动态拼接的。设计语音模板，便于统一管理和复用。

/**
 * 语音模板服务
 */
@Service
public class VoiceTemplateService {
    
    @Autowired
    private VoiceBroadcastService voiceService;
    
    /**
     * 排队叫号播报
     * @param deviceId 音箱ID
     * @param queueNumber 排队号码
     * @param windowNumber 窗口号
     */
    public void announceQueueNumber(String deviceId, String queueNumber, int windowNumber) {
        String text = String.format("请%d号顾客到%d号窗口办理业务", queueNumber, windowNumber);
        voiceService.speak(deviceId, text);
    }
    
    /**
     * 会员到店欢迎语
     * @param deviceId 音箱ID
     * @param memberName 会员姓名
     * @param level 会员等级
     */
    public void welcomeMember(String deviceId, String memberName, String level) {
        String text = String.format("欢迎%s会员%s光临本店，祝您购物愉快", level, memberName);
        voiceService.speak(deviceId, text);
    }
    
    /**
     * 促销活动播报
     * @param deviceId 音箱ID
     * @param promotionName 活动名称
     * @param discount 折扣信息
     */
    public void announcePromotion(String deviceId, String promotionName, String discount) {
        String text = String.format("好消息！%s，%s，欢迎选购", promotionName, discount);
        voiceService.speak(deviceId, text);
    }
    
    /**
     * 会议提醒播报
     * @param deviceId 音箱ID
     * @param meetingName 会议名称
     * @param room 会议室
     * @param minutesLeft 剩余分钟数
     */
    public void remindMeeting(String deviceId, String meetingName, String room, int minutesLeft) {
        String text = String.format("%s会议将在%d分钟后开始，请参会人员前往%s会议室",
                                   meetingName, minutesLeft, room);
        voiceService.speak(deviceId, text);
    }
}

4.5 核心功能三：多媒体文件播放

除了TTS文字转语音，设备还支持播放音频文件。这对于需要高品质语音（如品牌专用提示音）的场景非常有用。

4.6 核心功能四：设备状态查询

了解设备在线状态和当前播放状态，对于运维管理至关重要。

4.7 完整业务场景：服务大厅排队叫号

以银行/政务大厅为例，将语音音箱与排队叫号系统集成：

@Service
public class QueueCallingService {
    
    @Autowired
    private VoiceBroadcastService voiceService;
    
    @Autowired
    private QueueRepository queueRepo;
    
    /**
     * 窗口叫号
     * @param deviceId 音箱设备ID
     * @param windowNo 窗口号
     */
    public void callNextCustomer(String deviceId, int windowNo) {
        // 1. 获取下一个排队号码
        String nextQueueNumber = queueRepo.getNextQueueNumber();
        
        if (nextQueueNumber == null) {
            voiceService.speak(deviceId, "当前暂无排队顾客");
            return;
        }
        
        // 2. 更新排队状态
        queueRepo.markAsCalled(nextQueueNumber, windowNo);
        
        // 3. 合成播报内容
        String text = String.format("请%d号顾客到%d号窗口办理业务", nextQueueNumber, windowNo);
        
        // 4. 可选:添加提示音前导（播放提示音文件）
        voiceService.playAudio(deviceId, "https://cdn.example.com/ding.mp3");
        
        try { Thread.sleep(500); } catch (InterruptedException e) {}
        
        // 5. 播报叫号
        voiceService.speak(deviceId, text);
        
        // 6. 可选:重复播报（适用于嘈杂环境）
        try { Thread.sleep(2000); } catch (InterruptedException e) {}
        voiceService.speak(deviceId, text);
        
        log.info("窗口{}叫号: 号码={}", windowNo, nextQueueNumber);
    }
    
    /**
     * 批量叫号（多个窗口同时叫号）
     * 注意:多个音箱同时播报会造成干扰，错峰或分开发音
     */
    public void batchCall(List<WindowCallRequest> requests) {
        // 使用线程池异步处理，避免阻塞
        ExecutorService executor = Executors.newFixedThreadPool(requests.size());
        
        for (WindowCallRequest req : requests) {
            executor.submit(() -> {
                callNextCustomer(req.getDeviceId(), req.getWindowNo());
            });
        }
        
        executor.shutdown();
    }
}

5. 线下服务典型部署场景

5.1 银行/政务大厅排队叫号

配置项	值
设备数量	大厅1-2台，覆盖全部等候区
安装位置	叫号屏幕附近，或等候区中央
播放内容	叫号播报、温馨提示、业务宣传
集成系统	排队叫号系统、业务系统
价值	自动化叫号，降低窗口人员沟通成本；顾客体验提升

5.2 零售门店营销播报

配置项	值
设备数量	收银台1台 + 卖场区1-2台
安装位置	门店入口、促销专区、收银台
播放内容	促销活动、会员欢迎语、营业提醒
集成系统	POS系统、会员管理系统
价值	精准营销触达；会员到店自动识别欢迎，提升尊享感

5.3 医院候诊区叫号

配置项	值
设备数量	每诊区1-2台
安装位置	候诊椅区域上方
播放内容	就诊叫号、检查提醒、取药通知
集成系统	HIS系统、排队叫号系统
价值	减少护士口头叫号工作量；患者有序就诊

5.4 企业内部语音通知

配置项	值
设备数量	每楼层1台
安装位置	办公区走廊、茶水间、会议室
播放内容	会议提醒、考勤播报、安全警示
集成系统	OA系统、会议室预约系统
价值	智能化早会提醒，公司重要通知即时传达；员工无需紧盯手机

6. 高级功能与优化

6.1 队列管理

当短时间内有多个播报请求时，需要排队管理避免冲突。

@Component
public class VoiceQueueManager {
    
    private final Map<String, BlockingQueue<String>> deviceQueues = new ConcurrentHashMap<>();
    private final Map<String, ScheduledExecutorService> deviceExecutors = new ConcurrentHashMap<>();
    
    @Autowired
    private VoiceBroadcastService voiceService;
    
    @PostConstruct
    public void init() {
        // 为每个设备启动队列消费线程
        List<String> devices = deviceConfigService.getAllDeviceIds();
        for (String deviceId : devices) {
            startQueueConsumer(deviceId);
        }
    }
    
    /**
     * 添加播报到队列
     */
    public void enqueue(String deviceId, String text) {
        deviceQueues.computeIfAbsent(deviceId, k -> new LinkedBlockingQueue<>()).offer(text);
        log.debug("播报已入队: device={}, text={}", deviceId, text);
    }
    
    /**
     * 启动队列消费者
     */
    private void startQueueConsumer(String deviceId) {
        BlockingQueue<String> queue = deviceQueues.computeIfAbsent(deviceId, k -> new LinkedBlockingQueue<>());
        ScheduledExecutorService executor = Executors.newSingleThreadScheduledExecutor();
        deviceExecutors.put(deviceId, executor);
        
        // 每隔2秒检查一次队列，播报间隔确保设备有足够时间完成当前播报
        executor.scheduleAtFixedRate(() -> {
            String text = queue.poll();
            if (text != null) {
                voiceService.speak(deviceId, text);
            }
        }, 0, 2, TimeUnit.SECONDS);
    }
}

6.2 TTS语音优化

为了提高播报的自然度和辨识度，可在文案层面进行优化：

7. 集成难点与解决方案

常见问题	原因分析	解决方案
播报冲突/覆盖	短时间内多个请求发送到同一设备，后请求覆盖前一个	实现队列管理机制，顺序播报
网络波动导致指令失败	WiFi信号不稳定或云平台波动	增加指令重试机制（最多3次，随机间隔（或逐次增大间隔））
TTS语音不自然	合成引擎处理数字、标点的方式	优化文案格式；使用SSML标记控制语速和停顿
批量播报同步问题	多设备同时播报造成噪音干扰	实现错峰调度；根据区域分时播报
设备离线无法播报	网络中断或设备故障	状态监控告警；重要场景考虑双设备冗余
音量差异大	不同区域环境噪音差异	按区域独立配置音量；定时检测环境并自动调节

8. 方案价值总结

通过将芯步30W HTTP接口壁挂音箱集成到线下服务语音提醒项目中，实现以下核心价值：

极简接入：无需网关，设备直连WiFi，通过HTTP API即可调用
多语言兼容：任何支持HTTP请求的编程语言均可接入（Java、Python、Node.js、Go等）
私有化部署能力：支持纯局域网环境运行，满足政企客户数据安全要求
灵活的播报能力：支持TTS文字转语音和音频文件播放，适配多样化需求
与业务系统深度融合：排队叫号、POS、会员等系统可实时触发播报，实现自动化服务
稳定可靠：支持5组WiFi网络自动切换，保障服务连续性

该方案不仅适用于排队叫号场景，还可扩展至零售营销播报、医院就诊提醒、企业内部通知、安防警示等广泛线下服务场景。