使用 ESP-IDF 的 XIAO ESP32-C3 iBeacon 与 BME680 传感器
在本教程中,我们将构建一个低功耗温度监测系统,使用蓝牙低功耗(BLE)以 iBeacon 格式广播环境数据。我们将使用 Seeed Studio XIAO ESP32-C3、XIAO 扩展板和 Grove BME680 环境传感器。本项目演示了如何使用 ESP-IDF(Espressif 官方开发框架)构建强大的嵌入式应用程序。
概述
我们的系统将:
- 从 BME680 传感器读取温度、湿度和压力数据
- 将这些数据打包到 BLE 广播数据包中
- 定期唤醒、进行测量、广播数据,然后返回睡眠状态以节省电池电量
系统流程图

此流程图说明了我们系统的主要操作周期,从唤醒到返回深度睡眠。
硬件要求
Seeed Studio XIAO ESP32C3 | Seeed Studio Grove Base for XIAO | Grove BME680 环境传感器 |
---|---|---|
![]() | ![]() | ![]() |
- USB Type-C 数据线
- 安装了 ESP-IDF 的计算机
软件要求
- ESP-IDF(v5.0 或更高版本)
- Git
- 项目 GitHub 仓库
步骤 1:硬件设置

-
将 BME680 传感器连接到 XIAO 扩展板:
- 将 Grove BME680 传感器连接到 XIAO 扩展板上的其中一个 I2C 端口。
- 传感器通过 I2C 通信,因此任何兼容 I2C 的 Grove 端口都可以使用。
-
将 XIAO ESP32-C3 安装到扩展板上:
- 小心对齐并将 XIAO ESP32-C3 模块插入扩展板。
- 确保引脚正确对齐,模块牢固就位。
-
连接到计算机:
- 使用 USB Type-C 数据线将 XIAO 扩展板连接到计算机。
步骤 2:设置开发环境
-
安装 ESP-IDF: 按照适用于您操作系统的官方安装说明进行操作。
对于 Linux,您可以使用:
mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh
. ./export.sh -
克隆项目仓库:
cd ~/Desktop
git clone --recurse-submodules https://github.com/Priyanshu0901/xiao_ibeacon.git
cd xiao_ibeaconcaution--recurse-submodules
标志至关重要,因为项目依赖于作为 Git 子模块包含的外部库。没有这个标志,编译将失败。如果您已经在没有子模块的情况下克隆了仓库,请运行:
git submodule update --init --recursive
步骤 3:项目结构和理解组件
该项目由三个主要组件组成:
-
BME680 传感器组件 (
sensor_t_a_h
):- 处理与 BME680 传感器的通信
- 管理传感器初始化、读取和数据处理
- 提供温度、湿度和压力数据
-
BLE 信标组件 (
ble_beacon
):- 配置 BLE 协议栈
- 创建并广播包含传感器数据的 BLE 广告
- 管理 BLE 初始化和清理
-
电源管理组件 (
power_manager
):- 处理深度睡眠功能
- 管理节能操作
- 控制唤醒源和睡眠持续时间
组件交互

