ESP32-P4 OBC Firmware: SCD30 Sensor

Searching...

No Matches

Data Structures
struct	scd30_dev_t
	Structure representing the SCD30 device on an I²C bus. More...

Macros
#define	SCD30_I2C_ADDR (0x61)
	Default I²C address for SCD30 sensors.

Typedefs
typedef uint16_t	p_mbar_t
	Type for pressure [mbar].

typedef uint16_t	i_sec_t
	Type for measurement interval [s].

typedef uint16_t	uco2_ppm_t
	Type for CO₂ concentration [ppm] (forced recalibration only).

typedef uint16_t	tx100_celsius_t
	Type for temperature [°C × 100].

typedef uint16_t	alt_m_t
	Type for altitude [m].

typedef float	t_celsius_t
	Type for temperature [°C].

typedef float	rh_percent_t
	Type for relative humidity [%].

typedef float	co2_ppm_t
	Type for CO₂ [ppm].

typedef uint8_t	i2c_addr_t
	Type for I²C addresses.

typedef void *	scd30_handle_t
	Opaque handle for an SCD30 sensor.

Functions
scd30_handle_t	scd30_i2c_create (i2c_bus_handle_t bus, i2c_addr_t dev_addr)
	Create a handle for an SCD30 sensor but does not apply any configuration.

scd30_handle_t	scd30_i2c_init (i2c_bus_handle_t bus, i2c_addr_t dev_addr)
	Initialize the SCD30 sensor on the I²C bus with a default configuration.

void	scd30_i2c_delete (scd30_handle_t sensor)
	Deinitialize the SCD30 sensor and free resources.

esp_err_t	scd30_i2c_trigger_continuous_measurement (scd30_handle_t sensor, p_mbar_t p_comp)
	Trigger continuous measurement.

esp_err_t	scd30_i2c_stop_continuous_measurement (scd30_handle_t sensor)
	Stop continuous measurement.

esp_err_t	scd30_i2c_read_measurement_interval (scd30_handle_t sensor, i_sec_t *interval)
	Read the measurement interval.

esp_err_t	scd30_i2c_write_measurement_interval (scd30_handle_t sensor, i_sec_t interval)
	Set measurement interval.

esp_err_t	scd30_i2c_read_data_ready_status (scd30_handle_t sensor, bool *data_ready)
	Check whether new measurement data is available for read-out.

esp_err_t	scd30_i2c_read_measurement (scd30_handle_t sensor, co2_ppm_t co2, t_celsius_t temperature, rh_percent_t *humidity)
	Read CO₂, temperature and humidity measurements.

esp_err_t	scd30_i2c_read_automatic_self_calibration (scd30_handle_t sensor, bool *enabled)
	Get automatic self calibration (ASC) state.

esp_err_t	scd30_i2c_write_automatic_self_calibration (scd30_handle_t sensor, bool enabled)
	Enable or disable automatic self calibration (ASC).

esp_err_t	scd30_i2c_read_forced_recalibration_value (scd30_handle_t sensor, uco2_ppm_t *frc)
	Get forced recalibration (FRC) value.

esp_err_t	scd30_i2c_write_forced_recalibration_value (scd30_handle_t sensor, uco2_ppm_t target)
	Set forced recalibration (FRC) value.

esp_err_t	scd30_i2c_read_temperature_offset_ticks (scd30_handle_t sensor, tx100_celsius_t *offset)
	Get temperature offset in ticks.

esp_err_t	scd30_i2c_read_temperature_offset (scd30_handle_t sensor, t_celsius_t *offset)
	Get temperature offset.

esp_err_t	scd30_i2c_write_temperature_offset_ticks (scd30_handle_t sensor, tx100_celsius_t offset)
	Set temperature offset in ticks.

esp_err_t	scd30_i2c_write_temperature_offset (scd30_handle_t sensor, t_celsius_t offset)
	Set temperature offset.

esp_err_t	scd30_i2c_read_sensor_altitude (scd30_handle_t sensor, alt_m_t *altitude)
	Get configured sensor altitude.

esp_err_t	scd30_i2c_write_sensor_altitude (scd30_handle_t sensor, alt_m_t altitude)
	Set sensor altitude above sea level.

esp_err_t	scd30_i2c_read_firmware_version (scd30_handle_t sensor, uint16_t *firmware_version)
	Get firmware version.

