Tasmota 中的 Sensirion SEN6X 环境传感器库：CHANGELOG 版本演进与关键 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
本文以 Tasmota 仓库内置的 Sensirion SEN6X I²C Arduino 库（CHANGELOG.md）为主线，梳理该库从 0.1.0 到 1.2.0 的完整版本演进脉络，并结合库源码与 Tasmota 驱动逐一剖析每个变更对应的 API 实现与固件约束。读者读完后，将掌握 SEN6X/SEN66 传感器库的接口清单、命令码与数据缩放规则，理解序列号/产品名类型变更、CO₂ 返回类型调整、SHT 加热器时序等关键细节，并能在 Tasmota 的Sen6x*命令与 Arduino 示例中正确使用这些能力。
一、SEN6X 库在 Tasmota 仓库中的定位
Sensirion SEN6X 是面向室内空气质量监测的环境传感器平台（产品线包含 SEN62/SEN63C/SEN65/SEN66/SEN68/SEN69C 等型号，组合了 PM 颗粒物、温湿度 SHT4x、CO₂（SCD4x/STCC4）、VOC/NOx（SGP41）与 HCHO（SFA40）等多种测量单元）。SEN66 是其中集成度较高的型号，默认 I²C 地址为0x6B。
该 Arduino 库被以第三方库形式打包进 Tasmota 仓库的lib/lib_i2c/Sensirion_I2C_SEN6X_Tasmota/目录下，并由驱动 xsns_119_sen6x.ino 接入固件，向用户暴露Sen6x、Sen6xClean、Sen6xHeat、Sen6xTempOff、Sen6xVocTune、Sen6xNoxTune、Sen6xAlt、Sen6xPres、Sen6xCal等控制台命令。库的元信息见 library.properties（当前版本 1.2.0，依赖 Sensirion Core）。
库文件结构如下：
- src/SensirionI2cSen6x.h：公开类
SensirionI2cSen6x的全部接口声明、命令 ID 枚举与设备状态位定义； - src/SensirionI2cSen6x.cpp：各接口的 I²C 帧构造与收发实现；
- examples/exampleUsage/exampleUsage.ino：最小可用示例（复位 → 读序列号 → 启动连续测量 → 每秒读一次全量数据）；
- README.md：安装、接线与快速上手说明。
二、版本演进总览
CHANGELOG 遵循 Keep a Changelog 格式与语义化版本规范（Semantic Versioning），当前发布序列如下：
| 版本 | 发布日期 | 类型 | 核心变更 |
|---|---|---|---|
| 0.1.0 | 2024-10-31 | 首个版本 | 产品图片、启动/停止/读取测量接口、读取产品名/序列号/版本接口 |
| 1.0.0 | 2024-11-25 | 正式版 | 补齐所有公共接口；read_measured_values的 CO₂ 返回类型由 float 改为 uint16 |
| 1.0.1 | 2024-12-01 | 修复 | 修正"颗粒物数量浓度"读取方法的命名（mass concentration → number concentration），返回值本身无误 |
| 1.1.0 | 2025-02-12 | 变更 | 序列号与产品名改为按字符串解释（uint8[32]→int8[32]） |
| 1.2.0 | 2025-03-13 | 新增/变更 | 新增读取固件版本命令；新增读取 SHT 加热后温湿度命令（固件 ≥ 4.0）；SHT 加热激活时长缩短至 20ms |
下面逐版本深入解读，并在每个变更点给出源码级佐证。
三、v0.1.0：初始接口与最小可用闭环
首个版本（2024-10-31）为库奠定了三组核心能力：
- 测量的启停与读取：
startContinuousMeasurement()、stopMeasurement()、readMeasuredValues(...)； - 设备身份读取：
getProductName()、getSerialNumber()、getVersion()； - 产品图片：库内
images/目录下随附的传感器本体与接线图。
从 SensirionI2cSen6x.h 的枚举可以看出这些接口对应的命令 ID：
SEN66_START_CONTINUOUS_MEASUREMENT_CMD_ID = 0x21、SEN66_STOP_MEASUREMENT_CMD_ID = 0x104、SEN66_READ_MEASURED_VALUES_AS_INTEGERS_CMD_ID = 0x300；SEN66_GET_PRODUCT_NAME_CMD_ID = 0xd014、SEN66_GET_SERIAL_NUMBER_CMD_ID = 0xd033、SEN66_GET_VERSION_CMD_ID = 0xd100。
使用这些接口的最小流程见 exampleUsage.ino：Wire.begin()后调用sensor.begin(Wire, SEN6X_I2C_ADDR_6B)，先deviceReset()复位并延时 1200ms，再读取序列号，随后startContinuousMeasurement()进入测量模式；主循环中每 1 秒调用一次readMeasuredValues()输出 PM1.0/PM2.5/PM4.0/PM10.0、湿度、温度、VOC、NOx 与 CO₂。
四、v1.0.0：补齐公共接口与 CO₂ 返回类型修正
1.0.0（2024-11-25）完成两件事：
（1）"Add all public interfaces"——公共接口对齐官方驱动。对照 SensirionI2cSen6x.h 的完整方法清单，公共接口已覆盖：
- 测量类：
startContinuousMeasurement、stopMeasurement、getDataReady、readMeasuredValues、readMeasuredValuesAsIntegers、readNumberConcentrationValues、readNumberConcentrationValuesAsIntegers、readMeasuredRawValues； - 维护类：
startFanCleaning、activateShtHeater、getShtHeaterMeasurements、deviceReset、readDeviceStatus、readAndClearDeviceStatus； - 配置类：
set/getTemperatureOffsetParameters（5 个温度补偿槽位）、set/getVocAlgorithmTuningParameters、set/getNoxAlgorithmTuningParameters、setTemperatureAccelerationParameters、set/getVocAlgorithmState、performForcedCo2Recalibration、set/getCo2SensorAutomaticSelfCalibration、set/getAmbientPressure、set/getSensorAltitude； - 身份类：
getProductName、getSerialNumber、getVersion； - 静态缩放函数：
signalMassConcentrationPmX、signalNumberConcentrationPmX、signalTemperature、signalHumidity、signalVocIndex、signalNoxIndex、signalCo2、signalHcho。
（2）CO₂ 返回类型 float → uint16。readMeasuredValues()的最后一个参数在头文件中即为uint16_t& co2，CO₂ 单位为 ppm 且本身是整数量纲，改用uint16_t既贴合数据手册，也避免浮点转换开销；无效值用SEN6X_UINT_INVALID (0xFFFF)表示。signalCo2(uint16_t co2Raw)同样以uint16_t返回 ppm。
五、v1.0.1：颗粒物数量浓度的命名修正
1.0.1（2024-12-01）是一个纯命名层面的修复：原"质量浓度（mass concentration）"的命名被纠正为"数量浓度（number concentration）"，用于描述 PM0.5/PM1.0/PM2.5/PM4.0/PM10.0 的particles/cm³数量浓度读数。CHANGELOG 明确说明"返回的值一直是正确的"，只是方法名容易误导。
源码中对应方法为readNumberConcentrationValues(...)与readNumberConcentrationValuesAsIntegers(...)，输出参数依次为numberConcentrationPm0p5、numberConcentrationPm1p0、numberConcentrationPm2p5、numberConcentrationPm4p0、numberConcentrationPm10p0，均以 0.1 particles/cm³ 的缩放因子读取（raw / 10.0，见 SensirionI2cSen6x.cpp 中signalNumberConcentrationPm*系列实现）。
注意区分两类读数：质量浓度（µg/m³，PM1.0/2.5/4.0/10.0）与数量浓度（particles/cm³，PM0.5/1.0/2.5/4.0/10.0），二者缩放因子均为 10，但物理含义和粒径档位不同。
六、v1.1.0：序列号与产品名改为字符串类型
1.1.0（2025-02-12）把getProductName与getSerialNumber的输出缓冲类型从uint8[32]改为int8[32]。这在 C/C++ 中意味着缓冲区被显式视为可打印的 ASCII 字符串（int8_t配合(const char*)强转输出），而不是裸字节数组：
int16_t getProductName(int8_t productName[], uint16_t productNameSize); int16_t getSerialNumber(int8_t serialNumber[], uint16_t serialNumberSize);Tasmota 驱动 xsns_119_sen6x.ino 中即采用int8_t serial_number[32]/int8_t product_name[32]接收，并用GetCommandCode把产品名匹配到SEN62|SEN63C||SEN65|SEN66||SEN68|SEN69C型号表，从而确定该型号具备的测量特性（features[] = { 0, 2, 0, 1, 3, 0, 6, 7 }，分别编码 HCHO/CO₂/VOC 能力位）。实现层面，getProductName发送命令0xd014（接收帧 48 字节）、getSerialNumber发送命令0xd033（接收帧 48 字节），最多读取 32 个字符的以\0结尾字符串。
七、v1.2.0：固件版本读取与 SHT 加热器时序重构（重点）
1.2.0（2025-03-13）是本库最值得关注的一个版本，包含两项新增与一项时序变更，且都涉及传感器固件版本（≥ 4.0）条件分支。
7.1 新增getVersion：读取固件版本
新增的getVersion(uint8_t& firmwareMajor, uint8_t& firmwareMinor)返回固件主/次版本号，底层命令为SEN66_GET_VERSION_CMD_ID = 0xd100，接收帧长度 3 字节（SensirionI2cSen6x.cpp 第 907 行附近）。它解决了一个实际问题：后续 SHT 加热功能依赖固件版本，用户需要先查询版本号再决定调用哪套时序。
Tasmota 驱动在Sen6xInit()初始化序列中正是先deviceReset()、再getVersion(major, minor)、随后读序列号与产品名，并把major.minor记录到SEN6XDATA结构中；Sen6x命令的状态输出也包含"Version":"%d.%d"字段。
7.2 新增getShtHeaterMeasurements：读取加热后的温湿度
SEN66 内置 SHT 加热器用于在高湿度环境下逆转传感器"蠕变（creep）"。1.2.0 新增getShtHeaterMeasurements(int16_t& humidity, int16_t& temperature)，底层命令为SEN66_GET_SHT_HEATER_MEASUREMENTS_CMD_ID = 0x6790（接收帧 6 字节）。该命令仅固件版本 ≥ 4.0 可用，且必须紧跟在activateShtHeater()之后调用；若加热尚未完成，返回的湿度/温度值为0x7FFF（SEN6X_INT_INVALID）。注释表明该命令可以每 0.05s 轮询一次，用于精确判断加热结束时刻。
返回值缩放规则：湿度RH [%] = raw / 100，温度T [°C] = raw / 200。
7.3 SHT 加热激活时长缩短为 20ms
变更前activateShtHeater()激活 200mW 加热 1 秒；1.2.0 起激活时长缩减到 20ms，底层命令为SEN66_ACTIVATE_SHT_HEATER_CMD_ID = 0x6765。带来的时序要求是：
- 固件 ≥ 4.0：用
getShtHeaterMeasurements主动轮询确认加热是否结束； - 固件 < 4.0：发出加热命令后，至少等待1300ms才能发送下一条命令；
- 无论固件版本，加热命令后开始测量前应等待约 20 秒，使加热导致的温度扰动完全消退，以获取一致的温湿度读数（Tasmota 驱动中对应
SEN6X_STATE_SHT_HEATER_WAIT = 21秒状态机）。
八、CHANGELOG 变更在 Tasmota 固件中的落地映射
库的每次能力增长都在 xsns_119_sen6x.ino 的Sen6x*命令中得到对应（命令前缀由kSen6xCommands定义）：
| 库接口 | 对应 Tasmota 命令 | 说明 |
|---|---|---|
getVersion/getProductName/getSerialNumber | Sen6x | 状态信息：名称、序列号、固件版本、设备状态 |
startFanCleaning | Sen6xClean | 风扇全速 10 秒自动停止，之后需等待 10s（SEN6X_STATE_CLEAN_FAN_WAIT = 11） |
activateShtHeater | Sen6xHeat | 激活 SHT 加热器，随后进入 21 秒等待状态 |
setTemperatureOffsetParameters | Sen6xTempOff <offset>,<slope>,<time_constant>,<slot0..4> | 温度补偿，5 个槽位 |
setTemperatureAccelerationParameters | Sen6xTempAcc <k>,<p>,<t1>,<t2> | RH/T 引擎滤波参数 |
getVocAlgorithmState | Sen6xVocState | 读取 VOC 算法状态（12 字节，用于断电后恢复学习进度） |
set/getVocAlgorithmTuningParameters | Sen6xVocTune | 默认值100,12,12,180,50,230 |
set/getNoxAlgorithmTuningParameters | Sen6xNoxTune | 默认值1,12,720,230（学习增益恒为 12h、std 恒为 50，对 NOx 无实际影响） |
setSensorAltitude | Sen6xAlt <0..3000> | CO₂ 气压补偿（米） |
setAmbientPressure | Sen6xPres <700..1200> | CO₂ 气压补偿（hPa），会覆盖基于海拔的补偿 |
setCo2SensorAutomaticSelfCalibration/performForcedCo2Recalibration | Sen6xCal <0|1|351..10000> | 自动自校准开关；payload > 350 时执行强制重校准（FRC） |
其中 FRC 强制重校准的调用链充分体现了 CHANGELOG 中"接口完备性"的价值：Tasmota 收到Sen6xCal 444后会stopMeasurement()、等待约 1400ms、调用performForcedCo2Recalibration(reference, correction)，并以FRC = correction - 0x8000的规则把修正值返回给用户（失败返回 0xFFFF）。
九、升级到 1.2.0 的实践注意事项
结合 CHANGELOG 与源码，开发者在使用或升级到 1.2.0 时应重点关注：
- 固件版本先行：
getVersion应在初始化时尽早调用，用于分支判断 SHT 加热时序；Tasmota 驱动即采用该模式。 - SHT 加热时序：升级后不要再依赖"加热 1 秒"的旧行为；固件 ≥ 4.0 时用
getShtHeaterMeasurements（每 50ms 轮询）确认结束，固件 < 4.0 时硬性等待 1300ms，且两种情况下开始测量前都建议等待 20 秒。 - 字符串类型：序列号/产品名缓冲区使用
int8_t[32]，读取后可直接以(const char*)打印或做型号匹配。 - 无效值判断：读取整数值接口在无数据时返回
0xFFFF（uint16）或0x7FFF（int16），例如 CO₂ 在上电后前 5~6 秒、NOx 在上电后前 10~11 秒、HCHO 在首次测量后前 60 秒都可能处于无效状态；驱动中的Sen6xUInt16Div10等函数会将无效值转换为NAN而非存储脏数据（见 xsns_119_sen6x.ino 的Sen6xUpdate，读取失败时不覆盖旧值）。 - 命令可用状态：多数配置命令（VOC/NOx 调参、ALT、Cal 等）仅在 idle 模式生效，因此 Tasmota 统一用
Sen6xStopStartMeasurement()（停止并 1 秒后重启测量）包裹配置操作；仅setAmbientPressure、setTemperatureOffsetParameters可在测量状态下调用。
十、小结
从 0.1.0 到 1.2.0，Sensirion SEN6X 库的演进脉络清晰：先打通"测量 + 身份读取"的最小闭环，再补齐全部公共接口并修正 CO₂ 返回类型与数量浓度命名，随后把序列号/产品名规范为字符串，最终在 1.2.0 引入固件版本查询与 SHT 加热测量机制，使高湿度场景的维护操作变得可编程、可精确判断。这些能力全部落地于 Tasmota 的Sen6x*命令集，开发者可直接在控制台或 exampleUsage.ino 基础上，组合出"初始化探测 → 连续测量 → 周期维护（风扇清理 / SHT 加热）→ 状态诊断"的完整环境监测方案。
【免费下载链接】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），仅供参考