此图显示了不同软件组件如何与系统的硬件元素交互。
步骤 4:理解配置
在构建之前,让我们了解关键配置:
-
主应用程序设置(在
main.c
中):ADV_TIME_MS
:BLE 广告持续时间(500ms)POLL_INTERVAL_MS
:轮询传感器的频率(150ms)TIMEOUT_MS
:等待传感器读数的最大时间(2000ms)SLEEP_TIME_MS
:测量之间的睡眠时间(约 29.3 秒)
-
传感器配置(在
components/sensor_t_a_h/Kconfig
中):menu "BME68X Configuration"
config BME68X_I2C_ADDR
hex "BME68X I2C Address"
default 0x76
help
I2C address of the BME68X sensor. Default is 0x76.
Use 0x77 if SDO pin is pulled high.
choice BME68X_INTERFACE
prompt "BME68X Interface"
default BME68X_USE_I2C
help
Select the interface to use with BME68X sensor.
config BME68X_USE_I2C
bool "I2C Interface"
config BME68X_USE_SPI
bool "SPI Interface"
endchoice
if BME68X_USE_I2C
config BME68X_I2C_PORT
int "I2C Port Number"
range 0 1
default 0
help
I2C port number for BME68X.
config BME68X_I2C_SDA_PIN
int "I2C SDA GPIO"
range 0 48
default 12
help
GPIO pin for I2C SDA.
config BME68X_I2C_SCL_PIN
int "I2C SCL GPIO"
range 0 48
default 13
help
GPIO pin for I2C SCL.
config BME68X_I2C_CLOCK_SPEED
int "I2C Clock Frequency (Hz)"
range 100000 400000
default 100000
help
I2C clock frequency for BME68X. Standard mode (100 KHz) or Fast mode (400 KHz).
endif
endmenu -
BLE 配置(在
components/ble_beacon/common.h
中): BLE 设备名称在common.h
文件中定义:#define DEVICE_NAME "Xiao_TempSensor"
修改配置参数
使用 ESP-IDF 的 menuconfig 工具
ESP-IDF 框架提供了一个强大的配置工具叫做 menuconfig,它为修改项目设置提供了基于文本的用户界面。该工具基于 Kconfig,这是 Linux 内核使用的同一配置系统。
要启动配置界面:
idf.py menuconfig
这将显示一个基于文本的用户界面,包含配置类别:
应用程序配置 --->
ESP-IDF 组件 --->
SDK 工具配置 --->
编译器选项 --->
组件配置 --->
引导加载程序配置 --->
串行烧录器配置 --->
在 menuconfig 中导航:
- 使用
↑
和↓
箭头键导航 - 按
Enter
进入子菜单 - 按
Esc
返回 - 按
Space
切换选项 - 在布尔选项上按
Y
表示 'Yes',按N
表示 'No' - 按
?
查看当前选中选项的帮助 - 按
Q
或多次按Esc
退出,然后按Y
保存更改
查找传感器配置:
- 导航到
Component config
- 向下滚动找到
BME68X Configuration
- 按
Enter
查看传感器设置
查找 BLE 配置:
- 导航到
Component config
- 找到并进入
Bluetooth
- 选择
NimBLE Options
- 在这里您可以配置各种 BLE 参数
为 BME680 配置 I2C 引脚
要为 BME680 传感器配置 I2C 引脚:
- 在 menuconfig 中,导航到:
Component config
→BME68X Configuration
- 选择
I2C SDA GPIO
来更改 SDA 引脚 - 输入 SDA 的 GPIO 编号(默认为 12,但对于带扩展板的 XIAO ESP32-C3,使用 6)
- 选择
I2C SCL GPIO
来更改 SCL 引脚 - 输入 SCL 的 GPIO 编号(默认为 13,但对于带扩展板的 XIAO ESP32-C3,使用 7)
- 如果您的传感器有不同的 I2C 地址,选择
BME68X I2C Address
并修改它
通过 menuconfig 配置 BLE 参数
虽然设备名称在代码中定义,但其他 BLE 参数可以通过 menuconfig 配置:
- 导航到:
Component config
→Bluetooth
→NimBLE Options
- 在这里您可以修改:
- 最大并发连接数
- BLE 角色(中心/外围/观察者/广播者)
- 安全设置
- GAP 和 GATT 参数
- BLE 协议栈的内存分配
高级配置选项
对于高级用户,提供了额外的配置选项:
-
电源管理:
- 导航到:
Component config
→Power Management
- 启用/禁用自动轻度睡眠
- 配置 DFS(动态频率缩放)
- 导航到:
-
Flash 加密:
- 导航到:
Security features
- 为安全部署配置 flash 加密选项
- 导航到:
-
分区表:
- 导航到:
Partition Table
- 为不同应用需求修改 flash 分区
- 导航到:
-
日志记录:
- 导航到:
Component config
→Log output
- 配置调试日志级别和输出目标
- 导航到:
进行更改后,按 Q
退出并按 Y
保存更改。然后使用以下命令重新构建项目:
idf.py build
更改 BLE 设备名称
要更改 BLE 设备名称,您需要修改 components/ble_beacon/common.h
中的 DEVICE_NAME
宏:
-
打开文件:
nano components/ble_beacon/common.h
-
找到
DEVICE_NAME
定义并将其更改为您想要的名称:#define DEVICE_NAME "MyCustomSensor"
-
保存文件并重新构建项目。
步骤 5:构建和烧录项目
-
导航到项目目录:
cd ~/Desktop/xiao_ibeacon
-
配置项目:
idf.py set-target esp32c3
idf.py menuconfig通过菜单导航检查或调整设置:
- Component Config → BME680 Sensor Settings
- Component Config → BLE Beacon Settings
- Component Config → Power Management
-
构建项目:
idf.py build
-
将项目烧录到 XIAO ESP32-C3:
idf.py -p /dev/ttyUSB0 flash
注意:您的端口可能不同(Windows:COM3、COM4 等)
-
监控输出(可选):
idf.py -p /dev/ttyUSB0 monitor
按 Ctrl+] 退出监控。
步骤 6:测试 iBeacon
-
在智能手机上下载 BLE 扫描应用:
- iOS:"LightBlue" 或 "nRF Connect"
- Android:"nRF Connect" 或 "BLE Scanner"
-
打开应用并扫描 BLE 设备:
- 查找名为 "Xiao_TempSensor" 的设备
- 选择设备以查看其广播数据
-
理解广播数据: BLE 广播包含:
- 温度(摄氏度,按 100 倍缩放)
- 湿度(百分比)
- 压力(hPa,按 10 倍缩放)
-
预期行为:
- 设备大约每 30 秒唤醒一次
- 从 BME680 传感器读取数据
- 广播此数据 500 毫秒
- 然后进入深度睡眠以节省电力
Python 测试脚本
项目包含 Python 脚本来帮助测试和验证 BLE 信标功能。让我们探索它们:
设置 Python 环境
-
导航到测试脚本目录:
cd ~/Desktop/xiao_ibeacon/test_scripts
-
运行设置脚本创建和配置虚拟环境:
# 在 Linux/macOS 上
chmod +x setup_venv.sh
./setup_venv.sh
# 在 Windows 上
setup_venv.bat -
激活虚拟环境:
# 在 Linux/macOS 上
source venv/bin/activate
# 在 Windows 上
venv\Scripts\activate
设置脚本将安装所需的包:
bleak
:用于 BLE 通信colorama
:用于彩色终端输出
使用 BLE 扫描脚本
BLE 扫描脚本(ble_beacon_scanner.py
)扫描 BLE 广播并显示来自我们信标的传感器数据。
扫描器的主要功能:
- 查找名为 "Xiao_TempSensor" 的设备
- 解码制造商特定数据以提取温度、湿度和压力
- 在格式化的终端 UI 中显示值
- 随着接收到新广播持续更新
运行扫描器:
python ble_beacon_scanner.py
脚本将显示格式良好的输出,包含最新的传感器读数:
╔═══════════════════════════════════════════════╗
║ Xiao 温度传感器信标扫描器 ║
╠═══════════════════════════════════════════════╣
║ 最后更新: 15:42:27 ║
║ 信号强度: -63 dBm ║
╠═══════════════════════════════════════════════╣
║ 温度: 23.45 °C ║
║ 湿度: 48 % ║
║ 压力: 1013.2 hPa ║
╠═══════════════════════════════════════════════╣
║ 按 Ctrl+C 退出 ║
╚═══════════════════════════════════════════════╝
如果您在脚本中通过设置 DEBUG_MODE = True
启用调试模式,您将看到有关 BLE 广播和数据解析的额外信息。
信标数据格式
信标以压缩格式传输数据,以适应 BLE 广播限制:
- 公司 ID:0x02E5(乐鑫系统)
- 温度:16 位有符号整数,按 100 缩放(除以 100 得到 °C)
- 湿度:8 位无符号整数(直接百分比值)
- 压力:16 位无符号整数,按 10 缩放(除以 10 得到 hPa)
Python 脚本解码此格式并显示实际值。
测试过程流程

