sps30.h

Go to the documentation of this file.

/*
 * sps30.h
 *
 *  Created on: 2. 1. 2026
 *      Author: Milan
 *
 *  sensor SPS30 dust - particles  SPS30Datasheet.pdf
 *  https://sensirion.com/products/catalog/SPS30
 *  https://cdn.sparkfun.com/assets/2/d/2/a/6/Sensirion_SPS30_Particulate_Matter_Sensor_v0.9_D1__1_.pdf
 *
 *  SPS30 can be directly connected to SDA/SCL (I2C) or through HVAC click module
 *  this sensor unlike others runs on 5V
 *
 *  gemini: https://gemini.google.com/share/24ed9f3930ce
 */
 
#ifndef INC_SPS30_H_
#define INC_SPS30_H_
 
#include "mysensors_def.h"
 
#ifdef SENSOR_SPS30
 
#include "stm32wlxx_hal.h"
 
/*
 1. Mass Concentration ([μg/m3])
 
 These values represent the total weight of particles in a cubic meter of air. This is the standard metric used by government air quality indexes (AQI).
 mass_pm1_0: Ultra-fine particles smaller than 1.0 micrometers.
 mass_pm2_5: Fine particles smaller than 2.5 micrometers. This is the most critical health metric as these particles can enter the lungs and bloodstream.
 mass_pm4_0: Particles smaller than 4.0 micrometers.
 mass_pm10_0: Coarse particles smaller than 10 micrometers (e.g., dust, pollen).
 
 2. Number Concentration ([n/cm3])
 
 These values represent the "count" or quantity of individual particles found in a cubic centimeter of air.
 This is often more sensitive than mass for detecting the start of a fire or very fine smoke.
 num_pm0_5: Count of particles between 0.3 and 0.5 micrometers.
 num_pm1_0: Count of particles up to 1.0 micrometers.
 num_pm2_5: Count of particles up to 2.5 micrometers.
 num_pm4_0: Count of particles up to 4.0 micrometers.
 num_pm10_0: Count of particles up to 10 micrometers.
 
 3. Particle Size ([\mu m])
 typical_particle_size: This is the average diameter of the particles currently being detected.
 Low values (~0.4 - 1.0) usually indicate combustion smoke or fumes.
 High values (>2.0) usually indicate heavy dust or pollen.
 
 Particle Type, Typical Size (μm),  Struct Variable
 Wildfire Smoke 0.4 – 0.7           "num_pm0_5, mass_pm1_0"
 Bacteria       0.3 – 10            "mass_pm2_5, num_pm2_5"
 Dust/Pollen        10 – 100            mass_pm10_0
 
 
 Summary of PM2.5 Brackets (μg/m3)
 Level              Range           Health Implications
 Good               0.0 – 12.0      Little to no risk.
 Moderate           12.1 – 35.4     Risk for very sensitive people.
 Unhealthy (Sens.)  35.5 – 55.4     General public not likely affected; sensitive groups at risk.
 Unhealthy          55.5 – 150.4    Everyone may begin to experience health effects.
 Very Unhealthy     150.5 – 250.4   Health alert: everyone may experience serious effects.
 */
// don't change order !!!
#pragma pack(1)
/**
 * @brief Measurement data produced by the SPS30 particulate matter sensor.
 *        Populated by sps30_Read(); check IsDataValid before using the values.
 *
 * Mass concentrations (µg/m³) reflect the total mass of particles per unit
 * volume, which is the metric used by government AQI indices.
 * Number concentrations (n/cm³) count individual particles and are more
 * sensitive for detecting early-stage smoke or combustion products.
 */
typedef struct
{
    float Mass_pm1_0;           /**< Mass concentration of PM1.0 particles (< 1 µm) in µg/m³ */
    float Mass_pm2_5;           /**< Mass concentration of PM2.5 particles (< 2.5 µm) in µg/m³ – primary health metric */
    float Mass_pm4_0;           /**< Mass concentration of PM4.0 particles (< 4 µm) in µg/m³ */
    float Mass_pm10_0;          /**< Mass concentration of PM10 particles (< 10 µm) in µg/m³ */
    float Num_pm0_5;            /**< Number concentration of particles 0.3–0.5 µm in n/cm³ */
    float Num_pm1_0;            /**< Number concentration of particles up to 1.0 µm in n/cm³ */
    float Num_pm2_5;            /**< Number concentration of particles up to 2.5 µm in n/cm³ */
    float Num_pm4_0;            /**< Number concentration of particles up to 4.0 µm in n/cm³ */
    float Num_pm10_0;           /**< Number concentration of particles up to 10 µm in n/cm³ */
    float Typical_particle_size; /**< Mean particle diameter in µm (low ≈ smoke/combustion, high ≈ dust/pollen) */
    int8_t IsDataValid;         /**< 1 – values are valid; 0 – last read failed or data not yet available */
} sps30_t;
#pragma pack()
 
