# utools_bluetooth_utils

**Repository Path**: fancy171101034/utools_bluetooth_utils

## Basic Information

- **Project Name**: utools_bluetooth_utils
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-06
- **Last Updated**: 2026-04-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 蓝牙调试工具 (uTools 插件)

一个功能强大的 `uTools` 蓝牙调试插件，基于 `@abandonware/noble`，支持低功耗蓝牙(BLE)设备扫描、连接、读写和通知订阅。

## 功能特性

- 🔍 **设备扫描**：扫描周围的低功耗蓝牙设备，显示设备名称、ID、RSSI、制造商数据等信息
- 🔗 **设备连接**：支持连接任意 BLE 设备，浏览设备服务和特征值
- 📝 **数据写入**：支持文本、十六进制格式写入，支持从文件导入数据
- 📡 **通知订阅**：订阅特征值通知，实时接收设备推送的数据
- 📖 **数据读取**：读取特征值数据，以十六进制和文本格式展示
- 💾 **数据导出**：支持将接收的数据保存到文件
- ⚡ **快捷指令**：可保存常用指令，一键发送
- 🎨 **现代化 UI**：基于 Vue 3，界面简洁易用

## 系统要求

- [uTools](https://u.tools/) 客户端
- Node.js 16+（开发打包用）
- **支持平台**:
  - ✅ macOS
  - ✅ Windows
  - ✅ Linux

## 安装方法

### 从 uTools 插件市场安装

搜索「蓝牙调试工具」点击安装即可。

### 手动安装（开发者）

1. 下载最新版本的 [Release](https://github.com/your-username/utools-bluetooth-utils/releases)
2. 打开 uTools → 偏好设置 → 插件 → 双击 `dist.upx` 或拖入安装窗口

## 使用方法

### 1. 启动插件

在 uTools 中输入关键词 `蓝牙调试工具` 或 `bluetooth_utils` 启动。

### 2. 扫描设备

点击「开始扫描」按钮，插件会搜索周围的 BLE 设备，设备列表会实时更新。

### 3. 连接设备

点击设备列表中的任意设备即可发起连接，连接成功后会显示该设备的所有服务和特征值。

### 4. 操作特征值

- **读取数据**: 点击「读取」按钮读取特征值当前值
- **写入数据**: 输入数据（支持文本/十六进制）点击「写入」发送
- **订阅通知**: 点击「订阅」开启通知，设备推送的数据会实时显示在日志中

### 5. 快捷指令

在发送框输入数据后，点击「保存」即可将当前指令保存到快捷指令列表，后续点击即可快速发送。

## 项目结构

```
├── public/
│   ├── plugin.json      # uTools 插件配置
│   ├── preload/         # Preload 脚本目录
│   │   ├── preload.js   # Preload 主脚本（处理蓝牙操作）
│   │   └── package.json # Preload 依赖声明
│   └── logo.png         # 插件图标
├── src/
│   ├── components/      # Vue 组件
│   ├── App.vue          # 主应用组件
│   ├── main.js          # 入口文件
│   └── mock.js          # 浏览器开发模拟
├── index.html
├── package.json
└── vite.config.js       # Vite 构建配置
```

## 开发指南

### 环境准备

```bash
# 克隆项目
git clone <repository-url>
cd utools_bluetooth_utils

# 安装依赖
npm install
```

### 开发调试

```bash
npm run dev
```

在浏览器打开 `http://localhost:5173` 即可开发调试，蓝牙功能会使用模拟数据。

### 打包构建

```bash
npm run build
```

构建产物在 `dist` 目录，将 `dist` 目录压缩为 `dist.upx` 即可在 uTools 中安装。

## 技术说明

### 为什么使用 Preload + noble

uTools 插件的渲染进程无法直接使用 Node.js 原生模块，因此本插件采用 uTools 官方推荐的 [preload 方案](https://u.tools/docs/developer/preload.html):

- Preload 运行在 Node.js 环境，可以加载原生模块
- 蓝牙操作都在 Preload 中执行，通过 `window.services` 暴露给渲染进程
- `@abandonware/noble` 是 Node.js 生态中最成熟的 BLE 库，支持 macOS/Windows/Linux 多平台

### 跨平台说明

本插件使用的 `@abandonware/noble` 原生模块支持多平台:

- **macOS**: 使用原生 CoreBluetooth 框架
- **Windows**: 使用默认蓝牙驱动
- **Linux**: 需要 BlueZ 5 以上

打包插件时，`@abandonware/noble` 会自动根据当前操作系统安装对应平台的二进制文件。如果需要在两个平台使用，建议在对应平台分别打包，或在插件安装后重新构建原生模块。

## 常见问题

**Q: 加载蓝牙模块失败怎么办？**

A: 这通常是因为原生模块编译问题。可以尝试:
1. 在对应平台重新运行 `npm install`
2. 检查是否安装了构建工具（Xcode Command Line Tools / Visual Studio Build Tools）
3. 查看控制台错误信息，确认是否缺少依赖

**Q: Windows 上扫描不到设备？**

A: 请确认:
1. 蓝牙已开启且驱动正常
2. 使用的是蓝牙 4.0+ 适配器
3. 以管理员权限运行 uTools

**Q: Mac 上提示权限不足？**

A: 请在系统设置 → 隐私与安全性 中允许 uTools 使用蓝牙。

## 更新日志

### v1.0.0
- 基础功能完成：设备扫描、连接、读写、通知订阅
- 支持快捷指令保存
- 支持数据导出到文件
- 修复滚动条样式问题
- 优化进度条显示

## 许可证

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！