Sensirion SPS30 I²C Arduino 驱动版本演进与实战指南Tasmota 仓库内 arduino-i2c-sps30 库解析【免费下载链接】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 仓库内集成的 arduino-i2c-sps30 驱动库展开梳理其 CHANGELOG 记录的版本演进脉络并结合仓库内完整源码、示例工程与 Tasmota 传感器驱动实现深入讲解 SPS30 颗粒物传感器的接线方法、测量命令集、两种输出格式Uint16/Float的读取方式与 AVR 平台兼容性限制。读完本文你将掌握该驱动从 v1.0.0 到 v1.0.1 的完整变更细节并能在 Arduino 或 Tasmota 环境中正确初始化、唤醒、测量与维护 SPS30 传感器。Sensirion SPS30 颗粒物传感器产品外观一、CHANGELOG 核心内容驱动的版本演进脉络CHANGELOG.md 严格遵循 Keep a Changelog 规范编写并遵守语义化版本控制Semantic Versioning。其中记录了三个版本节点版本日期变更类型内容Unreleased——待发布内容当前为空1.0.12025-08-28Added将start_measurement示例参数改为枚举类型新增 Float 测量示例新增 AVR 开发板使用警告1.0.02025-08-25AddedSPS30 驱动首次正式发布Initial release该库由 Sensirion 官方维护从 metadata.yml 可见其由sensirion-driver-generator 1.3.4自动生成模型版本 1.0.2首次生成于 2025-08-15并于 2025-08-28 做了手工修改后以 1.0.1 发布。当前 library.properties 中登记的版本为1.0.1依赖 Sensirion Core 库类别为 Sensors支持所有 Arduino 架构architectures*。二、库概览安装方式与依赖关系该库名为Sensirion I2C SPS30用于通过 I²C 总线与 Sensirion SPS30 颗粒物Particulate Matter, PM传感器通信。安装方式有两种Arduino Library Manager 安装打开 Arduino IDE通过Sketch➔Include Library➔Manage Libraries...在搜索框输入Sensirion I2C SPS30并点击 Install。ZIP 手动安装下载最新 release 的.zip包通过Sketch➔Include Library➔Add .ZIP Library...添加。必须同时安装依赖库本库唯一的外部依赖是 Sensirion Core仓库内位于lib/lib_i2c/arduino-core可通过相同方式安装。在源码中SensirionI2cSps30.h头部即通过#include SensirionCore.h引入该依赖。三、硬件接线I²C 地址与引脚定义SPS30 的默认 I²C 地址为0x69在头文件中定义为#define SPS30_I2C_ADDR_69 0x69。传感器通过 SEL 引脚选择接口模式——将 SEL 拉低到 GND 即选择 I²C 模式。3.1 引脚定义表依据 README.md 中的官方说明SPS30 引脚如下Pin线缆颜色名称描述备注1红VDD供电电压5V推荐 5V2绿SDAI²C 串行数据输入/输出3黄SCLI²C 串行时钟输入4蓝SEL接口选择拉低到 GND 选择 I²C5黑GND地3.2 常用开发板接线对照以 ESP32 DevKitC 为例这也是 Tasmota 最常见的运行平台之一SPS30SPS30 Pin线缆颜色ESP32 引脚VDD1红5VSDA2绿GPIO 21SCL3黄GPIO 22SEL4蓝GNDGND5黑GNDESP32 DevKitC 与 SPS30 的 I²C 接线示意其余开发板Arduino UnoD18/SDA、D19/SCLArduino NanoA4/A5Arduino MicroD2/SDA、~D3/SCLArduino Mega 2560D20/SDA、D21/SCL的完整接线表可在 README.md 中查阅。四、API 命令全景从源码看底层协议驱动头文件 SensirionI2cSps30.h 通过枚举SPS30CmdId完整映射了 SPS30 的全部 I²C 命令 ID实现文件 SensirionI2cSps30.cpp 则基于 SensirionCore 的SensirionI2CTxFrame/SensirionI2CRxFrame收发帧。命令全景如下命令 ID命令名对应 API说明0x10Start MeasurementstartMeasurement()启动测量参数为输出格式枚举0x104Stop MeasurementstopMeasurement()返回 Idle 模式0x202Read Data-Ready FlagreadDataReadyFlag()轮询数据就绪标志0x0000 无新数据0x0001 就绪0x300Read Measured ValuesreadMeasurementValuesUint16()/readMeasurementValuesFloat()读取 10 项测量值两种格式0x1001Sleepsleep()进入睡眠模式同时停用 I²C 接口0x1103Wake-UpwakeUp()/wakeUpSequence()从睡眠唤醒见下节说明0x5607Start Fan CleaningstartFanCleaning()手动启动风扇清洁仅限 Measurement 模式0x8004Read/Write Auto Cleaning IntervalreadAutoCleaningInterval()/writeAutoCleaningInterval()读写自动清洁间隔单位秒0xd002Read Product TypereadProductType()读取 8 字符 ASCII 产品类型0xd033Read Serial NumberreadSerialNumber()读取最多 32 字符 ASCII 序列号0xd100Read Firmware VersionreadFirmwareVersion()读取固件主/次版本号0xd206Read Device Status RegisterreadDeviceStatusRegister()读取设备状态寄存器详见数据手册 4.4 节0xd210Clear Device Status RegisterclearDeviceStatusRegister()清除设备状态寄存器0xd304Device ResetdeviceReset()软件复位恢复到上电复位状态从源码可确认几个关键协议细节输出格式枚举SPS30OutputFormat中FLOAT 768、UINT16 1280通过startMeasurement()携带进命令帧测量值内容10 项输出包括 4 项质量浓度PM1.0/PM2.5/PM4.0/PM10.0单位 µg/m³、5 项数量浓度PM0.5/PM1.0/PM2.5/PM4.0/PM10.0单位 #/cm³以及典型粒径µm唤醒机制睡眠模式下 I²C 接口被禁用需要先在 SDA 线上发送一个低脉冲I²C Start 条件紧跟 Stop 条件重新激活接口随后 100ms 内发送 Wake-Up 命令才能进入 Idle 模式。如果软件无法构造该低脉冲也可以连续发送两次 Wake-Up 命令——第一次命令被忽略但会激活接口第二次真正生效。wakeUpSequence()正是按此逻辑连续调用两次wakeUp()。五、示例工程两种测量输出格式的完整用法仓库提供了两个官方示例工程对应 CHANGELOG 中 1.0.1 的Changed start_measurement example-value to enum与Added float example两项变更5.1 Uint16 模式示例exampleUsage.ino该示例展示了标准流程初始化串口115200 baud→Wire.begin()→sensor.begin(Wire, SPS30_I2C_ADDR_69)→ 先stopMeasurement()进入已知状态 → 读取序列号与产品类型 → 以SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_UINT16启动测量 → 每秒轮询readDataReadyFlag()后调用readMeasurementValuesUint16()读取并打印 10 项数据。关键代码片段SensirionI2cSps30 sensor; ... Wire.begin(); sensor.begin(Wire, SPS30_I2C_ADDR_69); sensor.stopMeasurement(); sensor.startMeasurement(SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_UINT16); ... error sensor.readDataReadyFlag(dataReadyFlag); if (error NO_ERROR) { error sensor.readMeasurementValuesUint16(mc1p0, mc2p5, mc4p0, mc10p0, nc0p5, nc1p0, nc2p5, nc4p0, nc10p0, typicalParticleSize); }1.0.1 的关键改进startMeasurement()的参数由裸数值改为枚举类型SPS30OutputFormat编译期即可检查参数合法性避免了传入非法格式值导致的协议错误。5.2 Float 模式示例exampleUsageFloat.ino该示例为 1.0.1 新增与 Uint16 版本唯一的实质性差异是启动测量时传入SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT并将所有测量变量声明为float类型读取时调用readMeasurementValuesFloat()。两种格式使用同一个命令 ID0x300区别仅在于启动测量时写入的输出格式参数以及接收帧的长度Uint16 为 30 字节Float 为 60 字节。实测建议两种模式下数据就绪后每 1 秒更新一次测量值。如果不需要严格同步读取可以忽略 Data-Ready 标志因为Read Measured Values命令始终返回最近一次测量结果。六、1.0.1 新增的 AVR 兼容性警告源码级实现CHANGELOG 中 1.0.1 的第三项变更Added warning for the use with AVR boards在源码 SensirionI2cSps30.cpp 中有直接实现。startMeasurement()开头通过#ifdef __AVR__预处理指令拦截#ifdef __AVR__ if (measurementOutputFormat SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT) { Serial.println(WARNING: AVR Boards are not fully compatible with SPS30 firmware-version 1.0:); Serial.println( - Float measurement mode will not work); delay(2000); assert(false); } #endif即在 AVR 平台如 Arduino Uno/Nano/Micro/Mega上若请求 Float 测量模式驱动会打印警告并触发assert(false)中止。README 同时补充了两条 AVR 平台的限制说明readSerialNumber仅能读取 20 字节对实际传感器序列号通常足够Float 测量模式因 Arduino Wire 库的局限性无法工作AVR 用户必须改用 Uint16 测量模式。这也解释了示例工程中默认示例使用 Uint16 格式的原因——保证跨平台可用性。ESP32 等 32 位平台不受此限制两种格式均可使用。七、Tasmota 中的集成从库到设备驱动本仓库作为 Tasmota 固件项目已在传感器驱动层集成了该库见 xsns_44_sps30.ino。该驱动在 I²C 地址 0x69 上注册设备通过I2cSetDevice(SPS30_I2C_ADDR_69, bus)做总线扫描与去重初始化流程与示例工程一致sps30.begin()→deviceReset()回到 Idle 模式→readFirmwareVersion()→readSerialNumber()并逐一做错误处理可选编译宏SPS30_ENABLE_SLEEP启用睡眠/唤醒功能利用 1.0.1 驱动新增的wakeUpSequence()语义连续两次wakeUp()SPS30_PARTS_PER_DECILITER可将数量浓度单位改为每分升粒子数SENSIRION_DEBUG开启调试日志测量的 PM1.0/PM2.5/PM4.0/PM10、NCPM 系列与典型粒径共 10 项数据通过 Tasmota 的标准传感器框架上报。启用方式在 tasmota_configurations.hESP8266 与通用配置或 tasmota_configurations_ESP32.hESP32 配置中取消#define USE_SPS30的注释即开启 I2cDriver30SPS30 颗粒物传感器I²C 地址 0x69约增加 1.7k 代码。因此本仓库内的 arduino-i2c-sps30 库既可直接用于独立 Arduino 工程也作为 Tasmota 固件的底层依赖被生产级设备驱动复用。八、版本演进小结与选型建议从 CHANGELOG.md 可以看到该驱动从 2025-08-25 的 1.0.0 初版到 2025-08-28 的 1.0.1 补强版迭代周期短、改动聚焦1.0.0SPS30 驱动首次发布提供完整命令集1.0.1①startMeasurement()参数枚举化更安全的 API② 新增 Float 模式示例工程exampleUsageFloat③ 增加 AVR 平台兼容性警告从源码层阻止 Float 模式在 AVR 上运行并给出明确提示。选型建议使用 ESP32/ESP8266 等 32 位平台时可自由选择 Float 或 Uint16 格式Float 精度更高、省去手动换算使用 AVR 系列开发板时务必选择 Uint16 模式并注意序列号读取上限为 20 字节。任何平台都建议通过readDataReadyFlag()同步读取以获得稳定的每秒测量节奏。【免费下载链接】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），仅供参考 Sensirion SPS30 I²C Arduino 驱动版本演进与实战指南：Tasmota 仓库内 arduino-i2c-sps30 库解析
Sensirion SPS30 I²C Arduino 驱动版本演进与实战指南Tasmota 仓库内 arduino-i2c-sps30 库解析【免费下载链接】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 仓库内集成的 arduino-i2c-sps30 驱动库展开梳理其 CHANGELOG 记录的版本演进脉络并结合仓库内完整源码、示例工程与 Tasmota 传感器驱动实现深入讲解 SPS30 颗粒物传感器的接线方法、测量命令集、两种输出格式Uint16/Float的读取方式与 AVR 平台兼容性限制。读完本文你将掌握该驱动从 v1.0.0 到 v1.0.1 的完整变更细节并能在 Arduino 或 Tasmota 环境中正确初始化、唤醒、测量与维护 SPS30 传感器。Sensirion SPS30 颗粒物传感器产品外观一、CHANGELOG 核心内容驱动的版本演进脉络CHANGELOG.md 严格遵循 Keep a Changelog 规范编写并遵守语义化版本控制Semantic Versioning。其中记录了三个版本节点版本日期变更类型内容Unreleased——待发布内容当前为空1.0.12025-08-28Added将start_measurement示例参数改为枚举类型新增 Float 测量示例新增 AVR 开发板使用警告1.0.02025-08-25AddedSPS30 驱动首次正式发布Initial release该库由 Sensirion 官方维护从 metadata.yml 可见其由sensirion-driver-generator 1.3.4自动生成模型版本 1.0.2首次生成于 2025-08-15并于 2025-08-28 做了手工修改后以 1.0.1 发布。当前 library.properties 中登记的版本为1.0.1依赖 Sensirion Core 库类别为 Sensors支持所有 Arduino 架构architectures*。二、库概览安装方式与依赖关系该库名为Sensirion I2C SPS30用于通过 I²C 总线与 Sensirion SPS30 颗粒物Particulate Matter, PM传感器通信。安装方式有两种Arduino Library Manager 安装打开 Arduino IDE通过Sketch➔Include Library➔Manage Libraries...在搜索框输入Sensirion I2C SPS30并点击 Install。ZIP 手动安装下载最新 release 的.zip包通过Sketch➔Include Library➔Add .ZIP Library...添加。必须同时安装依赖库本库唯一的外部依赖是 Sensirion Core仓库内位于lib/lib_i2c/arduino-core可通过相同方式安装。在源码中SensirionI2cSps30.h头部即通过#include SensirionCore.h引入该依赖。三、硬件接线I²C 地址与引脚定义SPS30 的默认 I²C 地址为0x69在头文件中定义为#define SPS30_I2C_ADDR_69 0x69。传感器通过 SEL 引脚选择接口模式——将 SEL 拉低到 GND 即选择 I²C 模式。3.1 引脚定义表依据 README.md 中的官方说明SPS30 引脚如下Pin线缆颜色名称描述备注1红VDD供电电压5V推荐 5V2绿SDAI²C 串行数据输入/输出3黄SCLI²C 串行时钟输入4蓝SEL接口选择拉低到 GND 选择 I²C5黑GND地3.2 常用开发板接线对照以 ESP32 DevKitC 为例这也是 Tasmota 最常见的运行平台之一SPS30SPS30 Pin线缆颜色ESP32 引脚VDD1红5VSDA2绿GPIO 21SCL3黄GPIO 22SEL4蓝GNDGND5黑GNDESP32 DevKitC 与 SPS30 的 I²C 接线示意其余开发板Arduino UnoD18/SDA、D19/SCLArduino NanoA4/A5Arduino MicroD2/SDA、~D3/SCLArduino Mega 2560D20/SDA、D21/SCL的完整接线表可在 README.md 中查阅。四、API 命令全景从源码看底层协议驱动头文件 SensirionI2cSps30.h 通过枚举SPS30CmdId完整映射了 SPS30 的全部 I²C 命令 ID实现文件 SensirionI2cSps30.cpp 则基于 SensirionCore 的SensirionI2CTxFrame/SensirionI2CRxFrame收发帧。命令全景如下命令 ID命令名对应 API说明0x10Start MeasurementstartMeasurement()启动测量参数为输出格式枚举0x104Stop MeasurementstopMeasurement()返回 Idle 模式0x202Read Data-Ready FlagreadDataReadyFlag()轮询数据就绪标志0x0000 无新数据0x0001 就绪0x300Read Measured ValuesreadMeasurementValuesUint16()/readMeasurementValuesFloat()读取 10 项测量值两种格式0x1001Sleepsleep()进入睡眠模式同时停用 I²C 接口0x1103Wake-UpwakeUp()/wakeUpSequence()从睡眠唤醒见下节说明0x5607Start Fan CleaningstartFanCleaning()手动启动风扇清洁仅限 Measurement 模式0x8004Read/Write Auto Cleaning IntervalreadAutoCleaningInterval()/writeAutoCleaningInterval()读写自动清洁间隔单位秒0xd002Read Product TypereadProductType()读取 8 字符 ASCII 产品类型0xd033Read Serial NumberreadSerialNumber()读取最多 32 字符 ASCII 序列号0xd100Read Firmware VersionreadFirmwareVersion()读取固件主/次版本号0xd206Read Device Status RegisterreadDeviceStatusRegister()读取设备状态寄存器详见数据手册 4.4 节0xd210Clear Device Status RegisterclearDeviceStatusRegister()清除设备状态寄存器0xd304Device ResetdeviceReset()软件复位恢复到上电复位状态从源码可确认几个关键协议细节输出格式枚举SPS30OutputFormat中FLOAT 768、UINT16 1280通过startMeasurement()携带进命令帧测量值内容10 项输出包括 4 项质量浓度PM1.0/PM2.5/PM4.0/PM10.0单位 µg/m³、5 项数量浓度PM0.5/PM1.0/PM2.5/PM4.0/PM10.0单位 #/cm³以及典型粒径µm唤醒机制睡眠模式下 I²C 接口被禁用需要先在 SDA 线上发送一个低脉冲I²C Start 条件紧跟 Stop 条件重新激活接口随后 100ms 内发送 Wake-Up 命令才能进入 Idle 模式。如果软件无法构造该低脉冲也可以连续发送两次 Wake-Up 命令——第一次命令被忽略但会激活接口第二次真正生效。wakeUpSequence()正是按此逻辑连续调用两次wakeUp()。五、示例工程两种测量输出格式的完整用法仓库提供了两个官方示例工程对应 CHANGELOG 中 1.0.1 的Changed start_measurement example-value to enum与Added float example两项变更5.1 Uint16 模式示例exampleUsage.ino该示例展示了标准流程初始化串口115200 baud→Wire.begin()→sensor.begin(Wire, SPS30_I2C_ADDR_69)→ 先stopMeasurement()进入已知状态 → 读取序列号与产品类型 → 以SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_UINT16启动测量 → 每秒轮询readDataReadyFlag()后调用readMeasurementValuesUint16()读取并打印 10 项数据。关键代码片段SensirionI2cSps30 sensor; ... Wire.begin(); sensor.begin(Wire, SPS30_I2C_ADDR_69); sensor.stopMeasurement(); sensor.startMeasurement(SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_UINT16); ... error sensor.readDataReadyFlag(dataReadyFlag); if (error NO_ERROR) { error sensor.readMeasurementValuesUint16(mc1p0, mc2p5, mc4p0, mc10p0, nc0p5, nc1p0, nc2p5, nc4p0, nc10p0, typicalParticleSize); }1.0.1 的关键改进startMeasurement()的参数由裸数值改为枚举类型SPS30OutputFormat编译期即可检查参数合法性避免了传入非法格式值导致的协议错误。5.2 Float 模式示例exampleUsageFloat.ino该示例为 1.0.1 新增与 Uint16 版本唯一的实质性差异是启动测量时传入SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT并将所有测量变量声明为float类型读取时调用readMeasurementValuesFloat()。两种格式使用同一个命令 ID0x300区别仅在于启动测量时写入的输出格式参数以及接收帧的长度Uint16 为 30 字节Float 为 60 字节。实测建议两种模式下数据就绪后每 1 秒更新一次测量值。如果不需要严格同步读取可以忽略 Data-Ready 标志因为Read Measured Values命令始终返回最近一次测量结果。六、1.0.1 新增的 AVR 兼容性警告源码级实现CHANGELOG 中 1.0.1 的第三项变更Added warning for the use with AVR boards在源码 SensirionI2cSps30.cpp 中有直接实现。startMeasurement()开头通过#ifdef __AVR__预处理指令拦截#ifdef __AVR__ if (measurementOutputFormat SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT) { Serial.println(WARNING: AVR Boards are not fully compatible with SPS30 firmware-version 1.0:); Serial.println( - Float measurement mode will not work); delay(2000); assert(false); } #endif即在 AVR 平台如 Arduino Uno/Nano/Micro/Mega上若请求 Float 测量模式驱动会打印警告并触发assert(false)中止。README 同时补充了两条 AVR 平台的限制说明readSerialNumber仅能读取 20 字节对实际传感器序列号通常足够Float 测量模式因 Arduino Wire 库的局限性无法工作AVR 用户必须改用 Uint16 测量模式。这也解释了示例工程中默认示例使用 Uint16 格式的原因——保证跨平台可用性。ESP32 等 32 位平台不受此限制两种格式均可使用。七、Tasmota 中的集成从库到设备驱动本仓库作为 Tasmota 固件项目已在传感器驱动层集成了该库见 xsns_44_sps30.ino。该驱动在 I²C 地址 0x69 上注册设备通过I2cSetDevice(SPS30_I2C_ADDR_69, bus)做总线扫描与去重初始化流程与示例工程一致sps30.begin()→deviceReset()回到 Idle 模式→readFirmwareVersion()→readSerialNumber()并逐一做错误处理可选编译宏SPS30_ENABLE_SLEEP启用睡眠/唤醒功能利用 1.0.1 驱动新增的wakeUpSequence()语义连续两次wakeUp()SPS30_PARTS_PER_DECILITER可将数量浓度单位改为每分升粒子数SENSIRION_DEBUG开启调试日志测量的 PM1.0/PM2.5/PM4.0/PM10、NCPM 系列与典型粒径共 10 项数据通过 Tasmota 的标准传感器框架上报。启用方式在 tasmota_configurations.hESP8266 与通用配置或 tasmota_configurations_ESP32.hESP32 配置中取消#define USE_SPS30的注释即开启 I2cDriver30SPS30 颗粒物传感器I²C 地址 0x69约增加 1.7k 代码。因此本仓库内的 arduino-i2c-sps30 库既可直接用于独立 Arduino 工程也作为 Tasmota 固件的底层依赖被生产级设备驱动复用。八、版本演进小结与选型建议从 CHANGELOG.md 可以看到该驱动从 2025-08-25 的 1.0.0 初版到 2025-08-28 的 1.0.1 补强版迭代周期短、改动聚焦1.0.0SPS30 驱动首次发布提供完整命令集1.0.1①startMeasurement()参数枚举化更安全的 API② 新增 Float 模式示例工程exampleUsageFloat③ 增加 AVR 平台兼容性警告从源码层阻止 Float 模式在 AVR 上运行并给出明确提示。选型建议使用 ESP32/ESP8266 等 32 位平台时可自由选择 Float 或 Uint16 格式Float 精度更高、省去手动换算使用 AVR 系列开发板时务必选择 Uint16 模式并注意序列号读取上限为 20 字节。任何平台都建议通过readDataReadyFlag()同步读取以获得稳定的每秒测量节奏。【免费下载链接】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），仅供参考