企业官网建设流程全解析

Tasmota 中 Sensirion SPS30 颗粒物传感器 I²C 接入完全指南：Arduino 库驱动与固件集成实践

【免费下载链接】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

导读

Sensirion SPS30 是一款基于激光散射原理的高精度颗粒物（PM）传感器，可同时输出 PM1.0、PM2.5、PM4.0、PM10 的质量浓度以及 0.5～10µm 五档粒径的粒子数浓度。本指南以仓库内 arduino-i2c-sps30 官方驱动库 为主线，完整讲解其在 Arduino 环境下的安装、接线与编程方法，并结合 Tasmota 固件中真实的 SPS30 驱动实现 说明如何在 ESP8266/ESP32 智能设备上通过 Web UI 与 MQTT 直接获取颗粒物数据。读完本文，你将掌握从传感器接线、库 API 调用到固件级数据上云的全链路实操能力。

SPS30 产品外观图

SPS30 传感器与驱动库概述

SPS30 是 Sensirion 推出的颗粒物传感器，支持 UART 与 I²C 两种接口。使用 I²C 接口时其默认地址为0x69，与该系列驱动族中的其他传感器不同，SPS30 全部支持本文涉及的所有测量命令。

驱动库以SensirionI2cSps30类为核心，封装了传感器全部 I²C 命令。仓库内该库由 sensirion-driver-generator 1.3.4 自动生成（见 SensirionI2cSps30.h 头部注释），版本 1.0.1，依赖 Sensirion Core 基础库。

从库的 library.properties 可以看出：

• 名称：Sensirion I2C SPS30，类别 Sensors，架构*（全平台）；
• 头文件为SensirionI2cSps30.h，依赖项为Sensirion Core。

安装驱动库与依赖

通过 Arduino 库管理器安装（推荐）

启动 Arduino IDE，通过菜单Sketch→Include Library→Manage Libraries...打开库管理器，在Filter your search...搜索框中输入Sensirion I2C SPS30，点击install按钮完成安装。

通过 ZIP 手动安装

如果库管理器中检索不到，可下载最新 release 的 .zip 压缩包，通过Sketch→Include Library→Add .ZIP Library...添加。

注意：请务必用同样的方式安装依赖库Sensirion Core（arduino-core），否则编译会因缺少SensirionCore.h而失败——驱动源文件顶部即#include <SensirionCore.h>与#include <Wire.h>。

传感器接线：引脚定义与板级接线表

引脚功能与线色对照

SPS30 引脚定义图

关键提示：

• 推荐供电电压为5V（VDD 支持 5V±10%，该电压同时也是 SDA/SCL 的电平基准，兼容 3.3V LVTTL 主控）；
• SEL 引脚必须拉低到 GND 才能启用 I²C 模式。悬空时传感器默认走 UART 接口，此时 I²C 不可用；
• 接线时务必遵循“共地”原则，VDD、GND 先连通后再接数据线。

各开发板 I²C 接线速查表

驱动库官方 README 给出了以下常见板卡的引脚对照（SEL 均接 GND）：

ESP32 DevKitC 与 SPS30 的 I²C 接线示意

说明：ESP32 的默认 I²C 引脚为 GPIO21（SDA）/GPIO22（SCL），这与 Tasmota 在 ESP32 平台上的 I²C 默认配置一致。ESP8266 默认则为 GPIO4（SDA）/GPIO5（SCL），具体以所用固件配置为准。

快速上手：运行官方示例

1. 按上文完成库与依赖安装；
2. 按上文接线表连接 SPS30 与开发板；
3. 在 Arduino IDE 中打开示例工程：File→Examples→Sensirion I2C SPS30→exampleUsage；
4. 点击 IDE 的Upload按钮（或Sketch→Upload）烧录；
5. 烧录完成后打开Serial Monitor或Serial Plotter，波特率务必设置为 115200 baud，即可观察到实时测量值。

仓库内包含两个示例工程：

• exampleUsage.ino：使用 Uint16 输出格式；
• exampleUsageFloat.ino：使用 Float 输出格式。

AVR 平台的重要限制

