Tasmota 中的 Adafruit CCS811：基于 I2C 的 eCO2/TVOC 空气质量传感器驱动实战

Tasmota 中的 Adafruit CCS811基于 I2C 的 eCO2/TVOC 空气质量传感器驱动实战【免费下载链接】TasmotaAlternative firmware for ESP8266 and ESP32 based devices with easy configuration using webUI, OTA updates, automation using timers or rules, expandability and entirely local control over MQTT, HTTP, Serial or KNX. Full documentation at项目地址: https://gitcode.com/GitHub_Trending/ta/TasmotaCCS811 是 ams原 Applied Sensors出品的低功耗室内空气质量传感器芯片能够输出等效二氧化碳浓度eCO2单位 ppm和总挥发性有机化合物浓度TVOC单位 ppb广泛用于室内空气监测、新风联动与智能家居场景。本文以 Tasmota 仓库中随附的 Adafruit CCS811 库lib/lib_i2c/Adafruit_CCS811-1.1.3/README.md为骨架先讲清该库的安装、I2C 接线与寄存器级工作原理再结合 xsns_31_ccs811.ino 与 xsns_31_ccs811_v2.ino 两个 Tasmota 驱动说明如何在固件中启用传感器、读取数据并接入 MQTT/Web 显示。读完本文你将能独立完成从库移植、接线调试到固件编译与数据上云的完整链路。一、库是什么Adafruit CCS811 概览Adafruit CCS811 Library 是 Adafruit 为自家 CCS811 气体传感器 breakout 板产品编号 3566编写的 Arduino 驱动库。它通过I2C 总线与芯片通信屏蔽了寄存器读写细节向上层提供简洁的测量接口。该库随 Tasmota 仓库一并托管在 lib/lib_i2c/Adafruit_CCS811-1.1.3/ 目录下是 Tasmota CCS811 传感器驱动的直接依赖。核心能力由 Adafruit_CCS811.h 中的公共接口可见读取eCO2等效 CO2ppm与TVOC总挥发性有机物ppb读取原始 ADC 值与传感器当前电流用于诊断设置环境温湿度补偿setEnvironmentalData提升算法精度读写基线值baseline用于长期漂移校正支持数据就绪中断、阈值中断与 4 档测量驱动模式内建软件复位、错误状态检查与 NTC 温度计算。二、安装与依赖原 README 明确指出安装该库最简单的方式是使用Arduino Library Manager搜索Adafruit CCS811并安装。在 Tasmota 项目中则无需手动安装——它已被内置在lib/lib_i2c/目录中随 PlatformIO 构建自动参与编译。依赖关系可从 library.properties 得到完整信息属性值nameAdafruit CCS811 Libraryversion1.1.3categorySensorsarchitectures*所有架构通用dependsAdafruit SSD1306, Adafruit GFX Library, Adafruit BusIO其中Adafruit SSD1306与Adafruit GFX Library是原 README 中列出的依赖主要用于 OLED 显示示例CCS811_OLED_Demo而Adafruit BusIO是库底层 I2C 访问的基础设施——源码中Adafruit_I2CDevice即来自 BusIO。如果你只做传感器读取而不使用 OLEDSSD1306/GFX 两个显示类依赖可以不需要但 BusIO 是必须的。三、硬件接线与 I2C 地址CCS811 通过I2C与主控通信。芯片默认 7 位地址为0x5A见 Adafruit_CCS811.h 中的#define CCS811_ADDRESS (0x5A)。Tasmota 驱动文件头部的注释给出了两个关键硬件要求I2C Address: 0x5A assumes ADDR connected to Gnd, Wake also must be grounded即地址引脚ADDR接地时为 0x5A部分模块可切换为 0x5B且nWAKE唤醒引脚必须接地否则芯片进入睡眠、无法通信。标准接线为VCC→ 3.3VGND→ GNDSDA→ 主控 I2C SDASCL→ 主控 I2C SCLnWAKE→ GNDnINT可选→ 主控 GPIO用于数据就绪中断值得注意的一个实现细节在 Adafruit_CCS811.cpp 的begin()中针对 ESP8266 平台额外调用了theWire-setClockStretchLimit(500)放宽时钟拉伸上限以适配 ESP8266 的 I2C 时序因此该库在 ESP8266 上也能稳定工作——这也是它能被 Tasmota同时支持 ESP8266/ESP32选用的原因之一。四、寄存器地图与初始化流程源码级原理4.1 寄存器地图从 Adafruit_CCS811.h 中的寄存器枚举可以完整还原芯片的内存映射寄存器地址用途STATUS0x00状态ERROR / DATA_READY / APP_VALID / FW_MODEMEAS_MODE0x01测量模式与中断配置ALG_RESULT_DATA0x02算法结果eCO2 TVOC 错误 IDRAW_DATA0x03原始 ADC 数据与电流ENV_DATA0x05环境温湿度补偿数据NTC0x06板载 NTC 温度测量THRESHOLDS0x10中断阈值与迟滞BASELINE0x11算法基线HW_ID0x20硬件 ID应为 0x81HW_VERSION0x21硬件版本FW_BOOT_VERSION0x23Bootloader 固件版本FW_APP_VERSION0x24应用固件版本ERROR_ID0xE0错误码SW_RESET0xFF软件复位另有 bootloader 专用寄存器APP_ERASE (0xF1)、APP_DATA (0xF2)、APP_VERIFY (0xF3)、APP_START (0xF4)用于固件烧录与启动应用固件。4.2 begin() 初始化流程begin(addr, theWire)的完整流程见 Adafruit_CCS811.cpp L17-L51通过Adafruit_I2CDevice建立 I2C 连接失败直接返回false发送软件复位序列{0x11, 0xE5, 0x72, 0x8A}到SW_RESET寄存器延时 100ms复位序列来自数据手册读取HW_ID校验是否为0x81CCS811_HW_ID_CODE防止误挂其他器件向 bootloader 发送APP_START启动应用固件再延时 100ms调用checkError()确认无错误、且FW_MODE位为 1已进入应用模式默认关闭中断并将驱动模式设为CCS811_DRIVE_MODE_1SEC每秒采样一次。4.3 驱动模式采样率setDriveMode()写入MEAS_MODE寄存器可选模式如下Adafruit_CCS811.h 中定义宏值采样间隔CCS811_DRIVE_MODE_IDLE0x00空闲不采样CCS811_DRIVE_MODE_1SEC0x01每 1 秒CCS811_DRIVE_MODE_10SEC0x02每 10 秒CCS811_DRIVE_MODE_60SEC0x03每 60 秒CCS811_DRIVE_MODE_250MS0x04每 250 毫秒默认 1 秒模式是功耗与响应速度的折中长时间运行的空气质量监测也可考虑 10 秒模式降低功耗。五、示例程序解读仓库内置两个官方示例位于 lib/lib_i2c/Adafruit_CCS811-1.1.3/examples/5.1 CCS811_test最小读取样例CCS811_test.ino 展示了最基础的数据读取流程#include Adafruit_CCS811.h Adafruit_CCS811 ccs; void setup() { Serial.begin(9600); if(!ccs.begin()){ Serial.println(Failed to start sensor! Please check your wiring.); while(1); } // Wait for the sensor to be ready while(!ccs.available()); } void loop() { if(ccs.available()){ if(!ccs.readData()){ Serial.print(CO2: ); Serial.print(ccs.geteCO2()); // ppm Serial.print(ppm, TVOC: ); Serial.println(ccs.getTVOC()); // ppb } else { Serial.println(ERROR!); while(1); } } delay(500); }关键点是available()轮询状态寄存器中的DATA_READY位readData()一次性读出 8 字节的ALG_RESULT_DATA并解析出 eCO2 与 TVOC返回值0表示无错误非 0 则为错误码即ERROR_ID寄存器的值。5.2 CCS811_OLED_Demo结合 OLED 显示CCS811_OLED_Demo.ino 演示了在 Adafruit SSD1306 OLED 上实时显示读数同时展示了两个进阶用法NTC 温度校准float temp ccs.calculateTemperature(); ccs.setTempOffset(temp - 25.0);利用板载 NTC 估算环境温度并补偿偏移数据上屏每 500ms 轮询一次将 eCO2ppm、TVOCppb和温度输出到 OLED。需要说明的是calculateTemperature()在源码注释中被标记为deprecated原因是hardware support removed by vendor厂商已移除对该功能的硬件支持因此新设计中更推荐使用外部温湿度传感器配合setEnvironmentalData()做补偿。六、关键 API 深度解析6.1 环境温湿度补偿setEnvironmentalData()CCS811 的内部算法会受环境温湿度影响提供准确的温湿度数据能显著提升 eCO2/TVOC 精度。库按芯片规格完成编码Adafruit_CCS811.cpp L134-L155湿度以1/512 %RH的定点格式存储默认 50%RH温度以1/512 ℃存储且存在偏移0 对应-25℃默认 25℃。uint16_t hum_conv humidity * 512.0f 0.5f; uint16_t temp_conv (temperature 25.0f) * 512.0f 0.5f;调用时直接传十进制数值即可setEnvironmentalData(55.5, 25.5)表示 55.5%RH、25.5℃。Tasmota 驱动正是利用这一点把系统内已采集的温湿度回填给 CCS811见下文第七节。6.2 基线管理getBaseline() / setBaseline()CCS811 的算法基线用于跟踪传感器的长期漂移。库将BASELINE寄存器的两个字节拼成 16 位整数返回方便用户存储到 EEPROM/配置中setBaseline()与之对称恢复保存的基线值该值不是人类可读的物理量必须原样存取。Tasmota 的 V2 驱动正是基于这一点提供了CCS811Baseline命令见下节。6.3 中断与阈值enableInterrupt() / setThresholds()enableInterrupt()/disableInterrupt()控制MEAS_MODE中的INT_DATARDY位使nINT引脚在新采样就绪时拉低读取ALG_RESULT_DATA后自动释放setThresholds(low_med, med_high, hysteresis 50)写入THRESHOLDS寄存器配合INT_THRESH位可实现越限中断——只有当 eCO2 穿过阈值且超过迟滞量时才触发中断避免频繁抖动适合做超标报警场景。6.4 错误处理checkError() 与错误位checkError()读取状态寄存器的ERROR位详细错误码则位于ERROR_ID寄存器头文件中定义了 6 个错误位WRITE_REG_INVALID、READ_REG_INVALID、MEASMODE_INVALID、MAX_RESISTANCE、HEATER_FAULT、HEATER_SUPPLY。其中HEATER_FAULT/HEATER_SUPPLY与芯片内部加热器有关若持续出现需检查供电是否稳定。七、Tasmota 固件中的集成实战7.1 编译开关Tasmota 通过 tasmota/my_user_config.hL710-L711中的宏启用 CCS811 支持// #define USE_CCS811 // [I2cDriver24] Enable CCS811 sensor (I2C address 0x5A) (2k2 code) // #define USE_CCS811_V2 // [I2cDriver24] Enable CCS811 sensor (I2C addresses 0x5A and 0x5B) (2k8 code)USE_CCS811基础版驱动约 2.2KB 固件支持单颗传感器0x5AUSE_CCS811_V2增强版驱动约 2.8KB同时扫描0x5A 与 0x5B两个地址最多支持 2 颗传感器并额外提供版本查询与基线读写命令。两个开关都绑定到 I2C 驱动编号24XI2C_24在 I2CDEVICES.md 中有对应说明support_features.ino中会依据该宏自动注册特性。启用任一宏后重新编译刷写固件即可。7.2 基础版驱动xsns_31_ccs811.ino的工作流程tasmota/tasmota_xsns_sensor/xsns_31_ccs811.ino 实现了一个典型的 Tasmota 传感器驱动检测FUNC_INIT → CCS811Detect遍历 Tasmota 的全部 I2C 总线I2cSetDevice预留地址后调用ccs.begin()成功则通过I2cSetActiveFound标记设备周期采样FUNC_EVERY_SECOND → CCS811Update每5 秒EVERYNSECONDS调用一次available()readData()刷新 eCO2/TVOC读取失败会连续计数超过 6 次约 30 秒后调用ccs.begin()重启传感器环境补偿联动当系统已获得温湿度数据TasmotaGlobal.humidity 0且温度有效时自动调用setEnvironmentalData()将温湿度回填给 CCS811数据输出FUNC_JSON_APPEND输出 MQTT JSONCCS811:{eCO2:412,TVOC:25}FUNC_WEB_SENSOR 则在 Web 控制台传感器页显示 CCS811 eCO2 xxx ppm 与 CCS811 TVOC xxx ppb 两行启用 Domoticz 时还会上报空气质量传感器值DomoticzSensor(DZ_AIRQUALITY, eCO2)。7.3 V2 增强版驱动xsns_31_ccs811_v2.inotasmota/tasmota_xsns_sensor/xsns_31_ccs811_v2.ino 在基础版之上做了多设备与命令扩展多传感器维护ccsd[MAXDEVICECOUNT]结构数组逐个扫描 0x5A/0x5B 地址为每个在线设备独立维护采样、失败重启与就绪状态从源码结构看其命令表注册了 3 个控制台命令CCS811HwVersion查询硬件版本、CCS811FwAppVersion查询应用固件版本、CCS811Baseline读写基线值邮箱级读写由于 Adafruit 库未暴露版本与基线寄存器驱动自行用Wire.beginTransmission实现了CCS811ReadMailboxValue/CCS811WriteMailboxValue直接读写FW_APP_VERSION、BASELINE等寄存器弥补了库的接口缺口同样支持温湿度回填补偿、约 30 秒失败自动重启机制。八、调试建议与注意事项以下经验均可从源码行为推导供实际调试参考上电后数据为 0 或长时间不变CCS811 算法需要一段运行时间建立基线数据手册建议 20 分钟以上达到稳定精度初期读数波动属正常现象持续失败时驱动会自动重启基础版与 V2 版都在连续失败约 30 秒后重新begin()这是驱动自愈机制配合CCS811相关日志V2 支持CCS811_DEBUG宏输出逐字节读写日志可定位 I2C 时序问题务必检查 nWAKE 引脚Tasmota 驱动头注释明确要求 Wake 接地漏接会导致begin()失败、无法枚举到设备用I2cScan验证硬件连通Tasmota 控制台可先执行 I2C 扫描确认 0x5A或 0x5B地址可见再启用 CCS811 驱动排查软件问题版本与基线命令仅 V2 提供如需读取FW_APP_VERSION或持久化基线应选用USE_CCS811_V2编译。九、小结Adafruit CCS811 库为室内空气质量监测提供了简洁可靠的 I2C 驱动层其寄存器封装、环境补偿、基线管理与中断机制设计清晰而 Tasmota 将它与自身的 I2C 基础设施、温湿度采集、MQTT/Web/Domoticz 输出无缝衔接使得在 ESP8266/ESP32 设备上快速落地eCO2/TVOC 实时监测成为一件低成本的事。从库源码Adafruit_CCS811.cpp到 Tasmota 驱动xsns_31_ccs811.ino一条完整的寄存器 → 库 API → 固件驱动 → 用户数据链路均可在此仓库中直接查阅可作为后续扩展如超标报警、新风联动的坚实基础。【免费下载链接】TasmotaAlternative firmware for ESP8266 and ESP32 based devices with easy configuration using webUI, OTA updates, automation using timers or rules, expandability and entirely local control over MQTT, HTTP, Serial or KNX. Full documentation at项目地址: https://gitcode.com/GitHub_Trending/ta/Tasmota创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考