更新记录

1.0.0（2026-03-02）

BLUFI 蓝牙配网工具开发文档

文档概述

本工具基于 uni-app 蓝牙 API 封装了完整的 BLUFI 协议配网流程，提供设备搜索、蓝牙连接、WiFi 列表获取、WiFi 配网等核心功能，支持 Promise 异步编程范式和事件回调机制，可快速集成到 uni-app 项目中实现蓝牙配网能力。

核心特点

1. 全流程封装：覆盖设备发现、连接、WiFi 采集、配网配置、连接释放全流程；
2. 异步友好：所有异步操作基于 Promise 封装，支持 async/await 语法；
3. 事件回调：提供设备发现、WiFi 列表更新等事件通知；
4. 兼容性适配：自动适配设备蓝牙服务/特征值 UUID，支持重试机制；
5. 简化集成：单文件引入，无需依赖多组件/页面，低耦合易扩展。

快速开始

1. 环境依赖

• 运行环境：uni-app 项目（支持微信小程序、App 等蓝牙可用环境）；
• 权限要求：设备开启蓝牙，小程序/APP 需获取蓝牙使用权限。

2. 安装引入

将 blufiSetup.js 文件放入项目目录，在需要使用的页面/组件中引入：

const BlufiSetup = require('./blufiSetup.js');

3. 基础使用流程

// 1. 创建配网实例
const blufi = new BlufiSetup({
  callback: function(event, data) {
    // 监听事件回调
    switch(event) {
      case 'deviceFound':
        console.log('发现新设备:', data);
        break;
      case 'wifiList':
        console.log('WiFi列表更新:', data);
        break;
    }
  }
});

// 2. 搜索蓝牙设备
blufi.searchDevices()
  .then(devices => {
    console.log('搜索到设备列表:', devices);
    const targetDevice = devices[0]; // 选择目标设备
    // 3. 连接设备
    return blufi.connectDevice(targetDevice.deviceId);
  })
  .then(() => {
    console.log('设备连接成功');
    // 4. 获取周边WiFi列表
    return blufi.getWifiList();
  })
  .then(wifiList => {
    console.log('WiFi列表:', wifiList);
    const targetWifi = wifiList[0]; // 选择目标WiFi
    // 5. 执行配网（传入WiFi名称和密码）
    return blufi.startSetup(targetWifi.SSID, 'wifi_password_123');
  })
  .then(() => {
    console.log('配网成功');
    // 6. 关闭蓝牙连接，释放资源
    blufi.closeConnect();
  })
  .catch(err => {
    console.error('配网流程异常:', err);
    blufi.closeConnect(); // 异常时也需关闭连接
  });

API 参考

1. 构造函数：BlufiSetup(options)

创建配网实例，支持传入配置项自定义行为。

回调事件说明

数据结构定义

• Device（设备）：

  {
  deviceId: String, // 设备唯一标识
  name: String, // 设备名称（匹配BLUFI/X2/K1/C1前缀）
  RSSI: Number // 信号强度（可选）
  }

• WiFi（WiFi信息）：

  {
  rssi: Number, // WiFi信号强度
  SSID: String, // WiFi名称（解码后）
  utfName: String // WiFi名称（UTF8编码）
  }

2. 实例方法

searchDevices()

功能：开启蓝牙适配器并搜索符合规则的 BLUFI 设备。
参数：无
返回值：Promise<Array<Device>> - 已发现的设备列表（去重后）
异常：蓝牙开启失败、搜索失败时触发 reject，返回错误对象。

stopSearch()

功能：停止蓝牙设备搜索，释放搜索资源。
参数：无
返回值：无

connectDevice(deviceId)

返回值：Promise<Array<Characteristic>> - 设备特征值列表
异常：连接超时、无可用服务/特征值时触发 reject。

getWifiList(retryCount = 0)

返回值：Promise<Array<WiFi>> - WiFi列表数据
异常：指令发送失败、重试次数超限触发 reject。

startSetup(ssid, password)

返回值：Promise<void> - 配网指令发送成功则resolve
异常：写入失败、设备无响应触发 reject。

closeConnect()

功能：关闭当前蓝牙连接，释放适配器资源。
参数：无
返回值：无

checkWritePermission(deviceId, serviceId, characteristicId)

返回值：Promise<Boolean> - 有写入权限则resolve(true)

核心常量说明（进阶）

以下常量为 BLUFI 协议核心定义，适配不同设备时可按需调整：

// 核心UUID（默认适配多数BLUFI设备，可根据设备文档修改）
service_uuid: '0000FFFF-0000-1000-8000-00805F9B34FB', // 蓝牙服务UUID
characteristic_write_uuid: '0000FF01-0000-1000-8000-00805F9B34FB', // 写入特征值UUID
characteristic_read_uuid: '0000FF02-0000-1000-8000-00805F9B34FB', // 通知特征值UUID

