API Reference

Sen5xI2cDevice

class sensirion_i2c_sen5x.device.Sen5xI2cDevice(connection, slave_address=105)

SEN5x I²C device.

This is a low-level driver which just provides all I²C commands as Python methods. Typically, calling a method sends one I²C request to the device and interprets its response (if any).

There is no caching functionality in this driver. For example if you call get_serial_number() 100 times, it will send the command 100 times over the I²C interface to the device. This makes the driver completely stateless.

__init__(connection, slave_address=105)

Constructs a new SEN5x I²C device.

Parameters:

• connection (I2cConnection) – The I²C connection to use for communication.
• slave_address (byte) – The I²C slave address, defaults to 0x69.

get_product_name()

Get the product name of the device.

Returns:The product name as an ASCII string. Return type:string

get_serial_number()

Get the serial number of the device.

Returns:The serial number as an ASCII string. Return type:string

get_version()

Get the version of the device firmware, hardware and communication protocol.

Returns:The device version. Return type:Sen5xVersion

read_device_status(clear=False)

Read and optionally clear the device status.

Parameters:clear (bool) – If True, the status flags on the device get cleared after reading them. Defaults to False. Returns:The device status as an object containing all status flags. Return type:Sen5xDeviceStatus

device_reset()

Execute a device reset (reboot firmware, similar to power cycle).

start_measurement()

Starts a continuous measurement.

Note

After starting the measurement, it takes some time (~1s) until the first measurement results are available. You could poll with the method read_data_ready() to check when the results are ready to read.

Note

If the device is in measure mode without particulate matter (low-power) and the firmware version is at least 2.0, this command enables PM measurement without affecting the already running RH/T/VOC/NOx measurements (except that the “data ready”-flag will be cleared). In previous firmware versions, this command is supported only in idle mode.

start_measurement_without_pm()

Start a continuous measurement without particulate matter (low-power).

Only RH/T/VOC/NOx are measured in this mode, particulate matter is disabled to reduce power consumption.

Note

After starting the measurement, it takes some time (~1s) until the first measurement results are available. You could poll with the method read_data_ready() to check when the results are ready to read.

Note

If the device is in measure mode with particulate matter (normal measure mode) and the firmware version is at least 2.0, this command disables PM measurement without affecting the already running RH/T/VOC/NOx measurements (except that the “data ready”-flag will be cleared). In previous firmware versions, this command is supported only in idle mode.

Attention

SEN50 does not support this feature.

stop_measurement()

Stop the running measurement.

Leaves the measure mode and returns to the idle mode.

If the device is already in idle mode, this command has no effect.

read_data_ready()

Read the data ready flag.

This command can be used to check if new measurement results are ready to read. The data ready flag is automatically reset after reading the measured values with read_measured_values().

Note

During fan (auto-)cleaning, no measurement data is available for several seconds and thus this flag will not be set until cleaning has finished. So please expect gaps of several seconds at any time if fan auto-cleaning is enabled.

Returns:True if new data is ready, False if not. When no measurement is running, False will be returned. Return type:bool

read_measured_values()

Read the measured mass concentration, RH/T and VOC/NOx values.

Note

The method read_data_ready() can be used to check if new data is available since the last read operation. If no new data is available, the previous values will be returned again. If no data is available at all (no measurement running or immediately after starting the measurement), the returned object will not contain any measurement results (property available of all values is False).

Attention

The returned object always contains all measurement signals, but it depends on the measure mode and the product which signal values are actually available. See Sen5xMeasuredValues for details how it handles values which are not available. In particular, mass concentration values are not available in the low-power measure mode, RH/T/VOC are not available with SEN50 and NOx is not available with SEN50 and SEN54. In idle mode, no signal values will be available at all.

Returns:The latest measurement results. Return type:Sen5xMeasuredValues

get_temperature_offset_parameters(raw=False)

Get the temperature offset parameters of the device.

Attention

SEN50 does not support this feature.

Parameters:raw (bool) – If False (the default), physical/normalized values (offset in °C, slope with scale factor 1, time constant in seconds) are returned. Otherwise the raw received integer values of offset (scaled with factor 200) and slope (scaled with factor 10000) are returned. Returns:Tuple with offset (°C or ticks), slope (scale factor 1 or 10000) and time constant [s]. Return type:float/int, float/int, int

set_temperature_offset_parameters(offset, slope, time_constant_s, raw=False)

Set the temperature offset parameters of the device.

This command allows to compensate temperature effects of the design-in at customer side by applying a custom temperature offset to the ambient temperature. The compensated ambient temperature is calculated as follows:

T_Ambient_Compensated = T_Ambient + offset + (slope * T_Ambient)

