API Reference

adafruit_sen6x

CircuitPython driver for the Sensirion SEN6x environmental sensor node

  • Author(s): Liz Clark

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_sen6x.DeviceStatus(status_data: int)

Helper class to parse the device status register

Parameters:

status_data – 32-bit status register value

property co2_sensor_1_error: bool

CO2 sensor 1 error (SEN68 only)

CO2 values might be unknown or wrong if this flag is set. This is a sticky error that persists until cleared.

property co2_sensor_2_error: bool

CO2 sensor 2 error (SEN66 only)

CO2 values might be unknown or wrong if this flag is set. RH and temperature values might be out of spec due to compensation algorithms. This is a sticky error that persists until cleared.

property errors: bool

Check if any error bits are set

property fan_error: bool

Fan error - fan is mechanically blocked or broken

Fan is switched on but 0 RPM measured for multiple consecutive intervals. All measured values are likely wrong if this error is reported. This is a sticky error that persists until cleared.

property gas_sensor_error: bool

VOC/NOx gas sensor error (SEN65, SEN66, SEN68)

VOC index and NOx index might be unknown or wrong if this flag is set. RH and temperature values might be out of spec due to compensation algorithms. This is a sticky error that persists until cleared.

property hcho_sensor_error: bool

Formaldehyde sensor error (SEN68 only)

HCHO values might be unknown or wrong if this flag is set. This is a sticky error that persists until cleared.

property pm_sensor_error: bool

Particulate matter sensor error (SEN63C, SEN65, SEN66, SEN68)

PM values might be unknown or wrong if this flag is set. RH and temperature values might be out of spec due to compensation algorithms. This is a sticky error that persists until cleared.

property rht_sensor_error: bool

Relative humidity and temperature sensor error (SEN63C, SEN65, SEN66, SEN68)

Temperature and humidity values might be unknown or wrong if this flag is set. Other measured values might be out of spec due to compensation algorithms. This is a sticky error that persists until cleared.

property speed_warning: bool

Fan speed out of range warning

property warnings: bool

Check if any warning bits are set

class adafruit_sen6x.SEN63C(i2c: busio.I2C, address: int = SEN6X_I2C_ADDRESS)

Driver for SEN63C sensor - measures PM, CO2, RH, and Temperature

Note: The CO2 sensor requires a 24-second conditioning period after starting a measurement. During this time, CO2 values will be reported as unknown (None).

all_measurements() → Dict[str, float | None]

All measurement values from SEN63C

Must be called when sensor is in measurement mode and data is ready. Note: CO2 values will be unknown (None) for the first 22-24 seconds after starting a measurement due to CO2 sensor conditioning.

Returns:

  • pm1_0: PM1.0 concentration (µg/m³) or None if unknown

  • pm2_5: PM2.5 concentration (µg/m³) or None if unknown

  • pm4_0: PM4.0 concentration (µg/m³) or None if unknown

  • pm10: PM10 concentration (µg/m³) or None if unknown

  • humidity: Relative humidity (%) or None if unknown

  • temperature: Temperature (°C) or None if unknown

  • co2: CO2 concentration (ppm) or None if unknown

Return type:

dict

Raises:

RuntimeError – If sensor is not in measurement mode

raw_values() → Dict[str, float | None]

Raw sensor values from SEN63C

Returns:

  • raw_humidity: Raw humidity (%) or None if unknown

  • raw_temperature: Raw temperature (°C) or None if unknown

Return type:

dict

class adafruit_sen6x.SEN66(i2c: busio.I2C, address: int = SEN6X_I2C_ADDRESS)

Driver for SEN66 sensor - measures PM, VOC, NOx, CO2, RH, and Temperature

all_measurements() → Dict[str, float | None]

All measurement values from SEN66

Must be called when sensor is in measurement mode and data is ready. Note: CO2 values will be 0xFFFF for first 5-6 seconds after measurement start. Note: NOx values will be 0x7FFF for first 10-11 seconds after power-on/reset.

Returns:

  • pm1_0: PM1.0 concentration (µg/m³) or None if unknown

  • pm2_5: PM2.5 concentration (µg/m³) or None if unknown

  • pm4_0: PM4.0 concentration (µg/m³) or None if unknown

  • pm10: PM10 concentration (µg/m³) or None if unknown

  • humidity: Relative humidity (%) or None if unknown

  • temperature: Temperature (°C) or None if unknown

  • voc_index: VOC index (1.0-500.0) or None if unknown

  • nox_index: NOx index (1.0-500.0) or None if unknown

  • co2: CO2 concentration (ppm) or None if unknown

