如何二次开发30W 远程控制户外防水壁挂音箱以实现远程音量调节_解决方案

CATALOG

芯步的30W户外防水壁挂音箱开放了完整的HTTP API接口，远程音量调节的核心是通过向 /device/control/ 接口下发特定的 order 指令来实现的。以下方案涵盖接口协议、签名算法及多语言代码示例。

一、技术概述

芯步的硬件设备（包括30W壁挂音箱）遵循“请求-响应”的模型。您无需复杂的SDK，只需能发起HTTP请求，即可通过云端API对设备进行二次开发控制。

核心流程：

获取凭证：在芯步控制台获取 AppID 和 AppSecret。
计算签名：由于接口需要防篡改，每次请求需动态计算 sign 参数。
下发指令：向指定API地址发送POST请求，Body中包含设备ID（Device ID）和音量控制命令。

二、接口与鉴权详解

在开始编码前，需要了解30W户外防水壁挂音箱（型号UNI-YY-YX-BG-30W等系列）的开放接口规则。

2.1 音量调节指令集

根据芯步对音频类设备的通用指令规范，调节音量的order参数为 volume，取值范围为 0 至 15（具体取决于该型号固件，通常0为静音，10-15为最大音量）。

2.2 请求地址与参数

接口地址https://api.thingboot.com/{AppID}/device/control/
请求方式POST
HeaderContent-Type: application/json

对于30W音箱，您需要在请求Body的order字段中构造如下的JSON对象：

注：部分旧型号可能支持范围0-9，而Pro版本或新型号支持更精细的0-15级调节。如果设定值无效，通过实际测试确认最大刻度。

2.3 签名算法

芯步的接口安全机制是通过URL参数携带签名

ts：当前Unix时间戳（秒级，10位数字）。
signmd5(md5(AppSecret) + ts)

三、实施步骤与代码示例

在实际开发中，您只需封装一个函数，该函数负责计算实时签名并发送音量指令。

步骤1：准备工作

在芯步控制台（Console）获取以下三个关键数据：

AppID：应用唯一标识。
AppSecret：开发者密码（用于计算签名）。
Device ID：目标30W音箱的设备编号（通常在设备列表或设备详情页查看）。

步骤2：代码实现（核心逻辑）

以下提供三种常用语言的二次开发示例，核心逻辑均为拼接动态URL、计算签名、发送JSON指令。

Python 3 示例

适用于后端服务、脚本或云函数。

import hashlib
import time
import requests
import json

def set_volume(device_id, volume_level):
    # 1. 配置参数
    app_id = "YOUR_APP_ID"          # 替换为控制台中的AppID
    app_secret = "YOUR_APP_SECRET"  # 替换为控制台中的AppSecret
    
    # 2. 计算签名 (ts 和 sign)
    ts = int(time.time())
    # 第一次MD5: 对AppSecret进行加密
    md5_app_secret = hashlib.md5(app_secret.encode()).hexdigest()
    # 拼接并第二次MD5
    sign_str = md5_app_secret + str(ts)
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 3. 构造请求URL
    url = f"https://api.thingboot.com/{app_id}/device/control/"
    params = {
        "sign": sign,
        "ts": ts
    }
    
    # 4. 构造Body (核心:音量指令)
    payload = {
        "device": device_id,
        "order": {"volume": volume_level}   # 关键点:调节音量
    }
    
    # 5. 发送请求
    response = requests.post(url, params=params, json=payload)
    return response.json()

# --- 调用示例 ---
# 假设您的设备ID是 "A89757"，想要把远程音箱音量调到 12
result = set_volume("A89757", 12)
print(result)
# 若返回 {"code":200, "msg":"ok"} 代表调节成功

Java 示例

适用于企业级Spring Boot后端。

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

public class YoyoVolumeControl {
    public static void main(String[] args) {
        String AppID = "YOUR_APP_ID";
        String AppSecret = "YOUR_APP_SECRET";
        String deviceId = "A89757";
        int volume = 10; // 目标音量
        
        long ts = System.currentTimeMillis() / 1000L;
        // 签名计算: md5( md5(secret) + ts )
        String sign = DigestUtils.md5Hex(DigestUtils.md5Hex(AppSecret) + ts);
        
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", AppID, sign, ts);
        
        // 构造指令: 使用 order 传递音量参数
        String orderJson = "{\"volume\":" + volume + "}";
        String body = String.format("{\"device\":\"%s\", \"order\":%s}", deviceId, orderJson);
        
        try {
            HttpResponse<String> response = Unirest.post(url)
                    .header("Content-Type", "application/json")
                    .body(body)
                    .asString();
            System.out.println(response.getBody()); // 检查 code 是否为 200
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Java依赖说明：代码示例使用了 Unirest 和 commons-codec 库，这是处理HTTP请求和MD5加密的常用组合。

C# / .NET 示例

适用于Windows桌面应用或Unity项目。

using System;
using System.Net.Http;
using System.Text;
using System.Security.Cryptography;
using Newtonsoft.Json;

public class AudioController 
{
    public async Task<string> SetVolumeAsync(string deviceId, int level) 
    {
        string appId = "YOUR_APP_ID";
        string secret = "YOUR_APP_SECRET";
        
        long ts = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        // 计算 MD5
        string md5Secret = GetMd5Hash(secret);
        string sign = GetMd5Hash(md5Secret + ts);
        
        string url = $"https://api.thingboot.com/{appId}/device/control/?sign={sign}&ts={ts}";
        
        var payload = new {
            device = deviceId,
            order = new { volume = level }
        };
        string jsonBody = JsonConvert.SerializeObject(payload);
        
        using (var client = new HttpClient()) {
            var content = new StringContent(jsonBody, Encoding.UTF8, "application/json");
            var response = await client.PostAsync(url, content);
            return await response.Content.ReadAsStringAsync();
        }
    }
    
    private string GetMd5Hash(string input) {
        using (MD5 md5 = MD5.Create()) {
            byte[] hashBytes = md5.ComputeHash(Encoding.UTF8.GetBytes(input));
            return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
        }
    }
}

四、关键注意事项与排障

在二次开发中，若遇到指令下发失败，请按以下常见问题排查：

HTTP状态码与Code码
- 5006 bad sign：签名错误。请请一定要确认时间戳ts是秒级（10位），且签名计算公式为 md5(md5(秘钥) + ts)，注意是字符串拼接后再加密。
- 5008 ip not in white list：IP白名单限制。如果您在控制台开启了IP检查，需要将部署代码的服务器公网IP加入白名单。
- 5009 too many request：请求频率超限。单个设备的控制接口限制为1次/秒，请勿在循环中无延迟调用。
网络环境该30W音箱仅支持2.4G WiFi。请确保设备所处环境信号良好，且能正常访问外网（除非您部署了私有化方案）。
功能扩展除了音量调节，该开放接口同样支持其他音频控制：
- 内容播报{“play:gbk:16”:“你好，欢迎光临”}
- 停止播放{“stop”:1}
- 切换音色{“voice”:1} （0女声/1男声）
私有化部署如果您对数据安全或网络延迟有比较高要求，芯步支持私有化部署。在这种情况下，API地址将变更为您自建服务器的IP，通讯协议不变。

通过以上方案，您可以轻松地将30W户外防水壁挂音箱集成到各类上位机系统、自助终端或智能控制平台中。