Where slope and offset are the values set with this command, smoothed with the specified time constant.

All temperatures (T_Ambient_Compensated, T_Ambient and offset) in this formula are represented in °C.

Note

This configuration is volatile, i.e. it will be reverted to the default value after a device reset.

Attention

SEN50 does not support this feature.

Parameters:

• offset (float/int) – Constant temperature offset (°C or ticks). The default value is 0.
• slope (float/int) – Normalized temperature offset slope (scale factor 1 or 10000). The default value is 0.
• time_constant (int) – Time constant [s] how fast the new slope and offset will be applied. After the specified value in seconds, 63% of the new slope and offset are applied. A time constant of zero means the new values will be applied immediately (within the next measure interval of 1 second).
• raw (bool) – If False (the default), physical/normalized values are expected (offset in °C, slope with scale factor 1, time constant in seconds). Otherwise, raw integer values are expected for offset (scaled with factor 200) and slope (scaled with factor 10000).

get_warm_start_parameter(raw=False)

Get the warm start parameter of the device.

Attention

SEN50 does not support this feature.

Parameters:raw (bool) – If False (the default), a normalized value in the range from 0.0 (cold start) to 1.0 (warm start) is returned. Otherwise the raw received integer value is returned (0..65535). Returns:Warm start parameter value (0..1 or 0..65535). Return type:float/int

set_warm_start_parameter(warm_start, raw=False)

Set the warm start parameter of the device.

The temperature compensation algorithm is optimized for a cold start by default, i.e. it is assumed that the “Start Measurement” command is called on a device not already warmed up by previous measurements. If the measurement is started on a device already warmed up, this parameter can be used to improve the accuracy of the ambient temperature output.

Note

This parameter can be changed in any state of the device (and the getter immediately returns the new value), but it is applied only the next time starting a measurement, i.e. when sending a “Start Measurement” command! So the parameter needs to be set before a warm-start measurement is started.

Note

This configuration is volatile, i.e. it will be reverted to the default value after a device reset.

Attention

SEN50 does not support this feature.

Parameters:

• warm_start (float/int) – Warm start parameter value (0..1 or 0..65535).
• raw (bool) – If False (the default), a normalized value in the range from 0.0 (cold start) to 1.0 (warm start) is expected. Otherwise a raw integer value is expected (0..65535).

get_rht_acceleration_mode()

Get the RH/T acceleration mode of the device.

Attention

SEN50 does not support this feature.

Returns:The current RH/T acceleration mode. See set_rht_acceleration_mode() for the list of available modes. Return type:int

set_rht_acceleration_mode(mode)

Set the RH/T acceleration mode of the device.

By default, the RH/T acceleration algorithm is optimized for a sensor which is positioned in free air. If the sensor is integrated into another device, the ambient RH/T output values might not be optimal due to different thermal behavior. This parameter can be used to adapt the RH/T acceleration behavior for the actual use-case, leading in an improvement of the ambient RH/T output accuracy. There is a limited set of different modes available, each identified by a number:

• 0: Default / Air Purifier / IAQ (slow)
• 1: IAQ (fast)
• 2: IAQ (medium)

Note

This parameter can be changed in any state of the device (and the getter immediately returns the new value), but it is applied only the next time starting a measurement, i.e. when sending a “Start Measurement” command. So the parameter needs to be set before a new measurement is started.

Note

This configuration is volatile, i.e. it will be reverted to the default value after a device reset.

Attention

SEN50 does not support this feature.

Parameters:mode (int) – The new RH/T acceleration mode. The default is 0.

get_voc_tuning_parameters()

Get the currently set parameters for customizing the VOC algorithm.

Attention

SEN50 does not support this feature.

Returns:

• index_offset (int) - VOC index representing typical (average) conditions.
• learning_time_offset_hours (int) - Time constant to estimate the VOC algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time.
• learning_time_gain_hours (int) - Time constant to estimate the VOC algorithm gain from the history in hours. Past events will be forgotten after about twice the learning time.
• gating_max_duration_minutes (int) - Maximum duration of gating in minutes (freeze of estimator during high VOC index signal). Zero disables the gating.
• std_initial (int) - Initial estimate for standard deviation. Lower value boosts events during initial learning period, but may result in larger device-to-device variations.
• gain_factor (int) - Gain factor to amplify or to attenuate the VOC index output.

Return type:tuple

set_voc_tuning_parameters(index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)

Sets parameters to customize the VOC algorithm.

Note

This command is available only in idle mode. In measure mode, this command has no effect. In addition, it has no effect if at least one parameter is outside the specified range.

Note

This configuration is volatile, i.e. it will be reverted to the default value after a device reset.

Attention

SEN50 does not support this feature.

