Web Bluetooth API 实战：实现网页与 BLE 设备通信

Web Bluetooth API 实战：实现网页与 BLE 设备通信 | 极客日志

graph LR A[Web 应用] -->|JavaScript| B(Web Bluetooth API) B --> C{浏览器安全策略} C --> D[BLE 设备] D --> E((GATT Server))

对比维度	经典蓝牙（BR/EDR）	低功耗蓝牙（BLE）
主要用途	音频流传输（如耳机）、文件传输	传感器数据上报、远程控制、状态同步
功耗水平	较高，适合持续供电设备	极低，适用于纽扣电池供电设备
数据速率	1–3 Mbps	1–2 Mbps（BLE 5.x 可达更高）
连接方式	点对点主从配对，连接稳定持久	快速建立/断开连接，支持一对多广播
协议复杂度	高，依赖 SCO/eSCO 链路	简化协议栈，基于事件驱动
通信模式	持续连接，周期性数据交换	广播 + 按需连接，事件触发式交互

graph TD A[Application] --> B[GATT] B --> C[ATT] C --> D[L2CAP] D --> E[SM / GAP] E --> F[Security Manager / Generic Access Profile] F --> G[Host Control Interface (HCI)] G --> H[Link Layer (LL)] H --> I[Physical Layer (PHY)]

字段	长度（字节）	说明
Preamble	1	同步头，固定为 0xAA 或 0x55
Access Address	4	固定为 0x8E89BED6，标识 BLE 广播包
PDU Header	2	包含 PDU 类型、长度等信息
Payload	0–37	实际携带的数据，最多 37 字节
CRC	3	校验码

[Length][AD Type][AD Data...]

AD Type (Hex)	名称	示例数据
0x01	Flags	0x06（LE General Discoverable Mode + BR/EDR not supported）
0x03	16-bit Service UUIDs	0xFEAA（Eddystone）
0x09	Complete Local Name	'Smart Thermometer'
0x0A	TX Power Level	-59 dBm

02 01 06 03 03 AA FE 0C 09 53 6D 61 72 74 20 54 68 65 72 6D 6F

模式	是否发送 SCAN_REQ	获取信息量	功耗
被动扫描	否	仅广告包内容	低
主动扫描	是	广告包 + 扫描响应	较高

sequenceDiagram participant Central as 中心设备 participant Peripheral as 外围设备 Peripheral->>Central: ADV_IND on Channel 37 Central->>Peripheral: CONNECT_REQ (Initiator Address, Access Address, etc.) Peripheral-->>Central: 进入连接状态 note right of Peripheral: 使用 Access Address 和 Hop Interval 建立同步 Central->>Peripheral: 发起 GATT 服务发现

参数	描述	影响
Connection Interval	主从设备通信的时间间隔（单位：1.25ms）	决定响应速度与功耗，范围 7.5ms–4s
Slave Latency	从机可跳过的连接事件次数	提高节能性，但增加延迟
Supervision Timeout	最大允许无响应时间（单位：10ms）	决定连接稳定性

Device └── Service (UUID: 0x180D)
    ├── Characteristic (UUID: 0x2A37)
    │   ├── Value: [0x06, 0x60]
    │   └── Descriptor (Client Characteristic Configuration)
    └── Characteristic (UUID: 0x2A38)
        └── Value: ...

OpCode	操作	示例
0x0B	Read Request	客户端请求读取某特征值
0x0C	Read Response	服务器返回数据
0x12	Write Request	写入特征值（需等待确认）
0x52	Write Command	'无响应写'，适用于频繁更新场景

const characteristic = await service.getCharacteristic('00002a37-0000-1000-8000-00805f9b34fb');
await characteristic.writeValue(new Uint8Array([1]).buffer);
console.log('Command sent via ATT Write Request');

层级	UUID	属性	说明
Service	0x180D	-	心率服务
└─ HR Measurement	0x2A37	Notify	心率数据，支持通知
└─ Body Sensor Location	0x2A38	Read	传感器佩戴位置（胸部、手腕等）
└─ HR Control Point	0x2A39	Write	控制命令（如重置能量扩展）

