Tasmota 与 Arduino 平台下 Sensirion SCD4X CO₂ 传感器的 I²C 驱动库实战指南
Tasmota 与 Arduino 平台下 Sensirion SCD4X CO₂ 传感器的 I²C 驱动库实战指南
导读
Sensirion SCD4X 系列(SCD40 / SCD41 / SCD43)是集 CO₂ 浓度、温度与相对湿度于一体的单芯片传感器,通过标准 I²C 接口(器件地址固定为 0x62)即可通信。本指南以 Tasmota 仓库中内置的 Sensirion I²C SCD4X Arduino 库 为骨架,完整讲解其安装、接线、快速上手的全部要点,并下沉到 库源码 与 Tasmota 的 SCD4X 驱动实现,让你既能在 Arduino IDE 中独立驱动 SCD4X,也能理解它在 Tasmota 固件中的真实调用链路与状态机设计。
SCD4X 传感器家族与驱动库概述
该库名为 Sensirion I2C SCD4x(版本 1.1.0,见 library.properties),由 Sensirion 官方维护,通过 I²C 总线与 SCD4X 家族传感器通信。从库头文件的自动生成标记(sensirion-driver-generator 1.1.2,Model-Version 2.0)可以看出,其全部命令均严格对应传感器数据手册。
注意:并非该家族所有传感器都支持全部测量命令。当某个测量功能并非全系支持时,本文会逐一标注适用的具体型号。
支持的传感器型号
库头文件 SensirionI2cScd4x.h 中预定义了三个型号的 I²C 地址宏:
| 传感器型号 | I²C 地址 |
|---|---|
| SCD40 | 0x62 |
| SCD41 | 0x62 |
| SCD43 | 0x62 |
三个型号共用同一个 7 位地址 0x62,因此同一条 I²C 总线上只能挂载一个 SCD4X 传感器。此外,getSensorVariant() / getSensorVariantRaw() 接口可以通过读取传感器的 variant 寄存器区分具体型号——库中通过 SCD4X_SENSOR_VARIANT_MASK = 0x00F000 与各型号特征值(SCD40=0x000000、SCD41=0x001000、SCD42=0x002000、SCD43=0x005000)比对判断,这在多型号混用的产线场景中非常实用。
本文后续说明与示例默认以 SCD41 为对象。
库的安装方式
该库已经随 Tasmota 仓库附带于 lib/lib_i2c/arduino-i2c-scd4x 目录,若在独立 Arduino 工程中使用,可按官方 README 的两种方式安装。
方式一:Arduino 库管理器
启动 Arduino IDE 后,通过菜单打开库管理器:
Sketch ➔ Include Library ➔ Manage Libraries...
在 "Filter your search..." 输入框中搜索 Sensirion I2C SCD4X,找到后点击 install 按钮安装。
方式二:ZIP 方式手动安装
若在库管理器中找不到,可下载最新 release 的 .zip 压缩包,然后通过:
Sketch ➔ Include Library ➔ Add .ZIP Library...
将其添加到 Arduino IDE。
依赖库
安装主库之外,务必用同样的方式安装依赖:
- Sensirion Core(
arduino-core):提供SensirionI2CTxFrame/SensirionI2CRxFrame/SensirionI2CCommunication等底层 I²C 帧封装与errorToString错误解析函数。该依赖在 Tasmota 仓库中对应 lib/lib_i2c/arduino-core,并在 library.properties 中以depends=Sensirion Core声明。
传感器接线(Pinout)
SCD4X 为标准 4 引脚封装,接线说明如下(官方 README):
| 引脚 | 线缆颜色 | 名称 | 说明 | 备注 |
|---|---|---|---|---|
| 1 | 黄色 | SCL | I²C 串行时钟输入 | |
| 2 | 黑色 | GND | 地 | |
| 3 | 红色 | VDD | 电源 | 2.4V ~ 5.5V |
| 4 | 绿色 | SDA | I²C 串行数据输入/输出 |
推荐供电电压为 3.3V。Tasmota 的驱动初始化代码中也特别执行了 PowerOnDelay(40)(见 xsns_92_scd40.ino),等待传感器上电后约 40ms 的启动时间,之后才开始 I²C 通信。
常见开发板的接线对照
以下接线表来自官方 README,均已按仓库路径整理:
Arduino Uno:SCL → D19/SCL,GND → GND,VDD → 3.3V,SDA → D18/SDA
Arduino Nano:SCL → A5,GND → GND,VDD → 3.3V,SDA → A4
Arduino Micro:SCL → ~D3/SCL,GND → GND,VDD → 3.3V,SDA → D2/SDA
Arduino Mega 2560:SCL → D21/SCL,GND → GND,VDD → 3.3V,SDA → D20/SDA
ESP32 DevKitC(与 Tasmota 最相关):SCL → GPIO 22,GND → GND,VDD → 3V3,SDA → GPIO 21
快速上手(Quick Start)
按官方 README 的步骤即可在 5 分钟内跑通第一个 SCD4X 测量程序:
- 按上文"库的安装方式"完成主库与依赖安装;
- 按上文"传感器接线"将 SCD4X 连接到开发板的 I²C 总线;
- 在 Arduino IDE 中打开示例工程:
示例默认针对 SCD41、I²C 地址 0x62 编写。若使用其他型号或地址,需要修改示例代码中的地址宏——预定义地址清单见 src/SensirionI2cScd4x.h;File ➔ Examples ➔ Sensirion I2C SCD4X ➔ exampleUsage - 点击 Arduino IDE 的
Upload按钮(或Sketch ➔ Upload)烧录固件; - 烧录完成后,通过
Tools菜单打开Serial Monitor或Serial Plotter观察测量值,波特率务必设置为 115200。
示例代码解析:周期性测量(exampleUsage)
仓库中的 examples/exampleUsage/exampleUsage.ino 完整展示了周期性测量模式的使用流程:
初始化阶段(setup()):
SensirionI2cScd4x sensor;
...
Wire.begin();
sensor.begin(Wire, SCD41_I2C_ADDR_62);
// 确保传感器处于干净状态
error = sensor.wakeUp();
error = sensor.stopPeriodicMeasurement();
error = sensor.reinit();
// 读取序列号,验证传感器在线
error = sensor.getSerialNumber(serialNumber);
// 启动 5 秒间隔的周期性测量
error = sensor.startPeriodicMeasurement();
测量阶段(loop()):
delay(5000); // 将采样频率降到 0.2Hz
error = sensor.getDataReadyStatus(dataReady);
while (!dataReady) { // 数据未就绪时轮询等待
delay(100);
error = sensor.getDataReadyStatus(dataReady);
}
error = sensor.readMeasurement(co2Concentration, temperature, relativeHumidity);
// 打印 CO2 concentration [ppm]、Temperature [°C]、Relative Humidity [%RH]
示例代码解析:单次测量省电模式(exampleScd41SingleShot)
对于电池供电场景,仓库还提供了 examples/exampleScd41SingleShot/exampleScd41SingleShot.ino。它演示了 SCD41 专属的按需单次测量流程:
error = sensor.wakeUp(); // 从休眠唤醒
error = sensor.measureSingleShot(); // 丢弃唤醒后的第一次测量
error = sensor.measureAndReadSingleShot(co2, temperature, humidity); // 正式单次测量并读取
delay(300000); // 休眠 5 分钟后再测
其中 measureAndReadSingleShot() 的库内实现(见 SensirionI2cScd4x.cpp)依次执行:measureSingleShot()(内部 delay(5000) 等待测量完成)→ 轮询 getDataReadyStatus() → readMeasurement() 读回物理量,将"触发-等待-读取"封装成了单个 API。
深入库源码:命令集与数据转换原理
库头文件以 SCD4xCmdId 枚举完整列出了数据手册中的全部 I²C 命令 ID(SensirionI2cScd4x.h),下表为核心命令及其适用条件:
| 命令 | 命令码 | 说明 | 可用状态 / 适用型号 |
|---|---|---|---|
| startPeriodicMeasurement | 0x21B1 | 启动周期测量,5 秒更新一次 | 仅 idle 态 |
| startLowPowerPeriodicMeasurement | 0x21AC | 低功耗周期测量,约 30 秒更新一次 | 仅 idle 态 |
| readMeasurementRaw | 0xEC05 | 读取 CO₂/温度/湿度原始值 | 测量中 |
| stopPeriodicMeasurement | 0x3F86 | 回到 idle 态,便于改配置或省电 | |
| setTemperatureOffsetRaw | 0x241D | 设置温度补偿偏移 | 仅 idle 态 |
| setSensorAltitude | 0x2427 | 设置海拔(0~3000m) | 仅 idle 态 |
| setAmbientPressureRaw | 0xE000 | 设置环境气压(70000~120000 Pa) | 测量中也可用 |
| performForcedRecalibration | 0x362F | 强制校准(FRC) | 仅 idle 态 |
| setAutomaticSelfCalibrationEnabled | 0x2416 | 开关自动自校准(ASC) | 仅 idle 态 |
| persistSettings | 0x3615 | 将易失配置写入 EEPROM | 仅 idle 态 |
| getSerialNumber | 0x3682 | 读取 48 位唯一序列号 | 仅 idle 态 |
| performSelfTest | 0x3639 | 自检(约 10 秒) | 仅 idle 态 |
| performFactoryReset | 0x3632 | 恢复出厂设置 | 仅 idle 态 |
| reinit | 0x3646 | 从 EEPROM 重载配置 | 仅 idle 态 |
| measureSingleShot | 0x219D | SCD41/SCD43 单次测量 | 仅 SCD41/SCD43 |
| measureSingleShotRhtOnly | 0x2196 | SCD41/SCD43 仅温湿度单次测量 | 仅 SCD41/SCD43 |
| powerDown / wakeUp | 0x36E0 / 0x36F6 | 休眠 / 唤醒 | 仅 SCD41 |
| set/get AutomaticSelfCalibrationInitialPeriod | 0x2445 / 0x2340 | ASC 初始校正周期(默认 44h,4h 整数倍) | 仅 SCD41,idle 态 |
| set/get AutomaticSelfCalibrationStandardPeriod | 0x244E / 0x234B | ASC 标准校正周期(默认 156h,4h 整数倍) | 仅 SCD41,idle 态 |
原始值到物理量的换算
库在 SensirionI2cScd4x.cpp 中提供了静态换算函数,将 16 位原始 ADC 值转换为物理量(与数据手册公式一致):
温度: temperature = -45.0 + (175.0 * rawTemperature) / 65535.0; // °C
相对湿度:relativeHumidity = (100.0 * rawRelativeHumidity) / 65535.0; // %RH
CO₂ 浓度:co2 = rawCo2Concentration; // ppm(原始值即 ppm)
温度偏移:temperatureOffset = (175 * rawTemperatureOffset) / 65535.0; // °C
环境气压:ambientPressure = rawAmbientPressure * 100; // Pa
注意历史版本曾误用 2^16 作为除数,CHANGELOG.md 记录了 0.4.0 版本已修正为 2^16 - 1(即 65535)。
readMeasurement() 的封装逻辑(SensirionI2cScd4x.cpp)就是先读原始值,再调用上述换算函数输出物理量。setTemperatureOffset() / setAmbientPressure() 则执行逆换算(乘 65535 再除 175 或 100)后写入原始寄存器。
关键时序细节(来自源码)
measureSingleShot()发送命令后delay(5000),即单次测量的最快采样间隔为 5 秒;performSelfTest()后delay(10000)等待自检完成;persistSettings()后delay(800);performFactoryReset()后delay(1200);stopPeriodicMeasurement()后delay(500);wakeUp()不期望传感器 ACK(SCD4X 处于休眠时不响应 I²C),发送后delay(30)等待唤醒;getDataReadyStatus()内部通过(dataReadyStatus & 2047) != 0判断低 11 位是否就绪(SensirionI2cScd4x.cpp)。
测量缓冲区语义
readMeasurement 的文档明确说明:每个信号更新周期内,测量数据只能被读取一次,读后缓冲区即被清空;若缓冲区无数据,传感器会返回 NACK。因此官方推荐先用 getDataReadyStatus 轮询就绪状态再读取,这也是两个示例工程的一致模式。
Tasmota 固件中的 SCD4X 集成(源码级对照)
在 Tasmota 仓库中,SCD4X 的实际驱动位于 tasmota/tasmota_xsns_sensor/xsns_92_scd40.ino(驱动号 92,I²C 设备号 62,对应地址 0x62)。它直接复用本库的 SensirionI2cScd4x 类,是理解"库 API 如何在真实固件中落地"的最佳范本。
编译开关
#define USE_SCD40 // 启用 SCD40/SCD41/SCD42/SCD43 支持
//#define USE_SCD40_LOWPOWER // 初始即以低功耗周期测量模式启动
初始化流程
Tasmota 的 Scd40Init()(xsns_92_scd40.ino)在扫描到 0x62 设备后执行:
scd40.begin(I2cGetWire(bus), SCD40_I2C_ADDR_62)绑定总线与地址;stopPeriodicMeasurement()→reinit()保证传感器处于干净状态;getSerialNumber()读取序列号,失败则跳过该总线;getSensorVariantRaw()读取型号,并按variant >> 12(0/1/2/5)映射到mScd40Names中的 "SCD40|SCD41|SCD42|||SCD43" 名称;- 根据是否定义
USE_SCD40_LOWPOWER,调用startLowPowerPeriodicMeasurement()(30s)或startPeriodicMeasurement()(5s)。
状态机驱动的测量循环
Tasmota 没有像 Arduino 示例那样用 loop() 死等,而是实现了基于 SCD40DATA->state 的异步状态机(xsns_92_scd40.ino):
SCD40_STATE_READ_MEASUREMENT(0):调用getDataReadyStatus()+readMeasurement()读取数据,随后切到启动态;SCD40_STATE_START_MEASUREMENT(5)/SCD40_STATE_START_LP_MEASUREMENT(30):以 5 秒 / 30 秒的递减计数作为测量间隔,计时归零后再次读取,避免阻塞主循环。
换算公式与库保持一致((175.0 * temperature) / 65536 - 45、(100.0 * humidity) / 65536,见 xsns_92_scd40.ino),且 CO₂ 浓度还会通过 LightSetSignal(CO2_LOW, CO2_HIGH, co2) 联动灯光信号。
控制台命令
Tasmota 为该传感器暴露了完整的控制台命令集(SCD40 前缀,定义于 xsns_92_scd40.ino),第三列为执行耗时:
| 指令 | 返回值 | 耗时 | 功能 |
|---|---|---|---|
| SCD40Alt | data | 1ms | 读取传感器海拔(m) |
| SCD40Alt x | errorvalue | 1ms | 设置传感器海拔(m) |
| SCD40Auto | data | 1ms | 读取 ASC 使能状态(bool) |
| SCD40Auto x | errorvalue | 1ms | 设置 ASC 使能状态 |
| SCD40Toff | data | 1ms | 读取温度偏移(℃) |
| SCD40Toff x | errorvalue | 1ms | 设置温度偏移(℃,存在取整) |
| SCD40Pres x | errorvalue | 1ms | 设置环境气压(mbar,会覆盖海拔设置) |
| SCD40Cal x | errorvalue | 400ms | 强制校准(ppm CO₂) |
| SCD40Test | errorvalue | 10000ms | 自检 |
| SCD40StLp | errorvalue | 0ms | 启动低功耗周期测量(1/30s) |
| SCD40Strt | errorvalue | 0ms | 启动周期测量(1/5s) |
| SCD40Stop | errorvalue | 500ms | 停止周期测量 |
| SCD40Pers | errorvalue | 800ms | 配置持久化到 EEPROM(保证 2000 次写循环) |
| SCD40Rein | errorvalue | 20ms | 传感器重初始化 |
| SCD40Fact | errorvalue | 1200ms | 恢复出厂设置 |
| SCD40Sing | errorvalue | 5000ms | (SCD41/SCD43 专用)单次测量 |
| SCD40SRHT | errorvalue | 50ms | (SCD41/SCD43 专用)仅温湿度单次测量 |
出错时 errorvalue 返回 -1,正常返回 0;查询类指令返回 -1 表示出错,否则返回实际值。
校准与配置建议(来自头文件文档)
库头文件对以下配置给出了权威的工程建议,写入配置后请调用 persistSettings() 保存到 EEPROM(EEPROM 保证至少 2000 次写循环,且 FRC/ASC 校准历史自动存入独立存储区域):
- 温度偏移(setTemperatureOffset):默认 4℃,推荐范围 0~20℃,建议在整机集成完成、热平衡后按公式
Toffset_actual = T_SCD4x - T_Reference + Toffset_previous标定;它不影响 CO₂ 精度,仅优化温湿度输出。 - 环境气压(setAmbientPressure):有效值 70000~120000 Pa,默认 101300 Pa;气压显著变化的场景强烈建议使用,设置后会覆盖基于海拔的补偿。
- 传感器海拔(setSensorAltitude):有效值 0~3000m,默认 0m;与气压补偿互斥,后设置者生效。
- 自动自校准 ASC:默认开启,算法假设每周累计运行至少 4 小时(周期测量 / 低功耗周期测量 / SCD41 的 5 分钟单次测量模式)会暴露于 400 ppm 背景浓度;默认目标基线 400 ppm。单次测量模式下,ASC 周期参数按 5 分钟间隔换算,若实际间隔不同需按比例缩放。
- 强制校准 FRC:需先以目标工作模式运行至少 3 分钟,再
stopPeriodicMeasurement()后执行;返回0xFFFF表示校准失败(传感器此前未运行)。
参与贡献与许可证
该库使用 clang-format 统一 .cpp / .h 文件的代码风格,贡献代码前请运行:
clang-format -i src/*.cpp src/*.h
-i 参数会直接改写所列文件;格式不符会导致 CI 构建失败。许可证详见库内的 LICENSE,版本演进记录见 CHANGELOG.md(其中 1.0.0 是破坏性版本:类名由 SensirionI2CScd4x 改为 SensirionI2cScd4x,begin() 增加地址参数,xxxTicks 更名 xxxRaw,序列号改为 uint64_t 返回)。
小结
SCD4X 以其"单芯片三合一 + 固定 0x62 地址 + 免外部校准"的特性,非常适合室内空气质量监测节点。通过本仓库内置的 Sensirion I²C SCD4X 库 与其在 Tasmota 驱动 中的真实落地,你可以快速掌握从 Arduino 裸驱动到固件级状态机集成的完整链路:先跑通 exampleUsage 验证硬件,再用 measureAndReadSingleShot 做低功耗设计,最后通过 Tasmota 的 SCD40 系列控制台命令完成校准、自检与配置持久化,实现完全本地化的 CO₂ 监测能力。