Parameters:

• index_offset (int) – VOC index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 100.
• learning_time_offset_hours (int) – Time constant to estimate the VOC algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
• learning_time_gain_hours (int) – Time constant to estimate the VOC algorithm gain from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
• gating_max_duration_minutes (int) – Maximum duration of gating in minutes (freeze of estimator during high VOC index signal). Set to zero to disable the gating. Allowed values are in range 0..3000. The default value is 180 minutes.
• std_initial (int) – Initial estimate for standard deviation. Lower value boosts events during initial learning period, but may result in larger device-to-device variations. Allowed values are in range 10..5000. The default value is 50.
• gain_factor (int) – Gain factor to amplify or to attenuate the VOC index output. Allowed values are in range 1..1000. The default value is 230.

get_nox_tuning_parameters()

Get the currently set parameters for customizing the NOx algorithm.

Attention

SEN50 and SEN54 do not support this feature.

Returns:

• index_offset (int) - NOx index representing typical (average) conditions.
• learning_time_offset_hours (int) - Time constant to estimate the NOx algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time.
• learning_time_gain_hours (int) - The time constant to estimate the NOx algorithm gain from the history has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command.
• gating_max_duration_minutes (int) - Maximum duration of gating in minutes (freeze of estimator during high NOx index signal). Zero disables the gating.
• std_initial (int) - The initial estimate for standard deviation has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command.
• gain_factor (int) - Gain factor to amplify or to attenuate the NOx index output.

Return type:tuple

set_nox_tuning_parameters(index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)

Sets parameters to customize the NOx algorithm.

Note

This command is available only in idle mode. In measure mode, this command has no effect. In addition, it has no effect if at least one parameter is outside the specified range.

Note

This configuration is volatile, i.e. it will be reverted to the default value after a device reset.

Attention

SEN50 and SEN54 do not support this feature.

Parameters:

• index_offset (int) – NOx index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 1.
• learning_time_offset_hours (int) – Time constant to estimate the NOx algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
• learning_time_gain_hours (int) – The time constant to estimate the NOx algorithm gain from the history has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command. This parameter must always be set to 12 hours.
• gating_max_duration_minutes (int) – Maximum duration of gating in minutes (freeze of estimator during high NOx index signal). Set to zero to disable the gating. Allowed values are in range 0..3000. The default value is 720 minutes.
• std_initial (int) – The initial estimate for standard deviation parameter has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command. This parameter must always be set to 50.
• gain_factor (int) – Gain factor to amplify or to attenuate the NOx index output. Allowed values are in range 1..1000. The default value is 230.

get_voc_state()

Get the current VOC algorithm state.

The returned data can be used to restore the state with the method set_voc_state() to resume operation after a short power cycle or device reset, skipping the initial learning phase of the VOC algorithm.

Note

This command can be used either in measure mode or in idle mode (which will then return the state at the time when the measurement was stopped). In measure mode, the state can be read each measure interval to always have the latest state available, even in case of a sudden power loss.

Note

This feature should only be used after at least 3 hours of continuous operation.

Attention

SEN50 does not support this feature.

Returns:Current VOC algorithm state. Return type:bytes

set_voc_state(state)

Set/restore the VOC algorithm state.

By default, the VOC algorithm resets its state to inital values each time a measurement is started, even if the measurement was stopped only for a short time. So the VOC index output value needs a long time until it is stable again. This can be avoided by restoring the algorithm state previously retrieved by get_voc_state() before starting the measure mode.

Note

This command is only available in idle mode and the state will be applied only once when starting the next measurement. Any further measurements (i.e. when stopping and restarting the measure mode) will reset the state to initial values. In measure mode, this command has no effect.

Note

This feature should not be used after interruptions of more than 10 minutes.

Attention

SEN50 does not support this feature.

Parameters:state (bytes) – VOC algorithm state to restore.

start_fan_cleaning()

Start fan cleaning.

Starts the fan cleaning manually by applying the maximum fan speed for a few seconds. The “data ready”-flag will be cleared immediately and during the next few seconds, no new measurement results will be available (old values will be returned). Once the cleaning is finished, the “data ready”-flag will be set and new measurement results will be available.

If you stop the measurement while fan cleaning is active, the cleaning will be aborted immediately.

Note

This command is only available in measure mode with PM measurement enabled, i.e. only if the fan is already running. In any other state, this command does nothing. In addition, when executing this command while cleaning is already active, the command does nothing.

get_fan_auto_cleaning_interval()

Get the fan auto cleaning interval of the device.

The device will automatically start the fan cleaning when the fan was running for this number of seconds.

Returns:Fan auto cleaning interval [s]. Zero means auto cleaning is disabled. Return type:int

