sgp40: Driver for SGP40 / SGP41 Indoor Air Quality Sensor for VOC (& NOx) Measurements
Defines
- GASINDEXALGORITHM_H_
- LIBRARY_VERSION_NAME
- GasIndexAlgorithm_ALGORITHM_TYPE_VOC
- GasIndexAlgorithm_ALGORITHM_TYPE_NOX
- GasIndexAlgorithm_DEFAULT_SAMPLING_INTERVAL
- GasIndexAlgorithm_INITIAL_BLACKOUT
- GasIndexAlgorithm_INDEX_GAIN
- GasIndexAlgorithm_SRAW_STD_INITIAL
- GasIndexAlgorithm_SRAW_STD_BONUS_VOC
- GasIndexAlgorithm_SRAW_STD_NOX
- GasIndexAlgorithm_TAU_MEAN_HOURS
- GasIndexAlgorithm_TAU_VARIANCE_HOURS
- GasIndexAlgorithm_TAU_INITIAL_MEAN_VOC
- GasIndexAlgorithm_TAU_INITIAL_MEAN_NOX
- GasIndexAlgorithm_INIT_DURATION_MEAN_VOC
- GasIndexAlgorithm_INIT_DURATION_MEAN_NOX
- GasIndexAlgorithm_INIT_TRANSITION_MEAN
- GasIndexAlgorithm_TAU_INITIAL_VARIANCE
- GasIndexAlgorithm_INIT_DURATION_VARIANCE_VOC
- GasIndexAlgorithm_INIT_DURATION_VARIANCE_NOX
- GasIndexAlgorithm_INIT_TRANSITION_VARIANCE
- GasIndexAlgorithm_GATING_THRESHOLD_VOC
- GasIndexAlgorithm_GATING_THRESHOLD_NOX
- GasIndexAlgorithm_GATING_THRESHOLD_INITIAL
- GasIndexAlgorithm_GATING_THRESHOLD_TRANSITION
- GasIndexAlgorithm_GATING_VOC_MAX_DURATION_MINUTES
- GasIndexAlgorithm_GATING_NOX_MAX_DURATION_MINUTES
- GasIndexAlgorithm_GATING_MAX_RATIO
- GasIndexAlgorithm_SIGMOID_L
- GasIndexAlgorithm_SIGMOID_K_VOC
- GasIndexAlgorithm_SIGMOID_X0_VOC
- GasIndexAlgorithm_SIGMOID_K_NOX
- GasIndexAlgorithm_SIGMOID_X0_NOX
- GasIndexAlgorithm_VOC_INDEX_OFFSET_DEFAULT
- GasIndexAlgorithm_NOX_INDEX_OFFSET_DEFAULT
- GasIndexAlgorithm_LP_TAU_FAST
- GasIndexAlgorithm_LP_TAU_SLOW
- GasIndexAlgorithm_LP_ALPHA
- GasIndexAlgorithm_VOC_SRAW_MINIMUM
- GasIndexAlgorithm_NOX_SRAW_MINIMUM
- GasIndexAlgorithm_PERSISTENCE_UPTIME_GAMMA
- GasIndexAlgorithm_TUNING_INDEX_OFFSET_MIN
- GasIndexAlgorithm_TUNING_INDEX_OFFSET_MAX
- GasIndexAlgorithm_TUNING_LEARNING_TIME_OFFSET_HOURS_MIN
- GasIndexAlgorithm_TUNING_LEARNING_TIME_OFFSET_HOURS_MAX
- GasIndexAlgorithm_TUNING_LEARNING_TIME_GAIN_HOURS_MIN
- GasIndexAlgorithm_TUNING_LEARNING_TIME_GAIN_HOURS_MAX
- GasIndexAlgorithm_TUNING_GATING_MAX_DURATION_MINUTES_MIN
- GasIndexAlgorithm_TUNING_GATING_MAX_DURATION_MINUTES_MAX
- GasIndexAlgorithm_TUNING_STD_INITIAL_MIN
- GasIndexAlgorithm_TUNING_STD_INITIAL_MAX
- GasIndexAlgorithm_TUNING_GAIN_FACTOR_MIN
- GasIndexAlgorithm_TUNING_GAIN_FACTOR_MAX
- GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__GAMMA_SCALING
- GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__ADDITIONAL_GAMMA_MEAN_SCALING
- GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__FIX16_MAX
Functions
- void GasIndexAlgorithm_init(GasIndexAlgorithmParams *params, int32_t algorithm_type)
Initialize the gas index algorithm parameters for the specified algorithm type and reset its internal states.
Call this once at the beginning.
- Parameters:
params – Pointer to the GasIndexAlgorithmParams struct
algorithm_type – 0 (GasIndexAlgorithm_ALGORITHM_TYPE_VOC) for VOC or 1 (GasIndexAlgorithm_ALGORITHM_TYPE_NOX) for NOx
- void GasIndexAlgorithm_init_with_sampling_interval(GasIndexAlgorithmParams *params, int32_t algorithm_type, float sampling_interval)
Initialize the gas index algorithm parameters for the specified algorithm type and reset its internal states.
Call this once at the beginning.
- Parameters:
params – Pointer to the GasIndexAlgorithmParams struct
algorithm_type – 0 (GasIndexAlgorithm_ALGORITHM_TYPE_VOC) for VOC or 1 (GasIndexAlgorithm_ALGORITHM_TYPE_NOX) for NOx
sampling_interval – The sampling interval in seconds the algorithm is called. Tested for 1s and 10s.
- void GasIndexAlgorithm_reset(GasIndexAlgorithmParams *params)
Reset the internal states of the gas index algorithm.
Previously set tuning parameters are preserved. Call this when resuming operation after a measurement interruption.
- Parameters:
params – Pointer to the GasIndexAlgorithmParams struct
- void GasIndexAlgorithm_get_states(const GasIndexAlgorithmParams *params, float *state0, float *state1)
Get current algorithm states.
Retrieved values can be used in GasIndexAlgorithm_set_states() to resume operation after a short interruption, skipping initial learning phase. NOTE: This feature can only be used for VOC algorithm type and after at least 3 hours of continuous operation.
- Parameters:
params – Pointer to the GasIndexAlgorithmParams struct
state0 – State0 to be stored
state1 – State1 to be stored
- void GasIndexAlgorithm_set_states(GasIndexAlgorithmParams *params, float state0, float state1)
Set previously retrieved algorithm states to resume operation after a short interruption, skipping initial learning phase.
This feature should not be used after interruptions of more than 10 minutes. Call this once after GasIndexAlgorithm_init() or GasIndexAlgorithm_reset() and the optional GasIndexAlgorithm_set_tuning_parameters(), if desired. Otherwise, the algorithm will start with initial learning phase. NOTE: This feature can only be used for VOC algorithm type.
- Parameters:
params – Pointer to the GasIndexAlgorithmParams struct
state0 – State0 to be restored
state1 – State1 to be restored
- void GasIndexAlgorithm_set_tuning_parameters(GasIndexAlgorithmParams *params, int32_t index_offset, int32_t learning_time_offset_hours, int32_t learning_time_gain_hours, int32_t gating_max_duration_minutes, int32_t std_initial, int32_t gain_factor)
Set parameters to customize the gas index algorithm.
Call this once after GasIndexAlgorithm_init() and before optional GasIndexAlgorithm_set_states(), if desired. Otherwise, the default values will be used.
- Parameters:
params – Pointer to the GasIndexAlgorithmParams struct
index_offset – Gas index representing typical (average) conditions. Range 1..250, default 100 for VOC and 1 for NOx
learning_time_offset_hours – Time constant of long-term estimator for offset. Past events will be forgotten after about twice the learning time. Range 1..1000 [hours], default 12 [hours]
learning_time_gain_hours – Time constant of long-term estimator for gain. Past events will be forgotten after about twice the learning time. Range 1..1000 [hours], default 12 [hours] NOTE: This value is not relevant for NOx algorithm type
gating_max_duration_minutes – Maximum duration of gating (freeze of estimator during high gas index signal). 0 (no gating) or range 1..3000 [minutes], default 180 [minutes] for VOC and 720 [minutes] for NOx
std_initial – Initial estimate for standard deviation. Lower value boosts events during initial learning period, but may result in larger device-to-device variations. Range 10..5000, default 50 NOTE: This value is not relevant for NOx algorithm type
gain_factor – Factor used to scale applied gain value when calculating gas index. Range 1..1000, default 230
- void GasIndexAlgorithm_get_tuning_parameters(const GasIndexAlgorithmParams *params, int32_t *index_offset, int32_t *learning_time_offset_hours, int32_t *learning_time_gain_hours, int32_t *gating_max_duration_minutes, int32_t *std_initial, int32_t *gain_factor)
Get current parameters to customize the gas index algorithm.
Refer to GasIndexAlgorithm_set_tuning_parameters() for description of the parameters.
- void GasIndexAlgorithm_get_sampling_interval(const GasIndexAlgorithmParams *params, float *sampling_interval)
Get the sampling interval parameter used by the algorithm.
- void GasIndexAlgorithm_process(GasIndexAlgorithmParams *params, int32_t sraw, int32_t *gas_index)
Calculate the gas index value from the raw sensor value.
- Parameters:
params – Pointer to the GasIndexAlgorithmParams struct
sraw – Raw value from the SGP4x sensor
gas_index – Calculated gas index value from the raw sensor value. Zero during initial blackout period and 1..500 afterwards
- struct GasIndexAlgorithmParams
#include <sensirion_gas_index_algorithm.h>Struct to hold all parameters and states of the gas algorithm.
Public Members
- int mAlgorithm_Type
- float mSamplingInterval
- float mIndex_Offset
- int32_t mSraw_Minimum
- float mGating_Max_Duration_Minutes
- float mInit_Duration_Mean
- float mInit_Duration_Variance
- float mGating_Threshold
- float mIndex_Gain
- float mTau_Mean_Hours
- float mTau_Variance_Hours
- float mSraw_Std_Initial
- float mUptime
- float mSraw
- float mGas_Index
- bool m_Mean_Variance_Estimator___Initialized
- float m_Mean_Variance_Estimator___Mean
- float m_Mean_Variance_Estimator___Sraw_Offset
- float m_Mean_Variance_Estimator___Std
- float m_Mean_Variance_Estimator___Gamma_Mean
- float m_Mean_Variance_Estimator___Gamma_Variance
- float m_Mean_Variance_Estimator___Gamma_Initial_Mean
- float m_Mean_Variance_Estimator___Gamma_Initial_Variance
- float m_Mean_Variance_Estimator__Gamma_Mean
- float m_Mean_Variance_Estimator__Gamma_Variance
- float m_Mean_Variance_Estimator___Uptime_Gamma
- float m_Mean_Variance_Estimator___Uptime_Gating
- float m_Mean_Variance_Estimator___Gating_Duration_Minutes
- float m_Mean_Variance_Estimator___Sigmoid__K
- float m_Mean_Variance_Estimator___Sigmoid__X0
- float m_Mox_Model__Sraw_Std
- float m_Mox_Model__Sraw_Mean
- float m_Sigmoid_Scaled__K
- float m_Sigmoid_Scaled__X0
- float m_Sigmoid_Scaled__Offset_Default
- float m_Adaptive_Lowpass__A1
- float m_Adaptive_Lowpass__A2
- bool m_Adaptive_Lowpass___Initialized
- float m_Adaptive_Lowpass___X1
- float m_Adaptive_Lowpass___X2
- float m_Adaptive_Lowpass___X3
ESP-IDF driver for SGP40 / SGP41 Indoor Air Quality Sensor for VOC (& NOx) Measurements.
Copyright (c) 2020 Ruslan V. Uss unclerus@gmail.com Copyright (c) 2025 Michael Hegel mrbotastic@gmail.com
BSD Licensed as described in the file LICENSE
Defines
- SGP4X_ADDR
I2C address.
Enums
Functions
- esp_err_t sgp4x_init_desc(sgp4x_t *dev, sgp4x_type_t type, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio)
Initialize device descriptor.
- Parameters:
dev – Device descriptor
type – Device type
port – I2C port
sda_gpio – SDA GPIO
scl_gpio – SCL GPIO
- Returns:
ESP_OKon success- Returns:
ESP_ERR_INVALID_ARGif the type is neitherSGP4x_TYPE_SGP40norSGP4x_TYPE_SGP41, or if the arguments are invalid- Returns:
ESP_ERR_NO_MEMif the device mutex could not be created
- esp_err_t sgp4x_free_desc(sgp4x_t *dev)
Free device descriptor.
- Parameters:
dev – Device descriptor
- Returns:
ESP_OKon success- Returns:
ESP_ERR_INVALID_ARGif the descriptor is not valid
- esp_err_t sgp4x_init(sgp4x_t *dev)
Read the device information and initialize the gas index algorithm.
Reads the serial number and the featureset, then prepares the VOC index algorithm and, for the SGP41, the NOx index algorithm. Must be called before any measurement.
- Parameters:
dev – Device descriptor
- Returns:
ESP_OKon success- Returns:
ESP_ERR_NOT_SUPPORTEDif the device type is unknown- Returns:
ESP_ERR_TIMEOUTif the device does not respond- Returns:
ESP_ERR_INVALID_CRCif the response is corrupted
- esp_err_t sgp4x_soft_reset(sgp4x_t *dev)
Reset the sensor and put it back to idle mode.
The datasheets describe
0x0006as an I2C general call that resets every device on the bus. Here the command is sent to the device address, so the other devices are not affected.
- Parameters:
dev – Device descriptor
- Returns:
ESP_OKon success- Returns:
ESP_ERR_TIMEOUTif the device does not respond
- esp_err_t sgp4x_self_test(sgp4x_t *dev)
Perform a built-in self-test.
The test takes 250 ms on the SGP40 and 320 ms on the SGP41. Should not be called during the conditioning on the SGP41.
- Parameters:
dev – Device descriptor
- Returns:
ESP_OKif the test passed- Returns:
ESP_FAILif the test failed- Returns:
ESP_ERR_NOT_SUPPORTEDif the device type is unknown- Returns:
ESP_ERR_TIMEOUTif the device does not respond
- esp_err_t sgp4x_heater_off(sgp4x_t *dev)
Turn the hotplate off, stop the measurement and put the device to idle mode.
On the SGP41 the conditioning must be done before resuming the measurements.
- Parameters:
dev – Device descriptor
- Returns:
ESP_OKon success- Returns:
ESP_ERR_TIMEOUTif the device does not respond
- esp_err_t sgp4x_start_conditioning(sgp4x_t *dev, float humidity, float temperature, uint16_t *raw_voc)
Start the conditioning.
SGP41 only
The conditioning is required after each restart of the sensor and after the hotplate has been switched off. According to the datasheet it must run for 10 seconds, and 10 seconds must not be exceeded to avoid damage to the sensing material. The conditioning is stopped by calling one of the measure functions.
- Parameters:
dev – Device descriptor
humidity – Relative humidity, percents. Use NaN if you want uncompensated measurement
temperature – Temperature, degrees Celsius. Use NaN if you want uncompensated measurement
raw_voc – [out] Raw value, proportional to the logarithm of the resistance of the sensing element
- Returns:
ESP_OKon success- Returns:
ESP_ERR_NOT_SUPPORTEDif the device is not an SGP41- Returns:
ESP_ERR_INVALID_ARGif the humidity or the temperature is out of the range0..100% or-45..130°C- Returns:
ESP_ERR_TIMEOUTif the device does not respond
- esp_err_t sgp4x_measure_raw(sgp4x_t *dev, float humidity, float temperature, uint16_t *raw_voc, uint16_t *raw_nox)
Perform a measurement.
Measures the raw signals. On the SGP41 both the VOC and the NOx values are read in a single command.
- Parameters:
dev – Device descriptor
humidity – Relative humidity, percents. Use NaN if you want uncompensated measurement
temperature – Temperature, degrees Celsius. Use NaN if you want uncompensated measurement
raw_voc – [out] Raw value, proportional to the logarithm of the resistance of the sensing element
raw_nox – [out] Raw value, proportional to the logarithm of the resistance of the sensing element. SGP41 only, must not be NULL on the SGP41
- Returns:
ESP_OKon success- Returns:
ESP_ERR_INVALID_ARGif the humidity or the temperature is out of the range0..100% or-45..130°C, or if a required pointer is NULL- Returns:
ESP_ERR_NOT_SUPPORTEDif the device type is unknown- Returns:
ESP_ERR_TIMEOUTif the device does not respond- Returns:
ESP_ERR_INVALID_CRCif the response is corrupted
- esp_err_t sgp4x_measure_index(sgp4x_t *dev, float humidity, float temperature, int32_t *voc_index, int32_t *nox_index)
Perform a measurement and update the gas indices.
Measures the raw signals and feeds them to the gas index algorithm. The measurement and the algorithm update are protected by the device mutex, so the descriptor can be used by several tasks. The calls should be made once per second: the algorithm expects a constant sampling interval.
- Parameters:
dev – Device descriptor
humidity – Relative humidity, percents. Use NaN if you want uncompensated measurement
temperature – Temperature, degrees Celsius. Use NaN if you want uncompensated measurement
voc_index – [out] Calculated VOC index
nox_index – [out] Calculated NOx index. SGP41 only, must not be NULL on the SGP41
- Returns:
ESP_OKon success- Returns:
ESP_ERR_INVALID_ARGif the humidity or the temperature is out of the range0..100% or-45..130°C, or if a required pointer is NULL- Returns:
ESP_ERR_NOT_SUPPORTEDif the device type is unknown- Returns:
ESP_ERR_TIMEOUTif the device does not respond- Returns:
ESP_ERR_INVALID_CRCif the response is corrupted
- struct sgp4x_t
#include <sgp4x.h>Device descriptor.
Public Members
- i2c_dev_t i2c_dev
I2C device descriptor.
- sgp4x_type_t type
Device type (SGP40 or SGP41)
- uint16_t serial[3]
Device serial number (3 words)
- uint16_t featureset
Device featureset version.
- GasIndexAlgorithmParams voc
VOC index algorithm parameters.
- GasIndexAlgorithmParams nox
NOx index algorithm parameters (SGP41 only)