co2_sensor.cpp 13.1 KB
Newer Older
1
2
#include "co2_sensor.h"

Eric Duminil's avatar
Eric Duminil committed
3
#include "web_config.h"
Eric Duminil's avatar
Eric Duminil committed
4
#include "ntp.h"
5
6
7
8
#include "led_effects.h"
#include "sensor_console.h"
#include <Wire.h>

Eric Duminil's avatar
Eric Duminil committed
9
10
11
// The SCD30 from Sensirion is a high quality Nondispersive Infrared (NDIR) based CO₂ sensor capable of detecting 400 to 10000ppm with an accuracy of ±(30ppm+3%).
// https://github.com/sparkfun/SparkFun_SCD30_Arduino_Library
#include "src/lib/SparkFun_SCD30_Arduino_Library/src/SparkFun_SCD30_Arduino_Library.h"  // From: http://librarymanager/All#SparkFun_SCD30
Eric Duminil's avatar
Eric Duminil committed
12
#include "src/lib/S8_UART/s8_uart.h"
Eric Duminil's avatar
Eric Duminil committed
13

14
namespace config {
15
  const uint16_t measurement_timestep_bootup = 5; // [s] Measurement timestep during acclimatization.
16
  const uint8_t max_deviation_during_bootup = 20; // [%]
17
18
19
  const int8_t max_deviation_during_calibration = 30; // [ppm]
  const int16_t timestep_during_calibration = 10; // [s] WARNING: Measurements can be unreliable for timesteps shorter than 10s.
  const int8_t stable_measurements_before_calibration = 120 / timestep_during_calibration; // [-] Stable measurements during at least 2 minutes.
20
  const uint16_t co2_alert_threshold = 2000; // [ppm] Display a flashing led ring, if concentration exceeds this value
21
  const bool debug_sensor_states = false; // If true, log state transitions over serial console
22
23
24
25
}

namespace sensor {
  SCD30 scd30;
26
  uint16_t co2 = 0;
27
28
  float temperature = 0;
  float humidity = 0;
29
  char timestamp[23];
30
  int16_t stable_measurements = 0;
Käppler's avatar
Käppler committed
31
32
33

  /**
   * Define sensor states
34
   * BOOTUP -> initial state, until first >0 ppm values are returned
Käppler's avatar
Käppler committed
35
   * READY -> sensor does output valid information (> 0 ppm) and no other condition takes place
Eric Duminil's avatar
Eric Duminil committed
36
   * NEEDS_CALIBRATION -> sensor measurements are too low (< 250 ppm)
37
38
   * PREPARE_CALIBRATION_UNSTABLE -> forced calibration was initiated, last measurements were too far apart
   * PREPARE_CALIBRATION_STABLE -> forced calibration was initiated, last measurements were close to each others
Käppler's avatar
Käppler committed
39
   */
40
41
42
  enum state {
    BOOTUP,
    READY,
43
    NEEDS_CALIBRATION,
44
    PREPARE_CALIBRATION_UNSTABLE,
45
    PREPARE_CALIBRATION_STABLE
Käppler's avatar
Käppler committed
46
  };
47
48
49
  const char *state_names[] = {
      "BOOTUP",
      "READY",
50
      "NEEDS_CALIBRATION",
51
      "PREPARE_CALIBRATION_UNSTABLE",
52
      "PREPARE_CALIBRATION_STABLE" };
53
54