set_fan_auto_cleaning_interval(interval_s)

Set the fan auto cleaning interval of the device.

The device will automatically start the fan cleaning when the fan was running for this number of seconds.

Note

This configuration is volatile, i.e. it will be reverted to the default value after a device reset.

Parameters:interval_s (int) – Fan auto cleaning interval [s]. Set to zero to disable auto cleaning. The default value is 604800 (1 week).

connection

Get the used I²C connection.

Returns:The used I²C connection. Return type:I2cConnection

execute(command)

Execute an I²C command on this device.

Parameters:command (I2cCommand) – The command to be executed. Returns:The interpreted response of the executed command. Return type:Depends on the executed command.

slave_address

Get the I²C slave address.

Returns:The I²C slave address. Return type:byte

Sen5xMeasuredValues

class sensirion_i2c_sen5x.measured_values.Sen5xMeasuredValues(values)

Represents a SEN5x measurement response for the “Read Measured Values” command.

__init__(values)

Constructor.

Example how to use this class:

values = device.read_measured_values()

# Pretty-print all values:
print(values)

# Access each physical value (as floats) separately:
mc_1p0 = values.mass_concentration_1p0.physical
mc_2p5 = values.mass_concentration_2p5.physical
mc_4p0 = values.mass_concentration_4p0.physical
mc_10p0 = values.mass_concentration_10p0.physical
ambient_rh = values.ambient_humidity.percent_rh
ambient_t = values.ambient_temperature.degrees_celsius
voc_index = values.voc_index.scaled
nox_index = values.nox_index.scaled

# Check if a value is available or not:
if values.nox_index.available:
    print("NOx ticks: {}".format(values.nox_index.ticks))
else:
    print("NOx is not available.")

Parameters:values (tuple(int)) – Raw integer values as received from the device.

values

All received raw values as a tuple of integers.

mass_concentration_1p0

Mass concentration PM1.0 (Sen5xMassConcentration).

mass_concentration_2p5

Mass concentration PM2.5 (Sen5xMassConcentration).

mass_concentration_4p0

Mass concentration PM4.0 (Sen5xMassConcentration).

mass_concentration_10p0

Mass concentration PM10.0 (Sen5xMassConcentration).

ambient_humidity

Ambient humidity (Sen5xHumidity).

ambient_temperature

Ambient temperature (Sen5xTemperature).

voc_index

VOC index (Sen5xAirQualityIndex).

nox_index

NOx index (Sen5xAirQualityIndex).

to_str(separator='\n')

Convert to printable string representation.

Parameters:separator (str) – Separator string. Returns:Printable representation. Return type:str

Response Data Types

Sen5xMassConcentration

class sensirion_i2c_sen5x.response_types.Sen5xMassConcentration(ticks)

Represents a SEN5x measurement response for the particulate matter mass concentration.

With the ticks attribute you can access the raw data as received from the device. For the converted physical value the physical attribute is available. The attribute available can be used to check whether the value is available or not.

__init__(ticks)

Creates an instance from the received raw data.

Parameters:ticks (int) – The read ticks as received from the device.

ticks

The ticks (int) as received from the device.

available

Flag (bool) whether the received value is available or not.

physical

The converted physical value (float) in µg/m³. This is NaN if the value is not available.

Sen5xHumidity

class sensirion_i2c_sen5x.response_types.Sen5xHumidity(ticks)

Represents a SEN5x measurement response for the humidity.

With the ticks attribute you can access the raw data as received from the device. For the converted value the percent_rh attribute is available. The attribute available can be used to check whether the value is available or not.

__init__(ticks)

Creates an instance from the received raw data.

Parameters:ticks (int) – The read ticks as received from the device.

ticks

The ticks (int) as received from the device.

available

Flag (bool) whether the received value is available or not.

percent_rh

The converted humidity (float) in %RH. This is NaN if the value is not available.

Sen5xTemperature

class sensirion_i2c_sen5x.response_types.Sen5xTemperature(ticks)

Represents a SEN5x measurement response for the temperature.

With the ticks attribute you can access the raw data as received from the device. For the converted values you can choose between degrees_celsius and degrees_fahrenheit. The attribute available can be used to check whether the value is available or not.

__init__(ticks)

Creates an instance from the received raw data.

Parameters:ticks (int) – The read ticks as received from the device.

ticks

The ticks (int) as received from the device.

available

Flag (bool) whether the received value is available or not.

degrees_celsius

The converted temperature (float) in °C. This is NaN if the value is not available.

degrees_fahrenheit

The converted temperature (float) in °F. This is NaN if the value is not available.

Sen5xAirQualityIndex

class sensirion_i2c_sen5x.response_types.Sen5xAirQualityIndex(ticks)

