scd4x - Driver for SCD40/SCD41 miniature CO₂ sensor¶
- group scd4x
ESP-IDF driver for SCD4x CO2 sensor.
Ported from https://github.com/Sensirion/raspberry-pi-i2c-scd4x
Copyright (c) 2021, Sensirion AG Copyright (c) 2021 Ruslan V. Uss unclerus@gmail.com
BSD Licensed as described in the file LICENSE
Defines
-
SCD4X_I2C_ADDR¶
Functions
-
esp_err_t scd4x_init_desc(i2c_dev_t *dev, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio)¶
Initialize device descriptor.
- Parameters
dev – Device descriptor
port – I2C port
sda_gpio – SDA GPIO
scl_gpio – SCL GPIO
- Returns
ESP_OK
on success
-
esp_err_t scd4x_free_desc(i2c_dev_t *dev)¶
Free device descriptor.
- Parameters
dev – Device descriptor
- Returns
ESP_OK
on success
-
esp_err_t scd4x_start_periodic_measurement(i2c_dev_t *dev)¶
Start periodic measurement.
Signal update interval is 5 seconds.
Note
This command is only available in idle mode.
- Parameters
dev – Device descriptor
- Returns
ESP_OK
on success
-
esp_err_t scd4x_read_measurement_ticks(i2c_dev_t *dev, uint16_t *co2, uint16_t *temperature, uint16_t *humidity)¶
Read sensor output.
The measurement data can only be read out once per signal update interval as the buffer is emptied upon read-out. If no data is available in the buffer, the sensor returns a NACK. To avoid a NACK response the scd4x_get_data_ready_status() can be called to check data status.
Note
This command is only available in measurement mode. The firmware updates the measurement values depending on the measurement mode.
- Parameters
dev – Device descriptor
co2 – CO₂ concentration in ppm
temperature – Convert value to °C by: -45 °C + 175 °C * value/2^16
humidity – Convert value to RH by: 100RH * value/2^16
- Returns
ESP_OK
on success
-
esp_err_t scd4x_read_measurement(i2c_dev_t *dev, uint16_t *co2, float *temperature, float *humidity)¶
Read sensor output and convert.
See scd4x_read_measurement_ticks() for more details.
Note
This command is only available in measurement mode. The firmware updates the measurement values depending on the measurement mode.
- Parameters
dev – Device descriptor
co2 – CO₂ concentration in ppm
temperature – Temperature in degrees Celsius (°C)
humidity – Relative humidity in percent RH
- Returns
ESP_OK
on success
-
esp_err_t scd4x_stop_periodic_measurement(i2c_dev_t *dev)¶
Stop periodic measurement.
Stop periodic measurement and return to idle mode for sensor configuration or to safe energy.
Note
This command is only available in measurement mode.
- Parameters
dev – Device descriptor
- Returns
ESP_OK
on success
-
esp_err_t scd4x_get_temperature_offset_ticks(i2c_dev_t *dev, uint16_t *t_offset)¶
Get temperature offset in ticks.
The temperature offset represents the difference between the measured temperature by the SCD4x and the actual ambient temperature. Per default, the temperature offset is set to 4°C.
Note
Only available in idle mode.
- Parameters
dev – Device descriptor
t_offset – Temperature offset. Convert value to °C by: 175 * value / 2^16
- Returns
ESP_OK
on success
-
esp_err_t scd4x_get_temperature_offset(i2c_dev_t *dev, float *t_offset)¶
Get temperature offset in °C.
See scd4x_get_temperature_offset_ticks() for more details.
Note
Only available in idle mode.
- Parameters
dev – Device descriptor
t_offset – Temperature offset in degrees Celsius (°C)
- Returns
ESP_OK
on success
-
esp_err_t scd4x_set_temperature_offset_ticks(i2c_dev_t *dev, uint16_t t_offset)¶
Set temperature offset in ticks.
Setting the temperature offset of the SCD4x inside the customer device correctly allows the user to leverage the RH and T output signal. Note that the temperature offset can depend on various factors such as the SCD4x measurement mode, self-heating of close components, the ambient temperature and air flow. Thus, the SCD4x temperature offset should be determined inside the customer device under its typical operation and in thermal equilibrium.
Note
Only available in idle mode.
- Parameters
dev – Device descriptor
t_offset – Temperature offset. Convert °C to value by: T * 2^16 / 175
- Returns
ESP_OK
on success
-
esp_err_t scd4x_set_temperature_offset(i2c_dev_t *dev, float t_offset)¶
Set temperature offset in °C.
See scd4x_set_temperature_offset_ticks() for more details.
Note
Only available in idle mode.
- Parameters
dev – Device descriptor
t_offset – Temperature offset in degrees Celsius (°C)
- Returns
ESP_OK
on success
-
esp_err_t scd4x_get_sensor_altitude(i2c_dev_t *dev, uint16_t *altitude)¶
Get configured sensor altitude.
Get configured sensor altitude in meters above sea level. Per default, the sensor altitude is set to 0 meter above sea-level.
Note
Only available in idle mode.
- Parameters
dev – Device descriptor.
altitude – Sensor altitude in meters.
- Returns
ESP_OK
on success
-
esp_err_t scd4x_set_sensor_altitude(i2c_dev_t *dev, uint16_t altitude)¶
Set sensor altitude in meters above sea level.
Note that setting a sensor altitude to the sensor overrides any pressure compensation based on a previously set ambient pressure.
Note
Only available in idle mode.
- Parameters
dev – Device descriptor.
altitude – Sensor altitude in meters.
- Returns
ESP_OK
on success
-
esp_err_t scd4x_set_ambient_ressure(i2c_dev_t *dev, uint16_t pressure)¶
Set ambient pressure.
The set_ambient_pressure command can be sent during periodic measurements to enable continuous pressure compensation. Note that setting an ambient pressure to the sensor overrides any pressure compensation based on a previously set sensor altitude.
Note
Available during measurements.
- Parameters
dev – Device descriptor.
pressure – Ambient pressure in hPa. Convert value to Pa by: value * 100
- Returns
ESP_OK
on success
-
esp_err_t scd4x_perform_forced_recalibration(i2c_dev_t *dev, uint16_t target_co2_concentration, uint16_t *frc_correction)¶
Perform forced recalibration.
To successfully conduct an accurate forced recalibration, the following steps need to be carried out:
Operate the SCD4x in a periodic measurement mode for > 3 minutes in an environment with homogenous and constant CO₂ concentration.
Stop periodic measurement. Wait 500 ms.
Subsequently call scd4x_perform_forced_recalibration() and optionally read out the baseline correction. A return value of 0xffff indicates that the forced recalibration failed.
- Parameters
dev – Device descriptor.
target_co2_concentration – Target CO₂ concentration in ppm.
frc_correction – FRC correction value in CO₂ ppm or 0xFFFF if the command failed.
- Returns
ESP_OK
on success
-
esp_err_t scd4x_get_automatic_self_calibration(i2c_dev_t *dev, bool *enabled)¶
Get automatic self calibration (ASC) state.
By default, the ASC is enabled.
- Parameters
dev – Device descriptor.
enabled – true if ASC is enabled, false otherwise
- Returns
ESP_OK
on success
-
esp_err_t scd4x_set_automatic_self_calibration(i2c_dev_t *dev, bool enabled)¶
Enable or disable automatic self calibration (ASC).
By default, the ASC is enabled.
- Parameters
dev – Device descriptor.
enabled – true to enable ASC, false to disable ASC
- Returns
ESP_OK
on success
-
esp_err_t scd4x_start_low_power_periodic_measurement(i2c_dev_t *dev)¶
Start low power periodic measurement.
Signal update interval is 30 seconds.
Note
This command is only available in idle mode.
- Parameters
dev – Device descriptor
- Returns
ESP_OK
on success
-
esp_err_t scd4x_get_data_ready_status(i2c_dev_t *dev, bool *data_ready)¶
Check whether new measurement data is available for read-out.
- Parameters
dev – Device descriptor
data_ready – true if data is ready, false otherwise
- Returns
ESP_OK
on success
-
esp_err_t scd4x_persist_settings(i2c_dev_t *dev)¶
Store current configuration in EEPROM.
Configuration settings such as the temperature offset, sensor altitude and the ASC enabled/disabled parameter are by default stored in the volatile memory (RAM) only and will be lost after a power-cycle. This funciton stores the current configuration in the EEPROM of the SCD4x, making them resistant to power-cycling. To avoid unnecessary wear of the EEPROM, function should only be called when persistence is required and if actual changes to the configuration have been made. Note that field calibration history (i.e. FRC and ASC) is stored in the EEPROM automatically.
- Parameters
dev – Device descriptor
- Returns
ESP_OK
on success
-
esp_err_t scd4x_get_serial_number(i2c_dev_t *dev, uint16_t *serial0, uint16_t *serial1, uint16_t *serial2)¶
Read serial number.
Reading out the serial number can be used to identify the chip and to verify the presence of the sensor. Function returns 3 words. Together, the 3 words constitute a unique serial number with a length of 48 bits (big endian format).
- Parameters
dev – Device descriptor
serial0 – First word of the 48 bit serial number
serial1 – Second word of the 48 bit serial number
serial2 – Third word of the 48 bit serial number
- Returns
ESP_OK
on success
-
esp_err_t scd4x_perform_self_test(i2c_dev_t *dev, bool *malfunction)¶
Perform self-test.
This function can be used as an end-of-line test to confirm sensor functionality.
- Parameters
dev – Device descriptor
malfunction – true if malfunction detected, false if device is OK
- Returns
ESP_OK
on success
-
esp_err_t scd4x_perform_factory_reset(i2c_dev_t *dev)¶
Factory reset sensor.
Initiates the reset of all configurations stored in the EEPROM and erases the FRC and ASC algorithm history.
- Parameters
dev – Device descriptor
- Returns
ESP_OK
on success
-
esp_err_t scd4x_reinit(i2c_dev_t *dev)¶
Reinitialize sensor.
The reinit command reinitializes the sensor by reloading user settings from EEPROM. Before sending the reinit command, the stop measurement command must be issued. If reinit command does not trigger the desired re-initialization, a power-cycle should be applied to the SCD4x.
Note
Only available in idle mode.
- Parameters
dev – Device descriptor
- Returns
ESP_OK
on success
-
esp_err_t scd4x_measure_single_shot(i2c_dev_t *dev)¶
Perform single measurement.
On-demand measurement of CO₂ concentration, relative humidity and temperature. The sensor output is read with the scd4x_read_measurement() function.
Note
Only available in idle mode.
- Parameters
dev – Device descriptor
- Returns
ESP_OK
on success
-
esp_err_t scd4x_measure_single_shot_rht_only(i2c_dev_t *dev)¶
Perform single measurement of of relative humidity and temperature only.
Note
Only available in idle mode.
- Parameters
dev – Device descriptor
- Returns
ESP_OK
on success
-
SCD4X_I2C_ADDR¶