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.1 | 2025-08-28 | Added | 将start_measurement示例参数改为枚举类型；新增 Float 测量示例；新增 AVR 开发板使用警告 |
| 1.0.0 | 2025-08-25 | Added | SPS30 驱动首次正式发布（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（推荐 5V） |
| 2 | 绿 | SDA | I²C 串行数据输入/输出 | |
| 3 | 黄 | SCL | I²C 串行时钟输入 | |
| 4 | 蓝 | SEL | 接口选择 | 拉低到 GND 选择 I²C |
| 5 | 黑 | GND | 地 |
3.2 常用开发板接线对照
以 ESP32 DevKitC 为例（这也是 Tasmota 最常见的运行平台之一）：
| SPS30 | SPS30 Pin | 线缆颜色 | ESP32 引脚 |
|---|---|---|---|
| VDD | 1 | 红 | 5V |
| SDA | 2 | 绿 | GPIO 21 |
| SCL | 3 | 黄 | GPIO 22 |
| SEL | 4 | 蓝 | GND |
| GND | 5 | 黑 | GND |
ESP32 DevKitC 与 SPS30 的 I²C 接线示意
其余开发板（Arduino Uno：D18/SDA、D19/SCL；Arduino Nano：A4/A5；Arduino Micro：D2/SDA、~D3/SCL；Arduino Mega 2560：D20/SDA、D21/SCL）的完整接线表可在 README.md 中查阅。
四、API 命令全景：从源码看底层协议
驱动头文件 SensirionI2cSps30.h 通过枚举SPS30CmdId完整映射了 SPS30 的全部 I²C 命令 ID，实现文件 SensirionI2cSps30.cpp 则基于 SensirionCore 的SensirionI2CTxFrame/SensirionI2CRxFrame收发帧。命令全景如下：
| 命令 ID | 命令名 | 对应 API | 说明 |
|---|---|---|---|
| 0x10 | Start Measurement | startMeasurement() | 启动测量，参数为输出格式枚举 |
| 0x104 | Stop Measurement | stopMeasurement() | 返回 Idle 模式 |
| 0x202 | Read Data-Ready Flag | readDataReadyFlag() | 轮询数据就绪标志（0x0000 无新数据，0x0001 就绪） |
| 0x300 | Read Measured Values | readMeasurementValuesUint16()/readMeasurementValuesFloat() | 读取 10 项测量值（两种格式） |
| 0x1001 | Sleep | sleep() | 进入睡眠模式，同时停用 I²C 接口 |
| 0x1103 | Wake-Up | wakeUp()/wakeUpSequence() | 从睡眠唤醒（见下节说明） |
| 0x5607 | Start Fan Cleaning | startFanCleaning() | 手动启动风扇清洁，仅限 Measurement 模式 |
| 0x8004 | Read/Write Auto Cleaning Interval | readAutoCleaningInterval()/writeAutoCleaningInterval() | 读写自动清洁间隔（单位：秒） |
| 0xd002 | Read Product Type | readProductType() | 读取 8 字符 ASCII 产品类型 |
| 0xd033 | Read Serial Number | readSerialNumber() | 读取最多 32 字符 ASCII 序列号 |
| 0xd100 | Read Firmware Version | readFirmwareVersion() | 读取固件主/次版本号 |
| 0xd206 | Read Device Status Register | readDeviceStatusRegister() | 读取设备状态寄存器（详见数据手册 4.4 节） |
| 0xd210 | Clear Device Status Register | clearDeviceStatusRegister() | 清除设备状态寄存器 |
| 0xd304 | Device Reset | deviceReset() | 软件复位，恢复到上电复位状态 |
从源码可确认几个关键协议细节：
- 输出格式枚举：
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()。两种格式使用同一个命令 ID（0x300），区别仅在于启动测量时写入的输出格式参数，以及接收帧的长度（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.h（ESP8266 与通用配置）或 tasmota_configurations_ESP32.h（ESP32 配置）中取消#define USE_SPS30的注释，即开启 I2cDriver30（SPS30 颗粒物传感器，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.0：SPS30 驱动首次发布，提供完整命令集；
- 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），仅供参考