Represents a SEN5x measurement response for the air quality index.

With the ticks attribute you can access the raw data as received from the device. For the converted value the scaled attribute is available. The attribute available can be used to check whether the value is available or not.

__init__(ticks)

Creates an instance from the received raw data.

Parameters:ticks (int) – The read ticks as received from the device.

ticks

The ticks (int) as received from the device.

available

Flag (bool) whether the received value is available or not.

scaled

The converted/scaled index (float). This is NaN if the value is not available.

Sen5xDeviceStatus

class sensirion_i2c_sen5x.response_types.Sen5xDeviceStatus(value)

Represents a SEN5x device status response.

With the value attribute you can access the raw value as received from the device. The convenience attribute flags allows you to get all set flags as strings. In addition, each flag is provided as separate bool attribute.

__init__(value)

Creates an instance from the received raw data.

Parameters:value (int) – The raw device status value as received from the device.

value

The value (int) as received from the device.

flags

All currently set flags as a list of flag names, i.e. list(str)

fan_error

Flag (bool) whether a fan error occurred.

laser_error

Flag (bool) whether a laser error occurred.

sht_error

Flag (bool) whether an SHT error occurred.

sgp_error

Flag (bool) whether an SGP error occurred.

fan_cleaning

Flag (bool) whether the fan cleaning is currently active.

fan_speed_out_of_specs

Flag (bool) whether the fan speed is currently out of specs.

Sen5xVersion

class sensirion_i2c_sen5x.response_types.Sen5xVersion(firmware, hardware, protocol)

Class representing all version numbers of an I2C device. This is used for the “Get Version” command.

__init__(firmware, hardware, protocol)

Constructor.

Parameters:

• firmware (Sen5xFirmwareVersion) – Firmware version.
• hardware (Sen5xHardwareVersion) – Hardware version.
• protocol (Sen5xProtocolVersion) – SHDLC protocol version.

class sensirion_i2c_sen5x.response_types.Sen5xFirmwareVersion(major, minor, debug)

Class representing the firmware version of a device.

__init__(major, minor, debug)

Constructor.

Parameters:

• major (byte) – Major version.
• minor (byte) – Minor version.
• debug (bool) – Debug flag (False for official releases).

class sensirion_i2c_sen5x.response_types.Sen5xHardwareVersion(major, minor)

Class representing the hardware version of a device.

__init__(major, minor)

Constructor.

Parameters:

• major (byte) – Major version.
• minor (byte) – Minor version.

class sensirion_i2c_sen5x.response_types.Sen5xProtocolVersion(major, minor)

Class representing the I2C protocol version of an I2C device.

__init__(major, minor)

Constructor.

Parameters:

• major (byte) – Major version.
• minor (byte) – Minor version.

Commands

CmdStartMeasurement

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdStartMeasurement

Start Measurement I²C Command

Starts a continuous measurement.

After starting the measurement, it takes some time (~1s) until the first measurement results are available. You could poll with the command 0x0202 “Read Data Ready” to check when the results are ready to read.

If the device is in measure mode without PM and the firmware version is higher than 1.0, this command enables PM measurement without affecting the already running RH/T/VOC/NOx measurements (except that the “data ready”-flag will be cleared). If the device is in idle mode, this command starts the normal measurement. In any other case (e.g. normal measure mode already running), this command has no effect.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdStartMeasurementWithoutPm

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdStartMeasurementWithoutPm

Start Measurement Without PM I²C Command

Starts a continuous measurement without PM. Only humidity, temperature, VOC and NOx are available in this mode. Laser and fan are switched off to keep power consumption low.

After starting the measurement, it takes some time (~1s) until the first measurement results are available. You could poll with the command 0x0202 “Read Data Ready” to check when the results are ready to read.

If the device is in the normal measure mode and the firmware version is higher than 1.0, this command disables PM measurement without affecting the already running RH/T/VOC/NOx measurements (except that the “data ready”-flag will be cleared). If the device is in idle mode, this command starts the measurement without PM. In any other case (e.g. measure mode without PM already running), this command has no effect.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdStopMeasurement

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdStopMeasurement

Stop Measurement I²C Command

Stops the measurement and returns to idle mode.

If the device is already in idle mode, this command has no effect.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdReadDataReady

class sensirion_i2c_sen5x.commands.wrapped.Sen5xI2cCmdReadDataReady

Read Data Ready I²C Command

This command can be used to check if new measurement results are ready to read. The data ready flag is automatically reset after reading the measurement values with the 0x03.. “Read Measured Values” commands.

Note