await characteristic.startNotifications();
characteristic.addEventListener('characteristicvaluechanged', (event) => {
    const value = event.target.value;
    const heartRate = value.getUint8(1); // 解析第二个字节
    console.log(`Current Heart Rate: ${heartRate} BPM`);
});

模式	安全性	用户交互	适用场景
Just Works	无 MITM 保护	无	不敏感数据（如灯光控制）
Passkey Entry	抵抗 MITM 攻击	输入 6 位数字	高安全需求设备
Out of Band (OOB)	高安全性	NFC/二维码辅助	工业级设备

目录	功能说明
`/src`	核心源码目录，包含蓝牙设备抽象类、连接管理器、数据处理器等可复用模块
`/examples`	提供多个独立 HTML 示例页面，用于演示不同 BLE 设备的交互逻辑（如 LED 控制、传感器读取）
`/docs`	文档生成输出目录，通常由 Markdown 源文件经静态站点生成器（如 Docusaurus 或 VitePress）编译而成
`/tests`	单元测试与端到端测试脚本存放位置，使用 Jest 或 Playwright 实现自动化验证
`/scripts`	构建、部署、格式化等辅助脚本（如启动本地服务器、打包生产资源）
`package.json`	定义项目元信息、依赖项、构建命令与发布配置

web-bluetooth-demo/
├── src/
│   ├── bluetooth/
│   │   ├── DeviceManager.js
│   │   ├── ServiceHandler.js
│   │   └── utils/DataConverter.js
│   └── index.js
├── examples/
│   ├── led-control.html
│   ├── heart-rate-monitor.html
│   └── uart-terminal.html
├── docs/
│   └── guide.md
├── tests/
│   └── unit/device-manager.test.js
├── scripts/
│   └── start-server.js
├── package.json
└── README.md

graph TD A[examples/led-control.html] --> B[src/index.js] B --> C[src/bluetooth/DeviceManager.js] C --> D[src/bluetooth/ServiceHandler.js] D --> E[src/utils/DataConverter.js] F[tests/unit/device-manager.test.js] --> C G[scripts/start-server.js] --> H[http server]

{
  "name": "web-bluetooth-starter",
  "version": "1.0.0",
  "description": "A starter kit for building Web Bluetooth applications",
  "main": "src/index.js",
  "scripts": {
    "start": "node scripts/start-server.js",
    "test": "jest --config jest.config.js",
    "build": "vite build",
    "format": "prettier --write \"src/**/*.js\""
  },
  "dependencies": {
    "@abandonware/bluetooth": "^6.5.0",
    "buffer": "^6.0.3"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "prettier": "^3.0.3",
    "vite": "^4.5.0",
    "vite-plugin-mkcert": "^1.14.0"
  },
  "keywords": ["web", "bluetooth", "ble", "iot"],
  "author": "Dev Team",
  "license": "MIT"
}

// vite.config.js
import { defineConfig } from 'vite';
import mkcert from 'vite-plugin-mkcert';

export default defineConfig({
  plugins: [
    mkcert() // 自动生成 localhost 的可信证书
  ],
  server: {
    https: true, // 必须开启 HTTPS
    port: 8080,
    host: 'localhost'
  }
});

# 初始化项目
npm init -y
# 安装 Vite 和 mkcert 插件
npm install --save-dev vite vite-plugin-mkcert
# 创建基本目录结构
mkdir src examples scripts
touch vite.config.js

// scripts/start-server.js
const { createServer } = require('vite');
const path = require('path');

async function startServer() {
  const server = await createServer({
    root: path.resolve(),
    configFile: path.resolve('vite.config.js'),
    server: {
      https: true,
      port: 8080
    }
  });
  await server.listen();
  server.printUrls(); // 输出访问地址
}

startServer().catch((err) => {
  console.error('Failed to start server:', err);
  process.exit(1);
});

<!-- examples/led-control.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>BLE LED Control</title>
  <script type="module" src="../src/index.js"></script>
</head>
<body>
  <button>Connect to BLE Device</button>
  <button>Toggle LED</button>
</body>
</html>

// src/index.js
const CONNECT_BTN = document.getElementById('connect');
const TOGGLE_BTN = document.getElementById('toggleLed');
let bluetoothDevice;
let characteristic;