esp_err_t	scd30_i2c_soft_reset (scd30_handle_t sensor)
	Reset the sensor.

Detailed Description

Copyright

Portions under BSD-3-Clause license, derived from:
- Copyright (c) 2021, Sensirion AG
- Copyright (c) 2021, Ruslan V. Uss
- Copyright (c) 2021, Nate Usher

Modifications and rewrite for new I²C interface:
- Copyright (c) 2026 Adrien Chevrier. Under AGPL-3.0-or-later license.

I²C ESP-IDF driver for the Sensirion SCD30 environmental sensor.

Adapted from https://github.com/esp-idf-lib/scd30/tree/main under BSD-3-Clause license.

Uses the new ESP-IDF I²C interface.

Data Structure Documentation

◆ scd30_dev_t

struct scd30_dev_t

Structure representing the SCD30 device on an I²C bus.

Data Fields
i2c_addr_t	dev_addr	I²C address of the sensor.
i2c_bus_device_handle_t	i2c_dev	I²C device handle.

Macro Definition Documentation

◆ SCD30_I2C_ADDR

#define SCD30_I2C_ADDR (0x61)

Default I²C address for SCD30 sensors.

Typedef Documentation

◆ alt_m_t

typedef uint16_t alt_m_t

Type for altitude [m].

◆ co2_ppm_t

typedef float co2_ppm_t

Type for CO₂ [ppm].

◆ i2c_addr_t

typedef uint8_t i2c_addr_t

Type for I²C addresses.

◆ i_sec_t

typedef uint16_t i_sec_t

Type for measurement interval [s].

◆ p_mbar_t

typedef uint16_t p_mbar_t

Type for pressure [mbar].

◆ rh_percent_t

typedef float rh_percent_t

Type for relative humidity [%].

◆ scd30_handle_t

typedef void* scd30_handle_t

Opaque handle for an SCD30 sensor.

◆ t_celsius_t

typedef float t_celsius_t

Type for temperature [°C].

◆ tx100_celsius_t

typedef uint16_t tx100_celsius_t

Type for temperature [°C × 100].

◆ uco2_ppm_t

typedef uint16_t uco2_ppm_t

Type for CO₂ concentration [ppm] (forced recalibration only).

Function Documentation

◆ scd30_i2c_create()

scd30_handle_t scd30_i2c_create	(	i2c_bus_handle_t	bus,
		i2c_addr_t	dev_addr )

Create a handle for an SCD30 sensor but does not apply any configuration.

Parameters

[in]	bus	The I²C bus handle.
[in]	dev_addr	The I²C address of the sensor.

Return values

scd30_handle_t	Handle to the sensor.
NULL	On failure.

Note: Must call scd30_i2c_delete() to free resources later.

Warning: This function must run inside a critical section.

◆ scd30_i2c_delete()

void scd30_i2c_delete ( scd30_handle_t sensor )

Deinitialize the SCD30 sensor and free resources.

Parameters

[in,out] sensor The sensor handle returned by scd30_i2c_init() or scd30_i2c_create().

Warning: This function must run inside a critical section.

◆ scd30_i2c_init()

scd30_handle_t scd30_i2c_init	(	i2c_bus_handle_t	bus,
		i2c_addr_t	dev_addr )

Initialize the SCD30 sensor on the I²C bus with a default configuration.

Parameters

[in]	bus	The I²C bus handle.
[in]	dev_addr	The I²C address of the sensor.

Return values

scd30_handle_t	Handle to the initialized sensor.
NULL	On failure.

Note: Must call scd30_i2c_delete() to free resources later.

Warning: This function must run inside a critical section.

◆ scd30_i2c_read_automatic_self_calibration()

esp_err_t scd30_i2c_read_automatic_self_calibration	(	scd30_handle_t	sensor,
		bool *	enabled )

Get automatic self calibration (ASC) state.

Note: By default, the ASC is disabled.

Parameters

[in]	sensor	The sensor handle.
[out]	enabled	`true` if ASC is enabled, `false` otherwise.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_read_data_ready_status()

esp_err_t scd30_i2c_read_data_ready_status	(	scd30_handle_t	sensor,
		bool *	data_ready )

Check whether new measurement data is available for read-out.

Parameters

[in]	sensor	The sensor handle.
[out]	data_ready	`true` if data is ready, `false` otherwise.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_read_firmware_version()

