environment4 2.1.0.0
Data Structures | Macros | Functions
sensirion_gas_index_algorithm.h File Reference
#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  GasIndexAlgorithmParams
 

Macros

#define bool   int
 
#define true   1
 
#define false   0
 
#define LIBRARY_VERSION_NAME   "3.2.0"
 
#define GasIndexAlgorithm_ALGORITHM_TYPE_VOC   (0)
 
#define GasIndexAlgorithm_ALGORITHM_TYPE_NOX   (1)
 
#define GasIndexAlgorithm_DEFAULT_SAMPLING_INTERVAL   (1.f)
 
#define GasIndexAlgorithm_INITIAL_BLACKOUT   (45.f)
 
#define GasIndexAlgorithm_INDEX_GAIN   (230.f)
 
#define GasIndexAlgorithm_SRAW_STD_INITIAL   (50.f)
 
#define GasIndexAlgorithm_SRAW_STD_BONUS_VOC   (220.f)
 
#define GasIndexAlgorithm_SRAW_STD_NOX   (2000.f)
 
#define GasIndexAlgorithm_TAU_MEAN_HOURS   (12.f)
 
#define GasIndexAlgorithm_TAU_VARIANCE_HOURS   (12.f)
 
#define GasIndexAlgorithm_TAU_INITIAL_MEAN_VOC   (20.f)
 
#define GasIndexAlgorithm_TAU_INITIAL_MEAN_NOX   (1200.f)
 
#define GasIndexAlgorithm_INIT_DURATION_MEAN_VOC   ((3600.f * 0.75f))
 
#define GasIndexAlgorithm_INIT_DURATION_MEAN_NOX   ((3600.f * 4.75f))
 
#define GasIndexAlgorithm_INIT_TRANSITION_MEAN   (0.01f)
 
#define GasIndexAlgorithm_TAU_INITIAL_VARIANCE   (2500.f)
 
#define GasIndexAlgorithm_INIT_DURATION_VARIANCE_VOC   ((3600.f * 1.45f))
 
#define GasIndexAlgorithm_INIT_DURATION_VARIANCE_NOX   ((3600.f * 5.70f))
 
#define GasIndexAlgorithm_INIT_TRANSITION_VARIANCE   (0.01f)
 
#define GasIndexAlgorithm_GATING_THRESHOLD_VOC   (340.f)
 
#define GasIndexAlgorithm_GATING_THRESHOLD_NOX   (30.f)
 
#define GasIndexAlgorithm_GATING_THRESHOLD_INITIAL   (510.f)
 
#define GasIndexAlgorithm_GATING_THRESHOLD_TRANSITION   (0.09f)
 
#define GasIndexAlgorithm_GATING_VOC_MAX_DURATION_MINUTES   ((60.f * 3.f))
 
#define GasIndexAlgorithm_GATING_NOX_MAX_DURATION_MINUTES   ((60.f * 12.f))
 
#define GasIndexAlgorithm_GATING_MAX_RATIO   (0.3f)
 
#define GasIndexAlgorithm_SIGMOID_L   (500.f)
 
#define GasIndexAlgorithm_SIGMOID_K_VOC   (-0.0065f)
 
#define GasIndexAlgorithm_SIGMOID_X0_VOC   (213.f)
 
#define GasIndexAlgorithm_SIGMOID_K_NOX   (-0.0101f)
 
#define GasIndexAlgorithm_SIGMOID_X0_NOX   (614.f)
 
#define GasIndexAlgorithm_VOC_INDEX_OFFSET_DEFAULT   (100.f)
 
#define GasIndexAlgorithm_NOX_INDEX_OFFSET_DEFAULT   (1.f)
 
#define GasIndexAlgorithm_LP_TAU_FAST   (20.0f)
 
#define GasIndexAlgorithm_LP_TAU_SLOW   (500.0f)
 
#define GasIndexAlgorithm_LP_ALPHA   (-0.2f)
 
#define GasIndexAlgorithm_VOC_SRAW_MINIMUM   (20000)
 
#define GasIndexAlgorithm_NOX_SRAW_MINIMUM   (10000)
 
#define GasIndexAlgorithm_PERSISTENCE_UPTIME_GAMMA   ((3.f * 3600.f))
 
#define GasIndexAlgorithm_TUNING_INDEX_OFFSET_MIN   (1)
 
#define GasIndexAlgorithm_TUNING_INDEX_OFFSET_MAX   (250)
 
#define GasIndexAlgorithm_TUNING_LEARNING_TIME_OFFSET_HOURS_MIN   (1)
 
#define GasIndexAlgorithm_TUNING_LEARNING_TIME_OFFSET_HOURS_MAX   (1000)
 
#define GasIndexAlgorithm_TUNING_LEARNING_TIME_GAIN_HOURS_MIN   (1)
 