  state current_state = BOOTUP;
Käppler's avatar
Käppler committed
55
  void switchState(state);
Eric Duminil's avatar
Eric Duminil committed
56
57
58
59
  void setCO2forDebugging(int32_t fakeCo2);
  void calibrateSensorToSpecificPPM(int32_t calibrationLevel);
  void calibrateSensorRightNow(int32_t calibrationLevel);
  void setAutoCalibration(int32_t autoCalibration);
Käppler's avatar
Käppler committed
60

61
62
  void initialize() {
#if defined(ESP8266)
63
    Wire.begin(12, 14); // ESP8266 - D6, D5;
64
65
#endif
#if defined(ESP32)
Eric Duminil's avatar
Eric Duminil committed
66
    Wire.begin(21, 22); // ESP32
67
68
69
70
71
72
73
74
    /**
     *  SCD30   ESP32
     *  VCC --- 3V3
     *  GND --- GND
     *  SCL --- SCL (GPIO22) //NOTE: GPIO3 Would be more convenient (right next to GND)
     *  SDA --- SDA (GPIO21) //NOTE: GPIO1 would be more convenient (right next to GPO3)
     */
#endif
75
76
    Serial.println();
    scd30.enableDebugging(); // Prints firmware version in the console.
77

78
    if (!scd30.begin(config::auto_calibrate_sensor)) {
Eric Duminil's avatar
Eric Duminil committed
79
80
81
      Serial.println(F("ERROR - CO2 sensor not detected. Please check wiring!"));
      led_effects::showKITTWheel(color::red, 30);
      ESP.restart();
82
83
    }

84
85
86
87
88
    // Changes of the SCD30's measurement timestep do not come into effect
    // before the next measurement takes place. That means that after a hard reset
    // of the ESP the SCD30 sometimes needs a long time until switching back to 2 s
    // for acclimatization. Resetting it after startup seems to fix this behaviour.
    scd30.reset();
Käppler's avatar
Käppler committed
89

Eric Duminil's avatar
Eric Duminil committed
90
91
    //NOTE: It seems that the sensor needs some time for getting/setting temperature offset.
    delay(500);
92
    Serial.print(F("Setting temperature offset to -"));
93
    Serial.print(abs(config::temperature_offset));
Eric Duminil's avatar
Eric Duminil committed
94
    Serial.println(F(" K."));
95
    scd30.setTemperatureOffset(abs(config::temperature_offset)); // setTemperatureOffset only accepts positive numbers, but shifts the temperature down.
Eric Duminil's avatar
Eric Duminil committed
96
    delay(500);
97

Eric Duminil's avatar
Eric Duminil committed
98
99
100
    //NOTE: Even once the temperature offset is saved, the sensor still needs some time (~10 minutes?) to apply it.
    Serial.print(F("Temperature offset is : "));
    Serial.print(getTemperatureOffset());
Eric Duminil's avatar
Eric Duminil committed
101
    Serial.println(F(" K"));
102

103
    Serial.print(F("Auto-calibration is "));
104
    Serial.println(config::auto_calibrate_sensor ? "ON." : "OFF.");
105

106
107
108
109
    // SCD30 has its own timer.
    //NOTE: The timer seems to be inaccurate, though, possibly depending on voltage. Should it be offset?
    Serial.println();
    Serial.print(F("Setting SCD30 timestep to "));
110
    Serial.print(config::measurement_timestep_bootup);
Eric Duminil's avatar
Eric Duminil committed
111
    Serial.println(F(" s during acclimatization."));
112
    scd30.setMeasurementInterval(config::measurement_timestep_bootup); // [s]
113

Eric Duminil's avatar
Eric Duminil committed
114
    sensor_console::defineIntCommand("co2", setCO2forDebugging, F("1500 (Sets co2 level, for debugging)"));
115
116
    sensor_console::defineIntCommand("timer", setTimer, F("30 (Sets measurement interval, in s)"));
    sensor_console::defineCommand("calibrate", startCalibrationProcess, F("(Starts calibration process)"));
Eric Duminil's avatar
Eric Duminil committed
117
    sensor_console::defineIntCommand("calibrate", calibrateSensorToSpecificPPM,
118
        F("600 (Starts calibration process, to given ppm)"));
Eric Duminil's avatar
Eric Duminil committed
119
    sensor_console::defineIntCommand("calibrate!", calibrateSensorRightNow,
120
121
        F("600 (Calibrates right now, to given ppm)"));
    sensor_console::defineIntCommand("auto_calibrate", setAutoCalibration, F("0/1 (Disables/enables autocalibration)"));
122
    sensor_console::defineCommand("reset_scd", resetSCD, F("(Resets SCD30)"));
123
124
  }

125
126
127
128
129
130
131
  bool hasSensorSettled() {
    static uint16_t last_co2 = 0;
    uint16_t delta;
    delta = abs(co2 - last_co2);
    last_co2 = co2;
    // We assume the sensor has acclimated to the environment if measurements
    // change less than a specified percentage of the current value.
Eric Duminil's avatar
Eric Duminil committed
132
    return (co2 > 0 && delta < ((uint32_t) co2 * config::max_deviation_during_bootup / 100));
133
134
  }

Eric Duminil's avatar
Eric Duminil committed
135
  bool enoughStableMeasurements() {
Eric Duminil's avatar
Eric Duminil committed
136
    static int16_t previous_co2 = 0;
Eric Duminil's avatar
Eric Duminil committed
137
138
    if (co2 > (previous_co2 - config::max_deviation_during_calibration)
        && co2 < (previous_co2 + config::max_deviation_during_calibration)) {
139
      stable_measurements++;
Eric Duminil's avatar
Eric Duminil committed
140
      Serial.print(F("Number of stable measurements : "));
141
142
143
      Serial.print(stable_measurements);
      Serial.print(F(" / "));
      Serial.println(config::stable_measurements_before_calibration);
144
      switchState(PREPARE_CALIBRATION_STABLE);
145
146
    } else {
      stable_measurements = 0;
147
      switchState(PREPARE_CALIBRATION_UNSTABLE);
148
    }
Eric Duminil's avatar
Eric Duminil committed
149
    previous_co2 = co2;
150
    return (stable_measurements == config::stable_measurements_before_calibration);
151
152
153
  }

