API Reference

adafruit_scd4x

Driver for Sensirion SCD4X CO2 sensor

  • Author(s): ladyada

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_scd4x.SCD4X(i2c_bus: I2C, address: int = 98)

CircuitPython helper class for using the SCD4X CO2 sensor

Parameters:

  • i2c_bus (I2C) – The I2C bus the SCD4X is connected to.

  • address (int) – The I2C device address for the sensor. Default is 0x62

Quickstart: Importing and using the SCD4X

Here is an example of using the SCD4X class. First you will need to import the libraries to use the sensor

import board
import adafruit_scd4x

Once this is done you can define your board.I2C object and define your sensor object

i2c = board.I2C()   # uses board.SCL and board.SDA
scd = adafruit_scd4x.SCD4X(i2c)
scd.start_periodic_measurement()

Now you have access to the CO2, temperature and humidity using the CO2, temperature and relative_humidity attributes

if scd.data_ready:
    temperature = scd.temperature
    relative_humidity = scd.relative_humidity
    co2_ppm_level = scd.CO2

Note

Once start_periodic_measurement() or start_low_periodice_measurement() are run most of the functions and properties except: read_measurement, get_data_ready_status, stop_periodic_measurement, set_ambient_pressure and get_ambient_pressure cause an error when accessed. If using these after starting measurement first run stop_periodic_measurement()

Some features are available on the SCD41 and SCD43 only, not the base SCD40:

A base SCD40 may execute these commands without raising, but the results are unspecified. Use sensor_variant_name to detect the part at runtime before relying on them.

property CO2: int

Returns the CO2 concentration in PPM (parts per million)

Note

Between measurements, the most recent reading will be cached and returned.

property altitude: int

Specifies the altitude at the measurement location in meters above sea level. Setting this value adjusts the CO2 measurement calculations to account for the air pressure’s effect on readings.

Note

This value will NOT be saved and will be reset on boot unless saved with persist_settings().

property ambient_pressure: int

The ambient pressure in hPa used to compensate CO2 measurements.

Setting this enables continuous pressure compensation and may be done at any time, including during periodic measurement. Valid values are 0 (compensation disabled) through 65535 hPa. Setting an ambient pressure overrides any compensation based on a previously set altitude. Multiply by 100 to convert to Pa.

Get and set share the I2C command 0xe000; the read/write bit in the I2C header selects which operation runs.

Note

This value will NOT be saved and will be reset on boot unless saved with persist_settings().

Returns:

the configured ambient pressure compensation, in hPa

Return type:

int

Raises:

AttributeError – if set outside the range 0-65535 hPa

property data_ready: bool

Check the sensor to see if new data is available

factory_reset() → None

Resets all configuration settings stored in the EEPROM and erases the FRC and ASC algorithm history.

Note

Stops periodic_measurement as a side-effect. Restart if desired.

force_calibration(target_co2: int) → int

Forces the sensor to recalibrate to a known CO2 level in PPM.

Returns the FRC correction the sensor applied, in PPM (this value may be negative). Before calling, the sensor must have been operated in a measurement mode for more than 3 minutes in a stable, homogeneous CO2 environment, otherwise the recalibration will fail.

Raises:

RuntimeError – if the sensor reports that the recalibration failed.

Note

Stops periodic_measurement as a side-effect. Restart if desired.

measure_single_shot() → None

On-demand measurement of CO2 concentration, relative humidity, and temperature.

Single shot measurement is available on the SCD41 and SCD43 only. A base SCD40 may execute this command without raising, but the returned values are unspecified and uncalibrated; confirm the part with sensor_variant_name before relying on it.

measure_single_shot_rht_only() → None

On-demand measurement of relative humidity and temperature only.

Available on the SCD41 and SCD43 only (see measure_single_shot() for the variant caveat). This command does not produce a CO2 value.

persist_settings() → None

Save temperature offset, altitude offset, and selfcal enable settings to EEPROM

power_down() → None

Put the sensor from idle into sleep mode to reduce current draw.