During fan (auto-)cleaning, no measurement data is available for several seconds and thus this flag will not be set until cleaning has finished. So please expect gaps of several seconds at any time if fan auto-cleaning is enabled.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:True if data is ready, False if not. When no measurement is running, False will be returned. Return type:bool Raises:I2cChecksumError – If a received CRC was wrong.

__init__()

Constructor.

CmdReadMeasuredValues

class sensirion_i2c_sen5x.commands.wrapped.Sen5xI2cCmdReadMeasuredValues

Read Measured Values I²C Command

Returns the measured values.

The command 0x0202 “Read Data Ready” can be used to check if new data is available since the last read operation. If no new data is available, the previous values will be returned again.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:Object containing all measured values. Return type:Sen5xMeasuredValues Raises:I2cChecksumError – If a received CRC was wrong.

__init__()

Constructor.

CmdGetTemperatureOffsetParameters

class sensirion_i2c_sen5x.commands.wrapped.Sen5xI2cCmdGetTemperatureOffsetParameters(raw=False)

Get Temperature Offset Parameters I²C Command

Gets the temperature offset parameters from the device.

__init__(raw=False)

Constructor.

Parameters:raw (bool) – If False (the default), physical values are returned ([°C] for offset, [1] for slope). Otherwise the raw received integer values of offset (scaled with factor 200) and slope (scaled with factor 10000) are returned.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:

• offset (float/int) - Constant temperature offset.
• slope (float/int) - Normalized temperature offset slope.
• time_constant (int) - Time constant [s] how fast the slope and offset are applied. After the specified value in seconds, 63% of the new slope and offset are applied.

Return type:tuple Raises:I2cChecksumError – If a received CRC was wrong.

CmdSetTemperatureOffsetParameters

class sensirion_i2c_sen5x.commands.wrapped.Sen5xI2cCmdSetTemperatureOffsetParameters(offset, slope, time_constant, raw=False)

Set Temperature Offset Parameters I²C Command

Sets the temperature offset parameters for the device.

Note

This configuration is volatile, i.e. the parameters will be reverted to their default value of zero after a device reset.

__init__(offset, slope, time_constant, raw=False)

Constructor.

Parameters:

• offset (float/int) – Constant temperature offset. The default value is 0.
• slope (float/int) – Normalized temperature offset slope. The default value is 0.
• time_constant (int) – Time constant [s] how fast the new slope and offset will be applied. After the specified value in seconds, 63% of the new slope and offset are applied. A time constant of zero means the new values will be applied immediately (within the next measure interval of 1 second).
• raw (bool) – If False (the default), physical values are expected ([°C] for offset, [1] for slope). Otherwise, raw integer values are expected for offset (scaled with factor 200) and slope (scaled with factor 10000).

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdGetWarmStartParameter

class sensirion_i2c_sen5x.commands.wrapped.Sen5xI2cCmdGetWarmStartParameter(raw=False)

Get Warm Start Parameter I²C Command

Gets the warm start parameter from the device.

__init__(raw=False)

Constructor.

Parameters:raw (bool) – If False (the default), a normalized value in the range from 0.0 (cold start) to 1.0 (warm start) is returned. Otherwise, the raw received integer value is returned (0..65535).

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:Warm start parameter value. Return type:float/int Raises:I2cChecksumError – If a received CRC was wrong.

CmdSetWarmStartParameter

class sensirion_i2c_sen5x.commands.wrapped.Sen5xI2cCmdSetWarmStartParameter(warm_start, raw=False)

Set Warm Start Parameter I²C Command

Sets the warm start parameter for the device.

Note

This parameter can be changed in any state of the device (and the getter immediately returns the new value), but it is applied only the next time starting a measurement, i.e. when sending a “Start Measurement” command! So the parameter needs to be set before a warm-start measurement is started.

Note

This configuration is volatile, i.e. the parameter will be reverted to its default value of zero after a device reset.

__init__(warm_start, raw=False)

Constructor.

Parameters:

• warm_start (float/int) – Warm start parameter value. The default value is 0.
• raw (bool) – If False (the default), a normalized value in the range from 0.0 (cold start) to 1.0 (warm start) is expected. Otherwise a raw integer value is expected (0..65535).

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdGetRhtAccelerationMode

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdGetRhtAccelerationMode

Get RH/T Acceleration Mode I²C Command

Gets the RH/T acceleration mode.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The current RH/T acceleration mode. Return type:int Raises:I2cChecksumError – If a received CRC was wrong.

CmdSetRhtAccelerationMode

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdSetRhtAccelerationMode(mode)

Set RH/T Acceleration Mode I²C Command

Sets the RH/T acceleration mode.

Note

This parameter can be changed in any state of the device (and the getter immediately returns the new value), but it is applied only the next time starting a measurement, i.e. when sending a “Start Measurement” command. So the parameter needs to be set before a new measurement is started.