  void startCalibrationProcess() {
154
    /** From the sensor documentation:
Eric Duminil's avatar
Eric Duminil committed
155
     * Before applying FRC, SCD30 needs to be operated for 2 minutes with the desired measurement period in continuous mode.
156
     */
157
158
159
160
    Serial.print(F("Setting SCD30 timestep to "));
    Serial.print(config::timestep_during_calibration);
    Serial.println(F("s, prior to calibration."));
    scd30.setMeasurementInterval(config::timestep_during_calibration); // [s] The change will only take effect after next measurement.
161
162
    Serial.println(F("Waiting until the measurements are stable for at least 2 minutes."));
    Serial.println(F("It could take a very long time."));
163
    switchState(PREPARE_CALIBRATION_UNSTABLE);
164
165
  }

166
  void calibrate() {
167
    Serial.print(F("Calibrating SCD30 now..."));
168
169
    scd30.setAltitudeCompensation(config::altitude_above_sea_level);
    scd30.setForcedRecalibrationFactor(config::co2_calibration_level);
170
171
    Serial.println(F(" Done!"));
    Serial.println(F("Sensor calibrated."));
172
    switchState(BOOTUP); // In order to stop the calibration and select the desired timestep.
173
174
    //WARNING: Do not reset the ampel or the SCD30!
    //At least one measurement needs to happen in order for the calibration to be correctly applied.
175
  }
176

177
  void logToSerial() {
Eric Duminil's avatar
Eric Duminil committed
178
179
    Serial.print(timestamp);
    Serial.print(F(" - co2(ppm): "));
180
181
    Serial.print(co2);
    Serial.print(F(" temp(C): "));
182
    Serial.print(temperature, 1);
183
    Serial.print(F(" humidity(%): "));
184
    Serial.println(humidity, 1);
185
186
  }

Käppler's avatar
Käppler committed
187
  void switchState(state new_state) {
188
189
190
    if (new_state == current_state) {
      return;
    }
191
192
193
    if (config::debug_sensor_states) {
      Serial.print(F("Changing sensor state: "));
      Serial.print(state_names[current_state]);
Eric Duminil's avatar
Eric Duminil committed
194
      Serial.print(F(" -> "));
195
196
      Serial.println(state_names[new_state]);
    }
Käppler's avatar
Käppler committed
197
198
199
    current_state = new_state;
  }

200
  void switchStateForCurrentPPM() {
201
    if (current_state == BOOTUP) {
Eric Duminil's avatar
Eric Duminil committed
202
203
204
      if (!hasSensorSettled()) {
        return;
      }
205
206
207
      switchState(READY);
      Serial.println(F("Sensor acclimatization finished."));
      Serial.print(F("Setting SCD30 timestep to "));
208
      Serial.print(config::measurement_timestep);
Eric Duminil's avatar
Eric Duminil committed
209
      Serial.println(F(" s."));
210
      if (config::measurement_timestep < 10) {
211
212
        Serial.println(F("WARNING: Timesteps shorter than 10s can lead to unreliable measurements!"));
      }
213
      scd30.setMeasurementInterval(config::measurement_timestep); // [s]
214
    }
Eric Duminil's avatar
Eric Duminil committed
215
216
217

    // Check for pre-calibration states first, because we do not want to
    // leave them before calibration is done.
Käppler's avatar
Käppler committed
218
    if ((current_state == PREPARE_CALIBRATION_UNSTABLE) || (current_state == PREPARE_CALIBRATION_STABLE)) {
Eric Duminil's avatar
Eric Duminil committed
219
      if (enoughStableMeasurements()) {
220
        calibrate();
221
222
223
224
225
226
227
228
229
      }
    } else if (co2 < 250) {
      // Sensor should be calibrated.
      switchState(NEEDS_CALIBRATION);
    } else {
      switchState(READY);
    }
  }

230
231
232
  void displayCO2OnLedRing() {
    /**
     * Display data, even if it's "old" (with breathing).
Eric Duminil's avatar
Eric Duminil committed
233
     * A short delay is required in order to let background tasks run on the ESP8266.
234
     * see https://github.com/esp8266/Arduino/issues/3241#issuecomment-301290392
235
     */
236
    if (co2 < config::co2_alert_threshold) {
237
      led_effects::displayCO2color(co2);
238
      delay(100);
239
    } else {
240
      // Display a flashing led ring, if concentration exceeds a specific value
241
      led_effects::alert(color::red);
242
243
244
    }
  }

245
  void showState() {
246
247
248
249
250
    switch (current_state) {
    case BOOTUP:
      led_effects::showWaitingLED(color::blue);
      break;
    case READY:
251
      displayCO2OnLedRing();
252
      break;
253
    case NEEDS_CALIBRATION:
254
255
      led_effects::showWaitingLED(color::magenta);
      break;
256
    case PREPARE_CALIBRATION_UNSTABLE:
257
258
      led_effects::showWaitingLED(color::red);
      break;
259
    case PREPARE_CALIBRATION_STABLE:
260
261
262
      led_effects::showWaitingLED(color::green);
      break;
    default:
Eric Duminil's avatar
Eric Duminil committed
263
      Serial.println(F("Encountered unknown sensor state")); // This should not happen.
264
265
266
    }
  }

Eric Duminil's avatar
Eric Duminil committed
267
  /** Gets fresh data if available, checks calibration status, displays CO2 levels.
268
   * Returns true if fresh data is available, for further processing (e.g. MQTT, CSV or LoRa)
Eric Duminil's avatar
Eric Duminil committed
269
270
271
272
273
   */
  bool processData() {
    bool freshData = scd30.dataAvailable();

    if (freshData) {
274
      ntp::getLocalTime(timestamp);
Eric Duminil's avatar
Eric Duminil committed
275
276
277
      co2 = scd30.getCO2();
      temperature = scd30.getTemperature();
      humidity = scd30.getHumidity();
278

279
      switchStateForCurrentPPM();
280

281
282
      // Log every time fresh data is available.
      logToSerial();
283
284
    }

285
    showState();
286

287
288
289
    // Report data for further processing only if the data is reliable
    // (state 'READY') or manual calibration is necessary (state 'NEEDS_CALIBRATION').
    return freshData && (current_state == READY || current_state == NEEDS_CALIBRATION);
290
  }
291

Eric Duminil's avatar
Eric Duminil committed
292
293
294
295
  float getTemperatureOffset() {
    return -abs(scd30.getTemperatureOffset());
  }

296
297
298
299
300
301
302
  /*****************************************************************
   * Callbacks for sensor commands                                 *
   *****************************************************************/
  void setCO2forDebugging(int32_t fakeCo2) {
    Serial.print(F("DEBUG. Setting CO2 to "));
    co2 = fakeCo2;
    Serial.println(co2);
303
    switchStateForCurrentPPM();
304
305
  }

306
  void setAutoCalibration(int32_t autoCalibration) {
307
    config::auto_calibrate_sensor = autoCalibration;
308
309
310
311
312
    scd30.setAutoSelfCalibration(autoCalibration);
    Serial.print(F("Setting auto-calibration to : "));
    Serial.println(autoCalibration ? F("On.") : F("Off."));
  }

313
314
315
316
  void setTimer(int32_t timestep) {
    if (timestep >= 2 && timestep <= 1800) {
      Serial.print(F("Setting Measurement Interval to : "));
      Serial.print(timestep);
Eric Duminil's avatar
Eric Duminil committed
317
      Serial.println(F("s (change will only be applied after next measurement)."));
Eric Duminil's avatar
Eric Duminil committed
318
      scd30.setMeasurementInterval(timestep);
319
      config::measurement_timestep = timestep;
320
321
322
323
324
325
326
      led_effects::showKITTWheel(color::green, 1);
    }
  }