Intended for power-cycled single shot operation (SCD41/SCD43). The sensor must be in the idle state when this is called. Wake it again with wake_up().

reinit() → None

Reinitializes the sensor by reloading user settings from EEPROM.

Note

Stops periodic_measurement as a side-effect. Restart if desired.

property relative_humidity: float

Returns the current relative humidity in %rH.

Note

Between measurements, the most recent reading will be cached and returned.

property self_calibration_enabled: bool

Enables or disables automatic self calibration (ASC). To work correctly, the sensor must be on and active for 7 days after enabling ASC, and exposed to fresh air for at least 1 hour per day. Consult the manufacturer’s documentation for more information.

Note

This value will NOT be saved and will be reset on boot unless saved with persist_settings().

property self_calibration_initial_period: int

The ASC initial period in hours. Default is 44. Must be a multiple of 4.

Mainly relevant for single shot operation, where the parameter assumes a 5 minute measurement interval and must be scaled for other intervals (see datasheet v1.7 Section 3.11.5). A value of 0 forces an immediate correction.

Note

Only available in idle mode. This value will NOT be saved and will be reset on boot unless saved with persist_settings().

property self_calibration_standard_period: int

The ASC standard period in hours. Default is 156. Must be a multiple of 4.

Mainly relevant for single shot operation, where the parameter assumes a 5 minute measurement interval and must be scaled for other intervals (see datasheet v1.7 Section 3.11.7). A value of 0 forces an immediate correction.

Note

Only available in idle mode. This value will NOT be saved and will be reset on boot unless saved with persist_settings().

property self_calibration_target: int

The ASC baseline target CO2 concentration in PPM. Default is 400.

This is the lower-bound background CO2 level the ASC algorithm assumes the sensor is regularly exposed to within one ASC period.

Note

Only available in idle mode. This value will NOT be saved and will be reset on boot unless saved with persist_settings().

self_test() → None

Performs a self test, takes up to 10 seconds

property sensor_variant: int

12 of the variant word).

Returns the 4-bit code: 0 = SCD40, 1 = SCD41, 5 = SCD43. See sensor_variant_name for the ASCII name.

Note

Only available in idle mode.

The SCD43 is listed with a code of 5 - per the datasheet. This property is for reading the raw variant code. Please use sensor_variant_name for a translated version of the model number that shows “SCD43”.

Type:

Read the sensor variant code (bits 15

property sensor_variant_name: str

Read the sensor variant and return its ASCII name.

Returns "SCD40", "SCD41" or "SCD43". Any undocumented variant code is returned as "SCD4x (0x<code>)".

Note

Only available in idle mode.

property serial_number: Tuple[int, int, int, int, int, int]

Request a 6-tuple containing the unique serial number for this sensor

set_ambient_pressure(ambient_pressure: int) → None

Set the ambient pressure in hPa at any time to adjust CO2 calculations

Deprecated in favor of ambient_pressure

start_low_periodic_measurement() → None

Put sensor into low power periodic measurement mode, about 30s per measurement. See start_periodic_measurement() for more details.

start_periodic_measurement() → None

Put sensor into periodic measurement mode, about 5s per measurement

Note

Only the following commands will work once in periodic measurement mode:

stop_periodic_measurement() → None

Stop measurement mode

property temperature: float

Returns the current temperature in degrees Celsius

Note

Between measurements, the most recent reading will be cached and returned.

property temperature_offset: float

Specifies the offset to be added to the reported measurements to account for a bias in the measured signal. Value is in degrees Celsius with a resolution of 0.01 degrees and a maximum value of 374 C.

Note

This value will NOT be saved and will be reset on boot unless saved with persist_settings().

wake_up() → None

Wake the sensor from sleep mode back into the idle state (SCD41/SCD43).

The SCD4x does not acknowledge this command, so the resulting I2C NACK is expected and ignored here. To confirm the sensor actually reached the idle state, read serial_number afterwards. Call this before measure_single_shot() if the sensor was previously powered down.