1 /* 2 * $NetBSD: sensirion_voc_algorithm.h,v 1.2 2022/09/25 12:41:46 andvar Exp $ 3 */ 4 5 /* 6 * Copyright (c) 2021, Sensirion AG 7 * All rights reserved. 8 * 9 * Redistribution and use in source and binary forms, with or without 10 * modification, are permitted provided that the following conditions are met: 11 * 12 * * Redistributions of source code must retain the above copyright notice, this 13 * list of conditions and the following disclaimer. 14 * 15 * * Redistributions in binary form must reproduce the above copyright notice, 16 * this list of conditions and the following disclaimer in the documentation 17 * and/or other materials provided with the distribution. 18 * 19 * * Neither the name of Sensirion AG nor the names of its 20 * contributors may be used to endorse or promote products derived from 21 * this software without specific prior written permission. 22 * 23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 24 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 27 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 28 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 29 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 30 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 31 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 32 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 33 * POSSIBILITY OF SUCH DAMAGE. 34 */ 35 36 #ifndef VOCALGORITHM_H_ 37 #define VOCALGORITHM_H_ 38 39 #include "sensirion_arch_config.h" 40 41 /* The fixed point arithmetic parts of this code were originally created by 42 * https://github.com/PetteriAimonen/libfixmath 43 */ 44 45 typedef int32_t fix16_t; 46 47 #define F16(x) \ 48 ((fix16_t)(((x) >= 0) ? ((x)*65536.0 + 0.5) : ((x)*65536.0 - 0.5))) 49 50 // Should be set by the building toolchain 51 #ifndef LIBRARY_VERSION_NAME 52 #define LIBRARY_VERSION_NAME "custom build" 53 #endif 54 55 #define VocAlgorithm_SAMPLING_INTERVAL (1.) 56 #define VocAlgorithm_INITIAL_BLACKOUT (45.) 57 #define VocAlgorithm_VOC_INDEX_GAIN (230.) 58 #define VocAlgorithm_SRAW_STD_INITIAL (50.) 59 #define VocAlgorithm_SRAW_STD_BONUS (220.) 60 #define VocAlgorithm_TAU_MEAN_VARIANCE_HOURS (12.) 61 #define VocAlgorithm_TAU_INITIAL_MEAN (20.) 62 #define VocAlgorithm_INIT_DURATION_MEAN ((3600. * 0.75)) 63 #define VocAlgorithm_INIT_TRANSITION_MEAN (0.01) 64 #define VocAlgorithm_TAU_INITIAL_VARIANCE (2500.) 65 #define VocAlgorithm_INIT_DURATION_VARIANCE ((3600. * 1.45)) 66 #define VocAlgorithm_INIT_TRANSITION_VARIANCE (0.01) 67 #define VocAlgorithm_GATING_THRESHOLD (340.) 68 #define VocAlgorithm_GATING_THRESHOLD_INITIAL (510.) 69 #define VocAlgorithm_GATING_THRESHOLD_TRANSITION (0.09) 70 #define VocAlgorithm_GATING_MAX_DURATION_MINUTES ((60. * 3.)) 71 #define VocAlgorithm_GATING_MAX_RATIO (0.3) 72 #define VocAlgorithm_SIGMOID_L (500.) 73 #define VocAlgorithm_SIGMOID_K (-0.0065) 74 #define VocAlgorithm_SIGMOID_X0 (213.) 75 #define VocAlgorithm_VOC_INDEX_OFFSET_DEFAULT (100.) 76 #define VocAlgorithm_LP_TAU_FAST (20.0) 77 #define VocAlgorithm_LP_TAU_SLOW (500.0) 78 #define VocAlgorithm_LP_ALPHA (-0.2) 79 #define VocAlgorithm_PERSISTENCE_UPTIME_GAMMA ((3. * 3600.)) 80 #define VocAlgorithm_MEAN_VARIANCE_ESTIMATOR__GAMMA_SCALING (64.) 81 #define VocAlgorithm_MEAN_VARIANCE_ESTIMATOR__FIX16_MAX (32767.) 82 83 /** 84 * Struct to hold all the states of the VOC algorithm. 85 */ 86 typedef struct { 87 fix16_t mVoc_Index_Offset; 88 fix16_t mTau_Mean_Variance_Hours; 89 fix16_t mGating_Max_Duration_Minutes; 90 fix16_t mSraw_Std_Initial; 91 fix16_t mUptime; 92 fix16_t mSraw; 93 fix16_t mVoc_Index; 94 fix16_t m_Mean_Variance_Estimator__Gating_Max_Duration_Minutes; 95 bool m_Mean_Variance_Estimator___Initialized; 96 fix16_t m_Mean_Variance_Estimator___Mean; 97 fix16_t m_Mean_Variance_Estimator___Sraw_Offset; 98 fix16_t m_Mean_Variance_Estimator___Std; 99 fix16_t m_Mean_Variance_Estimator___Gamma; 100 fix16_t m_Mean_Variance_Estimator___Gamma_Initial_Mean; 101 fix16_t m_Mean_Variance_Estimator___Gamma_Initial_Variance; 102 fix16_t m_Mean_Variance_Estimator__Gamma_Mean; 103 fix16_t m_Mean_Variance_Estimator__Gamma_Variance; 104 fix16_t m_Mean_Variance_Estimator___Uptime_Gamma; 105 fix16_t m_Mean_Variance_Estimator___Uptime_Gating; 106 fix16_t m_Mean_Variance_Estimator___Gating_Duration_Minutes; 107 fix16_t m_Mean_Variance_Estimator___Sigmoid__L; 108 fix16_t m_Mean_Variance_Estimator___Sigmoid__K; 109 fix16_t m_Mean_Variance_Estimator___Sigmoid__X0; 110 fix16_t m_Mox_Model__Sraw_Std; 111 fix16_t m_Mox_Model__Sraw_Mean; 112 fix16_t m_Sigmoid_Scaled__Offset; 113 fix16_t m_Adaptive_Lowpass__A1; 114 fix16_t m_Adaptive_Lowpass__A2; 115 bool m_Adaptive_Lowpass___Initialized; 116 fix16_t m_Adaptive_Lowpass___X1; 117 fix16_t m_Adaptive_Lowpass___X2; 118 fix16_t m_Adaptive_Lowpass___X3; 119 } VocAlgorithmParams; 120 121 /** 122 * Initialize the VOC algorithm parameters. Call this once at the beginning or 123 * whenever the sensor stopped measurements. 124 * @param params Pointer to the VocAlgorithmParams struct 125 */ 126 void VocAlgorithm_init(VocAlgorithmParams* params); 127 128 /** 129 * Get current algorithm states. Retrieved values can be used in 130 * VocAlgorithm_set_states() to resume operation after a short interruption, 131 * skipping initial learning phase. This feature can only be used after at least 132 * 3 hours of continuous operation. 133 * @param params Pointer to the VocAlgorithmParams struct 134 * @param state0 State0 to be stored 135 * @param state1 State1 to be stored 136 */ 137 void VocAlgorithm_get_states(VocAlgorithmParams* params, int32_t* state0, 138 int32_t* state1); 139 140 /** 141 * Set previously retrieved algorithm states to resume operation after a short 142 * interruption, skipping initial learning phase. This feature should not be 143 * used after interruptions of more than 10 minutes. Call this once after 144 * VocAlgorithm_init() and the optional VocAlgorithm_set_tuning_parameters(), if 145 * desired. Otherwise, the algorithm will start with initial learning phase. 146 * @param params Pointer to the VocAlgorithmParams struct 147 * @param state0 State0 to be restored 148 * @param state1 State1 to be restored 149 */ 150 void VocAlgorithm_set_states(VocAlgorithmParams* params, int32_t state0, 151 int32_t state1); 152 153 /** 154 * Set parameters to customize the VOC algorithm. Call this once after 155 * VocAlgorithm_init(), if desired. Otherwise, the default values will be used. 156 * 157 * @param params Pointer to the VocAlgorithmParams struct 158 * @param voc_index_offset VOC index representing typical (average) 159 * conditions. Range 1..250, default 100 160 * @param learning_time_hours Time constant of long-term estimator. 161 * Past events will be forgotten after about 162 * twice the learning time. 163 * Range 1..72 [hours], default 12 [hours] 164 * @param gating_max_duration_minutes Maximum duration of gating (freeze of 165 * estimator during high VOC index signal). 166 * 0 (no gating) or range 1..720 [minutes], 167 * default 180 [minutes] 168 * @param std_initial Initial estimate for standard deviation. 169 * Lower value boosts events during initial 170 * learning period, but may result in larger 171 * device-to-device variations. 172 * Range 10..500, default 50 173 */ 174 void VocAlgorithm_set_tuning_parameters(VocAlgorithmParams* params, 175 int32_t voc_index_offset, 176 int32_t learning_time_hours, 177 int32_t gating_max_duration_minutes, 178 int32_t std_initial); 179 180 /** 181 * Calculate the VOC index value from the raw sensor value. 182 * 183 * @param params Pointer to the VocAlgorithmParams struct 184 * @param sraw Raw value from the SGP40 sensor 185 * @param voc_index Calculated VOC index value from the raw sensor value. Zero 186 * during initial blackout period and 1..500 afterwards 187 */ 188 void VocAlgorithm_process(VocAlgorithmParams* params, int32_t sraw, 189 int32_t* voc_index); 190 191 #endif /* VOCALGORITHM_H_ */ 192