// 协议子类型定义
SUBTYPE_WIFI_MODE = 0x02; // WiFi模式配置
SUBTYPE_SET_SSID = 0x2; // 设置SSID
SUBTYPE_SET_PWD = 0x3; // 设置密码
SUBTYPE_WIFI_LIST_NEG = 11; // WiFi列表协商

注意事项

1. 权限与环境：
   • 使用前需确保设备蓝牙已开启，小程序/APP已获取蓝牙权限；
   • 微信小程序需在「微信公众平台」配置蓝牙接口权限，且仅支持安卓/iOS 10+。
2. 资源释放：
   • 配网完成/异常时必须调用 closeConnect() 关闭连接，避免蓝牙资源泄漏；
   • 页面卸载前需调用 stopSearch() 停止设备搜索。
3. 设备兼容性：
   • 不同厂商设备的服务/特征值UUID可能不同，需根据实际设备文档调整 service_uuid 等常量；
   • 配网过程中需保持设备在蓝牙有效范围内（建议1米内）。
4. 重试机制：
   • getWifiList/writeDeviceStart 内置重试机制（默认3次），可根据网络稳定性调整重试次数。

常见问题与解决方案

Q1：搜索不到设备？

• 检查设备是否开启蓝牙，且设备名称包含 BLUFI/X2/K1/C1 前缀（可修改 filterDevice 方法的正则规则适配其他前缀）；
• 确认环境蓝牙权限已授予，小程序需在真机测试（模拟器不支持蓝牙）。

Q2：连接设备失败？

• 检查设备ID是否正确，设备是否处于可连接状态；
• 部分设备需先配对再连接，可在连接前增加配对逻辑；
• 调整 connectDevice 中的超时时间（默认10秒）。

Q3：获取WiFi列表为空？

• 确认设备已成功连接且启用通知（查看控制台是否输出「通知启用成功」）；
• 检查设备是否支持WiFi扫描，部分设备需进入配网模式才会返回WiFi列表；
• 增加 getWifiList 的重试次数，或延迟调用（设备连接后建议延迟1-2秒再获取WiFi）。

Q4：配网成功但设备无法联网？

• 检查WiFi名称/密码是否正确（区分大小写、特殊字符）；
• 确认设备支持目标WiFi的频段（2.4G/5G，多数BLUFI设备仅支持2.4G）；
• 检查配网指令发送是否完整（查看控制台是否输出「配置信息发送成功」）。

平台兼容性

uni-app(4.0)

uni-app x(4.0)

BLUFI 蓝牙配网工具开发文档

文档概述

本工具基于 uni-app 蓝牙 API 封装了完整的 BLUFI 协议配网流程，提供设备搜索、蓝牙连接、WiFi 列表获取、WiFi 配网等核心功能，支持 Promise 异步编程范式和事件回调机制，可快速集成到 uni-app 项目中实现蓝牙配网能力。

核心特点

1. 全流程封装：覆盖设备发现、连接、WiFi 采集、配网配置、连接释放全流程；
2. 异步友好：所有异步操作基于 Promise 封装，支持 async/await 语法；
3. 事件回调：提供设备发现、WiFi 列表更新等事件通知；
4. 兼容性适配：自动适配设备蓝牙服务/特征值 UUID，支持重试机制；
5. 简化集成：单文件引入，无需依赖多组件/页面，低耦合易扩展。

快速开始

1. 环境依赖

• 运行环境：uni-app 项目（支持微信小程序、App 等蓝牙可用环境）；
• 权限要求：设备开启蓝牙，小程序/APP 需获取蓝牙使用权限。

2. 安装引入

将 blufiSetup.js 文件放入项目目录，在需要使用的页面/组件中引入：

const BlufiSetup = require('./blufiSetup.js');

3. 基础使用流程

// 1. 创建配网实例
const blufi = new BlufiSetup({
  callback: function(event, data) {
    // 监听事件回调
    switch(event) {
      case 'deviceFound':
        console.log('发现新设备:', data);
        break;
      case 'wifiList':
        console.log('WiFi列表更新:', data);
        break;
    }
  }
});

// 2. 搜索蓝牙设备
blufi.searchDevices()
  .then(devices => {
    console.log('搜索到设备列表:', devices);
    const targetDevice = devices[0]; // 选择目标设备
    // 3. 连接设备
    return blufi.connectDevice(targetDevice.deviceId);
  })
  .then(() => {
    console.log('设备连接成功');
    // 4. 获取周边WiFi列表
    return blufi.getWifiList();
  })
  .then(wifiList => {
    console.log('WiFi列表:', wifiList);
    const targetWifi = wifiList[0]; // 选择目标WiFi
    // 5. 执行配网（传入WiFi名称和密码）
    return blufi.startSetup(targetWifi.SSID, 'wifi_password_123');
  })
  .then(() => {
    console.log('配网成功');
    // 6. 关闭蓝牙连接，释放资源
    blufi.closeConnect();
  })
  .catch(err => {
    console.error('配网流程异常:', err);
    blufi.closeConnect(); // 异常时也需关闭连接
  });

