简介：本资源是一套完整的乐鑫ESP32-C3 BLE与微信小程序双向通信开发源码，面向物联网初学者及嵌入式开发者，解决硬件端BLE外设开发与小程序端低门槛无线交互的集成难题。项目涵盖Arduino框架下的ESP32-C3固件代码（.ino/.cpp/.h）、微信小程序前端代码（.wxml/.wxss/.js）、配套JSON配置、设备调试日志与多组示例（sample）、说明文档（md/readme）及部分编译中间文件（.o/.d/.bin），共713个文件，总大小32.22MB，结构完整、开箱即用。目前已有242人学习下载，适合快速搭建智能家居、健康监测等BLE+小程序原型系统。开发者可直接复用硬件控制逻辑、小程序蓝牙API调用封装、服务/特征值定义规范及跨平台通信调试方法，同时获得含注释的完整工程目录与典型场景实现（如设备发现、连接、数据收发、状态同步），显著降低BLE小程序联调门槛。
1. 用 ESP32-C3 做 BLE 设备，再让微信小程序连上它——不是“配网”也不是“扫码”，而是真正在 GATT 层双向通信
你手头有一块 ESP32-C3 开发板，想让它广播一个服务，暴露温度、开关状态或自定义控制特征；同时，你希望用户打开微信小程序，不装 App、不配 Wi-Fi、不输密码，就能实时读取传感器数据、点击按钮下发指令——这正是标题里「乐鑫 ESP32-C3 BLE（基于 Arduino 框架）和微信小程序」要解决的典型场景。它绕开了传统 IoT 的复杂配网流程，直击 BLE GATT 协议栈与小程序蓝牙 API 的衔接痛点。适合嵌入式初学者快速验证无线交互逻辑，也适合硬件产品经理做最小可行性原型（MVP）：用 Arduino IDE 写固件、用微信开发者工具调试前端，两端开发节奏完全解耦。注意，这不是模拟器跑通就完事——ESP32-C3 的 BLE 射频稳定性、Arduino Core for ESP32 的 BLE 库版本兼容性、微信小程序在 iOS/Android 上对 BLE 广播包解析差异，都会在真实连接时暴露。下文将从协议选型开始，逐层落地到可复现的编译命令、小程序 JS 接口调用链、以及三个必查的连接失败日志位置。
2. 为什么选 ESP32-C3 + Arduino 而非 ESP-IDF 或 nRF52？BLE 广播与 GATT 服务设计必须匹配小程序能力边界
2.1 选型依据：C3 的 RISC-V 核心 + 硬件 BLE 5.0 是微信小程序支持的最低可靠基线
微信小程序蓝牙 API（wx.openBluetoothAdapter→wx.startBluetoothDevicesDiscovery→wx.getConnectedBluetoothDevices）对底层 BLE 设备有明确约束：必须使用ADV_IND 广播类型（不可用 ADV_NONCONN_IND），广播包中需包含Complete Local Name和Service UUIDs（16-bit 或 128-bit），且不能依赖扫描响应包（Scan Response）传递关键服务信息——因为 iOS 微信客户端默认不主动请求 Scan Response。ESP32-C3 在 Arduino Core v2.0.11+ 中已原生支持BLEDevice::advertise()的完整广播配置，而早期 ESP32-S2 或 ESP8266 则因广播包长度限制或协议栈缺陷，常导致小程序扫描不到设备。对比 nRF52 系列，C3 的优势在于 Arduino 生态成熟：BLEDevice,BLEUtils,BLEService,BLECharacteristic四个类封装清晰，无需手动拼接 ATT PDU，且BLECharacteristic::setValue()自动触发 Notify 事件，与小程序wx.onBLEConnectionStateChange的状态机天然对齐。
提示：不要用
BLEDevice::setScanResponseData()补充服务信息。微信小程序（尤其 iOS 版本）在wx.startBluetoothDevicesDiscovery阶段仅解析广播包（Advertising Data），忽略 Scan Response。所有服务 UUID 必须塞进BLEDevice::setAdvertisingData()的advData结构体中。
2.2 定义 GATT 服务：用 128-bit UUID 避免 Android/iOS 缓存冲突，特征值权限必须显式声明
微信小程序要求每个BLECharacteristic必须明确声明PROPERTY_READ/PROPERTY_WRITE/PROPERTY_NOTIFY，否则wx.writeBLECharacteristicValue会静默失败。以下代码定义了一个标准控制服务（0x1810 Environmental Sensing Service 的简化变体），其中CONTROL_SERVICE_UUID使用 128-bit 格式生成（避免与系统预定义 UUID 冲突）：
#include <BLEDevice.h> #include <BLEUtils.h> #include <BLEServer.h> // 生成唯一 128-bit UUID：使用 https://www.uuidgenerator.net/ 生成，粘贴后去掉横线 #define CONTROL_SERVICE_UUID "0000abcd000040008000000000000000" #define CONTROL_CHAR_UUID "0000efgh000040008000000000000000" #define STATUS_CHAR_UUID "0000ijkl000040008000000000000000" void setup() { Serial.begin(115200); BLEDevice::init("ESP32-C3-LED"); // 设备名，必须与小程序 wx.startBluetoothDevicesDiscovery 的 nameFilter 匹配 BLEDevice::setEncryptionLevel(ESP_BLE_SEC_NONE); // 微信小程序不支持配对，必须设为无加密 BLEAdvertising *pAdvertising = BLEDevice::getAdvertising(); BLEDevice::setAdvertisingType(ADV_TYPE_ADV_IND); // 强制设置为可连接广播类型 // 构造广播数据：必须包含设备名 + 服务 UUID BLEAdvertisementData advData; advData.setName("ESP32-C3-LED"); advData.setUUIDList({CONTROL_SERVICE_UUID}); // 关键！服务 UUID 必须在此处声明 pAdvertising->setAdvertisingData(advData); // 创建 GATT 服务 BLEServer *pServer = BLEDevice::createServer(); BLEService *pService = pServer->createService(CONTROL_SERVICE_UUID); // 创建可写特征值（接收小程序指令） BLECharacteristic *pControlChar = pService->createCharacteristic( CONTROL_CHAR_UUID, BLECharacteristic::PROPERTY_WRITE | BLECharacteristic::PROPERTY_WRITE_NR // Write Without Response，降低延迟 ); pControlChar->setValue("0"); // 初始化值 // 创建可通知特征值（向小程序推送状态） BLECharacteristic *pStatusChar = pService->createCharacteristic( STATUS_CHAR_UUID, BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY ); pStatusChar->setValue("OFF"); pService->start(); pAdvertising->start(); Serial.println("BLE device advertising..."); }2.2.1 关键参数说明
BLEDevice::setEncryptionLevel(ESP_BLE_SEC_NONE)：微信小程序蓝牙 API 不支持配对流程，若设为ESP_BLE_SEC_UNAUTHENTICATED会导致 iOS 端连接后立即断开；advData.setUUIDList({CONTROL_SERVICE_UUID})：此行决定小程序能否发现该设备。若遗漏，wx.getConnectedBluetoothDevices()返回空数组；PROPERTY_WRITE_NR：小程序调用wx.writeBLECharacteristicValue时默认使用 Write Without Response，避免等待 ACK 增加操作延迟；pStatusChar->setValue("OFF")：初始值必须设置，否则小程序wx.readBLECharacteristicValue读取时返回空缓冲区。
2.3 Arduino IDE 环境配置：Core 版本、端口识别与上传超时的三重校验
ESP32-C3 在 Windows 上常出现「端口一会识别一会不识别」，本质是 CP210x 驱动与 USB 描述符协商失败。必须执行以下三步：
- 安装最新 CP210x 驱动（v6.10.0+）：从 Silicon Labs 官网下载，卸载旧驱动后重启；
- Arduino Core for ESP32 版本锁定为 2.0.11：在 Arduino IDE →
文件 > 首选项 > 附加开发板管理器网址中添加https://raw.githubusercontent.com/espressif/arduino-esp32/2.0.11/package_esp32_index.json，然后通过工具 > 开发板 > 开发板管理器安装对应版本（2.0.12+ 存在 BLE 广播包截断 Bug）； - 上传前强制进入下载模式：按住 BOOT 键，再按一次 RESET 键，松开 RESET 后再松开 BOOT —— 此操作可绕过 C3 的 USB CDC 自动识别不稳定问题。
注意：若仍报错
Failed to connect with ESP32: Timed out waiting for packet header，检查工具 > 端口是否显示COMx (Silicon Labs CP210x USB to UART Bridge)，而非(Standard Serial over Bluetooth link)。后者是 Windows 自动绑定的错误端口。
3. 微信小程序端：从wx.openBluetoothAdapter到wx.notifyBLECharacteristicValueChange的完整调用链与错误捕获
3.1 初始化与设备发现：nameFilter与services双重过滤是稳定连接的前提
小程序必须在app.js全局初始化蓝牙适配器，并在页面onLoad中启动设备发现。关键点在于：不能只依赖wx.getConnectedBluetoothDevices()，必须主动扫描，因为 ESP32-C3 默认不自动连接，且微信未提供「后台持续监听」能力。
// pages/index/index.js Page({ data: { connectedDeviceId: '', statusValue: 'OFF', isConnecting: false }, onLoad() { this.initBluetooth(); }, initBluetooth() { wx.openBluetoothAdapter({ success: () => { console.log('蓝牙适配器开启成功'); this.startDiscovery(); }, fail: (err) => { console.error('开启蓝牙失败', err); wx.showToast({ title: '请开启手机蓝牙', icon: 'none' }); } }); }, startDiscovery() { // nameFilter 必须与 ESP32-C3 的 BLEDevice::init("ESP32-C3-LED") 完全一致 // services 必须填入服务 UUID 字符串（128-bit 格式，小写，无横线） wx.startBluetoothDevicesDiscovery({ powerLevel: 'high', // 强制高功率扫描，提升 C3 广播包接收率 nameFilter: 'ESP32-C3-LED', services: ['0000abcd000040008000000000000000'], // 与固件中 CONTROL_SERVICE_UUID 严格对应 success: () => { console.log('开始扫描设备'); this.listenForFoundDevices(); } }); }, listenForFoundDevices() { wx.onBluetoothDeviceFound((res) => { console.log('发现设备:', res.devices); const targetDevice = res.devices.find(d => d.name === 'ESP32-C3-LED' && d.services?.includes('0000abcd000040008000000000000000') ); if (targetDevice) { this.connectToDevice(targetDevice.deviceId); } }); } });3.1.1 为什么nameFilter和services必须同时设置？
nameFilter过滤广播包中的设备名，减少无效设备数量；services过滤广播包中的 Service UUIDs 字段，避免扫描到其他 BLE 设备（如耳机、手环）；- 若只设
nameFilter，iOS 微信可能因广播包解析延迟，漏掉设备；若只设services，Android 可能匹配到同 UUID 的其他设备。
3.2 连接与特征值操作：wx.createBLEConnection后必须wx.getBLEDeviceServices+wx.getBLEDeviceCharacteristics
连接成功后，不能直接读写特征值。必须先获取服务列表，再获取特征值列表，否则wx.writeBLECharacteristicValue报错invalid characteristic。
connectToDevice(deviceId) { this.setData({ isConnecting: true }); wx.createBLEConnection({ deviceId, success: () => { console.log('连接成功'); this.setData({ connectedDeviceId: deviceId }); this.discoverServicesAndCharacteristics(deviceId); }, fail: (err) => { console.error('连接失败', err); this.setData({ isConnecting: false }); } }); }, discoverServicesAndCharacteristics(deviceId) { wx.getBLEDeviceServices({ deviceId, success: (res) => { console.log('服务列表:', res.services); const controlService = res.services.find(s => s.uuid.toLowerCase() === '0000abcd000040008000000000000000' ); if (controlService) { this.discoverCharacteristics(deviceId, controlService.uuid); } } }); }, discoverCharacteristics(deviceId, serviceUuid) { wx.getBLEDeviceCharacteristics({ deviceId, serviceId: serviceUuid, success: (res) => { console.log('特征值列表:', res.characteristics); const controlChar = res.characteristics.find(c => c.uuid.toLowerCase() === '0000efgh000040008000000000000000' ); const statusChar = res.characteristics.find(c => c.uuid.toLowerCase() === '0000ijkl000040008000000000000000' ); if (controlChar && statusChar) { this.startNotify(deviceId, serviceUuid, statusChar.uuid); this.setData({ controlChar: { deviceId, serviceId: serviceUuid, uuid: controlChar.uuid }, statusChar: { deviceId, serviceId: serviceUuid, uuid: statusChar.uuid } }); } } }); }, startNotify(deviceId, serviceId, characteristicId) { wx.notifyBLECharacteristicValueChange({ state: true, deviceId, serviceId, characteristicId, success: () => { console.log('Notify 已启用'); // 监听特征值变化 wx.onBLECharacteristicValueChange((res) => { const value = new Uint8Array(res.value); const str = String.fromCharCode(...value); this.setData({ statusValue: str }); }); } }); } });3.2.1wx.notifyBLECharacteristicValueChange的隐含前提
- 必须在
wx.getBLEDeviceCharacteristics成功后调用； characteristicId必须与固件中pStatusChar->getUUID().toString()输出的字符串完全一致（小写、无横线）；- 若固件未调用
pStatusChar->notify()，小程序不会收到任何数据——需在 ESP32-C3 代码中定时或事件触发pStatusChar->setValue("ON"); pStatusChar->notify();。
3.3 控制指令下发：wx.writeBLECharacteristicValue的 buffer 构造与 iOS 兼容性处理
小程序向 ESP32-C3 发送指令时，必须将字符串转为ArrayBuffer，且长度需与固件pControlChar->setValue()的缓冲区匹配。常见错误是直接传字符串导致 iOS 端写入失败。
sendCommand(command) { const { controlChar } = this.data; if (!controlChar) return; // 构造 ArrayBuffer：长度固定为 1 字节，内容为 '1' 或 '0' const buffer = new ArrayBuffer(1); const dataView = new DataView(buffer); dataView.setUint8(0, command === 'ON' ? 0x31 : 0x30); // ASCII '1' or '0' wx.writeBLECharacteristicValue({ deviceId: controlChar.deviceId, serviceId: controlChar.serviceId, characteristicId: controlChar.uuid, value: buffer, success: () => { console.log('指令发送成功'); }, fail: (err) => { console.error('指令发送失败', err); // 常见错误码：-1（未知错误）、10005（特征值不可写）、10007（连接已断开） if (err.errCode === 10005) { wx.showToast({ title: '设备不支持写入', icon: 'none' }); } } }); } });提示：iOS 微信对
value的 ArrayBuffer 长度极其敏感。若固件pControlChar定义为setValue("0")（长度 1），则小程序 buffer 长度必须为 1。若传入长度为 2 的 buffer，iOS 会静默丢弃。
4. 排查连接失败的三大日志源：串口输出、微信开发者工具调试器、手机系统蓝牙日志
4.1 ESP32-C3 串口日志：定位广播与连接状态机卡点
在loop()中添加状态打印，可快速判断是广播未发出，还是连接被拒绝：
void loop() { // 检查是否已有客户端连接 BLEDevice::poll(); // 必须调用，否则 notify 不生效 if (BLEDevice::getConnectedCount() > 0) { Serial.print("Connected clients: "); Serial.println(BLEDevice::getConnectedCount()); // 模拟状态更新：每 5 秒切换一次 LED 状态并通知 static unsigned long lastNotify = 0; if (millis() - lastNotify > 5000) { static bool ledOn = false; ledOn = !ledOn; pStatusChar->setValue(ledOn ? "ON" : "OFF"); pStatusChar->notify(); lastNotify = millis(); Serial.printf("Notified: %s\n", ledOn ? "ON" : "OFF"); } } else { Serial.println("No client connected"); } delay(1000); }4.1.1 关键日志含义
No client connected：小程序未发起连接，检查wx.createBLEConnection是否调用；Connected clients: 1：连接已建立，但小程序未收到 notify，检查wx.notifyBLECharacteristicValueChange是否启用；- 若串口无任何输出，说明
BLEDevice::init()失败，检查 Arduino Core 版本与 Board 设置（ESP32-C3 DevKitC-1，Flash Mode QIO，Partition Scheme Default）。
4.2 微信开发者工具调试器：抓取蓝牙 API 调用链与错误码映射
在开发者工具中打开「调试器」→「Network」→「Bluetooth」标签页，可查看每次 API 调用的完整请求/响应。重点关注：
| 错误码 | 含义 | 解决方案 |
|---|---|---|
| 10000 | 未开启蓝牙适配器 | 调用wx.openBluetoothAdapter后未等 success 回调就执行后续操作 |
| 10001 | 设备未找到 | nameFilter与固件BLEDevice::init()名称不一致，或广播包未包含 Service UUID |
| 10005 | 特征值不可写 | 固件中pControlChar未设置PROPERTY_WRITE，或小程序传入 buffer 长度不匹配 |
| 10007 | 连接已断开 | 小程序侧未监听wx.onBLEConnectionStateChange，或固件主动调用pServer->disconnect() |
注意：开发者工具的 Bluetooth 日志仅模拟 Android 行为，iOS 真机测试必须用「iPhone 设置 > 隐私与安全性 > 分析与改进 > 共享 iPhone 分析」开启日志，然后在「设置 > 蓝牙」中长按设备名查看连接详情。
4.3 手机系统级日志：Android Logcat 与 iOS Console 的交叉验证
Android 端（需开启 USB 调试）
# 过滤 BLE 相关日志 adb logcat -s BluetoothAdapter:B BluetoothDevice:B BluetoothGatt:B关注D/BluetoothGatt: connect() - device: XX:XX:XX:XX:XX:XX后是否出现onClientConnectionState() - status=0 clientIf=5（status=0 表示连接成功）。
iOS 端（需 Mac + Xcode）
- 连接 iPhone，Xcode →
Window > Devices and Simulators； - 选择设备 →
Open Console； - 过滤关键词
CBManager、CBPeripheral； - 成功连接时会出现
CBPeripheral connected，失败时显示CBPeripheral connection failed: Error Domain=CBErrorDomain Code=6（表示设备忙或拒绝连接）。
5. 优化 BLE 通信可靠性：MTU 协商、Notify 频率控制与小程序页面生命周期管理
5.1 主动协商 MTU：避免长消息被截断，提升单次传输效率
ESP32-C3 默认 MTU 为 23 字节，而微信小程序wx.writeBLECharacteristicValue最大支持 512 字节 buffer。若需传输 JSON 数据（如{ "temp": 25.3, "hum": 60 }），必须协商更大 MTU：
// 在 setup() 中连接建立后调用 class MyServerCallbacks : public BLEServerCallbacks { void onConnect(BLEServer* pServer) { Serial.println("Client connected"); // 主动请求 MTU 协商 pServer->getConnectedClient()->requestMTU(256); } void onMTUChange(uint16_t mtu) { Serial.printf("MTU changed to: %d\n", mtu); } };小程序侧无需额外操作，wx.writeBLECharacteristicValue自动适配协商后的 MTU。但注意：wx.readBLECharacteristicValue仍受限于固件pStatusChar->getValue().length()，若固件未调用pStatusChar->setValue()更新内容，读取结果为空。
5.2 Notify 频率控制：用delay(20)替代delay(1000)防止 iOS 限频
iOS 系统对 Notify 频率有严格限制（约 20Hz 上限）。若 ESP32-C3 每 100ms 调用pStatusChar->notify()，iOS 微信会丢弃部分通知。实测有效方案是：
// 在 loop() 中改为： static unsigned long lastNotify = 0; if (millis() - lastNotify > 20) { // 20ms 间隔 ≈ 50Hz，iOS 实际接受约 20~25Hz pStatusChar->notify(); lastNotify = millis(); }5.3 小程序页面生命周期管理：onHide时断开连接，onShow时重连
微信小程序切后台时，蓝牙连接可能被系统回收。必须在onHide中主动断开，并在onShow中重建：
onHide() { const { connectedDeviceId } = this.data; if (connectedDeviceId) { wx.closeBLEConnection({ deviceId: connectedDeviceId, success: () => { console.log('连接已关闭'); this.setData({ connectedDeviceId: '', statusValue: 'DISCONNECTED' }); } }); } }, onShow() { const { connectedDeviceId } = this.data; if (connectedDeviceId) { // 重新启用 Notify this.startNotify(connectedDeviceId, this.data.statusChar.serviceId, this.data.statusChar.uuid); } }此逻辑确保用户从微信聊天页返回小程序时，状态同步不中断。若省略onHide断开，再次进入时wx.createBLEConnection可能返回already connected错误，需捕获err.errCode === 10006并忽略。
本文还有配套的精品资源，点击获取