AVR 板卡与 SPS30 固件版本 > 1.0 并非完全兼容：

• readSerialNumber被限制为 20 字节（对几乎所有传感器而言已足够）；
• Float 测量模式不可用，这是 Wire 库的局限性所致，请改用 Uint16 测量模式。

这一限制在库实现中也有直接体现：SensirionI2cSps30.cpp 中，当编译目标为__AVR__且请求SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT时会打印警告并触发assert(false)。因此 AVR 板卡（Uno/Nano/Micro/Mega）应使用exampleUsage示例。

深入库 API：命令集与调用要点

传感器命令 ID 一览

从 SensirionI2cSps30.h 可看到库封装的完整命令集：

两种测量输出格式

库定义了两种输出格式枚举（SensirionI2cSps30.h）：

• SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT（=768）：大端 IEEE754 浮点，readMeasurementValuesFloat()使用，接收 60 字节；
• SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_UINT16（=1280）：大端无符号 16 位整数，readMeasurementValuesUint16()使用，接收 30 字节。

两种格式都输出相同的 10 项指标（SensirionI2cSps30.h）：

测量模式下传感器每秒更新一次数据并置位 Data-Ready 标志；读取测量值命令会复位该标志。即使忽略该标志直接读取，命令也总是返回最新一次测量结果。

睡眠与唤醒时序

传感器在睡眠模式下 I²C 接口是被禁用的，唤醒需要特殊时序（SensirionI2cSps30.h）：

1. 首选方案：先在 SDA 线上发送一个低脉冲（I²C Start 条件后紧跟 Stop 条件）激活接口，随后100ms 内发送wakeUp()命令；
2. 若软件无法构造“Start+Stop”脉冲，可连续发送两次wakeUp()：第一次被忽略但会激活接口，第二次生效。

库中的wakeUpSequence()方法（SensirionI2cSps30.cpp）正是封装了连续两次wakeUp()的写法。Tasmota 驱动同样采用该策略（见下文）。

完整示例代码解读

Uint16 模式（exampleUsage）

exampleUsage.ino 的核心流程：

SensirionI2cSps30 sensor; // 全局传感器对象 void setup() { Serial.begin(115200); while (!Serial) { delay(100); } Wire.begin(); sensor.begin(Wire, SPS30_I2C_ADDR_69); // 绑定 I²C 总线与地址 0x69 sensor.stopMeasurement(); // 先停止，确保处于 Idle 模式 int8_t serialNumber[32] = {0}; int8_t productType[8] = {0}; sensor.readSerialNumber(serialNumber, 32); sensor.readProductType(productType, 8); // 打印序列号与产品类型 sensor.startMeasurement(SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_UINT16); delay(100); } void loop() { uint16_t dataReadyFlag = 0; uint16_t mc1p0, mc2p5, mc4p0, mc10p0; uint16_t nc0p5, nc1p0, nc2p5, nc4p0, nc10p0, typicalParticleSize; delay(1000); // 每秒采样一次 error = sensor.readDataReadyFlag(dataReadyFlag); if (error != NO_ERROR) { /* 打印 errorToString 信息并返回 */ } error = sensor.readMeasurementValuesUint16(mc1p0, mc2p5, mc4p0, mc10p0, nc0p5, nc1p0, nc2p5, nc4p0, nc10p0, typicalParticleSize); if (error != NO_ERROR) { /* 打印错误并返回 */ } Serial.println(...); // 以制表符分隔打印全部 10 项数据 }

编码要点：

• 每个 API 均返回int16_t错误码，0（NO_ERROR）表示成功，可通过errorToString()将错误码转为可读文本；
• exampleUsageFloat.ino除将输出格式改为SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT、变量类型改为float、读取函数换为readMeasurementValuesFloat()外，流程完全一致；
• 示例中#ifdef NO_ERROR / #undef NO_ERROR / #define NO_ERROR 0的预处理写法，是为了消除其他库对NO_ERROR宏的重定义冲突。

Tasmota 固件中的 SPS30 集成

作为 ESP8266/ESP32 的开源替代固件，Tasmota 已将本驱动库用于其传感器框架，实现在 xsns_44_sps30.ino 中。