#define GasIndexAlgorithm_TUNING_LEARNING_TIME_GAIN_HOURS_MAX   (1000)
 
#define GasIndexAlgorithm_TUNING_GATING_MAX_DURATION_MINUTES_MIN   (0)
 
#define GasIndexAlgorithm_TUNING_GATING_MAX_DURATION_MINUTES_MAX   (3000)
 
#define GasIndexAlgorithm_TUNING_STD_INITIAL_MIN   (10)
 
#define GasIndexAlgorithm_TUNING_STD_INITIAL_MAX   (5000)
 
#define GasIndexAlgorithm_TUNING_GAIN_FACTOR_MIN   (1)
 
#define GasIndexAlgorithm_TUNING_GAIN_FACTOR_MAX   (1000)
 
#define GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__GAMMA_SCALING   (64.f)
 
#define GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__ADDITIONAL_GAMMA_MEAN_SCALING    (8.f)
 
#define GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__FIX16_MAX   (32767.f)
 

Functions

void GasIndexAlgorithm_init (GasIndexAlgorithmParams *params, int32_t algorithm_type)
 
void GasIndexAlgorithm_init_with_sampling_interval (GasIndexAlgorithmParams *params, int32_t algorithm_type, float sampling_interval)
 
void GasIndexAlgorithm_reset (GasIndexAlgorithmParams *params)
 
void GasIndexAlgorithm_get_states (GasIndexAlgorithmParams *params, float *state0, float *state1)
 
void GasIndexAlgorithm_set_states (GasIndexAlgorithmParams *params, float state0, float state1)
 
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)
 
void GasIndexAlgorithm_get_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)
 
void GasIndexAlgorithm_get_sampling_interval (GasIndexAlgorithmParams *params, float *sampling_interval)
 
void GasIndexAlgorithm_process (GasIndexAlgorithmParams *params, int32_t sraw, int32_t *gas_index)
 

Macro Definition Documentation

◆ bool

#define bool   int

◆ false

#define false   0

◆ GasIndexAlgorithm_ALGORITHM_TYPE_NOX

#define GasIndexAlgorithm_ALGORITHM_TYPE_NOX   (1)

◆ GasIndexAlgorithm_ALGORITHM_TYPE_VOC

#define GasIndexAlgorithm_ALGORITHM_TYPE_VOC   (0)

◆ GasIndexAlgorithm_DEFAULT_SAMPLING_INTERVAL

#define GasIndexAlgorithm_DEFAULT_SAMPLING_INTERVAL   (1.f)

◆ GasIndexAlgorithm_GATING_MAX_RATIO

#define GasIndexAlgorithm_GATING_MAX_RATIO   (0.3f)

◆ GasIndexAlgorithm_GATING_NOX_MAX_DURATION_MINUTES

#define GasIndexAlgorithm_GATING_NOX_MAX_DURATION_MINUTES   ((60.f * 12.f))

◆ GasIndexAlgorithm_GATING_THRESHOLD_INITIAL

#define GasIndexAlgorithm_GATING_THRESHOLD_INITIAL   (510.f)

◆ GasIndexAlgorithm_GATING_THRESHOLD_NOX

#define GasIndexAlgorithm_GATING_THRESHOLD_NOX   (30.f)

◆ GasIndexAlgorithm_GATING_THRESHOLD_TRANSITION

#define GasIndexAlgorithm_GATING_THRESHOLD_TRANSITION   (0.09f)

◆ GasIndexAlgorithm_GATING_THRESHOLD_VOC

#define GasIndexAlgorithm_GATING_THRESHOLD_VOC   (340.f)

◆ GasIndexAlgorithm_GATING_VOC_MAX_DURATION_MINUTES

#define GasIndexAlgorithm_GATING_VOC_MAX_DURATION_MINUTES   ((60.f * 3.f))

◆ GasIndexAlgorithm_INDEX_GAIN

#define GasIndexAlgorithm_INDEX_GAIN   (230.f)

◆ GasIndexAlgorithm_INIT_DURATION_MEAN_NOX

#define GasIndexAlgorithm_INIT_DURATION_MEAN_NOX   ((3600.f * 4.75f))

◆ GasIndexAlgorithm_INIT_DURATION_MEAN_VOC

#define GasIndexAlgorithm_INIT_DURATION_MEAN_VOC   ((3600.f * 0.75f))

◆ GasIndexAlgorithm_INIT_DURATION_VARIANCE_NOX

#define GasIndexAlgorithm_INIT_DURATION_VARIANCE_NOX   ((3600.f * 5.70f))

◆ GasIndexAlgorithm_INIT_DURATION_VARIANCE_VOC

#define GasIndexAlgorithm_INIT_DURATION_VARIANCE_VOC   ((3600.f * 1.45f))

◆ GasIndexAlgorithm_INIT_TRANSITION_MEAN