CONNECT_BTN.addEventListener('click', async () => {
  try {
    bluetoothDevice = await navigator.bluetooth.requestDevice({
      filters: [{ services: ['6e400001-b5a3-f393-e0a9-e50e24dcca9e'] }] // Nordic UART Service
    });
    const server = await bluetoothDevice.gatt.connect();
    const service = await server.getPrimaryService('6e400001-b5a3-f393-e0a9-e50e24dcca9e');
    characteristic = await service.getCharacteristic('6e400002-b5a3-f393-e0a9-e50e24dcca9e'); // TX Characteristic
    TOGGLE_BTN.disabled = false;
    console.log('Connected to device!');
  } catch (error) {
    console.error('Connection failed:', error);
  }
});

TOGGLE_BTN.addEventListener('click', async () => {
  const value = new Uint8Array([0x01]); // 发送 0x01 表示开灯
  await characteristic.writeValue(value);
});

// src/bluetooth/DeviceManager.js
class BluetoothDeviceManager {
  constructor(serviceUuids) {
    this.serviceUuids = serviceUuids;
    this.device = null;
    this.server = null;
    this.services = new Map();
  }

  async connect() {
    this.device = await navigator.bluetooth.requestDevice({
      filters: [{ services: this.serviceUuids }]
    });
    this.server = await this.device.gatt.connect();
    for (const uuid of this.serviceUuids) {
      const service = await this.server.getPrimaryService(uuid);
      this.services.set(uuid, service);
    }
    return this;
  }

  async getCharacteristic(serviceUuid, characteristicUuid) {
    const service = this.services.get(serviceUuid);
    if (!service) throw new Error(`Service ${serviceUuid} not found`);
    return await service.getCharacteristic(characteristicUuid);
  }

  async disconnect() {
    if (this.device?.gatt.connected) {
      this.device.gatt.disconnect();
    }
  }
}

export default BluetoothDeviceManager;

// 使用 EventEmitter 模拟状态通知
import { EventEmitter } from 'events';

class SensorDevice extends BluetoothDeviceManager {
  constructor() {
    super(['environment_sensing']);
    this.emitter = new EventEmitter();
  }

  async startMonitoring() {
    const char = await this.getCharacteristic('environment_sensing', 'temperature');
    await char.startNotifications();
    char.addEventListener('characteristicvaluechanged', (event) => {
      const value = event.target.value;
      const temp = value.getFloat32(0, true); // 小端浮点
      this.emitter.emit('temperatureUpdate', temp);
    });
  }
}

// 订阅温度变化
const sensor = new SensorDevice();
sensor.connect().then(() => sensor.startMonitoring());
sensor.emitter.on('temperatureUpdate', (temp) => {
  console.log(`Current Temp: ${temp.toFixed(2)}°C`);
});

# .github/workflows/test.yml
name: Run Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm test

const device = await navigator.bluetooth.requestDevice({
  filters: [
    { services: ['heart_rate'] },
    { namePrefix: 'SmartSensor-' }
  ],
  optionalServices: ['battery_service', 'device_information']
});

参数	类型	说明
`filters`	Array	必需条件，仅列出满足指定条件的设备
`services`	Array	设备必须广播此服务 UUID
`name` / `namePrefix`	String	匹配完整名称或前缀
`optionalServices`	Array	即使未广播也允许后续访问的服务

sequenceDiagram participant User participant Browser participant OS_BLE_Manager participant BLE_Device
User->>Browser: 点击'连接设备'
Browser->>OS_BLE_Manager: requestDevice(filters)
OS_BLE_Manager->>BLE_Device: 扫描匹配设备
BLE_Device-->>OS_BLE_Manager: 返回广播数据
OS_BLE_Manager-->>Browser: 显示候选设备列表
Browser-->>User: 弹出选择界面
User->>Browser: 选择目标设备
Browser->>OS_BLE_Manager: 请求建立连接
OS_BLE_Manager-->>Browser: 返回 BluetoothDevice 实例

// 连接到 GATT 服务器
const server = await device.gatt.connect();
console.log('GATT Server connected');

// 获取主服务（单一服务）
const service = await server.getPrimaryService('heart_rate');