启用驱动

在编译配置中取消注释宏即可启用（tasmota_configurations.h）：

//#define USE_SPS30 // [I2cDriver30] Enable Sensiron SPS30 particle sensor (I2C address 0x69) (+1.7 code)

对应 ESP32 配置见 tasmota_configurations_ESP32.h，用户自定义配置可写在 my_user_config.h。从源码结构看，该驱动在 Tasmota 的 I2C 驱动编号为XI2C_30，可通过I2cDriver30控制指令在运行时开关。

驱动初始化流程

Sps30Init() 展示了严谨的上电序列，可直接借鉴到自己的工程：

1. PowerOnDelay(60)—— 等待传感器上电启动完成（手册要求上电到 I²C 可通信的启动时间）；
2. 在多个 I²C 总线上尝试注册设备地址SPS30_I2C_ADDR_69；
3. sps30.begin(I2cGetWire(bus), SPS30_I2C_ADDR_69)绑定总线；
4. sps30.deviceReset()—— 软复位到确定的 Idle 状态；
5. sps30.readFirmwareVersion()与sps30.readSerialNumber()—— 校验通信并获取身份信息；
6. sps30.startMeasurement(SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT)—— 以 Float 模式启动测量；
7. 成功后通过I2cSetActiveFound(SPS30_I2C_ADDR_69, "SPS30", bus)上报发现设备。

数据采集与 MQTT/Web 呈现

Sps30EverySecond() 每 10 秒调用一次readMeasurementValuesFloat()，将 10 项测量值存入内部结构体；Sps30Show()则负责以 JSON 形式（{"SPS30":{"PM1_0":..,"PM2_5":..,"PM4_0":..,"PM10":..,"NCPM0_5":..,...,"TYPSIZ":..}}）追加到遥测消息，并同步渲染到 Web 传感器页面。Tasmota 会将 PM 质量浓度直接输出为 µg/m³，粒子数浓度输出为 #/cm³。

驱动还内置了自动清洁调度：累计运行7*24小时后自动执行一次sps30.startFanCleaning()，并通过 MQTT 发布"SPS30":"FanCleaning"事件。

控制命令

通过控制台或 MQTT 可下发Sensor44命令（Sps30Command()）：

Tasmota 驱动还提供了两个可选编译宏：SPS30_ENABLE_SLEEP（启用睡眠/唤醒以降低非测量期功耗）与SPS30_PARTS_PER_DECILITER（将粒子数浓度以每分升计数 ppd 输出，即 #/cm³ × 100）。启用睡眠后，Tasmota 会在设备重启前通过FUNC_SAVE_BEFORE_RESTART调用Sps30Wakeup()唤醒传感器，避免重启后无法识别。

常见问题排查

• 读取始终失败/超时：确认 SEL 引脚已接 GND（悬空为 UART 模式）、VDD 为 5V、SDA/SCL 与板卡 I²C 引脚对应正确；
• AVR 板卡断言失败：exampleUsageFloat在 AVR 上不可用，请改用 Uint16 模式；
• 传感器无响应但接线无误：对设备执行一次deviceReset()软复位，使传感器回到确定的 Idle 状态；若处于睡眠模式，需先执行wakeUpSequence()或连续两次wakeUp()激活 I²C 接口；
• 上电后立即通信失败：务必等待手册规定的上电启动时间（Tasmota 中为PowerOnDelay(60)）；
• 长时间运行数据异常：执行startFanCleaning()手动清洁光学仓，或检查readAutoCleaningInterval()返回的自动清洁间隔是否符合预期（可通过writeAutoCleaningInterval()调整，单位为秒）。

延伸阅读

• 驱动库完整文档：README.md；版本变更记录见 CHANGELOG.md；
• 库 API 头文件：SensirionI2cSps30.h，实现源码：SensirionI2cSps30.cpp；
• Tasmota 端集成源码：xsns_44_sps30.ino；
• 其余 I²C 设备驱动的启用方式可参考 tasmota_configurations.h 中的USE_宏体系。

【免费下载链接】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