#define GasIndexAlgorithm_INIT_TRANSITION_MEAN   (0.01f)

◆ GasIndexAlgorithm_INIT_TRANSITION_VARIANCE

#define GasIndexAlgorithm_INIT_TRANSITION_VARIANCE   (0.01f)

◆ GasIndexAlgorithm_INITIAL_BLACKOUT

#define GasIndexAlgorithm_INITIAL_BLACKOUT   (45.f)

◆ GasIndexAlgorithm_LP_ALPHA

#define GasIndexAlgorithm_LP_ALPHA   (-0.2f)

◆ GasIndexAlgorithm_LP_TAU_FAST

#define GasIndexAlgorithm_LP_TAU_FAST   (20.0f)

◆ GasIndexAlgorithm_LP_TAU_SLOW

#define GasIndexAlgorithm_LP_TAU_SLOW   (500.0f)

◆ GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__ADDITIONAL_GAMMA_MEAN_SCALING

#define GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__ADDITIONAL_GAMMA_MEAN_SCALING    (8.f)

◆ GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__FIX16_MAX

#define GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__FIX16_MAX   (32767.f)

◆ GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__GAMMA_SCALING

#define GasIndexAlgorithm_MEAN_VARIANCE_ESTIMATOR__GAMMA_SCALING   (64.f)

◆ GasIndexAlgorithm_NOX_INDEX_OFFSET_DEFAULT

#define GasIndexAlgorithm_NOX_INDEX_OFFSET_DEFAULT   (1.f)

◆ GasIndexAlgorithm_NOX_SRAW_MINIMUM

#define GasIndexAlgorithm_NOX_SRAW_MINIMUM   (10000)

◆ GasIndexAlgorithm_PERSISTENCE_UPTIME_GAMMA

#define GasIndexAlgorithm_PERSISTENCE_UPTIME_GAMMA   ((3.f * 3600.f))

◆ GasIndexAlgorithm_SIGMOID_K_NOX

#define GasIndexAlgorithm_SIGMOID_K_NOX   (-0.0101f)

◆ GasIndexAlgorithm_SIGMOID_K_VOC

#define GasIndexAlgorithm_SIGMOID_K_VOC   (-0.0065f)

◆ GasIndexAlgorithm_SIGMOID_L

#define GasIndexAlgorithm_SIGMOID_L   (500.f)

◆ GasIndexAlgorithm_SIGMOID_X0_NOX

#define GasIndexAlgorithm_SIGMOID_X0_NOX   (614.f)

◆ GasIndexAlgorithm_SIGMOID_X0_VOC

#define GasIndexAlgorithm_SIGMOID_X0_VOC   (213.f)

◆ GasIndexAlgorithm_SRAW_STD_BONUS_VOC

#define GasIndexAlgorithm_SRAW_STD_BONUS_VOC   (220.f)

◆ GasIndexAlgorithm_SRAW_STD_INITIAL

#define GasIndexAlgorithm_SRAW_STD_INITIAL   (50.f)

◆ GasIndexAlgorithm_SRAW_STD_NOX

#define GasIndexAlgorithm_SRAW_STD_NOX   (2000.f)

◆ GasIndexAlgorithm_TAU_INITIAL_MEAN_NOX

#define GasIndexAlgorithm_TAU_INITIAL_MEAN_NOX   (1200.f)

◆ GasIndexAlgorithm_TAU_INITIAL_MEAN_VOC

#define GasIndexAlgorithm_TAU_INITIAL_MEAN_VOC   (20.f)

◆ GasIndexAlgorithm_TAU_INITIAL_VARIANCE

#define GasIndexAlgorithm_TAU_INITIAL_VARIANCE   (2500.f)

◆ GasIndexAlgorithm_TAU_MEAN_HOURS

#define GasIndexAlgorithm_TAU_MEAN_HOURS   (12.f)

◆ GasIndexAlgorithm_TAU_VARIANCE_HOURS

#define GasIndexAlgorithm_TAU_VARIANCE_HOURS   (12.f)

◆ GasIndexAlgorithm_TUNING_GAIN_FACTOR_MAX

#define GasIndexAlgorithm_TUNING_GAIN_FACTOR_MAX   (1000)

◆ GasIndexAlgorithm_TUNING_GAIN_FACTOR_MIN

#define GasIndexAlgorithm_TUNING_GAIN_FACTOR_MIN   (1)

◆ GasIndexAlgorithm_TUNING_GATING_MAX_DURATION_MINUTES_MAX

#define GasIndexAlgorithm_TUNING_GATING_MAX_DURATION_MINUTES_MAX   (3000)

◆ GasIndexAlgorithm_TUNING_GATING_MAX_DURATION_MINUTES_MIN

#define GasIndexAlgorithm_TUNING_GATING_MAX_DURATION_MINUTES_MIN   (0)