// 获取多个服务（批量获取）
const [hrService, batService] = await Promise.all([
  server.getPrimaryService('heart_rate'),
  server.getPrimaryService('battery_service')
]);

// 获取特定特征值
const characteristic = await hrService.getCharacteristic('heart_rate_measurement');

操作类型	方法	是否需要通知启用	典型用途
读取当前值	`readValue()`	否	获取静态属性（如设备名）
写入指令	`writeValue()`	否	控制命令发送（开灯/关灯）
实时监听	`startNotifications()` + `addEventListener('characteristicvaluechanged')`	是	生物信号流、传感器数据推送

characteristic.addEventListener('characteristicvaluechanged', (event) => {
  const value = event.target.value;
  const decoder = new DataView(value.buffer);
  console.log('Received heart rate:', decoder.getUint8(1));
});
await characteristic.startNotifications();

// 示例：读取设备电量
async function readBatteryLevel(device) {
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('battery_service');
  const characteristic = await service.getCharacteristic('battery_level');
  const value = await characteristic.readValue(); // 返回 ArrayBuffer
  return value.getUint8(0); // 解析为无符号 8 位整数
}

// 示例：向 LED 控制特征写入开关命令
async function setLedState(device, on = true) {
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('led_service');
  const characteristic = await service.getCharacteristic('led_control');
  const command = new Uint8Array([on ? 1 : 0]);
  await characteristic.writeValue(command);
}

async function listenToAcceleration(device) {
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('custom_motion_service');
  const characteristic = await service.getCharacteristic('accel_data');
  
  // 启用通知
  await characteristic.startNotifications();
  
  // 注册监听器
  characteristic.addEventListener('characteristicvaluechanged', (e) => {
    const data = e.target.value;
    const view = new DataView(data.buffer);
    const x = view.getInt16(0, true); // 小端序
    const y = view.getInt16(2, true);
    const z = view.getInt16(4, true);
    console.log(`Accel: X=${x}, Y=${y}, Z=${z}`);
  });
}

graph TD A[Start Notifications] --> B{Device Sends Data}
B --> C[Fire 'characteristicvaluechanged' Event]
C --> D[Extract ArrayBuffer from Event]
D --> E[Parse with DataView]
E --> F[Update UI / Store Data]

function encodeMessage(tempCelsius, message) {
  const encoder = new TextEncoder();
  const textBytes = encoder.encode(message); // UTF-8 编码字符串
  
  // 总长度：2(byte for temp) + 1(len) + n(text)
  const buffer = new ArrayBuffer(3 + textBytes.length);
  const view = new DataView(buffer);
  
  view.setInt16(0, tempCelsius * 10, true); // 存储带一位小数的温度
  view.setUint8(2, textBytes.length); // 记录字符串长度
  
  const uint8View = new Uint8Array(buffer, 3); // 从偏移 3 开始写文本
  uint8View.set(textBytes);
  
  return buffer;
}

// 使用示例
const payload = encodeMessage(23.6, "Room Temp");
await uartChar.writeValue(payload);

function decodeMessage(arrayBuffer) {
  const view = new DataView(arrayBuffer);
  const tempFixed = view.getInt16(0, true) / 10; // 还原浮点温度
  const len = view.getUint8(2);
  const textBytes = new Uint8Array(arrayBuffer, 3, len);
  const decoder = new TextDecoder();
  const text = decoder.decode(textBytes);
  return { temperature: tempFixed, message: text };
}

地址偏移	小端（LE）	大端（BE）
0	0x34	0x12
1	0x12	0x34

const buffer = new ArrayBuffer(4);
const view = new DataView(buffer);

// 写入 float 3.14159，小端模式
view.setFloat32(0, Math.PI, true);

// 读取时也需指定相同字节序
const piRead = view.getFloat32(0, true); // 必须一致！

async function safeConnectToDevice() {
  try {
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ services: ['health_thermometer'] }]
    });
    const server = await device.gatt.connect();
    console.log('Connected successfully!');
    return server;
  } catch (error) {
    switch(error.name) {
      case 'NotFoundError':
        alert('未找到匹配设备，请检查是否开启并靠近。');
        break;
      case 'SecurityError':
        alert('页面未在安全上下文中运行（需要 HTTPS 或 localhost）。');
        break;
      case 'NotAllowedError':
        alert('用户拒绝了设备访问权限。');
        break;
      default:
        console.error('Unexpected error:', error);
        alert(`连接失败：${error.message}`);
    }
  }
}

