保姆级教程：用微信小程序蓝牙API控制ESP32板载LED（附完整源码）

从零构建微信小程序蓝牙控制ESP32 LED的完整指南

在物联网项目开发中，蓝牙低功耗（BLE）技术因其低功耗、低成本的特点，成为连接智能设备与移动应用的理想选择。本文将带领初学者一步步实现通过微信小程序控制ESP32开发板上的LED灯，涵盖从硬件配置到软件开发的完整流程。不同于简单的代码展示，本指南将深入解析每个关键步骤背后的原理，并分享实际开发中容易遇到的"坑"及其解决方案。

1. 环境准备与基础概念

在开始编码之前，我们需要准备好开发环境并理解几个核心概念。ESP32是一款集成了Wi-Fi和蓝牙功能的微控制器，而微信小程序提供了丰富的蓝牙API，两者结合可以构建各种物联网应用。

1.1 所需硬件与软件

• 硬件清单：

  • ESP32开发板（如ESP32-WROOM-32）
  • Micro USB数据线
  • LED灯及220Ω电阻（如果板载无LED）
  • 面包板和连接线（可选）

• 软件工具：

  • Arduino IDE（配置ESP32开发环境）
  • 微信开发者工具
  • 串口调试工具（如Putty或Arduino自带串口监视器）

提示：购买ESP32开发板时，建议选择带有CP2102或CH340芯片的版本，这些芯片负责USB转串口通信，驱动更容易安装。

1.2 BLE基础概念解析

理解以下BLE术语对开发至关重要：

在ESP32上，我们需要创建一个BLE服务，其中包含至少一个可写特征，用于接收来自小程序的控制指令。

2. ESP32端蓝牙服务配置

ESP32作为BLE外围设备，需要正确配置服务和特征才能与小程序通信。我们使用Arduino框架进行开发，这是最常用的ESP32开发方式之一。

2.1 基础蓝牙服务搭建

首先，在Arduino IDE中创建一个新项目，添加以下头文件：

#include <BLEDevice.h> #include <BLEServer.h> #include <BLEUtils.h> #include <BLE2902.h>

定义LED引脚和蓝牙相关变量：

#define LED_PIN 2 // 大多数ESP32开发板的板载LED连接GPIO2 BLEServer *pServer; BLEService *pService; BLECharacteristic *pCharacteristic; bool deviceConnected = false;

设置UUID（可使用在线UUID生成器创建）：

#define SERVICE_UUID "4fafc201-1fb5-459e-8fcc-c5c9c331914b" #define CHARACTERISTIC_UUID "beb5483e-36e1-4688-b7f5-ea07361b26a8"

2.2 特征回调函数实现

当小程序发送数据到ESP32时，我们需要通过回调函数处理这些数据：

