最近更新于 2026-07-26 17:16

测试环境

• ESP32-WROOM-32
• PlatformIO IDE 3.3.4
• PlatformIO Core 6.1.19
• pioarduino platform-espressif32 55.03.311（Arduino Release v3.3.11 based on ESP-IDF v5.5.5）

platformio.ini

[env:esp32dev]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip
board = esp32dev
framework = arduino
monitor_speed = 115200

实践

源码参考来源：https://github.com/espressif/arduino-esp32/blob/3.3.11/libraries/BLE/examples/Scan/Scan.ino

#include <Arduino.h>
#include <BLEDevice.h>           // BLE 核心库，提供初始化和设备管理功能
#include <BLEUtils.h>            // BLE 工具类，包含通用辅助函数
#include <BLEScan.h>             // BLE 扫描管理类
#include <BLEAdvertisedDevice.h> // BLE 广播设备类，用于解析扫描到的设备信息

// 单次 BLE 扫描的持续时间（单位：秒）
int scanTime = 5;
// 指向 BLE 扫描对象的指针
BLEScan *pBLEScan;

/**
 * @brief 自定义回调类，继承自 BLEAdvertisedDeviceCallbacks
 * @details 每当 ESP32 扫描到一个新的 BLE 广播设备时，就会自动触发该类中的回调函数
 */
class MyAdvertisedDeviceCallbacks : public BLEAdvertisedDeviceCallbacks
{
    /**
     * @brief 当扫描到设备时的回调函数
     * @param advertisedDevice 扫描到的 BLE 设备对象（包含 RSSI、广播名称、MAC 地址等信息）
     */
    void onResult(BLEAdvertisedDevice advertisedDevice)
    {
        // 将设备的所有广播属性格式化为字符串，并通过串口打印输出
        Serial.printf("广播设备：%s \n", advertisedDevice.toString().c_str());
    }
};

void setup()
{
    Serial.begin(115200);
    Serial.println("扫描中...");

    // 初始化 ESP32 的 BLE 设备，传入参数为空字符串表示不设置默认的广播名称
    BLEDevice::init("");

    // 获取 BLE 扫描单例对象的指针
    pBLEScan = BLEDevice::getScan();

    // 注册回调函数：实例化自定义回调类并绑定到扫描器，用于处理接收到的广播数据包
    pBLEScan->setAdvertisedDeviceCallbacks(new MyAdvertisedDeviceCallbacks());

    // 设置为主动扫描 (Active Scan) 模式：
    //    - true (主动扫描)：ESP32 会向广播设备发送扫描请求 (Scan Request) 以获取更多详细数据（如完整设备名），功耗稍高但信息更全
    //    - false (被动扫描)：仅静默接收设备发出的广播包，功耗低
    pBLEScan->setActiveScan(true);

    // 设置 BLE 扫描间隔 (Scan Interval) 和扫描窗口 (Scan Window)
    //    单位为毫秒 (ms)，此处 interval=100ms, window=99ms 表示每 100ms 里面有 99ms 在积极接收信号
    pBLEScan->setInterval(100);
    pBLEScan->setWindow(99); // 窗口时间必须小于或等于间隔时间
}

void loop()
{
    // 主循环体：重复执行 BLE 扫描

    // 启动 BLE 扫描：
    //    - 第一个参数 scanTime：扫描持续时间（秒）
    //    - 第二个参数 is_continual：设置为 false 表示扫描指定时间后停止；若为 true 则开启不间断持续扫描
    //    - 返回值：包含所有扫描到的设备信息的指针
    BLEScanResults *foundDevices = pBLEScan->start(scanTime, false);

    // 打印本次扫描到的设备总数
    Serial.print("发现设备数量：");
    Serial.println(foundDevices->getCount());
    Serial.println("扫描完成！");

    // 清空 BLE 扫描器缓冲区中的缓存数据，释放内存，防止长时间运行导致内存泄漏
    pBLEScan->clearResults();

    // 延迟 2 秒后开始下一轮扫描
    delay(2000);
}