先区分I2C地址和芯片身份
BME280提供温度、气压与湿度;BMP280没有湿度。二者可能都在0x76/0x77应答,扫描到地址不能决定驱动,更不能以PCB颜色、价格或卖家简称确认芯片。
Bosch手册给出只读标识寄存器0xD0:BME280为0x60,量产BMP280为0x58;BME手册还列出0x56/0x57为BMP样品标识,当前锁定驱动不接受它们。ID异常时保留日志并核对来源,不随意修改库里的校验常量。
本篇主例限定Adafruit PID2652 BME280,替代限定PID2651 BMP280。芯片ID支持型号判断,但不独立证明模块稳压、引脚、电平和真伪全部正确;供电仍先按具体模块资料核对。
参考:[3] Adafruit BME280 PID2652:端子、电平与默认地址[4] Bosch BME280手册:首页rev1.24,0xD0与BMP差异表[5] Bosch BMP280手册rev1.26:0xD0=0x58[6] ESPHome2026.9.1:BME280校验ID、补偿与读取失败[7] ESPHome2026.9.1:BMP280校验0x58与两项测量[8] Adafruit BMP280 PID2651:接线与地址
把模块模式与地址也写到接线表
PID2652的VIN接3V3,GND共地,SDI/SDA接GPIO8,SCK/SCL接GPIO9。该模块厂家I2C说明让其余脚留空;默认0x77,如按说明把SDO接GND或闭合地址跳线,地址改为0x76,代码的probe与驱动两处都要同步修改。
不要把本板默认状态套给裸BME280或未知模块;其他板的CSB拉法、上拉与电平可能不同。先断电接线,只留一只模块,使用桥接USB供电。本例没有5V信号、电池直接采样或高功率负载。
| DevKitC-1 v1.1 | PID2652 | 用途 |
|---|---|---|
| 3V3 | VIN | 本例3.3V域 |
| GND | GND | 公共参考 |
| GPIO8/J1-12 | SDI / SDA | I2C数据 |
| GPIO9/J1-15 | SCK / SCL | I2C时钟 |
| 其余 | 按厂家I2C说明留空 | 默认0x77;地址变化须记录 |
参考:[2] DevKitC-1 v1.1固定文档提交927ed7e:排针、电源与USB[3] Adafruit BME280 PID2652:端子、电平与默认地址[8] Adafruit BMP280 PID2651:接线与地址[12] Adafruit BMP280官方库2.6.8:默认0x77、替代0x76和ID0x58
完整主例:独立读ID,再交给BME驱动
按下载README安装Python3.12.13/ESPHome2026.9.1、创建私有secrets后先config再compile。完整配置的i2c_device独立于测量驱动,每10秒只读0xD0并报告Chip identity;即使BME驱动因错误型号failed,也能保留鉴别路径。
BME280驱动自己再次检查0x60,读取芯片补偿数据后给出°C、hPa、%RH。示例用10秒周期、各1x过采样、IIR关闭作为可解释起点;不把厂商补偿算法称为本站与标准仪器做过校准。
数值35秒没有新样本会变NaN,Data valid随之false。读命令或数据失败不会继续发布一条看似新的旧温湿度。芯片不存在时ID报告read-error,冷启动failed的组件恢复后需RESET。
esphome:
name: esp32-bme280
friendly_name: ESP32 BME280
min_version: 2026.9.1
on_boot:
priority: -100
then:
- logger.log: "S02-A booted; inspect real device logs"
esp32:
board: esp32-s3-devkitc-1
variant: ESP32S3
flash_size: 8MB
flash_mode: qio
flash_frequency: 80MHz
toolchain: esp-idf
framework:
type: esp-idf
version: 5.5.5
psram:
mode: octal
speed: 80MHz
logger:
baud_rate: 115200
hardware_uart: UART0
level: DEBUG
api:
encryption:
key: !secret api_key
reboot_timeout: 0s
ota:
- platform: esphome
encryption:
key: !secret api_key
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
reboot_timeout: 0s
ap:
ssid: "esp32-bme280 Recovery"
password: !secret fallback_password
ap_timeout: 90s
captive_portal:
i2c:
id: sensor_bus
sda: GPIO8
scl: GPIO9
frequency: 100kHz
scan: true
timeout: 10ms
# This probe is independent of the BME280 driver, so a wrong chip can still be identified.
i2c_device:
id: chip_probe
i2c_id: sensor_bus
address: 0x77
text_sensor:
- platform: template
id: chip_identity
name: "Chip identity"
update_interval: never
interval:
- interval: 10s
then:
- lambda: |-
uint8_t chip_id = 0;
if (!id(chip_probe).read_byte(0xD0, &chip_id)) {
id(chip_identity).publish_state("read-error");
ESP_LOGW("chip_id", "Cannot read register 0xD0 at 0x77");
return;
}
char result[5];
snprintf(result, sizeof(result), "0x%02X", chip_id);
id(chip_identity).publish_state(result);
ESP_LOGI("chip_id", "0xD0=%s; BME280 expects 0x60, BMP280 commonly 0x58", result);
sensor:
- platform: bme280_i2c
id: room_bme280
i2c_id: sensor_bus
address: 0x77
update_interval: 10s
iir_filter: "OFF"
temperature:
id: bme_temperature
name: "Temperature"
oversampling: 1x
filters:
- timeout: 35s
pressure:
id: bme_pressure
name: "Pressure"
oversampling: 1x
filters:
- timeout: 35s
humidity:
id: bme_humidity
name: "Humidity"
oversampling: 1x
filters:
- timeout: 35s
binary_sensor:
- platform: template
name: "Data valid"
lambda: |-
return id(bme_temperature).has_state() && std::isfinite(id(bme_temperature).state)
&& id(bme_pressure).has_state() && std::isfinite(id(bme_pressure).state)
&& id(bme_humidity).has_state() && std::isfinite(id(bme_humidity).state);
参考:[1] ESPHome2026.9.1固定发布与源码[4] Bosch BME280手册:首页rev1.24,0xD0与BMP差异表[6] ESPHome2026.9.1:BME280校验ID、补偿与读取失败[9] ESPHome2026.9.1:timeout过滤器实际NaN失效逻辑
读到0x58时,有一份完整的两项替代固件
若实际确认为Adafruit PID2651 BMP280,下载包提供完整bmp280-alternative.yaml,使用bmp280_i2c,只输出温度和气压。先核对该模块厂家资料与0x77地址,再用相同config、compile、run流程写入替代文件。不是把主例里的BME280文字改成BMP280就结束。
替代配置仍有ID诊断、35秒超时和Data valid,但不包含humidity。需要湿度时应补上真实湿度传感器或更换正确器件,不能保留一个固定0或旧湿度实体。HA里旧设备留下的湿度实体也需标明不再提供,不让它看起来仍在测量。
若手上是未知来源的同名模块,先断电补齐型号、电平与地址依据,再决定是否可采用这个替代;本文的构建范围不等于已经在所有BMP280板实测。
.venv/bin/esphome config bmp280-alternative.yaml
.venv/bin/esphome compile bmp280-alternative.yaml
.venv/bin/esphome run bmp280-alternative.yaml --device PORT参考:[5] Bosch BMP280手册rev1.26:0xD0=0x58[7] ESPHome2026.9.1:BMP280校验0x58与两项测量[8] Adafruit BMP280 PID2651:接线与地址[12] Adafruit BMP280官方库2.6.8:默认0x77、替代0x76和ID0x58
让HA实体不可用,别把绝对气压叫精确海拔
按真实entity_id修改home-assistant-template.yaml并合并HA现有template列表。availability要求Data valid为on且数值源有效,包装实体在断线超时后成为unavailable;源NaN本身在HA是unknown,API掉线则是另一种不可用来源。
主例三个单位为°C、hPa和%RH;1hPa=100Pa,不能拿Pa数值直接贴hPa单位。本例发布所在地绝对气压,天气和海拔都会影响它。没有匹配的海平面参考与校准,标准大气换算不能成为精确实测海拔,所以本例不发布高度实体。
温度还受模块自热、主控热源与摆放影响。比较准确度需要记录仪表与环境;本篇没有实测误差、精度或长期稳定性数据。BMP替代的HA模板只能保留两个实际测量项,完整替代模板也在下载中提供。
参考:[4] Bosch BME280手册:首页rev1.24,0xD0与BMP差异表[5] Bosch BMP280手册rev1.26:0xD0=0x58[6] ESPHome2026.9.1:BME280校验ID、补偿与读取失败[9] ESPHome2026.9.1:timeout过滤器实际NaN失效逻辑[10] Home Assistant:Template availability和数值状态[11] HA Core2026.10.2:ESPHome集成源码
按ID、单位、断线和恢复逐项验收
正常时保存0xD0实际值、扫描地址、固件标记和三项单位;观测Data valid与HA包装状态。随后重启HA,检查设备仍工作、API重连和状态恢复,不能只看供电灯。
运行中失去样本的场景要先断电,在BME/BMP单模块SDA信号支路预装低压SPST开关;保持VIN/GND/SCL连接。重新上电取得有效样本后,记录最后有效时刻,再只操作开关断开SDA,不带电拔电源或挪杜邦线。ID应转read-error;最后有效样本之后约35秒数值失效、valid=false、HA包装实体unavailable,逐项记录真实时刻与状态。闭合开关后观察新的有限测量与包装恢复,必要时RESET重新初始化。
冷启动缺模块单独测试:断电移除SDA再上电,ID读失败且无有效测量,valid=false,包装实体应不可用;冷启动failed的组件恢复接线后须RESET。恢复时断电接回、RESET,再复核芯片ID、有限数值、valid和HA包装实体。observations.csv保持空白,等待你填实际结果。
读不到ID先查VIN/GND、SDI/SCK、0x76/0x77与模式;读到0x58却BME驱动报Wrong chip ID时换正确的完整替代配置,不先重装随机库。本站没有HA或实板运行结果,当前只报告真实config/固件构建与来源检查。
- 做到这里,你应该看到
- 实际ID、正确单位、断线不可用与恢复后的正常值分别留证;未知项仍写未测。
参考:[3] Adafruit BME280 PID2652:端子、电平与默认地址[4] Bosch BME280手册:首页rev1.24,0xD0与BMP差异表[5] Bosch BMP280手册rev1.26:0xD0=0x58[6] ESPHome2026.9.1:BME280校验ID、补偿与读取失败[7] ESPHome2026.9.1:BMP280校验0x58与两项测量[8] Adafruit BMP280 PID2651:接线与地址[9] ESPHome2026.9.1:timeout过滤器实际NaN失效逻辑[10] Home Assistant:Template availability和数值状态[11] HA Core2026.10.2:ESPHome集成源码
资料来源与版本说明
本文依据下列官方文档与上游资料独立整理,适用范围与版本以本文所列组合为准。资料核对日期:。资料核对、程序构建与实板测试分别记录,不互相替代。
- ESPHome2026.9.1固定发布与源码
- DevKitC-1 v1.1固定文档提交927ed7e:排针、电源与USB
- Adafruit BME280 PID2652:端子、电平与默认地址
- Bosch BME280手册:首页rev1.24,0xD0与BMP差异表
- Bosch BMP280手册rev1.26:0xD0=0x58
- ESPHome2026.9.1:BME280校验ID、补偿与读取失败
- ESPHome2026.9.1:BMP280校验0x58与两项测量
- Adafruit BMP280 PID2651:接线与地址
- ESPHome2026.9.1:timeout过滤器实际NaN失效逻辑
- Home Assistant:Template availability和数值状态
- HA Core2026.10.2:ESPHome集成源码
- Adafruit BMP280官方库2.6.8:默认0x77、替代0x76和ID0x58