错误名	触发场景	应对策略
`NotFoundError`	无匹配设备	提示重新扫描或检查设备电源
`NotAllowedError`	用户取消选择	提供引导按钮再次尝试
`NetworkError`	GATT 连接超时	显示'连接中断'并建议重试
`SecurityError`	非 HTTPS 环境	自动跳转至安全链接

let reconnectAttempts = 0;
const MAX_RETRIES = 5;

function setupDisconnectHandler(device) {
  device.addEventListener('gattserverdisconnected', async () => {
    if (reconnectAttempts < MAX_RETRIES) {
      console.warn(`Connection lost. Attempt ${++reconnectAttempts}...`);
      setTimeout(async () => {
        try {
          await device.gatt.connect();
          console.log('Reconnected!');
          reconnectAttempts = 0;
        } catch (err) {
          console.error('Reconnection failed:', err);
          setupDisconnectHandler(device); // 继续监听下次断开
        }
      }, 3000 * reconnectAttempts); // 指数退避
    } else {
      alert('多次重连失败，请手动重新连接设备。');
    }
  });
}

stateDiagram-v2
[*] --> Connected
Connected --> Disconnected: gattserverdisconnected
Disconnected --> Reconnecting: 启动定时重连
Reconnecting --> Connected: connect() success
Reconnecting --> Failed: attempts > MAX_RETRIES
Failed --> [*]: 用户干预

<!DOCTYPE html>
<html lang="zh">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <title>Web BLE 温湿度监控</title>
  <style>
    body { font-family: Arial, sans-serif; padding: 20px; }
    button { padding: 10px 15px; margin: 5px; font-size: 16px; }
    ul { list-style-type: none; padding: 0; }
    li { padding: 8px; border-bottom: 1px solid #eee; }
    .data-display { margin-top: 20px; padding: 15px; background-color: #f4f4f4; border-radius: 5px; }
    canvas { width: 100%; max-width: 600px; margin-top: 20px; }
  </style>
</head>
<body>
  <h1>智能传感器 Web 控制面板</h1>
  <!-- 扫描与连接 -->
  <button id="scanBtn">扫描 BLE 设备</button>
  <ul id="deviceList"></ul>
  <!-- 实时数据显示 -->
  <div class="data-display">
    <h3>实时传感器数据</h3>
    <p>温度：<span id="temperature">--</span> °C</p>
    <p>湿度：<span id="humidity">--</span> %</p>
  </div>
  <!-- 图表容器 -->
  <canvas id="chart"></canvas>
  <script src="app.js"></script>
</body>
</html>

document.getElementById('scanBtn').addEventListener('click', async () => {
  try {
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ services: ['environmental_sensing'] }],
      optionalServices: ['battery_service']
    });
    const listItem = document.createElement('li');
    listItem.textContent = `${device.name} (RSSI: ${device.rssi || 'N/A'})`;
    document.getElementById('deviceList').appendChild(listItem);
    
    // 连接 GATT 并开始通信...
    const server = await device.gatt.connect();
    console.log('GATT 服务器已连接:', server);
  } catch (error) {
    console.error('设备选择失败:', error);
    alert(`错误：${error.message}`);
  }
});

类型	UUID
Service UUID	`6E400001-B5A3-F393-E0A9-E50E24DCCA9E`
TX Characteristic (接收端写入)	`6E400002-B5A3-F393-E0A9-E50E24DCCA9E`
RX Characteristic (通知启用)	`6E400003-B5A3-F393-E0A9-E50E24DCCA9E`