◆ GasIndexAlgorithm_TUNING_INDEX_OFFSET_MAX

#define GasIndexAlgorithm_TUNING_INDEX_OFFSET_MAX   (250)

◆ GasIndexAlgorithm_TUNING_INDEX_OFFSET_MIN

#define GasIndexAlgorithm_TUNING_INDEX_OFFSET_MIN   (1)

◆ GasIndexAlgorithm_TUNING_LEARNING_TIME_GAIN_HOURS_MAX

#define GasIndexAlgorithm_TUNING_LEARNING_TIME_GAIN_HOURS_MAX   (1000)

◆ GasIndexAlgorithm_TUNING_LEARNING_TIME_GAIN_HOURS_MIN

#define GasIndexAlgorithm_TUNING_LEARNING_TIME_GAIN_HOURS_MIN   (1)

◆ GasIndexAlgorithm_TUNING_LEARNING_TIME_OFFSET_HOURS_MAX

#define GasIndexAlgorithm_TUNING_LEARNING_TIME_OFFSET_HOURS_MAX   (1000)

◆ GasIndexAlgorithm_TUNING_LEARNING_TIME_OFFSET_HOURS_MIN

#define GasIndexAlgorithm_TUNING_LEARNING_TIME_OFFSET_HOURS_MIN   (1)

◆ GasIndexAlgorithm_TUNING_STD_INITIAL_MAX

#define GasIndexAlgorithm_TUNING_STD_INITIAL_MAX   (5000)

◆ GasIndexAlgorithm_TUNING_STD_INITIAL_MIN

#define GasIndexAlgorithm_TUNING_STD_INITIAL_MIN   (10)

◆ GasIndexAlgorithm_VOC_INDEX_OFFSET_DEFAULT

#define GasIndexAlgorithm_VOC_INDEX_OFFSET_DEFAULT   (100.f)

◆ GasIndexAlgorithm_VOC_SRAW_MINIMUM

#define GasIndexAlgorithm_VOC_SRAW_MINIMUM   (20000)

◆ LIBRARY_VERSION_NAME

#define LIBRARY_VERSION_NAME   "3.2.0"

◆ true

#define true   1

Function Documentation

◆ GasIndexAlgorithm_get_sampling_interval()

void GasIndexAlgorithm_get_sampling_interval ( GasIndexAlgorithmParams * params,
float * sampling_interval )

Get the sampling interval parameter used by the algorithm.

◆ GasIndexAlgorithm_get_states()

void GasIndexAlgorithm_get_states ( 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
paramsPointer to the GasIndexAlgorithmParams struct
state0State0 to be stored
state1State1 to be stored

◆ GasIndexAlgorithm_get_tuning_parameters()

void GasIndexAlgorithm_get_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 )

Get current parameters to customize the gas index algorithm. Refer to GasIndexAlgorithm_set_tuning_parameters() for description of the parameters.

◆ GasIndexAlgorithm_init()

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
paramsPointer to the GasIndexAlgorithmParams struct
algorithm_type0 (GasIndexAlgorithm_ALGORITHM_TYPE_VOC) for VOC or 1 (GasIndexAlgorithm_ALGORITHM_TYPE_NOX) for NOx

◆ GasIndexAlgorithm_init_with_sampling_interval()

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
paramsPointer to the GasIndexAlgorithmParams struct
algorithm_type0 (GasIndexAlgorithm_ALGORITHM_TYPE_VOC) for VOC or 1 (GasIndexAlgorithm_ALGORITHM_TYPE_NOX) for NOx
sampling_intervalThe sampling interval in seconds the algorithm is called. Tested for 1s and 10s.

◆ GasIndexAlgorithm_process()

void GasIndexAlgorithm_process ( GasIndexAlgorithmParams * params,
int32_t sraw,
int32_t * gas_index )

Calculate the gas index value from the raw sensor value.

Parameters
paramsPointer to the GasIndexAlgorithmParams struct
srawRaw value from the SGP4x sensor
gas_indexCalculated gas index value from the raw sensor value. Zero during initial blackout period and 1..500 afterwards

◆ GasIndexAlgorithm_reset()

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
paramsPointer to the GasIndexAlgorithmParams struct

◆ GasIndexAlgorithm_set_states()

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
paramsPointer to the GasIndexAlgorithmParams struct
state0State0 to be restored
state1State1 to be restored

◆ GasIndexAlgorithm_set_tuning_parameters()

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
paramsPointer to the GasIndexAlgorithmParams struct
index_offsetGas index representing typical (average) conditions. Range 1..250, default 100 for VOC and 1 for NOx
learning_time_offset_hoursTime 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_hoursTime 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_minutesMaximum 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_initialInitial 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_factorFactor used to scale applied gain value when calculating gas index. Range 1..1000, default 230