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

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.510µ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 Corearduino-core否则编译会因缺少SensirionCore.h而失败——驱动源文件顶部即#include SensirionCore.h与#include Wire.h。传感器接线引脚定义与板级接线表引脚功能与线色对照引脚线色名称说明备注1红VDD供电电压5V2绿SDAI²C 串行数据输入/输出3黄SCLI²C 串行时钟输入4蓝SEL接口选择拉至 GND 选择 I²C5黑GND地SPS30 引脚定义图关键提示推荐供电电压为5VVDD 支持 5V±10%该电压同时也是 SDA/SCL 的电平基准兼容 3.3V LVTTL 主控SEL 引脚必须拉低到 GND 才能启用 I²C 模式。悬空时传感器默认走 UART 接口此时 I²C 不可用接线时务必遵循“共地”原则VDD、GND 先连通后再接数据线。各开发板 I²C 接线速查表驱动库官方 README 给出了以下常见板卡的引脚对照SEL 均接 GND开发板VDDSDASCLSELGNDArduino Uno5VD18/SDAD19/SCLGNDGNDArduino Nano5VA4A5GNDGNDArduino Micro5VD2/SDA~D3/SCLGNDGNDArduino Mega 25605VD20/SDAD21/SCLGNDGNDESP32 DevKitC5VGPIO 21GPIO 22GNDGNDESP32 DevKitC 与 SPS30 的 I²C 接线示意说明ESP32 的默认 I²C 引脚为 GPIO21SDA/GPIO22SCL这与 Tasmota 在 ESP32 平台上的 I²C 默认配置一致。ESP8266 默认则为 GPIO4SDA/GPIO5SCL具体以所用固件配置为准。快速上手运行官方示例按上文完成库与依赖安装按上文接线表连接 SPS30 与开发板在 Arduino IDE 中打开示例工程File→Examples→Sensirion I2C SPS30→exampleUsage点击 IDE 的Upload按钮或Sketch→Upload烧录烧录完成后打开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 可看到库封装的完整命令集命令命令 ID对应方法说明开始测量0x10startMeasurement(format)仅可在 Idle 模式执行停止测量0x104stopMeasurement()返回 Idle 模式读数据就绪标志0x202readDataReadyFlag()0x0000 无新数据0x0001 有新数据读测量值0x300readMeasurementValuesUint16/Float()读取全部 10 项测量值睡眠0x1001sleep()仅可在 Idle 模式执行同时关闭 I²C 接口唤醒0x1103wakeUp()见下方唤醒时序说明手动风扇清洁0x5607startFanCleaning()仅可在测量模式执行读写自动清洁间隔0x8004read/writeAutoCleaningInterval()单位为秒读产品类型0xd002readProductType()8 字节 ASCII读序列号0xd033readSerialNumber()最长 32 字节 ASCII读固件版本0xd100readFirmwareVersion()major.minor读/清设备状态寄存器0xd206 / 0xd210readDeviceStatusRegister()/clearDeviceStatusRegister()详见数据手册 4.4 节设备软复位0xd304deviceReset()复位后等效于上电状态两种测量输出格式库定义了两种输出格式枚举SensirionI2cSps30.hSPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT768大端 IEEE754 浮点readMeasurementValuesFloat()使用接收 60 字节SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_UINT161280大端无符号 16 位整数readMeasurementValuesUint16()使用接收 30 字节。两种格式都输出相同的 10 项指标SensirionI2cSps30.h参数含义单位mc1p0 / mc2p5 / mc4p0 / mc10p0PM1.0 / PM2.5 / PM4.0 / PM10 质量浓度µg/m³nc0p5 / nc1p0 / nc2p5 / nc4p0 / nc10p0PM0.5 / PM1.0 / PM2.5 / PM4.0 / PM10 粒子数浓度#/cm³typicalParticleSize典型粒径µm测量模式下传感器每秒更新一次数据并置位 Data-Ready 标志读取测量值命令会复位该标志。即使忽略该标志直接读取命令也总是返回最新一次测量结果。睡眠与唤醒时序传感器在睡眠模式下 I²C 接口是被禁用的唤醒需要特殊时序SensirionI2cSps30.h首选方案先在 SDA 线上发送一个低脉冲I²C Start 条件后紧跟 Stop 条件激活接口随后100ms 内发送wakeUp()命令若软件无法构造“StartStop”脉冲可连续发送两次wakeUp()第一次被忽略但会激活接口第二次生效。库中的wakeUpSequence()方法SensirionI2cSps30.cpp正是封装了连续两次wakeUp()的写法。Tasmota 驱动同样采用该策略见下文。完整示例代码解读Uint16 模式exampleUsageexampleUsage.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错误码0NO_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() 展示了严谨的上电序列可直接借鉴到自己的工程PowerOnDelay(60)—— 等待传感器上电启动完成手册要求上电到 I²C 可通信的启动时间在多个 I²C 总线上尝试注册设备地址SPS30_I2C_ADDR_69sps30.begin(I2cGetWire(bus), SPS30_I2C_ADDR_69)绑定总线sps30.deviceReset()—— 软复位到确定的 Idle 状态sps30.readFirmwareVersion()与sps30.readSerialNumber()—— 校验通信并获取身份信息sps30.startMeasurement(SPS30_OUTPUT_FORMAT_OUTPUT_FORMAT_FLOAT)—— 以 Float 模式启动测量成功后通过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()命令行为Sensor44 0停止测量可配合睡眠模式省电Sensor44 1启动测量Sensor44 c立即执行一次风扇清洁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.cppTasmota 端集成源码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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考