/**
 * @brief Air Quality Index (AQI) level based on PM2.5 mass concentration.
 *        Follows US EPA / WHO PM2.5 breakpoints (µg/m³).
 */
typedef enum
{
    AQI_GOOD = 0,              /**< 0.0 – 12.0 µg/m³  – little or no health risk */
    AQI_MODERATE,              /**< 12.1 – 35.4 µg/m³ – acceptable; some risk for very sensitive individuals */
    AQI_UNHEALTHY_SENSITIVE,   /**< 35.5 – 55.4 µg/m³ – sensitive groups (asthma, heart disease) may be affected */
    AQI_UNHEALTHY,             /**< 55.5 – 150.4 µg/m³ – everyone may begin to experience health effects */
    AQI_VERY_UNHEALTHY,        /**< 150.5 – 250.4 µg/m³ – health alert; serious effects possible for all */
    AQI_HAZARDOUS              /**< > 250.4 µg/m³ – emergency conditions; entire population at risk */
} AQI_Level_t;
 
/** @brief Live measurement data from the SPS30 sensor; updated by sps30_Read(). */
extern sps30_t _sps30Data;
/** @brief Snapshot copy of the last completed SPS30 measurement; used for LoRaWAN transmission. */
extern sps30_t _bck_sps30Data;
 
/**
 * @brief Classify the current PM2.5 mass concentration according to the AQI scale.
 * @param label  Optional output pointer; if non-NULL, *label is set to a static
 *               human-readable string (e.g. "Good", "Moderate", "Hazardous").
 * @return The AQI_Level_t value corresponding to the PM2.5 concentration in
 *         _sps30Data.Mass_pm2_5.
 */
AQI_Level_t sps30_ClassifyPM25(char** label);
 
/**
 * @brief - check if SPS30 sensor is present
 * @param tryInit - in case sensor is not yet initialized, 1 - attempt to initialize again, 0 - no
 * @retval 1 - is present, 0 - is not
 */
int8_t sps30_Is(I2C_HandleTypeDef *hi2c, int8_t tryInit);
 
/**
 * @brief initialization of sensor sps30
 * @retval HAL_OK - sensor is present, HAL_ERROR - error
 */
HAL_StatusTypeDef sps30_Init(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief Turn on laser and fan to allow measurements
 * @retval HAL_OK, HAL_ERROR
 */
HAL_StatusTypeDef sps30_On(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief Turn off laser and fan to stop measurements
 * @retval HAL_OK, HAL_ERROR
 */
HAL_StatusTypeDef sps30_Off(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief Check if data is available
 * @retval HAL_OK, HAL_ERROR, HAL_BUSY
 */
HAL_StatusTypeDef sps30_IsDataReady(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief Read data if data is available
 */
HAL_StatusTypeDef sps30_Read(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief - helper to check if sensor is on or not
 */
HAL_StatusTypeDef sps30_IsOnOff(I2C_HandleTypeDef *hi2c, uint8_t *onOff);
 
/**
 * @brief manually start fan for cleaning, runs for about 10s
 * Note: The sensor will be busy cleaning for 10 seconds.
 * Data read during this time might be inconsistent due to high airflow.
 */
HAL_StatusTypeDef sps30_StartCleaning(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief interval for auto cleaning
 *
 */
HAL_StatusTypeDef sps30_GetAutoCleanInterval(I2C_HandleTypeDef *hi2c, uint32_t *interval_sec);
 
/**
 * @brief set interval for auto cleaning
 */
HAL_StatusTypeDef sps30_SetAutoCleanInterval(I2C_HandleTypeDef *hi2c, uint32_t interval_sec);
 
/**
 * @brief the sensor need to be cleaning
 * @retval 0 - no need, 1 - sensor is clearing
 */
int8_t sps30_Service(I2C_HandleTypeDef *hi2c);
 
/**
 * @brief log data to buffer
 */
void sps30_LogData(char* buf);
 
#endif
 
#endif /* INC_SPS30_H_ */