async function connectUARTDevice() {
  const serviceUUID = '6e400001-b5a3-f393-e0a9-e50e24dcca9e';
  const txCharUUID = '6e400002-b5a3-f393-e0a9-e50e24dcca9e';
  const rxCharUUID = '6e400003-b5a3-f393-e0a9-e50e24dcca9e';
  
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ namePrefix: 'NUS' }],
    optionalServices: [serviceUUID]
  });
  
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService(serviceUUID);
  
  // 获取 TX 特征（用于发送）
  const txCharacteristic = await service.getCharacteristic(txCharUUID);
  
  // 获取 RX 特征并开启通知
  const rxCharacteristic = await service.getCharacteristic(rxCharUUID);
  await rxCharacteristic.startNotifications();
  
  rxCharacteristic.addEventListener('characteristicvaluechanged', (event) => {
    const value = event.target.value;
    const decoder = new TextDecoder();
    const text = decoder.decode(value);
    console.log('收到:', text);
    document.getElementById('receivedData').textContent += text;
  });
  
  // 示例：发送命令
  const encoder = new TextEncoder();
  const data = encoder.encode('GET_TEMP\n');
  await txCharacteristic.writeValue(data);
}

#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_BME280.h>
#include <CurieBLE.h>

Adafruit_BME280 bme;
BLEPeripheral blePeripheral;
BLEService environmentalService("181A");
BLEFloatCharacteristic tempChar("2A6E", BLERead | BLENotify);
BLEFloatCharacteristic humidChar("2A6F", BLERead | BLENotify);

void setup() {
  Serial.begin(9600);
  if (!bme.begin(0x76)) {
    while (1);
  }
  blePeripheral.setLocalName("WebSensor");
  blePeripheral.setAdvertisedServiceUuid(environmentalService.uuid());
  blePeripheral.addAttribute(environmentalService);
  blePeripheral.addAttribute(tempChar);
  blePeripheral.addAttribute(humidChar);
  blePeripheral.begin();
}

void loop() {
  float t = bme.readTemperature();
  float h = bme.readHumidity();
  tempChar.setValue(t);
  humidChar.setValue(h);
  blePeripheral.poll();
  delay(2000);
}

<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>

const ctx = document.getElementById('chart').getContext('2d');
const chart = new Chart(ctx, {
  type: 'line',
  data: {
    labels: [], // 时间戳
    datasets: [
      { label: '温度 (°C)', borderColor: 'rgb(255, 99, 132)', data: [] },
      { label: '湿度 (%)', borderColor: 'rgb(54, 162, 235)', data: [] }
    ]
  }
});

// 更新图表函数
function updateChart(temp, humi) {
  const time = new Date().toLocaleTimeString();
  chart.data.labels.push(time);
  chart.data.datasets[0].data.push(temp);
  chart.data.datasets[1].data.push(humi);
  
  // 限制数据点数量
  if (chart.data.labels.length > 10) {
    chart.data.labels.shift();
    chart.data.datasets[0].data.shift();
    chart.data.datasets[1].data.shift();
  }
  chart.update();
}

await tempChar.startNotifications();
tempChar.addEventListener('characteristicvaluechanged', (e) => {
  const temp = e.target.value.getFloat32(0, true); // 小端序
  document.getElementById('temperature').textContent = temp.toFixed(2);
  updateChart(temp, parseFloat(document.getElementById('humidity').textContent));
});

console.debug('Connection state:', device.gatt.connected);

错误信息	原因	解决方案
`SecurityError: Access to the feature is disallowed by user permission setting.`	用户未授权	确保 HTTPS、点击触发、提供说明文案
`NotFoundError: No device selected.`	过滤条件无匹配	放宽 filters，添加 `name` , `manufacturerData` 条件
`NetworkError: GATT operation failed for unknown reason.`	设备断开或忙	添加重连机制、延迟重试
`DOMException: Characteristic value length is invalid.`	ArrayBuffer 长度不符	检查 writeValue() 输入长度限制

sequenceDiagram participant User participant WebPage participant BluetoothStack participant BLEDevice
User->>WebPage: 点击'扫描'
WebPage->>BluetoothStack: requestDevice()
BluetoothStack->>User: 显示设备选择器
User->>BluetoothStack: 选择设备
BluetoothStack->>BLEDevice: 发起连接
BLEDevice-->>BluetoothStack: 返回服务列表
BluetoothStack-->>WebPage: 返回 GATT Server
WebPage->>BLEDevice: getPrimaryService + startNotifications
loop 每 2 秒
  BLEDevice->>WebPage: 推送温度/湿度数据
  WebPage->>WebPage: 更新 DOM 与图表