  void calibrateSensorToSpecificPPM(int32_t calibrationLevel) {
    if (calibrationLevel >= 400 && calibrationLevel <= 2000) {
      Serial.print(F("Force calibration, at "));
327
328
      config::co2_calibration_level = calibrationLevel;
      Serial.print(config::co2_calibration_level);
Eric Duminil's avatar
Eric Duminil committed
329
      Serial.println(F(" ppm."));
Eric Duminil's avatar
Eric Duminil committed
330
      startCalibrationProcess();
331
332
333
334
    }
  }

  void calibrateSensorRightNow(int32_t calibrationLevel) {
Eric Duminil's avatar
Eric Duminil committed
335
336
    if (calibrationLevel >= 400 && calibrationLevel <= 2000) {
      Serial.print(F("Force calibration, right now, at "));
337
338
      config::co2_calibration_level = calibrationLevel;
      Serial.print(config::co2_calibration_level);
Eric Duminil's avatar
Eric Duminil committed
339
      Serial.println(F(" ppm."));
340
      calibrate();
Eric Duminil's avatar
Eric Duminil committed
341
    }
342
  }
343
344
345
346
347
348

  void resetSCD() {
    Serial.print(F("Resetting SCD30..."));
    scd30.reset();
    Serial.println(F("done."));
  }
349
}