ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
mics_math.h
Go to the documentation of this file.
1#pragma once
2// Pure math of the two MiCS-5524 conversion models; the per-gas constants live in coefficients.py.
3// dfrobot: x = VCC - V_ao, ratio = x / x_air (sampled in clean air), ppm = (threshold - ratio) / gain.
4// datasheet: RS = (VCC * RL) / V_ao - RL, ratio = RS / R0 (RS in clean air), ppm = a * ratio^b.
5// Every helper returns NaN for input that cannot produce a reading. No ESPHome dependencies, so the
6// host tests cover it.
7
8#include <cmath>
9#include <cstdint>
10
12
18
21 float threshold;
22 float gain;
23 float min_ppm;
24 float max_ppm;
25};
26
27// ------------------------------------------------------------------ vendor model
28
31inline constexpr float VENDOR_DEAD_INPUT_FRACTION = 0.05f;
32
36inline float air_value_from_voltage(float voltage, float vcc) {
37 if (!std::isfinite(voltage) || !std::isfinite(vcc) || voltage <= VENDOR_DEAD_INPUT_FRACTION * vcc || voltage > vcc)
38 return NAN;
39 return vcc - voltage;
40}
41
43inline float ratio_from_air_value(float x, float x_air) {
44 if (!std::isfinite(x) || x < 0.0f || !std::isfinite(x_air) || x_air <= 0.0f)
45 return NAN;
46 return x / x_air;
47}
48
51inline float ppm_from_vendor_curve(float ratio, const VendorCurve &curve) {
52 if (!std::isfinite(ratio))
53 return NAN;
54 if (ratio > curve.threshold)
55 return 0.0f;
56
57 const float ppm = (curve.threshold - ratio) / curve.gain;
58 if (ppm < curve.min_ppm)
59 return 0.0f;
60 if (ppm > curve.max_ppm)
61 return curve.max_ppm;
62 return ppm;
63}
64
65// --------------------------------------------------------------- datasheet model
66
70inline constexpr float MAX_RS_OVER_RL = 200.0f;
71
73inline float datasheet_dead_input_voltage(float vcc) { return vcc / (MAX_RS_OVER_RL + 1.0f); }
74
77inline float rs_from_voltage(float voltage, float vcc, float rl) {
78 if (!std::isfinite(voltage) || !std::isfinite(vcc) || !std::isfinite(rl) || rl <= 0.0f || voltage > vcc ||
79 voltage <= datasheet_dead_input_voltage(vcc))
80 return NAN;
81 return vcc * rl / voltage - rl;
82}
83
85inline float ratio_from_rs(float rs, float r0) {
86 if (!std::isfinite(rs) || rs < 0.0f || !std::isfinite(r0) || r0 <= 0.0f)
87 return NAN;
88 return rs / r0;
89}
90
93inline float ppm_from_power_law(float a, float b, float ratio) {
94 if (!std::isfinite(a) || !std::isfinite(b) || !std::isfinite(ratio) || ratio < 0.0f || a <= 0.0f)
95 return NAN;
96
97 const float ppm = a * powf(ratio, b);
98 return std::isnan(ppm) ? NAN : ppm;
99}
100
104inline float clamp_ppm(float ppm, float min_ppm, float max_ppm) {
105 if (std::isnan(ppm))
106 return NAN;
107 if (ppm <= 0.0f)
108 return 0.0f;
109 if (std::isfinite(min_ppm) && ppm < min_ppm)
110 return 0.0f;
111 if (std::isfinite(max_ppm) && ppm > max_ppm)
112 return max_ppm;
113 return std::isfinite(ppm) ? ppm : NAN;
114}
115
116// ----------------------------------------------------------------- calibration
117
119inline constexpr float MAX_CALIBRATION_SPREAD = 0.25f;
120
122inline bool calibration_is_stable(float min_value, float max_value, float mean) {
123 if (!std::isfinite(min_value) || !std::isfinite(max_value) || !std::isfinite(mean) || mean <= 0.0f)
124 return false;
125 return max_value - min_value <= MAX_CALIBRATION_SPREAD * mean;
126}
127
128} // namespace esphome::mics_5524::micsmath
constexpr float MAX_RS_OVER_RL
Largest RS the datasheet model reads, as a multiple of RL.
Definition mics_math.h:70
bool calibration_is_stable(float min_value, float max_value, float mean)
True when the clean-air samples spread at most MAX_CALIBRATION_SPREAD of their mean.
Definition mics_math.h:122
constexpr float VENDOR_DEAD_INPUT_FRACTION
Share of VCC at or below which the vendor model reads the output as disconnected: clean air sits a vo...
Definition mics_math.h:31
float ratio_from_rs(float rs, float r0)
ratio = RS / R0 (NaN when either value is unusable); 0 is the saturated end.
Definition mics_math.h:85
constexpr float MAX_CALIBRATION_SPREAD
Largest relative spread (max - min) / mean a clean-air calibration accepts.
Definition mics_math.h:119
float air_value_from_voltage(float voltage, float vcc)
x = VCC - V_ao: 0 at VCC (a saturated sensor, never clean air).
Definition mics_math.h:36
float ppm_from_power_law(float a, float b, float ratio)
ppm = a * ratio^b; NaN for a ratio or coefficient that cannot produce a reading.
Definition mics_math.h:93
float clamp_ppm(float ppm, float min_ppm, float max_ppm)
Clamp to the configured range: below min_ppm counts as not detected and reads 0, 0 itself never chang...
Definition mics_math.h:104
float rs_from_voltage(float voltage, float vcc, float rl)
RS = (VCC * RL) / V - RL in kOhm: 0 at VCC (a saturated sensor).
Definition mics_math.h:77
float ratio_from_air_value(float x, float x_air)
ratio = x / x_air (NaN when either value is unusable).
Definition mics_math.h:43
ConversionModel
Generated through CONVERSION_MODELS in init.py.
Definition mics_math.h:14
float ppm_from_vendor_curve(float ratio, const VendorCurve &curve)
ratio -> ppm as DFRobot_MICS getGasData(): 0 above the threshold or below the vendor range,...
Definition mics_math.h:51
float datasheet_dead_input_voltage(float vcc)
Smallest V_ao the datasheet model reads: the output of RS = MAX_RS_OVER_RL * RL.
Definition mics_math.h:73
Per-gas constants of the vendor model.
Definition mics_math.h:20
float max_ppm
upper end of the measuring range
Definition mics_math.h:24
float threshold
ratio at or below which the gas counts as detected
Definition mics_math.h:21
float min_ppm
the vendor reports 0 ppm below this
Definition mics_math.h:23
uint16_t x
Definition tt21100.cpp:5