sgp40 - Driver for SGP40 Indoor Air Quality Sensor for VOC Measurements

group sgp40

Library for calculating concentration of volatile organic compounds.

ESP-IDF driver for SGP40 Indoor Air Quality Sensor for VOC Measurements.

Copyright (c) 2020 Ruslan V. Uss unclerus@gmail.com

BSD Licensed as described in the file LICENSE

Defines

F16(x)
VocAlgorithm_SAMPLING_INTERVAL
VocAlgorithm_INITIAL_BLACKOUT
VocAlgorithm_VOC_INDEX_GAIN
VocAlgorithm_SRAW_STD_INITIAL
VocAlgorithm_SRAW_STD_BONUS
VocAlgorithm_TAU_MEAN_VARIANCE_HOURS
VocAlgorithm_TAU_INITIAL_MEAN
VocAlgorithm_INIT_DURATION_MEAN
VocAlgorithm_INIT_TRANSITION_MEAN
VocAlgorithm_TAU_INITIAL_VARIANCE
VocAlgorithm_INIT_DURATION_VARIANCE
VocAlgorithm_INIT_TRANSITION_VARIANCE
VocAlgorithm_GATING_THRESHOLD
VocAlgorithm_GATING_THRESHOLD_INITIAL
VocAlgorithm_GATING_THRESHOLD_TRANSITION
VocAlgorithm_GATING_MAX_DURATION_MINUTES
VocAlgorithm_GATING_MAX_RATIO
VocAlgorithm_SIGMOID_L
VocAlgorithm_SIGMOID_K
VocAlgorithm_SIGMOID_X0
VocAlgorithm_VOC_INDEX_OFFSET_DEFAULT
VocAlgorithm_LP_TAU_FAST
VocAlgorithm_LP_TAU_SLOW
VocAlgorithm_LP_ALPHA
VocAlgorithm_PERSISTENCE_UPTIME_GAMMA
VocAlgorithm_MEAN_VARIANCE_ESTIMATOR__GAMMA_SCALING
VocAlgorithm_MEAN_VARIANCE_ESTIMATOR__FIX16_MAX
SGP40_ADDR

I2C address.

Typedefs

typedef int32_t fix16_t

Functions

void VocAlgorithm_init(VocAlgorithmParams *params)

Initialize the VOC algorithm parameters.

Call this once at the beginning or whenever the sensor stopped measurements.

Parameters:

params – Pointer to the VocAlgorithmParams struct

void VocAlgorithm_get_states(VocAlgorithmParams *params, int32_t *state0, int32_t *state1)

Get current algorithm states.

Retrieved values can be used in VocAlgorithm_set_states() to resume operation after a short interruption, skipping initial learning phase. This feature can only be used after at least 3 hours of continuous operation.

Parameters:
  • params – Pointer to the VocAlgorithmParams struct

  • state0 – State0 to be stored

  • state1 – State1 to be stored

void VocAlgorithm_set_states(VocAlgorithmParams *params, int32_t state0, int32_t state1)

Set previously retrieved algorithm states to resume operation after a short interruption, skipping initial learning phase.

This feature should not be used after inerruptions of more than 10 minutes. Call this once after VocAlgorithm_init() and the optional VocAlgorithm_set_tuning_parameters(), if desired. Otherwise, the algorithm will start with initial learning phase.

Parameters:
  • params – Pointer to the VocAlgorithmParams struct

  • state0 – State0 to be restored

  • state1 – State1 to be restored

void VocAlgorithm_set_tuning_parameters(VocAlgorithmParams *params, int32_t voc_index_offset, int32_t learning_time_hours, int32_t gating_max_duration_minutes, int32_t std_initial)

Set parameters to customize the VOC algorithm.

Call this once after VocAlgorithm_init(), if desired. Otherwise, the default values will be used.

Parameters:
  • params – Pointer to the VocAlgorithmParams struct

  • voc_index_offset – VOC index representing typical (average) conditions. Range 1..250, default 100

  • learning_time_hours – Time constant of long-term estimator. Past events will be forgotten after about twice the learning time. Range 1..72 [hours], default 12 [hours]

  • gating_max_duration_minutes – Maximum duration of gating (freeze of estimator during high VOC index signal). 0 (no gating) or range 1..720 [minutes], default 180 [minutes]

  • 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..500, default 50

void VocAlgorithm_process(VocAlgorithmParams *params, int32_t sraw, int32_t *voc_index)

Calculate the VOC index value from the raw sensor value.

Parameters:
  • params – Pointer to the VocAlgorithmParams struct

  • sraw – Raw value from the SGP40 sensor

  • voc_index – Calculated VOC index value from the raw sensor value. Zero during initial blackout period and 1..500 afterwards

esp_err_t sgp40_init_desc(sgp40_t *dev, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio)

Initialize device descriptor.

Parameters:
  • dev – Device descriptor

  • port – I2C port

  • sda_gpio – SDA GPIO

  • scl_gpio – SCL GPIO

Returns:

ESP_OK on success

esp_err_t sgp40_free_desc(sgp40_t *dev)

Free device descriptor.

Parameters:

dev – Device descriptor

Returns:

ESP_OK on success

esp_err_t sgp40_init(sgp40_t *dev)

Read device information, initialize the VOC algorithm.

Parameters:

dev – Device descriptor

Returns:

ESP_OK on success

esp_err_t sgp40_soft_reset(sgp40_t *dev)

Reset device, than put it to idle mode.

Parameters:

dev – Device descriptor

Returns:

ESP_OK on success

esp_err_t sgp40_self_test(sgp40_t *dev)

Perform a self-test.

Parameters:

dev – Device descriptor

Returns:

ESP_OK on success

esp_err_t sgp40_heater_off(sgp40_t *dev)

Turn hotplate off, stop measurement and put device to idle mode.

Parameters:

dev – Device descriptor

Returns:

ESP_OK on success

esp_err_t sgp40_measure_raw(sgp40_t *dev, float humidity, float temperature, uint16_t *raw)

Perform a measurement.

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[out] Raw value, proportional to the logarithm of the resistance of the sensing element

Returns:

ESP_OK on success

esp_err_t sgp40_measure_voc(sgp40_t *dev, float humidity, float temperature, int32_t *voc_index)

Perform a measurement and update VOC index.

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

Returns:

struct VocAlgorithmParams
#include <sensirion_voc_algorithm.h>

Struct to hold all the states of the VOC algorithm.

struct sgp40_t
#include <sgp40.h>

Device descriptor.