class MyCallbacks: public BLECharacteristicCallbacks { void onWrite(BLECharacteristic *pCharacteristic) { std::string value = pCharacteristic->getValue(); if (value.length() > 0) { Serial.print("Received Value: "); for (int i = 0; i < value.length(); i++) { Serial.print(value[i]); } Serial.println(); // 控制LED if (value[0] == '1') { digitalWrite(LED_PIN, HIGH); Serial.println("LED ON"); } else if (value[0] == '0') { digitalWrite(LED_PIN, LOW); Serial.println("LED OFF"); } } } };

2.3 完整setup函数

在setup()函数中初始化所有组件：

void setup() { Serial.begin(115200); pinMode(LED_PIN, OUTPUT); // 创建BLE设备 BLEDevice::init("ESP32_LED_Controller"); // 设备名称 // 创建BLE服务器 pServer = BLEDevice::createServer(); // 创建BLE服务 pService = pServer->createService(SERVICE_UUID); // 创建可写特征 pCharacteristic = pService->createCharacteristic( CHARACTERISTIC_UUID, BLECharacteristic::PROPERTY_WRITE ); pCharacteristic->setCallbacks(new MyCallbacks()); // 启动服务 pService->start(); // 开始广播 BLEAdvertising *pAdvertising = BLEDevice::getAdvertising(); pAdvertising->addServiceUUID(SERVICE_UUID); pAdvertising->setScanResponse(true); pAdvertising->setMinPreferred(0x06); // 有助于iPhone连接 BLEDevice::startAdvertising(); Serial.println("等待客户端连接..."); }

3. 微信小程序端开发

微信小程序提供了丰富的蓝牙API，我们需要合理使用这些API实现与ESP32的通信。小程序开发主要分为UI界面和蓝牙逻辑两部分。

3.1 小程序页面布局

在pages/index/index.wxml中创建基本界面：

<view class="container"> <button bindtap="startSearch" type="primary">搜索设备</button> <view wx:if="{{devices.length}}" class="device-list"> <view wx:for="{{devices}}" wx:key="deviceId" class="device-item" bindtap="connectDevice" >Page({ data: { devices: [], connected: false, deviceId: '', serviceId: '', characteristicId: '' }, // 初始化蓝牙适配器 startSearch() { wx.openBluetoothAdapter({ success: (res) => { this.startDiscovery(); }, fail: (err) => { console.error('蓝牙初始化失败', err); wx.showToast({ title: '请检查蓝牙是否开启', icon: 'none' }); } }); }, // 开始搜索设备 startDiscovery() { wx.startBluetoothDevicesDiscovery({ allowDuplicatesKey: false, success: (res) => { this.onDeviceFound(); }, fail: (err) => { console.error('搜索失败', err); } }); }, // 监听发现设备事件 onDeviceFound() { wx.onBluetoothDeviceFound((res) => { const devices = res.devices.filter(device => device.name && device.name.indexOf('ESP32') !== -1 ); if (devices.length) { this.setData({ devices }); } }); }, // 连接设备 connectDevice(e) { const deviceId = e.currentTarget.dataset.deviceId; wx.createBLEConnection({ deviceId, success: (res) => { this.setData({ connected: true, deviceId }); this.getService(deviceId); }, fail: (err) => { console.error('连接失败', err); } }); }, // 获取服务 getService(deviceId) { wx.getBLEDeviceServices({ deviceId, success: (res) => { const service = res.services.find(s => s.uuid.indexOf('4fafc201') !== -1 ); if (service) { this.setData({ serviceId: service.uuid }); this.getCharacteristic(deviceId, service.uuid); } } }); }, // 获取特征 getCharacteristic(deviceId, serviceId) { wx.getBLEDeviceCharacteristics({ deviceId, serviceId, success: (res) => { const characteristic = res.characteristics.find(c => c.uuid.indexOf('beb5483e') !== -1 && c.properties.write ); if (characteristic) { this.setData({ characteristicId: characteristic.uuid }); } } }); } });

3.3 LED控制功能实现

继续在pages/index/index.js中添加LED控制方法：

{ // ...前面的代码 // 写入数据通用方法 writeValue(value) { const buffer = new ArrayBuffer(1); const dataView = new DataView(buffer); dataView.setUint8(0, value); wx.writeBLECharacteristicValue({ deviceId: this.data.deviceId, serviceId: this.data.serviceId, characteristicId: this.data.characteristicId, value: buffer, success: (res) => { console.log('写入成功', value); }, fail: (err) => { console.error('写入失败', err); } }); }, // 开灯 turnOnLED() { this.writeValue(0x31); // ASCII '1' wx.showToast({ title: '开灯指令已发送' }); }, // 关灯 turnOffLED() { this.writeValue(0x30); // ASCII '0' wx.showToast({ title: '关灯指令已发送' }); }, // 断开连接 disconnect() { wx.closeBLEConnection({ deviceId: this.data.deviceId, success: (res) => { this.setData({ connected: false }); wx.showToast({ title: '已断开连接' }); } }); } }

4. 调试技巧与常见问题解决

在实际开发过程中，开发者可能会遇到各种问题。本节将分享一些实用的调试技巧和常见问题的解决方案。

4.1 蓝牙连接问题排查

当遇到连接问题时，可以按照以下步骤排查：

1. 检查设备可见性：

   • 确保ESP32正在广播
   • 在小程序端检查是否能扫描到设备
   • 确认设备名称和UUID匹配

2. 检查服务发现：

   • 使用蓝牙调试工具（如nRF Connect）验证ESP32的服务和特征
   • 确保特征属性（读/写/通知）设置正确

3. 连接稳定性问题：

   • 在ESP32端增加连接状态回调
   • 在小程序端监听连接状态变化

// ESP32端添加连接状态回调 class MyServerCallbacks: public BLEServerCallbacks { void onConnect(BLEServer* pServer) { deviceConnected = true; Serial.println("设备已连接"); }; void onDisconnect(BLEServer* pServer) { deviceConnected = false; Serial.println("设备已断开"); // 重新开始广播以便再次连接 pServer->getAdvertising()->start(); } }; // 在setup()中设置回调 pServer->setCallbacks(new MyServerCallbacks());

4.2 数据格式处理技巧

BLE通信中的数据通常以ArrayBuffer格式传输，正确处理数据格式至关重要：

• 小程序端数据转换：

  // ArrayBuffer转字符串 function ab2str(buffer) { return String.fromCharCode.apply(null, new Uint8Array(buffer)); } // 字符串转ArrayBuffer function str2ab(str) { const buf = new ArrayBuffer(str.length); const bufView = new Uint8Array(buf); for (let i = 0; i < str.length; i++) { bufView[i] = str.charCodeAt(i); } return buf; }

• ESP32端数据解析：

  void onWrite(BLECharacteristic *pCharacteristic) { std::string value = pCharacteristic->getValue(); if (value.length() > 0) { // 直接访问第一个字节 char cmd = value[0]; // 或者转换为C字符串 const char* str = value.c_str(); // 也可以按字节处理 for (int i = 0; i < value.length(); i++) { uint8_t byte = value[i]; // 处理每个字节 } } }

4.3 性能优化建议

1. 降低广播间隔：

   // ESP32端设置广播参数 BLEAdvertising *pAdvertising = pServer->getAdvertising(); pAdvertising->setMinInterval(0x20); // 32*0.625ms = 20ms pAdvertising->setMaxInterval(0x40); // 64*0.625ms = 40ms

2. 小程序端优化搜索：

   // 只搜索特定名称的设备 wx.onBluetoothDeviceFound((res) => { const esp32Devices = res.devices.filter(device => device.name && device.name.includes('ESP32') ); this.setData({ devices: esp32Devices }); }); // 搜索5秒后自动停止 setTimeout(() => { wx.stopBluetoothDevicesDiscovery(); }, 5000);

3. 错误处理与用户反馈：

   wx.writeBLECharacteristicValue({ // ...其他参数 fail: (err) => { console.error('写入失败', err); if (err.errCode === 10004) { wx.showToast({ title: '写入失败，请检查连接', icon: 'none' }); } } });

5. 项目扩展与进阶应用

掌握了基础功能后，我们可以进一步扩展项目功能，实现更复杂的物联网应用。

5.1 多设备管理与状态同步

在实际应用中，可能需要控制多个ESP32设备或同步设备状态：

1. 多设备管理实现：

   // 在小程序端维护设备列表 data: { devices: [], connectedDevices: {} // 以deviceId为key存储连接状态 }, // 连接多个设备 connectMultiple() { this.data.devices.forEach(device => { wx.createBLEConnection({ deviceId: device.deviceId, success: (res) => { this.setData({ [`connectedDevices.${device.deviceId}`]: true }); } }); }); }

2. ESP32端状态上报：

   // 添加可读特征用于状态上报 BLECharacteristic *pStatusCharacteristic = pService->createCharacteristic( STATUS_UUID, BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY ); // 定期上报状态 void loop() { if (deviceConnected) { uint8_t status = digitalRead(LED_PIN); pStatusCharacteristic->setValue(&status, 1); pStatusCharacteristic->notify(); delay(1000); } }

5.2 安全增强与数据加密

对于实际应用场景，安全性是不可忽视的重要因素：

1. 配对与绑定：

   // ESP32端设置安全模式 BLESecurity *pSecurity = new BLESecurity(); pSecurity->setAuthenticationMode(ESP_LE_AUTH_REQ_SC_BOND);

2. 数据加密传输：

   // 小程序端加密数据 function encryptData(data, key) { // 实现简单的XOR加密 const encrypted = new Uint8Array(data.length); for (let i = 0; i < data.length; i++) { encrypted[i] = data[i] ^ key.charCodeAt(i % key.length); } return encrypted.buffer; } // 发送加密数据 const encrypted = encryptData(new Uint8Array([0x31]), 'secret'); wx.writeBLECharacteristicValue({ // ...其他参数 value: encrypted });

5.3 云端集成与远程控制

将设备接入云端可以实现远程控制功能：

1. 微信小程序云开发：

   // 使用云函数中转控制指令 wx.cloud.callFunction({ name: 'controlDevice', data: { deviceId: 'esp32-001', command: 'on' }, success: (res) => { console.log('云端指令发送成功'); } });

2. ESP32端实现MQTT客户端：

   #include <WiFi.h> #include <PubSubClient.h> WiFiClient espClient; PubSubClient client(espClient); void callback(char* topic, byte* payload, unsigned int length) { if (strcmp(topic, "home/led") == 0) { if (payload[0] == '1') { digitalWrite(LED_PIN, HIGH); } else { digitalWrite(LED_PIN, LOW); } } } void setup() { // ...蓝牙初始化代码 // 连接WiFi WiFi.begin("SSID", "password"); // 设置MQTT client.setServer("mqtt.server.com", 1883); client.setCallback(callback); } void loop() { if (!client.connected()) { reconnect(); } client.loop(); // ...蓝牙处理代码 }

在实际项目中，我发现最常遇到的问题是小程序端无法发现ESP32设备，这通常是由于UUID不匹配或蓝牙广播参数设置不当造成的。使用专业的蓝牙调试工具检查ESP32的广播数据包，可以快速定位问题所在。