esp_err_t scd30_i2c_read_firmware_version	(	scd30_handle_t	sensor,
		uint16_t *	firmware_version )

Get firmware version.

Can be used to read out the firmware version of the SCD30 module. The MSB is the major firmware version, the LSB is the minor firmware version.

Parameters

[in]	sensor	The sensor handle.
[out]	firmware_version	Firmware version

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_read_forced_recalibration_value()

esp_err_t scd30_i2c_read_forced_recalibration_value	(	scd30_handle_t	sensor,
		uco2_ppm_t *	frc )

Get forced recalibration (FRC) value.

See also: scd30_i2c_write_forced_recalibration_value()

The most recently used reference value is stored in volatile memory and can be read using this function. After re-powering the sensor, it returns the default reference value of 400 ppm.

Parameters

[in]	sensor	The sensor handle.
[out]	frc	FRC value.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_read_measurement()

esp_err_t scd30_i2c_read_measurement	(	scd30_handle_t	sensor,
		co2_ppm_t *	co2,
		t_celsius_t *	temperature,
		rh_percent_t *	humidity )

Read CO₂, temperature and humidity measurements.

Parameters

[in]	sensor	The sensor handle.
[out]	co2	Pointer to store CO₂ concentration.
[out]	temperature	Pointer to store temperature.
[out]	humidity	Pointer to store relative humidity.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_read_measurement_interval()

esp_err_t scd30_i2c_read_measurement_interval	(	scd30_handle_t	sensor,
		i_sec_t *	interval )

Read the measurement interval.

Gets the interval used by the SCD30 sensor to measure in continuous measurement mode. Saved in non-volatile memory.

Parameters

[in]	sensor	The sensor handle.
[out]	interval	Pointer to store the interval in seconds.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_read_sensor_altitude()

esp_err_t scd30_i2c_read_sensor_altitude	(	scd30_handle_t	sensor,
		alt_m_t *	altitude )

Get configured sensor altitude.

Get configured sensor altitude above sea level. Per default, the sensor altitude is set to 0 m above sea-level.

Note: Only available in idle mode.

Parameters

[in]	sensor	The sensor handle.
[out]	altitude	Sensor altitude.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_read_temperature_offset()

esp_err_t scd30_i2c_read_temperature_offset	(	scd30_handle_t	sensor,
		t_celsius_t *	offset )

Get temperature offset.

Get the current temperature offset value, saved in non-volatile memory.

Note: Only available in idle mode.

See also: scd30_i2c_read_temperature_offset_ticks()

Parameters

[in]	sensor	The sensor handle.
[out]	offset	Temperature offset.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_read_temperature_offset_ticks()

esp_err_t scd30_i2c_read_temperature_offset_ticks	(	scd30_handle_t	sensor,
		tx100_celsius_t *	offset )

Get temperature offset in ticks.

Get the current temperature offset value, saved in non-volatile memory.

Note: Only available in idle mode.

Parameters

[in]	sensor	The sensor handle.
[out]	offset	Temperature offset in ticks.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_soft_reset()

esp_err_t scd30_i2c_soft_reset ( scd30_handle_t sensor )

Reset the sensor.

Soft reset mechanism that forces the sensor into the same state as after powering up. After a soft reset, the sensor will reload all calibrated data.

Parameters

[in] sensor The sensor handle.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_stop_continuous_measurement()

esp_err_t scd30_i2c_stop_continuous_measurement ( scd30_handle_t sensor )

Stop continuous measurement.

Parameters

[in] sensor The sensor handle.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_trigger_continuous_measurement()

esp_err_t scd30_i2c_trigger_continuous_measurement	(	scd30_handle_t	sensor,
		p_mbar_t	p_comp )

Trigger continuous measurement.

@not Signal update interval is 2 seconds by default.

Parameters