步骤 7:工作原理 - 深入了解
传感器初始化和读取
BME680 传感器通过以下步骤初始化:
- I2C 配置:在适当的引脚上设置 I2C 通信(对于带扩展板的 XIAO ESP32-C3,GPIO6/GPIO7 用于 SDA/SCL)
- 传感器初始化:配置 BME680 传感器的温度、湿度、压力和气体测量设置
- 读取过程:启动测量并等待数据准备就绪
- 数据处理:将原始传感器值转换为人类可读的测量值

BLE 广播
BLE 功能的工作原理如下:
- BLE 协议栈初始化:设置 ESP32 的 BLE 协议栈
- 广播配置:配置广播参数(间隔、数据格式)
- 数据打包:获取传感器读数并将其打包到制造商特定数据中
- 广播启动/停止:控制广播时序

电源管理
电源管理系统使用 ESP32-C3 的内置睡眠功能:
- 深度睡眠配置:使用 ESP-IDF 的睡眠 API(
esp_sleep_enable_timer_wakeup()
)配置唤醒定时器 - 唤醒源:将定时器设置为唯一的唤醒源(系统将在指定持续时间后唤醒)
- 睡眠进入:在使用
esp_deep_sleep_start()
进入深度睡眠之前安全关闭活动外设 - 唤醒过程:当定时器到期时,系统执行重置并从头开始重新启动应用程序