API 参考

1. 构造函数：BlufiSetup(options)

创建配网实例，支持传入配置项自定义行为。

回调事件说明

数据结构定义

• Device（设备）：

  {
  deviceId: String, // 设备唯一标识
  name: String, // 设备名称（匹配BLUFI/X2/K1/C1前缀）
  RSSI: Number // 信号强度（可选）
  }

• WiFi（WiFi信息）：

  {
  rssi: Number, // WiFi信号强度
  SSID: String, // WiFi名称（解码后）
  utfName: String // WiFi名称（UTF8编码）
  }

2. 实例方法

searchDevices()

功能：开启蓝牙适配器并搜索符合规则的 BLUFI 设备。
参数：无
返回值：Promise<Array<Device>> - 已发现的设备列表（去重后）
异常：蓝牙开启失败、搜索失败时触发 reject，返回错误对象。

stopSearch()

功能：停止蓝牙设备搜索，释放搜索资源。
参数：无
返回值：无

connectDevice(deviceId)

返回值：Promise<Array<Characteristic>> - 设备特征值列表
异常：连接超时、无可用服务/特征值时触发 reject。

getWifiList(retryCount = 0)

返回值：Promise<Array<WiFi>> - WiFi列表数据
异常：指令发送失败、重试次数超限触发 reject。

startSetup(ssid, password)

返回值：Promise<void> - 配网指令发送成功则resolve
异常：写入失败、设备无响应触发 reject。

closeConnect()

功能：关闭当前蓝牙连接，释放适配器资源。
参数：无
返回值：无

checkWritePermission(deviceId, serviceId, characteristicId)

返回值：Promise<Boolean> - 有写入权限则resolve(true)

核心常量说明（进阶）

以下常量为 BLUFI 协议核心定义，适配不同设备时可按需调整：

// 核心UUID（默认适配多数BLUFI设备，可根据设备文档修改）
service_uuid: '0000FFFF-0000-1000-8000-00805F9B34FB', // 蓝牙服务UUID
characteristic_write_uuid: '0000FF01-0000-1000-8000-00805F9B34FB', // 写入特征值UUID
characteristic_read_uuid: '0000FF02-0000-1000-8000-00805F9B34FB', // 通知特征值UUID

// 协议子类型定义
SUBTYPE_WIFI_MODE = 0x02; // WiFi模式配置
SUBTYPE_SET_SSID = 0x2; // 设置SSID
SUBTYPE_SET_PWD = 0x3; // 设置密码
SUBTYPE_WIFI_LIST_NEG = 11; // WiFi列表协商

注意事项

1. 权限与环境：
   • 使用前需确保设备蓝牙已开启，小程序/APP已获取蓝牙权限；
   • 微信小程序需在「微信公众平台」配置蓝牙接口权限，且仅支持安卓/iOS 10+。
2. 资源释放：
   • 配网完成/异常时必须调用 closeConnect() 关闭连接，避免蓝牙资源泄漏；
   • 页面卸载前需调用 stopSearch() 停止设备搜索。
3. 设备兼容性：
   • 不同厂商设备的服务/特征值UUID可能不同，需根据实际设备文档调整 service_uuid 等常量；
   • 配网过程中需保持设备在蓝牙有效范围内（建议1米内）。
4. 重试机制：
   • getWifiList/writeDeviceStart 内置重试机制（默认3次），可根据网络稳定性调整重试次数。

常见问题与解决方案

Q1：搜索不到设备？

• 检查设备是否开启蓝牙，且设备名称包含 BLUFI/X2/K1/C1 前缀（可修改 filterDevice 方法的正则规则适配其他前缀）；
• 确认环境蓝牙权限已授予，小程序需在真机测试（模拟器不支持蓝牙）。

Q2：连接设备失败？

• 检查设备ID是否正确，设备是否处于可连接状态；
• 部分设备需先配对再连接，可在连接前增加配对逻辑；
• 调整 connectDevice 中的超时时间（默认10秒）。

Q3：获取WiFi列表为空？

• 确认设备已成功连接且启用通知（查看控制台是否输出「通知启用成功」）；
• 检查设备是否支持WiFi扫描，部分设备需进入配网模式才会返回WiFi列表；
• 增加 getWifiList 的重试次数，或延迟调用（设备连接后建议延迟1-2秒再获取WiFi）。

Q4：配网成功但设备无法联网？

• 检查WiFi名称/密码是否正确（区分大小写、特殊字符）；
• 确认设备支持目标WiFi的频段（2.4G/5G，多数BLUFI设备仅支持2.4G）；
• 检查配网指令发送是否完整（查看控制台是否输出「配置信息发送成功」）。