[in]	sensor	The sensor handle.
[in]	p_comp	Optional ambient pressure compensation [mbar], `0` to deactivate.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL` or `p_comp` is not within the range [700;1400] mbar.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_write_automatic_self_calibration()

esp_err_t scd30_i2c_write_automatic_self_calibration	(	scd30_handle_t	sensor,
		bool	enabled )

Enable or disable automatic self calibration (ASC).

Note: By default, the ASC is disabled.

Parameters

[in]	sensor	The sensor handle.
[in]	enabled	`true` to enable ASC, `false` to disable ASC.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_write_forced_recalibration_value()

esp_err_t scd30_i2c_write_forced_recalibration_value	(	scd30_handle_t	sensor,
		uco2_ppm_t	target )

Set forced recalibration (FRC) value.

See also: scd30_i2c_read_forced_recalibration_value()

FRC compensates for sensor drift when a known CO₂ reference concentration is available near the SCD30. For best results, run the sensor in a stable environment in continuous mode at a 2 s measurement rate for at least 2 min before issuing the FRC command and sending the reference value. Setting a reference CO₂ concentration using this method always overrides ASC corrections.

This permanently updates the calibration curve and persists after re-powering the sensor.

Parameters

[in]	sensor	The sensor handle.
[in]	target	Target FRC value.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL` or `target` is not within the range [400;2000] ppm.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_write_measurement_interval()

esp_err_t scd30_i2c_write_measurement_interval	(	scd30_handle_t	sensor,
		i_sec_t	interval )

Set measurement interval.

Sets the interval used by the SCD30 sensor to measure in continuous measurement mode. Saved in non-volatile memory.

Parameters

[in]	sensor	The sensor handle.
[in]	interval	Measurement interval in seconds.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL` or `interval` is not within the range ]2;1800[ s.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_write_sensor_altitude()

esp_err_t scd30_i2c_write_sensor_altitude	(	scd30_handle_t	sensor,
		alt_m_t	altitude )

Set sensor altitude above sea level.

Note: Setting a sensor altitude to the sensor overrides any pressure compensation based on a previously set ambient pressure.

Parameters

[in]	sensor	The sensor handle.
[in]	altitude	Sensor altitude.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_write_temperature_offset()

esp_err_t scd30_i2c_write_temperature_offset	(	scd30_handle_t	sensor,
		t_celsius_t	offset )

Set temperature offset.

Set the temperature offset value to be saved in non-volatile memory. The last set value will be used for temperature offset compensation after repowering.

See also: scd30_i2c_write_temperature_offset_ticks()

Parameters

[in]	sensor	The sensor handle.
[in]	offset	Temperature offset.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL` .
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

◆ scd30_i2c_write_temperature_offset_ticks()

esp_err_t scd30_i2c_write_temperature_offset_ticks	(	scd30_handle_t	sensor,
		tx100_celsius_t	offset )

Set temperature offset in ticks.

Set the temperature offset value to be saved in non-volatile memory. The last set value will be used for temperature offset compensation after re-powering.

Parameters

[in]	sensor	The sensor handle.
[in]	offset	Temperature offset in ticks.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If any parameter is `NULL`.
ESP_FAIL	Sending command error, slave doesn't ACK the transfer.
ESP_ERR_INVALID_STATE	I²C driver not installed or not in master mode.
ESP_ERR_TIMEOUT	Operation timeout because the bus is busy.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ scd30_dev_t

Macro Definition Documentation

◆ SCD30_I2C_ADDR

Typedef Documentation

◆ alt_m_t

◆ co2_ppm_t

◆ i2c_addr_t

◆ i_sec_t

◆ p_mbar_t

◆ rh_percent_t

◆ scd30_handle_t

◆ t_celsius_t

◆ tx100_celsius_t

◆ uco2_ppm_t

Function Documentation

◆ scd30_i2c_create()

◆ scd30_i2c_delete()

◆ scd30_i2c_init()

◆ scd30_i2c_read_automatic_self_calibration()

◆ scd30_i2c_read_data_ready_status()

◆ scd30_i2c_read_firmware_version()

◆ scd30_i2c_read_forced_recalibration_value()

◆ scd30_i2c_read_measurement()

◆ scd30_i2c_read_measurement_interval()

◆ scd30_i2c_read_sensor_altitude()

◆ scd30_i2c_read_temperature_offset()

◆ scd30_i2c_read_temperature_offset_ticks()

◆ scd30_i2c_soft_reset()

◆ scd30_i2c_stop_continuous_measurement()

◆ scd30_i2c_trigger_continuous_measurement()

◆ scd30_i2c_write_automatic_self_calibration()

◆ scd30_i2c_write_forced_recalibration_value()

◆ scd30_i2c_write_measurement_interval()

◆ scd30_i2c_write_sensor_altitude()

◆ scd30_i2c_write_temperature_offset()

◆ scd30_i2c_write_temperature_offset_ticks()