[JS/TS] 开源蓝牙调试工具开发实战：基于uni-app与Vue3的跨平台解决方案

随着物联网和智能硬件的快速发展，蓝牙通信已成为设备间交互的重要方式。然而，对于开发者而言，调试蓝牙设备通常是一项繁琐且高度依赖特定平台的工作。不同操作系统对蓝牙的支持方式各异，开发和测试过程往往需要在多个环境间反复切换，效率低下。本文将介绍一款基于现代化技术栈构建的、真正实现跨平台、功能完整的开源蓝牙调试工具——BLE Toolkit+，它能有效解决上述痛点。

项目介绍

BLE Toolkit+ 是一款专业的蓝牙调试工具，采用 uni-app 与 Vue 3 进行开发，能够支持多平台部署，包括微信小程序、iOS原生应用和Android原生应用。该工具专为蓝牙设备的调试和开发设计，集成了设备扫描、服务发现、特征值读写等核心功能。无论是嵌入式开发者调试ESP32等模块，还是移动端应用开发者验证蓝牙通信逻辑，都能通过此工具高效地完成工作。

项目核心功能

1. 设备扫描与发现：实时扫描并列出附近所有可连接的蓝牙设备。
2. 设备信息查看：展示设备的详细信息，包括名称、信号强度（RSSI）以及原始广播数据。
3. 服务与特征值解析：完整解析蓝牙设备的服务（Service）与特征值（Characteristic），支持读取、写入及启用通知（Notify）。
4. 自定义广播：支持在 iOS 和 Android 平台上模拟 BLE 外设，进行自定义蓝牙广播。
5. 灵活数据交互：数据写入支持 UTF-8 文本与 HEX 格式，满足不同通信协议的需求。
6. ESP32 深度集成：提供针对 ESP32 开发板的配套支持，包含示例固件与通信代码。

技术架构详解

核心技术栈

• 应用框架：Vue 3
• UI组件库：@dcloudio/uni-ui
• 核心插件：BLE-Module（用于实现自定义蓝牙广播功能）

多平台支持

• 微信小程序：调用微信小程序原生蓝牙API。
• iOS原生应用：基于苹果的 CoreBluetooth 框架开发。
• Android原生应用：兼容 Android 5.0 及以上版本的系统。想深入了解如何构建跨端应用，可以参考云栈社区的前端框架与工程化相关内容。

硬件与固件（以ESP32为例）

• 开发板：ESP32系列
• 开发环境：Arduino IDE
• 关键库：ESP32内置的BLE库

预定义蓝牙服务

项目示例固件预设了两个标准的BLE服务，方便开发者快速测试：

服务1 (UUID: 4fafc201-1fb5-459e-8fcc-c5c9c331914b)

• 写特征值：支持文本/HEX格式数据写入。
• 通知特征值：启用后可接收设备主动推送的数据。

服务2 (UUID: 4fafc201-1fb5-459e-8fcc-c5c9c331914c)

• 只读特征值：用于读取设备信息。
• 只写特征值：用于发送控制命令。
• 通知特征值：用于接收设备状态更新。

ESP32 固件编译步骤

1. 安装 Arduino IDE。
2. 通过开发板管理器安装 ESP32 支持包。
3. 确保已包含必要的库文件（如内置BLE库）。
4. 打开项目源码，编译并上传至 ESP32 开发板。

快速开始指南

环境准备与运行

克隆项目后，首先安装依赖并选择对应的平台运行：

# 安装项目依赖
npm install

# 运行到不同平台
npm run dev:h5        # H5 网页版
npm run dev:mp-weixin # 微信小程序开发者工具
npm run dev:app       # iOS/Android App (需HBuilderX)

核心代码示例 (uni-app蓝牙API)

以下代码片段展示了如何使用 uni-app 的蓝牙API进行设备搜索与连接：

// 1. 初始化蓝牙适配器
uni.openBluetoothAdapter({
  success: () => {
    console.log('蓝牙适配器初始化成功');
    // 2. 开始搜索附近的蓝牙设备
    uni.startBluetoothDevicesDiscovery({
      success: () => {
        console.log('开始搜索设备...');
      }
    });
  }
});

// 3. 监听发现新设备的事件
uni.onBluetoothDeviceFound((devices) => {
  console.log('发现新设备:', devices);
});

// 4. 连接指定设备
function connectDevice(deviceId) {
  uni.createBLEConnection({
    deviceId: deviceId,
    success: () => {
      console.log('设备连接成功');
      // 5. 获取已连接设备的服务列表
      uni.getBLEDeviceServices({
        deviceId: deviceId,
        success: (res) => {
          console.log('设备服务列表:', res.services);
        }
      });
    }
  });
}

多平台权限配置

Android 权限

在 AndroidManifest.xml 中声明以下权限（根据Android版本需要动态申请）：

• BLUETOOTH & BLUETOOTH_ADMIN：基础蓝牙权限。
• ACCESS_FINE_LOCATION：Android系统要求扫描蓝牙设备必须拥有定位权限。
• BLUETOOTH_SCAN / BLUETOOTH_ADVERTISE / BLUETOOTH_CONNECT (Android 12+): 新的运行时权限。关于移动端开发的更多实践，可以查看Android/iOS开发专题。

iOS 配置

在 Info.plist 中添加 NSBluetoothAlwaysUsageDescription 键值对，说明应用使用蓝牙的用途，否则无法调用蓝牙功能。

微信小程序

需在微信公众平台的小程序管理后台，于“开发”->“开发管理”->“接口设置”中，开启“蓝牙”相关接口的权限。

项目效果展示

获取项目源码

该项目已在 Gitee 平台开源。项目仓库中不仅包含了完整的 uni-app 前端源码，还提供了配套的 ESP32 Arduino 工程，内含文中所述的两个标准 BLE 服务示例，全面支持读写、通知等操作模式。详细的开发文档、权限配置指南和编译说明均可从仓库获取。

项目地址：https://gitee.com/luoyaosheng/smart-ble

结语

BLE Toolkit+ 不仅仅是一个调试工具，更是对碎片化的跨平台蓝牙开发体验的一次有效整合。它利用现代Vue 3和uni-app技术，将不同平台的原生蓝牙能力统一封装，为物联网开发者和硬件工程师提供了一个高效、便捷的调试入口。无论是快速验证蓝牙模块的基础功能，还是深入分析和调试复杂的自定义通信协议，这款开源工具都能提供有力的支持，是提升智能硬件开发效率的利器。在构建此类涉及设备交互的复杂应用时，一个稳定的后端架构同样重要，感兴趣的开发者可以延伸了解云原生与基础设施的相关知识。