电源管理组件(power_manager.c
)提供了一个简单的接口来处理睡眠模式:
// 初始化电源管理器
power_manager_init();
// 稍后,当需要进入睡眠时:
power_manager_enter_deep_sleep(30000); // 睡眠30秒
当设备进入深度睡眠时,功耗会急剧下降(约10-20 μA),从而实现长电池续航。设备会完全关闭,并在定时器到期时重新启动,因此任何需要保留的状态都必须存储在RTC内存或非易失性存储中。
功耗配置文件
功耗分析设置

功耗配置文件
系统具有不同的功耗使用阶段,如下面的功耗配置文件所示:

功耗阶段:
- 睡眠阶段:深度睡眠模式下约150μA(ESP32-C3 RTC控制器激活 + bme680睡眠)
- 唤醒和初始化:启动和传感器初始化期间约40mA
- 活跃BLE广播:BLE传输期间峰值约16mA
- 清理和进入睡眠:进入睡眠前资源清理期间约5mA

电池续航计算:
- 深度睡眠时的平均电流(28秒):150μA
- 活跃阶段的平均电流(2秒):约40mA
- 有效平均电流:3.92 mA(1分钟内测量)
- 使用典型的1500 mAh锂离子电池:
- 1500 mAh ÷ 3.92 mA ≈ 382小时 ≈ 15.9天
功耗优化技巧:
- 减少广播时间以最小化高电流周期
- 使用最低可行的广播功率
- 禁用未使用的外设
- 优化传感器读取过程
- 考虑延长睡眠持续时间
步骤8:自定义项目
您可以自定义项目的各个方面:
-
更改睡眠持续时间:
- 编辑
main.c
中的SLEEP_TIME_MS
来调整读取数据的频率
- 编辑
-
修改传感器设置:
- 使用
idf.py menuconfig
来更改传感器采样率、滤波器等
- 使用
-
调整BLE参数:
- 在BLE信标组件中更改设备名称或广播间隔
-
添加其他传感器:
- 扩展传感器组件以包含其他Grove传感器
添加您自己的传感器
要将不同的传感器集成到此项目中,请按照以下步骤操作:
-
创建新的传感器组件:
# 创建组件目录结构
mkdir -p components/my_new_sensor/include
touch components/my_new_sensor/CMakeLists.txt
touch components/my_new_sensor/Kconfig
touch components/my_new_sensor/my_new_sensor.c
touch components/my_new_sensor/include/my_new_sensor.h -
实现组件接口:
- 定义初始化函数
- 创建数据读取函数
- 设置任何必要的配置
示例头文件(
my_new_sensor.h
):#pragma once
#include <stdbool.h>
#include "esp_err.h"
typedef struct {
float value1;
float value2;
// Additional sensor values
} my_sensor_data_t;
/**
* @brief Initialize the sensor
* @return ESP_OK on success
*/
esp_err_t my_sensor_init(void);
/**
* @brief Read data from the sensor
* @param data Pointer to structure to store readings
* @return ESP_OK on success
*/
esp_err_t my_sensor_read(my_sensor_data_t *data); -
配置构建系统: 示例
CMakeLists.txt
:idf_component_register(
SRCS "my_new_sensor.c"
INCLUDE_DIRS "include"
REQUIRES driver
) -
更新主应用程序:
- 将您的组件添加到主应用程序的依赖项中
- 在主应用程序流程中初始化您的传感器
- 将您的传感器读数包含在 BLE 广播数据中
在
main.c
中的集成示例:#include "my_new_sensor.h"
void app_main(void) {
// Initialize other components
// ...
// Initialize your new sensor
ESP_ERROR_CHECK(my_new_sensor_init());
// Read from your sensor
my_sensor_data_t sensor_data;
ESP_ERROR_CHECK(my_sensor_read(&sensor_data));
// Modify BLE data to include your sensor readings
// ...
} -
扩展 BLE 广播数据:
- 更新 BLE 信标组件,在广播中包含您的传感器数据
- 为您的新测量值分配适当的数据类型 ID
-
更新配置:
- 在
components/my_new_sensor/Kconfig
中为您的传感器添加 Kconfig 选项 - 这允许用户通过 menuconfig 配置您的传感器
- 在
通过遵循这种结构化方法,您可以无缝集成额外的传感器,同时保持项目的模块化架构。
故障排除
重要提示
正常运行期间无串口输出
为了获得最佳的功耗效率,设备在正常运行期间不会通过串口输出调试信息。当设备处于深度睡眠模式时,LED 也不会闪烁。这是为了最小化功耗而有意设计的。
重新刷写设备
要重新刷写设备:
- 在开始刷写过程时按下 XIAO 板上的复位按钮
- 将您的刷写命令与短暂的活动期(当设备不在深度睡眠中时)同步
- 或者,按住复位按钮,启动刷写命令,然后在刷写开始时释放复位按钮
重新启用开发调试输出
在开发自己的模块或调试时,您可以重新启用串口输出:
- 运行
idf.py menuconfig
- 导航到
Component config
→Log output
- 将默认日志级别设置为
INFO
或DEBUG
- 将日志输出目标配置为
UART0
- 记住在部署前再次禁用详细日志记录以保持电池寿命
传感器未检测到
如果您遇到传感器检测问题:
-
检查连接:
- 确保 Grove 线缆正确连接到传感器和扩展板
- 验证您使用的是 I2C Grove 端口
-
I2C 地址问题:
- BME680 的默认 I2C 地址是 0x76。某些模块可能使用 0x77。
- 如果需要,在配置中编辑 I2C 地址
-
电源问题:
- 确保 XIAO 获得足够的电源
- 尝试不同的 USB 线缆或端口
BLE 未广播
如果检测不到 BLE 广播:
-
检查 BLE 扫描器应用:
- 尝试不同的 BLE 扫描器应用
- 确保您的手机上启用了蓝牙
-
监控调试输出:
- 使用
idf.py monitor
检查错误消息
- 使用
-
广播持续时间:
- 默认设置仅广播 500ms。如果您错过了,请在
main.c
中增加ADV_TIME_MS
- 默认设置仅广播 500ms。如果您错过了,请在
构建或刷写失败
如果您遇到构建或刷写问题:
-
ESP-IDF 版本:
- 确保您使用的是 ESP-IDF v5.0 或更新版本
- 在命令前运行
. $IDF_PATH/export.sh
(Linux/macOS)或%IDF_PATH%\export.bat
(Windows)
-
USB 连接:
- 验证 USB 连接稳定
- 尝试在刷写前按下 XIAO 扩展板上的复位按钮
-
端口问题:
- 使用
ls /dev/tty*
(Linux/macOS)或设备管理器(Windows)识别正确的端口 - 使用
-p
标志指定正确的端口
- 使用
结论
您现在已经构建了一个功耗高效的环境监测系统,它使用 BLE 广播温度、湿度、压力和空气质量数据。这个项目演示了几个重要概念:
- 传感器集成:在 ESP-IDF 中使用 I2C 传感器
- BLE 通信:创建和管理 BLE 广播
- 电源管理:实现深度睡眠以实现电池高效运行
- ESP-IDF 开发:使用 Espressif 官方框架进行 ESP32 开发
整体系统架构

这个基础可以扩展为创建更复杂的物联网传感器节点、环境监测系统或资产跟踪解决方案。
资源
✨ 贡献者项目
- 此项目由 Seeed Studio 贡献者项目支持。
- 特别感谢 Priyanshu Roy 的专注努力。您的工作将被展示。
技术支持与产品讨论
感谢您选择我们的产品!我们在这里为您提供不同的支持,以确保您使用我们产品的体验尽可能顺畅。我们提供多种沟通渠道,以满足不同的偏好和需求。