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, Sensirion AG All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of Sensirion AG nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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

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.

Return

ESP_OK on success

Parameters

  • dev: Device descriptor

  • port: I2C port

  • sda_gpio: SDA GPIO

  • scl_gpio: SCL GPIO

esp_err_t sgp40_free_desc(sgp40_t *dev)

Free device descriptor.

Return

ESP_OK on success

Parameters

  • dev: Device descriptor

esp_err_t sgp40_init(sgp40_t *dev)

Read device information, initialize the VOC algorithm.

Return

ESP_OK on success

Parameters

  • dev: Device descriptor

esp_err_t sgp40_soft_reset(sgp40_t *dev)

Reset device, than put it to idle mode.

Return

ESP_OK on success

Parameters

  • dev: Device descriptor

esp_err_t sgp40_self_test(sgp40_t *dev)

Perform a self-test.

Return

ESP_OK on success

Parameters

  • dev: Device descriptor

esp_err_t sgp40_heater_off(sgp40_t *dev)

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

Return

ESP_OK on success

Parameters

  • dev: Device descriptor

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

Perform a measurement.

Return

ESP_OK on success

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

  • [out] raw: Raw value, proportional to the logarithm of the resistance of the sensing element

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

Perform a measurement and update VOC index.

Return

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

  • [out] voc_index: Calculated VOC index

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.