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

enum sgp4x_type_t

Device types.

Values:

enumerator SGP4x_TYPE_SGP40

SGP40.

enumerator SGP4x_TYPE_SGP41

SGP41.

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_OK on success

Returns:

ESP_ERR_INVALID_ARG if the type is neither SGP4x_TYPE_SGP40 nor SGP4x_TYPE_SGP41, or if the arguments are invalid

Returns:

ESP_ERR_NO_MEM if 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_OK on success

Returns:

ESP_ERR_INVALID_ARG if 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_OK on success

Returns:

ESP_ERR_NOT_SUPPORTED if the device type is unknown

Returns:

ESP_ERR_TIMEOUT if the device does not respond

Returns:

ESP_ERR_INVALID_CRC if 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 0x0006 as 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_OK on success

Returns:

ESP_ERR_TIMEOUT if 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_OK if the test passed

Returns:

ESP_FAIL if the test failed

Returns:

ESP_ERR_NOT_SUPPORTED if the device type is unknown

Returns:

ESP_ERR_TIMEOUT if 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_OK on success

Returns:

ESP_ERR_TIMEOUT if 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_OK on success

Returns:

ESP_ERR_NOT_SUPPORTED if the device is not an SGP41

Returns:

ESP_ERR_INVALID_ARG if the humidity or the temperature is out of the range 0..100 % or -45..130 °C

Returns:

ESP_ERR_TIMEOUT if 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_OK on success

Returns:

ESP_ERR_INVALID_ARG if the humidity or the temperature is out of the range 0..100 % or -45..130 °C, or if a required pointer is NULL

Returns:

ESP_ERR_NOT_SUPPORTED if the device type is unknown

Returns:

ESP_ERR_TIMEOUT if the device does not respond

Returns:

ESP_ERR_INVALID_CRC if 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_OK on success

Returns:

ESP_ERR_INVALID_ARG if the humidity or the temperature is out of the range 0..100 % or -45..130 °C, or if a required pointer is NULL

Returns:

ESP_ERR_NOT_SUPPORTED if the device type is unknown

Returns:

ESP_ERR_TIMEOUT if the device does not respond

Returns:

ESP_ERR_INVALID_CRC if 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)