end

Web Bluetooth API 实战：实现网页与 BLE 设备通信

Web Bluetooth API 技术详解与实战

1. Web Bluetooth API 技术概述

2. BLE 低功耗蓝牙通信原理

2.1 蓝牙技术演进与 BLE 架构

2.1.1 经典蓝牙与低功耗蓝牙的区别

2.1.2 BLE 协议栈分层结构（PHY、LL、HCI、L2CAP、ATT、GATT）

物理层（PHY）

链路层（Link Layer, LL）

主机控制接口（HCI）

L2CAP（逻辑链路控制与适配协议）

ATT（Attribute Protocol）

GATT（Generic Attribute Profile）

2.1.3 主从设备角色与广播机制

2.2 BLE 广播与连接过程详解

2.2.1 广播包类型（Advertising PDU）与有效载荷解析

2.2.2 扫描响应与主动/被动扫描模式

2.2.3 建立连接的时序流程与参数协商

2.3 GATT 模型与数据组织方式

2.3.1 服务（Service）、特征值（Characteristic）与描述符（Descriptor）的关系

2.3.2 属性协议 ATT 的读写操作机制

2.3.3 典型 GATT 配置文件（如 Heart Rate Profile）示例

2.4 BLE 通信安全性与功耗优化

2.4.1 加密配对流程（Just Works, Passkey Entry）

2.4.2 连接间隔、从机延迟与功耗平衡策略

3. WebBluetoothAPI 存储库结构与使用指南

3.1 开源存储库的功能定位与架构设计

3.1.1 项目目录结构解析（src/, examples/, docs/）

依赖关系可视化：Mermaid 流程图

3.1.2 核心模块划分与依赖管理（package.json 分析）

参数说明与逻辑分析：

代码块解读：Vite 插件配置示例

3.2 环境搭建与快速入门实践

3.2.1 Node.js 环境配置与本地服务器部署

3.2.2 示例程序运行：点亮 BLE LED 设备

示例 HTML 页面结构：

JavaScript 控制逻辑（简化版）：

3.3 API 封装与工具类设计模式

3.3.1 蓝牙设备抽象类的设计思路

3.3.2 事件驱动模型在蓝牙通信中的应用

3.4 版本控制与贡献流程

3.4.1 Git 分支策略与 Pull Request 规范

3.4.2 单元测试与 CI/CD 集成说明

4. JavaScript 实现蓝牙数据交互

4.1 浏览器中调用 Web Bluetooth API 的编程模型

4.1.1 requestDevice() 方法的过滤条件设置

参数说明：

逻辑分析：

4.1.2 获取 GATT 服务器（getPrimaryService(s)）与特征操作

逐行解读：

特征操作方式对比表：

4.2 特征值的读取、写入与通知订阅

4.2.1 readValue() 与 writeValue() 的 ArrayBuffer 处理

参数说明：

关键点解析：

4.2.2 startNotifications() 实现实时数据监听

字段解释：

4.3 数据编码与类型转换实战

4.3.1 字符串、整数、浮点数在 DataView 中的序列化

分析：

4.3.2 处理小端与大端字节序问题

4.4 异常处理与连接状态监控

4.4.1 catch 错误捕获与用户友好的提示机制

常见错误类型对照表：

4.4.2 监听 disconnect 事件并实现自动重连逻辑

策略说明：

5. 基于 Web 的 BLE 设备控制实战

5.1 HTML 构建蓝牙应用用户界面

5.2 BLE UART 协议解析与应用集成

5.2.1 UART over BLE 的服务 UUID 定义

5.2.2 发送与接收文本消息的完整链路实现

5.3 完整项目：网页端控制智能温湿度传感器

5.3.1 使用 DHT11/BME280 传感器并通过 Arduino 发送 BLE 数据

5.3.2 网页端获取数据并绘制动态图表（Chart.js 集成）

5.4 Web 蓝牙应用调试与测试方法

5.4.1 Chrome DevTools 中的 Bluetooth 面板使用技巧

5.4.2 利用 nRF Connect 对比验证通信行为

5.4.3 跨浏览器兼容性测试与安全权限异常排查

微信扫一扫，关注极客日志

更多推荐文章