__init__(mode)

Constructor.

Parameters:mode (int) – The new RH/T acceleration mode.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdGetVocAlgorithmTuningParameters

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdGetVocAlgorithmTuningParameters

Get VOC Algorithm Tuning Parameters I²C Command

Gets the currently set tuning parameters of the VOC algorithm.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:

• index_offset (int) - VOC index representing typical (average) conditions.
• learning_time_offset_hours (int) - Time constant to estimate the VOC algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time.
• learning_time_gain_hours (int) - Time constant to estimate the VOC algorithm gain from the history in hours. Past events will be forgotten after about twice the learning time.
• gating_max_duration_minutes (int) - Maximum duration of gating in minutes (freeze of estimator during high VOC index signal). Zero disables the gating.
• std_initial (int) - Initial estimate for standard deviation. Lower value boosts events during initial learning period, but may result in larger device-to-device variations.
• gain_factor (int) - Gain factor to amplify or to attenuate the VOC index output.

Return type:tuple Raises:I2cChecksumError – If a received CRC was wrong.

CmdSetVocAlgorithmTuningParameters

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdSetVocAlgorithmTuningParameters(index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)

Set VOC Algorithm Tuning Parameters I²C Command

Sets the tuning parameters of the VOC algorithm.

Note

This command is available only in idle mode. In measure mode, this command has no effect. In addition, it has no effect if at least one parameter is outside the specified range.

__init__(index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)

Constructor.

Parameters:

• index_offset (int) – VOC index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 100.
• learning_time_offset_hours (int) – Time constant to estimate the VOC algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
• learning_time_gain_hours (int) – Time constant to estimate the VOC algorithm gain from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
• gating_max_duration_minutes (int) – Maximum duration of gating in minutes (freeze of estimator during high VOC index signal). Set to zero to disable the gating. Allowed values are in range 0..3000. The default value is 180 minutes.
• std_initial (int) – Initial estimate for standard deviation. Lower value boosts events during initial learning period, but may result in larger device-to-device variations. Allowed values are in range 10..5000. The default value is 50.
• gain_factor (int) – Gain factor to amplify or to attenuate the VOC index output. Allowed values are in range 1..1000. The default value is 230.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdGetNoxAlgorithmTuningParameters

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdGetNoxAlgorithmTuningParameters

Get NOx Algorithm Tuning Parameters I²C Command

Gets the currently set tuning parameters of the NOx algorithm.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:

• index_offset (int) - NOx index representing typical (average) conditions.
• learning_time_offset_hours (int) - Time constant to estimate the NOx algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time.
• learning_time_gain_hours (int) - The time constant to estimate the NOx algorithm gain from the history has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command.
• gating_max_duration_minutes (int) - Maximum duration of gating in minutes (freeze of estimator during high NOx index signal). Zero disables the gating.
• std_initial (int) - The initial estimate for standard deviation has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command.
• gain_factor (int) - Gain factor to amplify or to attenuate the NOx index output.

Return type:tuple Raises:I2cChecksumError – If a received CRC was wrong.

CmdSetNoxAlgorithmTuningParameters

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdSetNoxAlgorithmTuningParameters(index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)

Set NOx Algorithm Tuning Parameters I²C Command

Sets the tuning parameters of the NOx algorithm.

Note

This command is available only in idle mode. In measure mode, this command has no effect. In addition, it has no effect if at least one parameter is outside the specified range.

__init__(index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)

Constructor.

Parameters:

• index_offset (int) – NOx index representing typical (average) conditions. Allowed values are in range 1..250. The default value is 1.
• learning_time_offset_hours (int) – Time constant to estimate the NOx algorithm offset from the history in hours. Past events will be forgotten after about twice the learning time. Allowed values are in range 1..1000. The default value is 12 hours.
• learning_time_gain_hours (int) – The time constant to estimate the NOx algorithm gain from the history has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command. This parameter must always be set to 12 hours.
• gating_max_duration_minutes (int) – Maximum duration of gating in minutes (freeze of estimator during high NOx index signal). Set to zero to disable the gating. Allowed values are in range 0..3000. The default value is 720 minutes.
• std_initial (int) – The initial estimate for standard deviation parameter has no impact for NOx. This parameter is still in place for consistency reasons with the VOC tuning parameters command. This parameter must always be set to 50.
• gain_factor (int) – Gain factor to amplify or to attenuate the NOx index output. Allowed values are in range 1..1000. The default value is 230.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdGetVocAlgorithmState

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdGetVocAlgorithmState

Get VOC Algorithm State I²C Command