Return type:

dict

Raises:

RuntimeError – If sensor is not in measurement mode

property nox_algorithm: Dict[str, int]

NOx algorithm tuning parameters

Returns:

Current NOx algorithm parameters

Return type:

dict

nox_algorithm_tuning(index_offset: int = 1, learning_time_offset_hours: int = 12, gating_max_duration_minutes: int = 720, gain_factor: int = 230) → None

NOx algorithm tuning parameters

Parameters:

  • index_offset – NOx index for average conditions (1-250, default: 1)

  • learning_time_offset_hours – Time constant for offset learning (1-1000, default: 12)

  • gating_max_duration_minutes – Max gating duration (0-3000, default: 720, 0=disabled)

  • gain_factor – Output gain factor (1-1000, default: 230)

Note: learning_time_gain_hours is fixed at 12, std_initial is fixed at 50 for NOx. Configuration is volatile and reset to defaults after power cycle.

raw_values() → Dict[str, float | None]

Raw sensor values from SEN66

Returns:

  • raw_humidity: Raw humidity (%)

  • raw_temperature: Raw temperature (°C)

  • raw_voc: Raw VOC ticks (no scale)

  • raw_nox: Raw NOx ticks (no scale)

  • raw_co2: Raw CO2 concentration (ppm, updated every 5s)

Return type:

dict

property voc_algorithm: Dict[str, int]

VOC algorithm tuning parameters

Returns:

Current VOC algorithm parameters

Return type:

dict

property voc_algorithm_state: bytes

VOC algorithm state for backup/restore

Can be called in either idle or measurement mode. In measurement mode, returns the current state. In idle mode, returns the state from when measurement was stopped.

Returns:

8-byte algorithm state that can be restored later

Return type:

bytes

voc_algorithm_tuning(index_offset: int = 100, learning_time_offset_hours: int = 12, learning_time_gain_hours: int = 12, gating_max_duration_minutes: int = 180, std_initial: int = 50, gain_factor: int = 230) → None

VOC algorithm tuning parameters

Parameters:

  • index_offset – VOC index for average conditions (1-250, default: 100)

  • learning_time_offset_hours – Time constant for offset learning (1-1000, default: 12)

  • learning_time_gain_hours – Time constant for gain learning (1-1000, default: 12)

  • gating_max_duration_minutes – Max gating duration (0-3000, default: 180, 0=disabled)

  • std_initial – Initial standard deviation (10-5000, default: 50)

  • gain_factor – Output gain factor (1-1000, default: 230)

Note: Configuration is volatile and reset to defaults after power cycle

class adafruit_sen6x.SEN6x(i2c: busio.I2C, address: int = SEN6X_I2C_ADDRESS)

Base class for Sensirion SEN6x environmental sensors

activate_sht_heater() → None

Activate the SHT sensor heater to reverse humidity creep

Raises:

RuntimeError – If sensor is currently measuring

property ambient_pressure: int

Ambient pressure used for CO2 compensation

Returns:

Current ambient pressure in hPa (hectopascals)

Return type:

int

check_sensor_errors() → None

Check device status and raise exception if critical errors present

This is a convenience method that checks for sensor errors that would make measurements unreliable. It’s recommended to call this before reading measurements.

Raises:

RuntimeError – If critical sensor errors are detected

clear_device_status() → None

Clear the device status register

This clears all error and warning flags. Note that if the error condition persists, the flags will be set again. All error flags are “sticky” - they remain set even if the error condition goes away, until explicitly cleared by this command or a device reset.

property co2: float | None

CO2 concentration in ppm

Applies to: SEN63C, SEN66, SEN69C

property co2_automatic_self_calibration: bool

CO2 sensor automatic self-calibration (ASC) status

Returns:

True if ASC is enabled, False if disabled

Return type:

bool

property data_ready: bool

Check if new measurement data is ready

Returns:

True if new data is available

Return type:

bool

property device_status: DeviceStatus

The device status register

Returns:

Object containing parsed status information

Return type:

DeviceStatus

property error_status_description: Dict[str, str]

Human-readable description of current errors and their effects

