ESP32 BLE实战：手把手教你用Web蓝牙API控制智能旋钮（附完整代码）

ESP32 BLE实战手把手教你用Web蓝牙API控制智能旋钮附完整代码在智能家居和物联网设备快速普及的今天蓝牙低功耗BLE技术因其低功耗、低成本的优势成为连接智能设备的首选方案之一。ESP32作为一款集成了Wi-Fi和蓝牙双模通信的微控制器凭借其出色的性能和丰富的开发资源成为物联网开发者的热门选择。本文将带你从零开始实现一个基于ESP32的BLE智能旋钮并通过Web Bluetooth API在浏览器中直接控制无需安装任何APP。1. BLE基础与项目架构设计蓝牙低功耗BLE通信中设备分为服务器Server和客户端Client两种角色。在我们的智能旋钮项目中ESP32作为服务器端负责广播服务和传输旋钮数据浏览器作为客户端通过Web Bluetooth API发现并连接ESP32实现数据的读写交互。GATT协议是BLE通信的核心它定义了数据的组织方式服务Service代表设备提供的功能集合如电池服务、设备信息服务等特性Characteristic服务中的具体数据点包含实际值和操作权限描述符Descriptor提供特性的额外元信息智能旋钮的BLE服务设计如下表组件UUID权限描述主服务4fafc201-1fb5-459e-8fcc-c5c9c331914b-包含旋钮和按钮特性旋钮特性beb5483e-36e1-4688-b7f5-ea07361b26a8读/写/通知传输旋钮旋转值按钮特性cba1d466-344c-4be3-ab3f-189f80dd7518读/写/通知传输按钮按压状态2. ESP32 BLE服务器实现2.1 硬件准备与开发环境搭建所需硬件组件ESP32开发板如ESP32-WROOM-32旋转编码器EC11或类似型号两个轻触开关10kΩ电阻若干面包板和连接线开发环境配置步骤安装Arduino IDE1.8.x或更高版本添加ESP32开发板支持# 在Arduino首选项中添加开发板管理器URL https://dl.espressif.com/dl/package_esp32_index.json安装ESP32开发板包通过开发板管理器安装BLE库在库管理器中搜索ESP32 BLE Arduino并安装2.2 BLE服务端完整代码实现以下是ESP32端的完整代码实现了包含旋钮和按钮特性的BLE服务#include BLEDevice.h #include BLEUtils.h #include BLEServer.h #define SERVICE_UUID 4fafc201-1fb5-459e-8fcc-c5c9c331914b #define KNOB_CHAR_UUID beb5483e-36e1-4688-b7f5-ea07361b26a8 #define BUTTON_CHAR_UUID cba1d466-344c-4be3-ab3f-189f80dd7518 // 引脚定义 const int encoderPinA 34; const int encoderPinB 35; const int button1Pin 32; const int button2Pin 33; // 全局变量 int encoderPos 0; int button1State 0; int button2State 0; bool deviceConnected false; // BLE特性定义 BLECharacteristic *pKnobCharacteristic; BLECharacteristic *pButtonCharacteristic; class MyServerCallbacks: public BLEServerCallbacks { void onConnect(BLEServer* pServer) { deviceConnected true; Serial.println(Device connected); } void onDisconnect(BLEServer* pServer) { deviceConnected false; Serial.println(Device disconnected); // 断开后重新开始广播 pServer-startAdvertising(); } }; void setup() { Serial.begin(115200); // 初始化GPIO pinMode(encoderPinA, INPUT); pinMode(encoderPinB, INPUT); pinMode(button1Pin, INPUT_PULLUP); pinMode(button2Pin, INPUT_PULLUP); // 创建BLE设备 BLEDevice::init(SmartKnob); BLEServer *pServer BLEDevice::createServer(); pServer-setCallbacks(new MyServerCallbacks()); // 创建BLE服务 BLEService *pService pServer-createService(SERVICE_UUID); // 添加旋钮特性 pKnobCharacteristic pService-createCharacteristic( KNOB_CHAR_UUID, BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY ); pKnobCharacteristic-setValue(0); // 添加按钮特性 pButtonCharacteristic pService-createCharacteristic( BUTTON_CHAR_UUID, BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY ); pButtonCharacteristic-setValue(0,0); // 启动服务 pService-start(); // 开始广播 BLEAdvertising *pAdvertising BLEDevice::getAdvertising(); pAdvertising-addServiceUUID(SERVICE_UUID); pAdvertising-setScanResponse(true); pAdvertising-setMinPreferred(0x06); BLEDevice::startAdvertising(); Serial.println(Waiting for a client connection...); } void loop() { // 读取旋钮状态 static int lastEncoderPos 0; int a digitalRead(encoderPinA); int b digitalRead(encoderPinB); // 此处添加旋钮解码逻辑... // 读取按钮状态 int newButton1State digitalRead(button1Pin); int newButton2State digitalRead(button2Pin); // 如果状态变化且设备已连接更新BLE特性 if (deviceConnected (encoderPos ! lastEncoderPos || newButton1State ! button1State || newButton2State ! button2State)) { // 更新旋钮值 char knobStr[16]; sprintf(knobStr, %d, encoderPos); pKnobCharacteristic-setValue(knobStr); pKnobCharacteristic-notify(); // 更新按钮状态 char buttonStr[16]; sprintf(buttonStr, %d,%d, newButton1State LOW ? 1 : 0, newButton2State LOW ? 1 : 0); pButtonCharacteristic-setValue(buttonStr); pButtonCharacteristic-notify(); lastEncoderPos encoderPos; button1State newButton1State; button2State newButton2State; } delay(10); }提示在实际项目中建议为旋钮编码器添加去抖动处理并在loop()中实现更精确的旋转检测算法。3. Web蓝牙客户端开发3.1 Web Bluetooth API基础Web Bluetooth API允许网页与附近的BLE设备通信主要接口包括navigator.bluetooth.requestDevice()请求连接设备device.gatt.connect()连接GATT服务器server.getPrimaryService()获取服务service.getCharacteristic()获取特性characteristic.readValue()/writeValue()读写数据characteristic.startNotifications()启用通知3.2 完整网页控制界面实现以下HTML代码实现了完整的Web控制界面包含设备连接、数据读取和实时通知功能!DOCTYPE html html head title智能旋钮控制器/title style body { font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; } .control-panel { border: 1px solid #ddd; padding: 20px; border-radius: 8px; } .status { margin: 15px 0; padding: 10px; background: #f5f5f5; border-radius: 4px; } button { padding: 10px 15px; background: #4285f4; color: white; border: none; border-radius: 4px; cursor: pointer; } button:disabled { background: #cccccc; } .knob-value { font-size: 24px; font-weight: bold; text-align: center; margin: 20px 0; } .button-state { display: flex; justify-content: space-around; margin: 20px 0; } .button { padding: 10px; border: 1px solid #ddd; border-radius: 4px; text-align: center; } .active { background: #4285f4; color: white; } /style /head body h1智能旋钮控制器/h1 div classcontrol-panel button idconnectBtn连接设备/button div classstatus idconnectionStatus未连接/div h3旋钮值/h3 div classknob-value idknobValue--/div h3按钮状态/h3 div classbutton-state div classbutton idbutton1按钮1: 未按下/div div classbutton idbutton2按钮2: 未按下/div /div /div script let bluetoothDevice; let knobCharacteristic; let buttonCharacteristic; document.getElementById(connectBtn).addEventListener(click, connectToDevice); async function connectToDevice() { try { console.log(Requesting Bluetooth Device...); bluetoothDevice await navigator.bluetooth.requestDevice({ filters: [{ name: SmartKnob }], optionalServices: [SERVICE_UUID] }); document.getElementById(connectionStatus).textContent 连接中...; console.log(Connecting to GATT Server...); const server await bluetoothDevice.gatt.connect(); document.getElementById(connectionStatus).textContent 已连接: bluetoothDevice.name; console.log(Getting Service...); const service await server.getPrimaryService(SERVICE_UUID); console.log(Getting Characteristics...); knobCharacteristic await service.getCharacteristic(KNOB_CHAR_UUID); buttonCharacteristic await service.getCharacteristic(BUTTON_CHAR_UUID); // 设置旋钮值变化通知 knobCharacteristic.addEventListener(characteristicvaluechanged, event { const value new TextDecoder().decode(event.target.value); document.getElementById(knobValue).textContent value; }); await knobCharacteristic.startNotifications(); // 设置按钮状态变化通知 buttonCharacteristic.addEventListener(characteristicvaluechanged, event { const value new TextDecoder().decode(event.target.value); const [btn1, btn2] value.split(,); const button1Element document.getElementById(button1); const button2Element document.getElementById(button2); button1Element.textContent 按钮1: ${btn1 1 ? 已按下 : 未按下}; button2Element.textContent 按钮2: ${btn2 1 ? 已按下 : 未按下}; button1Element.classList.toggle(active, btn1 1); button2Element.classList.toggle(active, btn2 1); }); await buttonCharacteristic.startNotifications(); // 读取初始值 const knobValue await knobCharacteristic.readValue(); document.getElementById(knobValue).textContent new TextDecoder().decode(knobValue); const buttonValue await buttonCharacteristic.readValue(); const [btn1, btn2] new TextDecoder().decode(buttonValue).split(,); const button1Element document.getElementById(button1); const button2Element document.getElementById(button2); button1Element.textContent 按钮1: ${btn1 1 ? 已按下 : 未按下}; button2Element.textContent 按钮2: ${btn2 1 ? 已按下 : 未按下}; button1Element.classList.toggle(active, btn1 1); button2Element.classList.toggle(active, btn2 1); // 处理设备断开连接 bluetoothDevice.addEventListener(gattserverdisconnected, onDisconnected); } catch(error) { console.error(Error:, error); document.getElementById(connectionStatus).textContent 连接失败: error.message; } } function onDisconnected() { console.log(Device disconnected); document.getElementById(connectionStatus).textContent 设备已断开; document.getElementById(knobValue).textContent --; document.getElementById(button1).textContent 按钮1: 未连接; document.getElementById(button2).textContent 按钮2: 未连接; document.getElementById(button1).classList.remove(active); document.getElementById(button2).classList.remove(active); } // 定义UUID常量 const SERVICE_UUID 4fafc201-1fb5-459e-8fcc-c5c9c331914b; const KNOB_CHAR_UUID beb5483e-36e1-4688-b7f5-ea07361b26a8; const BUTTON_CHAR_UUID cba1d466-344c-4be3-ab3f-189f80dd7518; /script /body /html4. 常见问题与优化策略4.1 连接稳定性问题解决方案在实际测试中可能会遇到以下连接问题设备无法被发现确保ESP32正在广播调用startAdvertising()检查设备名称是否匹配在Web Bluetooth的requestDevice()中添加optionalServices频繁断开连接实现自动重连机制bluetoothDevice.addEventListener(gattserverdisconnected, () { console.log(尝试重新连接...); setTimeout(connectToDevice, 1000); });在ESP32端增加断开检测和重新广播if (!deviceConnected oldDeviceConnected) { delay(500); // 等待连接完全断开 pServer-startAdvertising(); oldDeviceConnected deviceConnected; }通知丢失问题合并多个特性值到一个特性中传输增加数据校验和重传机制降低通知发送频率适当增加delay4.2 性能优化技巧数据格式优化使用二进制格式代替字符串传输uint8_t buffer[5]; buffer[0] encoderPos 0xFF; buffer[1] (encoderPos 8) 0xFF; buffer[2] button1State; buffer[3] button2State; pCombinedCharacteristic-setValue(buffer, 4);电源管理调整广播间隔pAdvertising-setMinPreferred(0x12); // 降低广播频率无连接时进入低功耗模式Web端优化添加连接状态指示器实现数据变化平滑过渡动画添加本地存储保存设备配对信息4.3 扩展功能实现基于现有框架可以轻松扩展更多功能多设备控制// 同时连接多个ESP32设备 const devices await Promise.all([ navigator.bluetooth.requestDevice({ filters: [{ name: SmartKnob-1 }] }), navigator.bluetooth.requestDevice({ filters: [{ name: SmartKnob-2 }] }) ]);数据记录与分析const knobHistory []; knobCharacteristic.addEventListener(characteristicvaluechanged, event { const value parseFloat(new TextDecoder().decode(event.target.value)); knobHistory.push({ timestamp: Date.now(), value }); // 绘制历史曲线图... });远程控制通过WebSocket将BLE数据转发到云端实现多用户协同控制在实际项目中我发现将ESP32的BLE广播间隔设置为100ms左右0x06能在连接速度和功耗间取得良好平衡。对于需要频繁更新数据的场景建议使用单个特性传输多个参数这比多个特性分别通知更可靠。