Gets the current VOC algorithm state. This data can be used to restore the state with the “Set VOC Algorithm State” command after a short power cycle or device reset.

This command can be used either in measure mode or in idle mode (which will then return the state at the time when the measurement was stopped). In measure mode, the state can be read each measure interval to always have the latest state available, even in case of a sudden power loss.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:Current VOC algorithm state. Return type:bytes Raises:I2cChecksumError – If a received CRC was wrong.

CmdSetVocAlgorithmState

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdSetVocAlgorithmState(state)

Set VOC Algorithm State I²C Command

Sets the VOC algorithm state previously received with the “Get VOC Algorithm State” command.

Note

This command is only available in idle mode and the state will be applied only once when starting the next measurement. Any further measurements (i.e. when stopping and restarting the measure mode) will reset the state to initial values. In measure mode, this command has no effect.

__init__(state)

Constructor.

Parameters:state (bytes) – VOC algorithm state to restore.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdStartFanCleaning

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdStartFanCleaning

Start Fan Cleaning I²C Command

Starts the fan cleaning manually. The “data ready”-flag will be cleared immediately and during the next few seconds, no new measurement results will be available (old values will be returned). Once the cleaning is finished, the “data ready”-flag will be set and new measurement results will be available.

When executing this command while cleaning is already active, the command does nothing.

If you stop the measurement while fan cleaning is active, the cleaning will be aborted immediately.

Note

This command is only available in measure mode with PM measurement enabled, i.e. only if the fan is already running. In any other state, this command does nothing.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdGetFanAutoCleaningInterval

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdGetFanAutoCleaningInterval

Get Fan Auto Cleaning Interval I²C Command

Gets the fan auto cleaning interval from the device.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:Fan auto cleaning interval [s]. Zero means auto cleaning is disabled. Return type:int Raises:I2cChecksumError – If a received CRC was wrong.

CmdSetFanAutoCleaningInterval

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdSetFanAutoCleaningInterval(interval)

Set Fan Auto Cleaning Interval I²C Command

Sets the fan auto cleaning interval for the device.

__init__(interval)

Constructor.

Parameters:interval (int) – Fan auto cleaning interval [s]. Set to zero to disable auto cleaning.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.

CmdGetProductName

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdGetProductName

Get Product Name I²C Command

Gets the product name from the device.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:Null-terminated ASCII string containing the product name. Up to 32 characters can be read from the device. Return type:str Raises:I2cChecksumError – If a received CRC was wrong.

CmdGetSerialNumber

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdGetSerialNumber

Get Serial Number I²C Command

Gets the serial number from the device.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:Null-terminated ASCII string containing the serial number. Up to 32 characters can be read from the device. Return type:str Raises:I2cChecksumError – If a received CRC was wrong.

CmdGetVersion

class sensirion_i2c_sen5x.commands.wrapped.Sen5xI2cCmdGetVersion

Get Version I²C Command

Gets the version information for the hardware, firmware and communication protocol.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The device version as an object. Return type:Sen5xVersion Raises:I2cChecksumError – If a received CRC was wrong.

__init__()

Constructor.

CmdReadDeviceStatus

class sensirion_i2c_sen5x.commands.wrapped.Sen5xI2cCmdReadDeviceStatus

Read Device Status I²C Command

Reads the current device status flags.

Note

The status flags of type “Error” are sticky, i.e. they are not cleared automatically even if the error condition no longer exists. So they can only be cleared manually with the command 0xD210 “Read And Clear Device Status” or with a device reset. All other flags are not sticky, i.e. they are cleared automatically if the trigger condition disappears.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:Device status as an object. Return type:Sen5xDeviceStatus Raises:I2cChecksumError – If a received CRC was wrong.

__init__()

Constructor.

CmdReadAndClearDeviceStatus

class sensirion_i2c_sen5x.commands.wrapped.Sen5xI2cCmdReadAndClearDeviceStatus

Read And Clear Device Status I²C Command

Reads the current device status (like command 0xD206 “Read Device Status”) and afterwards clears all flags.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the interpreted data.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:Device status as an object. Return type:Sen5xDeviceStatus Raises:I2cChecksumError – If a received CRC was wrong.

__init__()

Constructor.

CmdDeviceReset

class sensirion_i2c_sen5x.commands.generated.Sen5xI2cCmdDeviceReset

Device Reset I²C Command

Executes a reset on the device. This has the same effect as a power cycle.

__init__()

Constructor.

interpret_response(data)

Validates the CRCs of the received data from the device and returns the data with all CRCs removed.

Parameters:data (bytes) – Received raw bytes from the read operation. Returns:The received bytes, or None if there is no data received. Return type:bytes or None Raises:I2cChecksumError – If a received CRC was wrong.