Returns:

Dictionary with error names and their implications

Return type:

dict

force_co2_recalibration(target_co2_ppm: int) → int | None

Perform forced CO2 recalibration (FRC)

Forces the CO2 sensor to recalibrate to a known reference concentration. This should be done when the sensor is in a controlled environment with a known CO2 concentration (e.g., fresh outdoor air at ~420 ppm).

Parameters:

target_co2_ppm – Known CO2 concentration in ppm at current location

Returns:

CO2 correction applied in ppm, or None if recalibration failed

Return type:

int

Raises:

RuntimeError – If sensor is currently measuring

Note: Sensor must be in idle mode. Wait at least 1000ms after power-on or 600ms after stop_measurement() before calling this.

property humidity: float | None

Relative humidity in percent

property nox_index: float | None

NOx index (1.0-500.0)

Applies to: SEN65, SEN66, SEN68, SEN69C

number_concentration() → Dict[str, float | None]

Particle number concentration values

Returns:

Dictionary containing number concentrations (particles/cm³):

  • nc_pm0_5: PM0.5 number concentration

  • nc_pm1_0: PM1.0 number concentration

  • nc_pm2_5: PM2.5 number concentration

  • nc_pm4_0: PM4.0 number concentration

  • nc_pm10: PM10 number concentration

Return type:

dict

property pm10: float | None

PM10 concentration in µg/m³

property pm1_0: float | None

PM1.0 concentration in µg/m³

property pm2_5: float | None

PM2.5 concentration in µg/m³

property pm4_0: float | None

PM4.0 concentration in µg/m³

property product_name: str

The product name (32 bytes)

reset() → None

Reset the sensor

After reset, the sensor needs time to start up before accepting commands. All configuration parameters are reset to default values.

property sensor_altitude: int

Sensor altitude used for CO2 compensation

Returns:

Current sensor altitude in meters above sea level

Return type:

int

property serial_number: str

The sensor serial number as ASCII string (up to 32 characters)

property sht_heater_measurements: Dict[str, float | None]

Measurements when SHT heater is active (firmware >= 4.0)

Returns heating progress measurements. If heating not finished, returns None values.

Returns:

{‘humidity’: value or None, ‘temperature’: value or None}

Return type:

dict

start_fan_cleaning() → None

Start the fan cleaning procedure

This accelerates the fan to maximum speed for 10 seconds to blow out dust that has accumulated in the fan/sensor housing. This command can only be executed when the sensor is in idle mode (not measuring).

After fan cleaning, wait at least 10 seconds before starting measurement.

Raises:

RuntimeError – If sensor is currently measuring

start_measurement() → None

Start continuous measurement mode

Once started, the sensor will continuously update its readings. Use data_ready property to check when new data is available.

stop_measurement() → None

Stop continuous measurement mode

Note: This command takes up to 1 second to execute.

property temperature: float | None

Temperature in Celsius

temperature_acceleration(k: float = 10.0, p: float = 10.0, t1: float = 10.0, t2: float = 10.0) → None

Temperature acceleration parameters for RH/T engine

Overwrites default temperature acceleration parameters.

Parameters:

  • k – Filter constant K (default: 10.0, actual = value/10)

  • p – Filter constant P (default: 10.0, actual = value/10)

  • t1 – Time constant T1 in seconds (default: 10.0, actual = value/10)

  • t2 – Time constant T2 in seconds (default: 10.0, actual = value/10)

Note: Configuration is volatile and reset to defaults after power cycle. Must be called in idle mode.

temperature_offset(offset: float = 0.0, slope: float = 0.0, time_constant: int = 0, slot: int = 0) → None

Temperature offset parameters for design-in compensation

Compensated temperature = ambient_temp + (slope * ambient_temp) + offset

Parameters:

  • offset – Constant temperature offset in °C (default: 0.0)

  • slope – Temperature dependent offset factor (default: 0.0)

  • time_constant – Time constant in seconds for applying changes (default: 0 = immediate)

  • slot – Offset slot to modify (0-4, default: 0)

Note: Configuration is volatile and reset to defaults after power cycle

property version: Tuple[int, int]

Firmware version information

Returns:

(major_version, minor_version)

Return type:

tuple

property voc_index: float | None

VOC index (1.0-500.0)

Applies to: SEN65, SEN66, SEN68, SEN69C