1. 一块 GY-21P 四个引脚:功能库把环境传感器接成一条 I2C 总线
拿一块 GY-21P 贴到 ESP8266 开发板上,只接 VIN、GND、SCL、SDA 四根线,再引入 Adafruit 那几个功能库,Arduino 的 loop 里就能同时读出温度、气压、海拔和湿度。第一次做的人多半以为难点在传感器本身,实际容易出问题的地方全在库这一侧:三个库的依赖顺序、BMP280 到底挂在 0x77 还是 0x76、begin() 返回 false 后程序直接 while(1) 卡死、海拔参数还停在出厂默认的 1013.25。下面按我实际接线的顺序走,从装库、接线,到读数、排错,每一步都给出能直接编译的代码和参数含义,刚上手 ESP8266/Arduino、想给物联网节点加环境传感的人可以照着做。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库的安装与总线接线:GY-21P 接上 ESP8266 的第一步
GY-21P 是一块把 BMP280 和 SI7021 焊在同一块小板上的组合模块,前者测气压和温度,后者测湿度和温度,共用一组 I2C 引脚。它省掉了分别接线和分别供电的麻烦,但也意味着一条总线上要同时挂两颗芯片、两个功能库,任何一边的初始化没通过,另一边的数据也读不踏实。
这一章先把「装哪几个库、库之间谁依赖谁、线怎么接、地址是多少」定下来,再给一份能直接烧进去的最小工程。后面几章的读数、排错都建立在这份骨架上,骨架跑通了再谈参数。
2.1 一个组合模块为什么要装三个功能库
Adafruit 这一套把驱动拆得比较细:Adafruit_Sensor 是一层统一的传感器抽象,提供 Adafruit_Sensor 基类和事件结构,BMP280 库在编译时依赖它;Adafruit_BMP280_Library 负责 BMP280 的温度、气压、海拔换算;Adafruit_Si7021 单独负责 SI7021 的湿度和温度。也就是说 #include <Adafruit_Sensor.h> 能过,不是因为你装了 BMP280 库,而是因为统一传感器库也在。三个库各管一段,缺一个就在编译期报错。
为什么不自己对着寄存器写?BMP280 的数据手册里有一整套温度补偿系数,出厂时烧在芯片的校准寄存器里,读出来之后要按一组多项式换算,写错一个系数温度就偏好几度;SI7021 的测量命令、CRC 校验和转换等待也有自己的时序。自己写驱动不是不行,但第一次做的时候,把补偿算法调对的成本远高于把库装对,而且调错了很难从串口数字上看出问题。
| 做法 | 代码量 | 主要风险 | 适合场景 |
|---|---|---|---|
| 自己写寄存器驱动 | 几百行起 | 补偿系数、时序、CRC 容易写错 | 需要裁剪、移植到无库环境 |
| Adafruit 功能库 | 几十行 | 库版本与依赖、地址配置 | 快速验证、原型、毕设 |
提示:库管理器里同名的库可能不止一个,认准 Adafruit 出品的那个。装错作者的同名库,include 路径和类名都对不上,后面所有代码都要返工。
2.2 库管理器里的安装顺序与依赖
Arduino IDE 的库管理器按名字搜索,装的时候按依赖顺序来,能少走一步回头路:
- 先搜 Adafruit Unified Sensor,装上。这是
Adafruit_Sensor.h的来源,BMP280 库编译时要找它。 - 再搜 Adafruit BMP280 Library,装上。
- 最后搜 Adafruit Si7021,装上。
顺序反了也不会装不上,但编译时如果先装 BMP280 库、后装统一传感器库,第一次编译大概率报 Adafruit_Sensor.h: No such file or directory。看到这个报错先回去补第 1 步,不用怀疑代码写得不对。
装完之后在示例列表里能看到对应示例,能打开、能编译通过,说明库这一层已经就位。这一步不用改任何代码,就是验证 include 路径通不通。
2.3 ESP8266 的 I2C 引脚、供电与地址
GY-21P 引出四根线:VIN、GND、SCL、SDA。多数 ESP8266 开发板默认的 I2C 是 GPIO4 作 SDA、GPIO5 作 SCL,对应板上丝印的 D2 和 D1;接线时按丝印接,不要按 GPIO 编号去数排针,D 编号和 GPIO 编号不是一回事。
供电只接 3.3V。BMP280 和 SI7021 都是 3.3V 器件,GY-21P 上没有电平转换,VIN 接 5V 有可能当场把芯片送走。这条是血泪经验:模块上没有明显的电源标记时,先查芯片手册的供电范围再上电。
地址方面,BMP280 的 7 位地址由模块上的地址跳线决定,常见是 0x77,部分模块焊成 0x76;SI7021 固定 0x40。上电后先跑一遍 I2C 总线扫描,看到 0x40 和 0x77(或 0x76)两个地址都在,再往下写代码,比对着代码猜快得多。
| GY-21P 引脚 | 接到 ESP8266 | 说明 |
|---|---|---|
| VIN | 3.3V | 不要接 5V |
| GND | GND | 共地 |
| SCL | GPIO5 / D1 | I2C 时钟 |
| SDA | GPIO4 / D2 | I2C 数据 |
| 芯片 | 7 位地址 | 测量对象 |
|---|---|---|
| BMP280 | 0x77(部分 0x76) | 温度、气压、海拔 |
| SI7021 | 0x40 | 湿度、温度 |
2.4 最小工程骨架
把下面这份代码原样建一个 sketch,选好板型和串口就能编译:
cpp复制#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_BMP280.h>
#include "Adafruit_Si7021.h"
Adafruit_BMP280 bme; // I2C 连接,默认地址 0x77
Adafruit_Si7021 sensor = Adafruit_Si7021(); // SI7021 固定地址 0x40
void setup()
{
Serial.begin(9600);
Serial.println("BMP280 and SI7021 (GY-21p) test");
if (!bme.begin())
{
Serial.println("Could not find a valid BMP280 sensor, check wiring!");
while (1);
}
if (!sensor.begin())
{
Serial.println("Did not find Si7021 sensor!");
while (true);
}
}
void loop()
{
Serial.println("BMP280 results");
Serial.print("Temperature = ");
Serial.print(bme.readTemperature());
Serial.println(" *C");
Serial.print("Pressure = ");
Serial.print(bme.readPressure());
Serial.println(" Pa");
Serial.print("Approx altitude = ");
Serial.print(bme.readAltitude(1013.25)); // 需替换成本地海平面气压
Serial.println(" m");
Serial.println();
Serial.println("SI7021 results");
Serial.print("Humidity: ");
Serial.println(sensor.readHumidity(), 2);
Serial.print("Temperature: ");
Serial.println(sensor.readTemperature(), 2);
Serial.println();
delay(2000);
}
逐块说明:
Adafruit_BMP280 bme;用默认构造函数,库内部按 0x77 寻址;如果扫描发现模块是 0x76,把初始化改成bme.begin(0x76)。后面那句// I2C只是说明走的是 I2C 而不是 SPI,不影响编译。Adafruit_Si7021 sensor = Adafruit_Si7021();是库要求的写法,SI7021 没有地址参数可调,固定 0x40。Serial.begin(9600)定的是串口波特率,后面串口监视器要选同一个值,否则看到的是一屏乱码。- setup 里两个
if (!...)是整份代码的第一道闸门,begin() 返回 false 就打印报错并进死循环,目的是让问题在串口上「看得见」,不然后面读出来的全是无意义的 0。 - loop 里先读 BMP280 再读 SI7021,中间没有额外延时,只有末尾的
delay(2000)。这个 2000 ms 是整轮的节奏,两颗芯片的转换时间都远小于它,留出余量主要是给串口打印和后续上报用。
这一份骨架能跑通,说明库、接线、地址三件事都对上了;跑不通的情况留到第 4 章按报错逐条拆。
3. 功能库初始化的两道门:begin() 通过之前别急着读数
串口里能稳定看到 BMP280 和 SI7021 两组数据,只说明初始化这一关过去了。真正把数据用起来之前,还有两件事要弄清楚:begin() 到底检查了什么,以及每个读取函数返回的单位是什么。这两点搞混,读数看着正常,用起来全是错,还很难定位。
3.1 begin() 检查的是总线上有没有人应答
bme.begin() 做的事可以拆成三步:先在 I2C 总线上向目标地址发一次探测,看有没有从机应答;再读 BMP280 的芯片 ID 寄存器,确认读回的值是这颗芯片该有的值;最后写配置寄存器,把测量模式、过采样这些参数设定好。三步里有一步不对就返回 false。
sensor.begin() 类似,SI7021 会读电子 ID 或发一次测量命令来确认芯片在位。返回 false 的含义是「总线上没人应答或者应答的不是这颗芯片」,不是「读出来的数不准」。这个区别很关键:如果 begin() 已经返回 true,后面读数漂移,问题在参数和换算上;如果 begin() 返回 false,后面根本不该有数据,先别去调补偿参数。
示例里 begin() 失败就 while (1);,用死循环把程序停在那里。台面上调试时挺好用,串口停在报错那一行,一眼就知道是哪颗芯片没认到;但产品里这么写,现场
