ESPHome  2024.10.2
scd4x.cpp
Go to the documentation of this file.
1 #include "scd4x.h"
2 #include "esphome/core/hal.h"
3 #include "esphome/core/log.h"
4 
5 namespace esphome {
6 namespace scd4x {
7 
8 static const char *const TAG = "scd4x";
9 
10 static const uint16_t SCD4X_CMD_GET_SERIAL_NUMBER = 0x3682;
11 static const uint16_t SCD4X_CMD_TEMPERATURE_OFFSET = 0x241d;
12 static const uint16_t SCD4X_CMD_ALTITUDE_COMPENSATION = 0x2427;
13 static const uint16_t SCD4X_CMD_AMBIENT_PRESSURE_COMPENSATION = 0xe000;
14 static const uint16_t SCD4X_CMD_AUTOMATIC_SELF_CALIBRATION = 0x2416;
15 static const uint16_t SCD4X_CMD_START_CONTINUOUS_MEASUREMENTS = 0x21b1;
16 static const uint16_t SCD4X_CMD_START_LOW_POWER_CONTINUOUS_MEASUREMENTS = 0x21ac;
17 static const uint16_t SCD4X_CMD_START_LOW_POWER_SINGLE_SHOT = 0x219d; // SCD41 only
18 static const uint16_t SCD4X_CMD_START_LOW_POWER_SINGLE_SHOT_RHT_ONLY = 0x2196;
19 static const uint16_t SCD4X_CMD_GET_DATA_READY_STATUS = 0xe4b8;
20 static const uint16_t SCD4X_CMD_READ_MEASUREMENT = 0xec05;
21 static const uint16_t SCD4X_CMD_PERFORM_FORCED_CALIBRATION = 0x362f;
22 static const uint16_t SCD4X_CMD_STOP_MEASUREMENTS = 0x3f86;
23 static const uint16_t SCD4X_CMD_FACTORY_RESET = 0x3632;
24 static const uint16_t SCD4X_CMD_GET_FEATURESET = 0x202f;
25 static const float SCD4X_TEMPERATURE_OFFSET_MULTIPLIER = (1 << 16) / 175.0f;
26 static const uint16_t SCD41_ID = 0x1408;
27 static const uint16_t SCD40_ID = 0x440;
28 
30  ESP_LOGCONFIG(TAG, "Setting up scd4x...");
31  // the sensor needs 1000 ms to enter the idle state
32  this->set_timeout(1000, [this]() {
33  this->status_clear_error();
34  if (!this->write_command(SCD4X_CMD_STOP_MEASUREMENTS)) {
35  ESP_LOGE(TAG, "Failed to stop measurements");
36  this->mark_failed();
37  return;
38  }
39  // According to the SCD4x datasheet the sensor will only respond to other commands after waiting 500 ms after
40  // issuing the stop_periodic_measurement command
41  this->set_timeout(500, [this]() {
42  uint16_t raw_serial_number[3];
43  if (!this->get_register(SCD4X_CMD_GET_SERIAL_NUMBER, raw_serial_number, 3, 1)) {
44  ESP_LOGE(TAG, "Failed to read serial number");
46  this->mark_failed();
47  return;
48  }
49  ESP_LOGD(TAG, "Serial number %02d.%02d.%02d", (uint16_t(raw_serial_number[0]) >> 8),
50  uint16_t(raw_serial_number[0] & 0xFF), (uint16_t(raw_serial_number[1]) >> 8));
51 
52  if (!this->write_command(SCD4X_CMD_TEMPERATURE_OFFSET,
53  (uint16_t) (temperature_offset_ * SCD4X_TEMPERATURE_OFFSET_MULTIPLIER))) {
54  ESP_LOGE(TAG, "Error setting temperature offset.");
56  this->mark_failed();
57  return;
58  }
59 
60  // If pressure compensation available use it
61  // else use altitude
64  ESP_LOGE(TAG, "Error setting ambient pressure compensation.");
66  this->mark_failed();
67  return;
68  }
69  } else {
70  if (!this->write_command(SCD4X_CMD_ALTITUDE_COMPENSATION, altitude_compensation_)) {
71  ESP_LOGE(TAG, "Error setting altitude compensation.");
73  this->mark_failed();
74  return;
75  }
76  }
77 
78  if (!this->write_command(SCD4X_CMD_AUTOMATIC_SELF_CALIBRATION, enable_asc_ ? 1 : 0)) {
79  ESP_LOGE(TAG, "Error setting automatic self calibration.");
81  this->mark_failed();
82  return;
83  }
84 
85  initialized_ = true;
86  // Finally start sensor measurements
87  this->start_measurement_();
88  ESP_LOGD(TAG, "Sensor initialized");
89  });
90  });
91 }
92 
94  ESP_LOGCONFIG(TAG, "scd4x:");
95  LOG_I2C_DEVICE(this);
96  if (this->is_failed()) {
97  switch (this->error_code_) {
99  ESP_LOGW(TAG, "Communication failed! Is the sensor connected?");
100  break;
102  ESP_LOGW(TAG, "Measurement Initialization failed!");
103  break;
105  ESP_LOGW(TAG, "Unable to read sensor firmware version");
106  break;
107  default:
108  ESP_LOGW(TAG, "Unknown setup error!");
109  break;
110  }
111  }
112  ESP_LOGCONFIG(TAG, " Automatic self calibration: %s", ONOFF(this->enable_asc_));
113  if (this->ambient_pressure_source_ != nullptr) {
114  ESP_LOGCONFIG(TAG, " Dynamic ambient pressure compensation using sensor '%s'",
116  } else {
117  if (this->ambient_pressure_compensation_) {
118  ESP_LOGCONFIG(TAG, " Altitude compensation disabled");
119  ESP_LOGCONFIG(TAG, " Ambient pressure compensation: %dmBar", this->ambient_pressure_);
120  } else {
121  ESP_LOGCONFIG(TAG, " Ambient pressure compensation disabled");
122  ESP_LOGCONFIG(TAG, " Altitude compensation: %dm", this->altitude_compensation_);
123  }
124  }
125  switch (this->measurement_mode_) {
126  case PERIODIC:
127  ESP_LOGCONFIG(TAG, " Measurement mode: periodic (5s)");
128  break;
129  case LOW_POWER_PERIODIC:
130  ESP_LOGCONFIG(TAG, " Measurement mode: low power periodic (30s)");
131  break;
132  case SINGLE_SHOT:
133  ESP_LOGCONFIG(TAG, " Measurement mode: single shot");
134  break;
136  ESP_LOGCONFIG(TAG, " Measurement mode: single shot rht only");
137  break;
138  }
139  ESP_LOGCONFIG(TAG, " Temperature offset: %.2f °C", this->temperature_offset_);
140  LOG_UPDATE_INTERVAL(this);
141  LOG_SENSOR(" ", "CO2", this->co2_sensor_);
142  LOG_SENSOR(" ", "Temperature", this->temperature_sensor_);
143  LOG_SENSOR(" ", "Humidity", this->humidity_sensor_);
144 }
145 
147  if (!initialized_) {
148  return;
149  }
150 
151  if (this->ambient_pressure_source_ != nullptr) {
152  float pressure = this->ambient_pressure_source_->state;
153  if (!std::isnan(pressure)) {
155  }
156  }
157 
158  uint32_t wait_time = 0;
161  wait_time =
162  this->measurement_mode_ == SINGLE_SHOT ? 5000 : 50; // Single shot measurement takes 5 secs rht mode 50 ms
163  }
164  this->set_timeout(wait_time, [this]() {
165  // Check if data is ready
166  if (!this->write_command(SCD4X_CMD_GET_DATA_READY_STATUS)) {
167  this->status_set_warning();
168  return;
169  }
170 
171  uint16_t raw_read_status;
172 
173  if (!this->read_data(raw_read_status) || raw_read_status == 0x00) {
174  this->status_set_warning();
175  ESP_LOGW(TAG, "Data not ready yet!");
176  return;
177  }
178 
179  if (!this->write_command(SCD4X_CMD_READ_MEASUREMENT)) {
180  ESP_LOGW(TAG, "Error reading measurement!");
181  this->status_set_warning();
182  return; // NO RETRY
183  }
184  // Read off sensor data
185  uint16_t raw_data[3];
186  if (!this->read_data(raw_data, 3)) {
187  this->status_set_warning();
188  return;
189  }
190  if (this->co2_sensor_ != nullptr)
191  this->co2_sensor_->publish_state(raw_data[0]);
192 
193  if (this->temperature_sensor_ != nullptr) {
194  const float temperature = -45.0f + (175.0f * (raw_data[1])) / (1 << 16);
195  this->temperature_sensor_->publish_state(temperature);
196  }
197  if (this->humidity_sensor_ != nullptr) {
198  const float humidity = (100.0f * raw_data[2]) / (1 << 16);
199  this->humidity_sensor_->publish_state(humidity);
200  }
201  this->status_clear_warning();
202  }); // set_timeout
203 }
204 
205 bool SCD4XComponent::perform_forced_calibration(uint16_t current_co2_concentration) {
206  /*
207  Operate the SCD4x in the operation mode later used in normal sensor operation (periodic measurement, low power
208  periodic measurement or single shot) for > 3 minutes in an environment with homogeneous and constant CO2
209  concentration before performing a forced recalibration.
210  */
211  if (!this->write_command(SCD4X_CMD_STOP_MEASUREMENTS)) {
212  ESP_LOGE(TAG, "Failed to stop measurements");
213  this->status_set_warning();
214  }
215  this->set_timeout(500, [this, current_co2_concentration]() {
216  if (this->write_command(SCD4X_CMD_PERFORM_FORCED_CALIBRATION, current_co2_concentration)) {
217  ESP_LOGD(TAG, "setting forced calibration Co2 level %d ppm", current_co2_concentration);
218  // frc takes 400 ms
219  // because this method will be used very rarly
220  // the simple approach with delay is ok
221  delay(400); // NOLINT'
222  if (!this->start_measurement_()) {
223  return false;
224  } else {
225  ESP_LOGD(TAG, "forced calibration complete");
226  }
227  return true;
228  } else {
229  ESP_LOGE(TAG, "force calibration failed");
230  this->error_code_ = FRC_FAILED;
231  this->status_set_warning();
232  return false;
233  }
234  });
235  return true;
236 }
237 
239  if (!this->write_command(SCD4X_CMD_STOP_MEASUREMENTS)) {
240  ESP_LOGE(TAG, "Failed to stop measurements");
241  this->status_set_warning();
242  return false;
243  }
244 
245  this->set_timeout(500, [this]() {
246  if (!this->write_command(SCD4X_CMD_FACTORY_RESET)) {
247  ESP_LOGE(TAG, "Failed to send factory reset command");
248  this->status_set_warning();
249  return false;
250  }
251  ESP_LOGD(TAG, "Factory reset complete");
252  return true;
253  });
254  return true;
255 }
256 
259  uint16_t new_ambient_pressure = (uint16_t) pressure_in_hpa;
260  if (!initialized_) {
261  ambient_pressure_ = new_ambient_pressure;
262  return;
263  }
264  // Only send pressure value if it has changed since last update
265  if (new_ambient_pressure != ambient_pressure_) {
266  update_ambient_pressure_compensation_(new_ambient_pressure);
267  ambient_pressure_ = new_ambient_pressure;
268  } else {
269  ESP_LOGD(TAG, "ambient pressure compensation skipped - no change required");
270  }
271 }
272 
274  if (this->write_command(SCD4X_CMD_AMBIENT_PRESSURE_COMPENSATION, pressure_in_hpa)) {
275  ESP_LOGD(TAG, "setting ambient pressure compensation to %d hPa", pressure_in_hpa);
276  return true;
277  } else {
278  ESP_LOGE(TAG, "Error setting ambient pressure compensation.");
279  return false;
280  }
281 }
282 
284  uint16_t measurement_command = SCD4X_CMD_START_CONTINUOUS_MEASUREMENTS;
285  switch (this->measurement_mode_) {
286  case PERIODIC:
287  measurement_command = SCD4X_CMD_START_CONTINUOUS_MEASUREMENTS;
288  break;
289  case LOW_POWER_PERIODIC:
290  measurement_command = SCD4X_CMD_START_LOW_POWER_CONTINUOUS_MEASUREMENTS;
291  break;
292  case SINGLE_SHOT:
293  measurement_command = SCD4X_CMD_START_LOW_POWER_SINGLE_SHOT;
294  break;
296  measurement_command = SCD4X_CMD_START_LOW_POWER_SINGLE_SHOT_RHT_ONLY;
297  break;
298  }
299 
300  static uint8_t remaining_retries = 3;
301  while (remaining_retries) {
302  if (!this->write_command(measurement_command)) {
303  ESP_LOGE(TAG, "Error starting measurements.");
305  this->status_set_warning();
306  if (--remaining_retries == 0)
307  return false;
308  delay(50); // NOLINT wait 50 ms and try again
309  }
310  this->status_clear_warning();
311  return true;
312  }
313  return false;
314 }
315 
316 } // namespace scd4x
317 } // namespace esphome
sensor::Sensor * co2_sensor_
Definition: scd4x.h:53
void set_ambient_pressure_compensation(float pressure_in_hpa)
Definition: scd4x.cpp:257
sensor::Sensor * temperature_sensor_
Definition: scd4x.h:54
void dump_config() override
Definition: scd4x.cpp:93
void status_set_warning(const char *message="unspecified")
Definition: component.cpp:151
uint8_t pressure
Definition: tt21100.cpp:19
bool write_command(T i2c_register)
Write a command to the i2c device.
Definition: i2c_sensirion.h:82
bool is_failed() const
Definition: component.cpp:143
bool perform_forced_calibration(uint16_t current_co2_concentration)
Definition: scd4x.cpp:205
void set_timeout(const std::string &name, uint32_t timeout, std::function< void()> &&f)
Set a timeout function with a unique name.
Definition: component.cpp:69
sensor::Sensor * ambient_pressure_source_
Definition: scd4x.h:57
MeasurementMode measurement_mode_
Definition: scd4x.h:52
bool read_data(uint16_t *data, uint8_t len)
Read data words from i2c device.
float state
This member variable stores the last state that has passed through all filters.
Definition: sensor.h:131
void setup() override
Definition: scd4x.cpp:29
void status_clear_warning()
Definition: component.cpp:166
void publish_state(float state)
Publish a new state to the front-end.
Definition: sensor.cpp:39
bool update_ambient_pressure_compensation_(uint16_t pressure_in_hpa)
Definition: scd4x.cpp:273
uint16_t temperature
Definition: sun_gtil2.cpp:26
constexpr const char * c_str() const
Definition: string_ref.h:68
void status_clear_error()
Definition: component.cpp:172
bool get_register(uint16_t command, uint16_t *data, uint8_t len, uint8_t delay=0)
get data words from i2c register.
Definition: i2c_sensirion.h:43
virtual void mark_failed()
Mark this component as failed.
Definition: component.cpp:118
sensor::Sensor * humidity_sensor_
Definition: scd4x.h:55
void update() override
Definition: scd4x.cpp:146
Implementation of SPI Controller mode.
Definition: a01nyub.cpp:7
uint16_t altitude_compensation_
Definition: scd4x.h:48
const StringRef & get_name() const
Definition: entity_base.cpp:10
void IRAM_ATTR HOT delay(uint32_t ms)
Definition: core.cpp:26