Tasmota 与 Arduino 平台下 Sensirion SCD4X CO₂ 传感器的 I²C 驱动库实战指南

原创2026-09-12 23:30:161,820 阅读
文章标签:物联网智能家居嵌入式固件IoT协议硬件开发边缘网关

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 串行数据输入/输出

SCD4X 传感器模块引脚定义

推荐供电电压为 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

ESP32 DevKitC 与 SCD4X 的 I²C 接线图

快速上手(Quick Start)

按官方 README 的步骤即可在 5 分钟内跑通第一个 SCD4X 测量程序:

  1. 按上文"库的安装方式"完成主库与依赖安装;
  2. 按上文"传感器接线"将 SCD4X 连接到开发板的 I²C 总线;
  3. 在 Arduino IDE 中打开示例工程:
    File ➔ Examples ➔ Sensirion I2C SCD4X ➔ exampleUsage
    
    示例默认针对 SCD41、I²C 地址 0x62 编写。若使用其他型号或地址,需要修改示例代码中的地址宏——预定义地址清单见 src/SensirionI2cScd4x.h;
  4. 点击 Arduino IDE 的 Upload 按钮(或 Sketch ➔ Upload)烧录固件;
  5. 烧录完成后,通过 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 设备后执行:

  1. scd40.begin(I2cGetWire(bus), SCD40_I2C_ADDR_62) 绑定总线与地址;
  2. stopPeriodicMeasurement() → reinit() 保证传感器处于干净状态;
  3. getSerialNumber() 读取序列号,失败则跳过该总线;
  4. getSensorVariantRaw() 读取型号,并按 variant >> 12(0/1/2/5)映射到 mScd40Names 中的 "SCD40|SCD41|SCD42|||SCD43" 名称;
  5. 根据是否定义 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₂ 监测能力。

登录后查看全文
Tasmota