一、产品概述与对接前提

芯步智能语音壁挂音箱Pro 40W是一款支持WiFi 2.4G无线网络的智能音频设备，采用HTTP开放接口，支持任何支持HTTP请求的编程语言进行对接。该音箱内置了各5种铃声、提示音和警示音，无需上传音频文件，通过接口指令即可直接触发播放。

对接前的准备工作：

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

二、接口鉴权机制

芯步开放平台采用双重MD5签名机制进行身份验证，每次API请求需携带签名和当前时间戳。

签名计算规则

核心公式：

sign = MD5(MD5(AppSecret) + ts)

计算步骤：

1. 将AppSecret进行第一次MD5加密，得到 secret_md5

2. 将 secret_md5 与当前Unix时间戳（秒）拼接

3. 对拼接后的字符串进行第二次MD5加密，得到最终签名

各语言实现示例：

请求地址格式

http(s)://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

其中 {AppID} 需替换为实际的应用ID。

三、铃声/提示音/警示音播放指令详解

40W网络音频壁挂音箱内置了三类预置音效，每类包含5种选项，通过不同的命令参数进行调用。

3.1 命令参数对照表

3.2 指令下发格式

HTTP POST 方式（JSON格式，推荐）：

HTTP POST 方式（表单格式）：

device=设备ID&order={"ring":"3"}

从代码层面调用示例：

3.3 常用组合场景

第一种场景：门铃/来访提醒

第二种场景：新订单通知

第三种场景：设备故障/紧急告警

四、前置设置：音量调节

为确保铃声播放效果，在播放前或设备初始化时设置合适的音量。音量取值范围为0-9。

音量设置指令

完整初始化示例（多指令组合）

音箱支持依次下发多条命令进行初始化设置：

音量参数参考

五、进阶功能：语音播报与铃声组合

音箱支持文字转语音播报功能，可将文本实时转为语音播放，并可与铃声/提示音组合使用。

5.1 纯语音播报

5.2 提示音+语音组合

在播报文本前拼接提示音标记，可实现“提示音+语音”的连续播放效果：

上述命令执行效果：先播放3号提示音，然后播报“欢迎光临”语音。

5.3 支持的特殊语法

六、设备状态与指令执行确认

6.1 同步响应说明

HTTP接口返回200状态码仅表示平台成功接收指令，并不代表设备已实际执行。设备可能处于离线状态或指令参数错误。

6.2 异步确认机制

对于需要确认设备执行结果的场景，：

1. 在指令中携带 extra 字段作为业务追踪标识

2. 接收云端的异步消息推送，确认设备执行状态

系统会在异步推送中原样返回此extra字段内容，便于业务系统关联追踪。

七、批量设备控制

当需要对多个音箱同时播放同一铃声时，支持在单次请求中指定多个设备ID。

多设备指令格式

设备ID间使用逗号或竖线分隔：

限制说明：

• 单次最多可指定100台设备

• 所有设备必须属于同一产品类型

• 所有设备将执行相同的指令

八、故障排查指南

8.1 常见错误码

8.2 播放无声音排查步骤

1. 检查设备在线状态：登录物联网控制台查看设备是否显示“在线”

2. 验证音量设置：确认音量未设置为0

3. 测试基础指令：先下发 {"ring":"1"} 确认铃声功能正常

4. 检查网络信号：设备指示灯是否正常（停止闪烁表示网络正常）

5. 确认WiFi频段：确保路由器开启了2.4G WiFi（5G频段不被支持）

8.3 配网说明

若音箱尚未连接网络，可通过物联网控制台的“网络配置”功能，或使用“芯步小程序”进行配网，需确保现场WiFi为2.4G频段。

九、方案总结

通过芯步开放平台的HTTP接口，对接40W网络音频壁挂音箱实现内置铃声播放，整体流程如下：

1. 前期准备：获取AppID、AppSecret、Device ID，完成音箱WiFi配网

2. 接口鉴权：按MD5(MD5(AppSecret)+ts)规则计算签名

3. 指令下发：通过HTTP POST向 /device/control/ 发送指令

4. 铃声控制：使用 ring、message、alert 命令分别控制三类内置音效

5. 效果增强：可组合音量设置、语音播报等功能丰富应用场景

6. 可靠性保障：通过异步消息推送确认设备执行结果

该方案适用于订单提醒、门铃呼叫、设备告警、工位呼叫等多种业务场景，对接周期短，无需上传音频资源，即调即用。