保姆级教程：用微信小程序蓝牙API控制ESP32开发板上的LED灯（附完整代码）

从零构建微信小程序蓝牙控制ESP32智能灯控系统1. 项目概述与核心组件解析智能硬件与移动端的无缝交互已成为物联网领域的标配能力。本项目将基于微信小程序蓝牙API与ESP32开发板构建一套完整的LED灯控系统。不同于简单的功能演示我们将深入剖析每个技术环节的设计原理与实现细节。核心组件选型依据ESP32开发板集成双核处理器与蓝牙4.2/5.0双模支持性价比远超传统Arduino微信小程序无需安装即可使用的跨平台解决方案蓝牙API兼容iOS/AndroidBLE协议低功耗特性适合持续连接的物联网场景理论传输距离可达100米硬件准备清单ESP32开发板推荐ESP32-WROOM-32LED灯模块或板载LED杜邦线若干Micro USB数据线开发环境需求Arduino IDE 2.0需安装ESP32开发板支持包微信开发者工具最新稳定版智能手机支持BLE 4.0以上2. ESP32固件开发深度优化2.1 BLE服务架构设计ESP32的BLE服务采用GATT通用属性规范架构需要精确定义服务UUID和特征值。以下是通过UUID生成工具创建的标准化服务结构// UUID生成工具https://www.uuidgenerator.net/ #define SERVICE_UUID 9a9e0000-332a-11ed-aaab-002590f5c000 #define CHARACTERISTIC_UUID_RX 9a9e0001-332a-11ed-aaab-002590f5c000 #define CHARACTERISTIC_UUID_TX 9a9e0002-332a-11ed-aaab-002590f5c0002.2 增强型固件代码实现以下代码增加了错误处理和状态反馈机制#include BLEDevice.h #include BLEServer.h #include BLEUtils.h #include BLE2902.h #define LED_PIN 2 // 使用GPIO2连接LED BLEServer *pServer; BLECharacteristic *pTxCharacteristic; bool deviceConnected false; class MyServerCallbacks: public BLEServerCallbacks { void onConnect(BLEServer* pServer) { deviceConnected true; Serial.println(设备已连接); }; void onDisconnect(BLEServer* pServer) { deviceConnected false; Serial.println(设备已断开); pServer-getAdvertising()-start(); } }; class MyCallbacks: public BLECharacteristicCallbacks { void onWrite(BLECharacteristic *pCharacteristic) { std::string rxValue pCharacteristic-getValue(); if (rxValue.length() 0) { Serial.printf(收到数据: [%s]\n, rxValue.c_str()); switch(rxValue[0]) { case 1: digitalWrite(LED_PIN, HIGH); pTxCharacteristic-setValue(LED已开启); break; case 0: digitalWrite(LED_PIN, LOW); pTxCharacteristic-setValue(LED已关闭); break; default: pTxCharacteristic-setValue(无效指令); } pTxCharacteristic-notify(); } } }; void setup() { Serial.begin(115200); pinMode(LED_PIN, OUTPUT); BLEDevice::init(SmartLight-ESP32); pServer BLEDevice::createServer(); pServer-setCallbacks(new MyServerCallbacks()); BLEService *pService pServer-createService(SERVICE_UUID); pTxCharacteristic pService-createCharacteristic( CHARACTERISTIC_UUID_TX, BLECharacteristic::PROPERTY_NOTIFY ); pTxCharacteristic-addDescriptor(new BLE2902()); BLECharacteristic *pRxCharacteristic pService-createCharacteristic( CHARACTERISTIC_UUID_RX, BLECharacteristic::PROPERTY_WRITE ); pRxCharacteristic-setCallbacks(new MyCallbacks()); pService-start(); pServer-getAdvertising()-start(); Serial.println(等待客户端连接...); } void loop() { if (deviceConnected) { // 可添加定期状态推送逻辑 delay(1000); } }3. 微信小程序开发全流程3.1 项目配置与权限管理在app.json中必须声明蓝牙权限{ permission: { scope.bluetooth: { desc: 需要蓝牙权限控制智能灯具 } } }3.2 蓝牙通信核心模块创建bluetoothManager.js封装蓝牙操作const BTManager { devices: [], connectedDevice: null, serviceId: 9a9e0000-332a-11ed-aaab-002590f5c000, rxCharId: 9a9e0001-332a-11ed-aaab-002590f5c000, txCharId: 9a9e0002-332a-11ed-aaab-002590f5c000, initBluetooth() { return new Promise((resolve, reject) { wx.openBluetoothAdapter({ success: res { console.log(蓝牙适配器初始化成功); this.startDiscovery(); resolve(res); }, fail: err { console.error(蓝牙初始化失败, err); reject(err); } }); }); }, startDiscovery() { wx.startBluetoothDevicesDiscovery({ allowDuplicatesKey: false, success: res { console.log(开始搜索设备); this.onDeviceFound(); } }); }, onDeviceFound() { wx.onBluetoothDeviceFound(devices { devices.devices.forEach(device { if (device.name device.name.includes(SmartLight)) { this.devices.push(device); } }); }); }, connectDevice(deviceId) { return new Promise((resolve, reject) { wx.createBLEConnection({ deviceId, success: res { this.connectedDevice deviceId; this.getService(); resolve(res); }, fail: reject }); }); }, getService() { wx.getBLEDeviceServices({ deviceId: this.connectedDevice, success: res { res.services.forEach(service { if (service.uuid this.serviceId) { this.getCharacteristics(); } }); } }); }, getCharacteristics() { wx.getBLEDeviceCharacteristics({ deviceId: this.connectedDevice, serviceId: this.serviceId, success: res { res.characteristics.forEach(char { if (char.uuid this.txCharId char.properties.notify) { this.notifyCharacteristic(); } }); } }); }, notifyCharacteristic() { wx.notifyBLECharacteristicValueChange({ deviceId: this.connectedDevice, serviceId: this.serviceId, characteristicId: this.txCharId, state: true, }); wx.onBLECharacteristicValueChange(res { console.log(收到通知:, this.ab2hex(res.value)); }); }, writeCommand(cmd) { const buffer new ArrayBuffer(1); const dataView new DataView(buffer); dataView.setUint8(0, cmd on ? 0x31 : 0x30); // ASCII 1 or 0 wx.writeBLECharacteristicValue({ deviceId: this.connectedDevice, serviceId: this.serviceId, characteristicId: this.rxCharId, value: buffer, }); }, ab2hex(buffer) { const hexArr Array.prototype.map.call( new Uint8Array(buffer), bit (00 bit.toString(16)).slice(-2) ); return hexArr.join(); } }; export default BTManager;4. 用户界面设计与交互优化4.1 设备扫描界面view classcontainer view classheader text智能灯控系统/text button bindtapinitBluetooth初始化蓝牙/button /view view classscan-area button bindtapstartScan disabled{{isScanning}} {{isScanning ? 扫描中... : 开始扫描}} /button button bindtapstopScan停止扫描/button /view scroll-view classdevice-list scroll-y view wx:for{{devices}} wx:keydeviceId classdevice-item bindtapconnectDevice >view classcontrol-panel view classstatus text当前状态: {{lightStatus}}/text /view view classbuttons button bindtapturnOn typeprimary sizedefault开启灯光/button button bindtapturnOff typewarn sizedefault关闭灯光/button /view view classlog text操作日志:/text scroll-view scroll-y styleheight: 200px; text wx:for{{logs}} wx:keytime{{item.time}} - {{item.message}}\n/text /scroll-view /view /view5. 高级功能扩展与调试技巧5.1 蓝牙通信优化策略连接稳定性方案实现自动重连机制添加心跳包检测连接状态使用队列管理发送指令class ConnectionManager { constructor() { this.commandQueue []; this.isSending false; } addCommand(cmd) { this.commandQueue.push(cmd); this.processQueue(); } processQueue() { if (!this.isSending this.commandQueue.length 0) { this.isSending true; const cmd this.commandQueue.shift(); BTManager.writeCommand(cmd).then(() { this.isSending false; this.processQueue(); }).catch(err { console.error(命令发送失败, err); this.isSending false; setTimeout(() this.processQueue(), 1000); }); } } }5.2 常见问题排查指南问题现象可能原因解决方案搜索不到设备ESP32未正确广播检查固件是否正常运行确认服务UUID正确连接后立即断开服务特征值不匹配验证小程序和固件的UUID是否完全一致发送指令无响应特征值属性配置错误确认特征值具有write属性数据接收乱码编码格式不一致统一使用ArrayBuffer进行数据传输5.3 性能监控与调试在ESP32端添加性能统计代码void printMemoryUsage() { Serial.printf(Free heap: %d bytes\n, ESP.getFreeHeap()); Serial.printf(Minimum free heap: %d bytes\n, ESP.getMinFreeHeap()); } void setup() { // ...原有代码... printMemoryUsage(); } void loop() { static unsigned long lastPrint 0; if (millis() - lastPrint 10000) { printMemoryUsage(); lastPrint millis(); } }6. 项目进阶方向智能家居集成方案通过MQTT协议实现云端控制添加PWM调光功能实现定时任务和情景模式开发语音控制接口对接小爱同学/天猫精灵硬件扩展建议使用继电器模块控制大功率灯具添加光敏传感器实现自动亮度调节集成温湿度传感器打造环境监测系统使用RGB LED实现多彩灯光效果实际开发中发现ESP32的蓝牙堆栈偶尔会出现内存泄漏问题。建议在长时间运行的场景中定期重启蓝牙服务void restartBluetooth() { BLEDevice::deinit(); delay(1000); BLEDevice::init(SmartLight-ESP32); // 重新初始化服务和特征值... }