API Reference

Svm41I2cDevice

class sensirion_i2c_svm41.device.Svm41I2cDevice(connection, slave_address=106)[source]

SVM41 I²C device class to allow executing I²C commands.

__init__(connection, slave_address=106)[source]

Constructs a new SVM41 I²C device.

Parameters:

  • connection (I2cConnection) – The I²C connection to use for communication.

  • slave_address (byte) – The I²C slave address, defaults to 0x6A.

device_reset()[source]

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

get_serial_number()[source]

Get the serial number of the device.

Returns:

The serial number as an ASCII string.

Return type:

string

get_version()[source]

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

Returns:

The device version.

Return type:

Version

get_compensation_temperature_offset()[source]

Gets the temperature offset for RHT measurements.

Returns:

Temperature offset in degrees celsius.

Return type:

float

set_compensation_temperature_offset(t_offset)[source]

Sets the temperature offset for RHT measurements.

Note

Execute the command store_nv_data() command after writing the parameter to store it in the non-volatile memory of the device otherwise the parameter will be reset upton a device reset.

Parameters:

t_offset (float) – Temperature offset in degrees celsius.

get_voc_tuning_parameters()[source]

Gets the currently set parameters for customizing the VOC algorithm.

Returns:

  • voc_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) - Factor to amplify or to attenuate the VOC Index output.

Return type:

tuple

set_voc_tuning_parameters(voc_index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)[source]

Sets parameters to customize the VOC algorithm. This command is only available in idle mode.

Note

Execute the command store_nv_data() after writing the parameter to store it in the non-volatile memory of the device otherwise the parameter will be reset upton a device reset.

Parameters:

  • voc_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()[source]

Gets the currently set parameters for customizing the NOx algorithm.

Returns:

  • nox_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. This getter will always return the default value.

  • 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. This getter will always return the default value.

  • gain_factor (int) - Factor to amplify or to attenuate the NOx Index output.

Return type:

tuple

set_nox_tuning_parameters(nox_index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)[source]

Sets parameters to customize the NOx algorithm. This command is only available in idle mode.

Note

Execute the store command after writing the parameter to store it in the non-volatile memory of the device otherwise the parameter will be reset upton a device reset.

Parameters:

  • nox_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 the NOx algorithm. 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 the NOx algorithm. 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 VOC index output. Allowed values are in range 1..1000. The default value is 230.

store_nv_data()[source]

Stores all customer engine parameters to the non-volatile memory.

get_voc_state()[source]

Gets the current VOC algorithm state. Retrieved values can be used to set the VOC algorithm state to resume operation after a short interruption, skipping initial learning phase. This command is only available during measurement mode.

Note

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

Returns:

Current VOC algorithm state.

Return type:

bytes

set_voc_state(state)[source]

Set previously retrieved VOC algorithm state to resume operation after a short interruption, skipping initial learning phase. This command is only available in idle mode.

Note

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

Parameters:

state (bytes) – Current VOC algorithm state.

start_measurement()[source]

Starts continuous measurement.

Note

This command is only available in idle mode.

stop_measurement()[source]

Leaves the measurement mode and returns to the idle mode.

Note

This command is only available in measurement mode.

read_measured_values()[source]

Returns the new measurement results.

Note

This command is only available in measurement mode. The firmware updates the measurement values every second. Polling data with a faster sampling rate will return the same values. The first measurement is available 1 second after the start measurement command is issued. Any readout prior to this will return zero initialized values.

Returns:

The measured humidity, temperature, voc and nox air quality.

  • humidity (Humidity) - Humidity response object.

  • temperature (Temperature) - Temperature response object.

  • air_quality_voc (AirQualityVoc) - Air quality voc response object.

  • air_quality_nox (AirQualityNox) - Air quality nox response object.

Return type:

tuple

read_measured_values_raw()[source]

Returns the new measurement results with raw values added.

Note

This command is only available in measurement mode. The firmware updates the measurement values every second. Polling data with a faster sampling rate will return the same values. The first measurement is available 1 second after the start measurement command is issued. Any readout prior to this will return zero initialized values.

Returns:

The measured air quality, humidity and temperature including the raw values without algorithm compensation.

  • raw_humidity (Humidity) - Humidity response object.

  • raw_temperature (Temperature) - Temperature response object.

  • raw_voc_ticks (int) - Raw VOC output ticks as read from the SGP sensor.

  • raw_nox_ticks (int) - Raw NOx output ticks as read from the SGP sensor.

Return type:

tuple

Response Data Types

Air Quality VOC

class sensirion_i2c_svm41.response_types.AirQualityVoc(ticks)[source]

Represents a measurement response for the VOC air quality.

With the ticks you can access the raw data as received from the device. For the converted value the voc_index attribute is available.

__init__(ticks)[source]

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.

voc_index

The converted VOC index.

Air Quality NOx

class sensirion_i2c_svm41.response_types.AirQualityNox(ticks)[source]

Represents a measurement response for the NOx air quality.

With the ticks you can access the raw data as received from the device. For the converted value the nox_index attribute is available.

__init__(ticks)[source]

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.

nox_index

The converted NOx index.

Humidity

class sensirion_i2c_svm41.response_types.Humidity(ticks)[source]

Represents a measurement response for the humidity.

With the ticks you can access the raw data as received from the device. For the converted value the percent_rh attribute is available.

__init__(ticks)[source]

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.

percent_rh

The converted humidity in %RH.

Temperature

class sensirion_i2c_svm41.response_types.Temperature(ticks)[source]

Represents a measurement response for the temperature.

With the ticks you can access the raw data as received from the device. For the converted values you can choose between degrees_celsius and degrees_fahrenheit.

__init__(ticks)[source]

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.

degrees_celsius

The converted temperature in °C.

degrees_fahrenheit

The converted temperature in °F.

Version

class sensirion_i2c_svm41.version_types.FirmwareVersion(major, minor, debug)[source]

Class representing the firmware version of a device.

__init__(major, minor, debug)[source]

Constructor.

Parameters:

  • major (byte) – Major version (0..255).

  • minor (byte) – Minor version (0..99).

  • debug (bool) – Debug flag (False for official releases).

class sensirion_i2c_svm41.version_types.HardwareVersion(major, minor)[source]

Class representing the hardware version of a device.

__init__(major, minor)[source]

Constructor.

Parameters:

  • major (byte) – Major version (0..255).

  • minor (byte) – Minor version (0..99).

class sensirion_i2c_svm41.version_types.ProtocolVersion(major, minor)[source]

Class representing the I2C protocol version of an I2C device.

__init__(major, minor)[source]

Constructor.

Parameters:

  • major (byte) – Major version (0..255).

  • minor (byte) – Minor version (0..99).

class sensirion_i2c_svm41.version_types.Version(firmware, hardware, protocol)[source]

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

__init__(firmware, hardware, protocol)[source]

Constructor.

Parameters:

Commands

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdGetSerialNumber[source]

Get Serial Number I²C Command

Gets the serial number from the device.

__init__()[source]

Constructor.

interpret_response(data)[source]

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:

Ascii string containing the serial number. The string has the null-termination character included.

Return type:

str

Raises:

I2cChecksumError – If a received CRC was wrong.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdDeviceReset[source]

Device Reset I²C Command

Executs a reset on the device.

Note

The device will reply before executing the reset.

__init__()[source]

Constructor.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdStartMeasurement[source]

Start Measurement I²C Command

Starts continuous measurement in polling mode.

Note

This command is only available in idle mode.

__init__()[source]

Constructor.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdStopMeasurement[source]

Stop Measurement I²C Command

Stops the measurement mode and returns to idle mode.

Note

This command is only available in measurement mode.

__init__()[source]

Constructor.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdGetVocAlgorithmTuningParameters[source]

Get VOC Algorithm Tuning Parameters I²C Command

Gets the currently set parameters for customizing the VOC algorithm

__init__()[source]

Constructor.

interpret_response(data)[source]

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:

  • voc_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) - Factor to amplify or to attenuate the VOC Index output.

Return type:

tuple

Raises:

I2cChecksumError – If a received CRC was wrong.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdSetVocAlgorithmTuningParameters(voc_index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)[source]

Set VOC Algorithm Tuning Parameters I²C Command

Sets the parameters to customize the VOC algorithm. This command is only available in idle mode.

__init__(voc_index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)[source]

Constructor.

Parameters:

  • voc_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.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdGetVocAlgorithmState[source]

Get VOC Algorithm State I²C Command

Gets the current VOC algorithm state.

__init__()[source]

Constructor.

interpret_response(data)[source]

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.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdSetVocAlgorithmState(state)[source]

Set VOC Algorithm State I²C Command

Sets the VOC algorithm state. This command is only available in idle mode.

__init__(state)[source]

Constructor.

Parameters:

state (bytes) – Current VOC algorithm state.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdGetNoxAlgorithmTuningParameters[source]

Get NOx Algorithm Tuning Parameters I²C Command

Gets the currently set parameters for customizing the NOx algorithm

__init__()[source]

Constructor.

interpret_response(data)[source]

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:

  • nox_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. This getter will always return the default value.

  • 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. This getter will always return the default value.

  • gain_factor (int) - Factor to amplify or to attenuate the NOx Index output.

Return type:

tuple

Raises:

I2cChecksumError – If a received CRC was wrong.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdSetNoxAlgorithmTuningParameters(nox_index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)[source]

Set NOx Algorithm Tuning Parameters I²C Command

Sets the parameters to customize the NOx algorithm. This command is only available in idle mode.

__init__(nox_index_offset, learning_time_offset_hours, learning_time_gain_hours, gating_max_duration_minutes, std_initial, gain_factor)[source]

Constructor.

Parameters:

  • nox_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 the NOx algorithm. 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 the NOx algorithm. 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 VOC index output. Allowed values are in range 1..1000. The default value is 230.

class sensirion_i2c_svm41.commands.generated.Svm41I2cCmdStoreNvData[source]

Store Nv Data I²C Command

Stores all algorithm parameters to the non-volatile memory.

__init__()[source]

Constructor.

class sensirion_i2c_svm41.commands.wrapped.Svm41I2cCmdGetVersion[source]

Get Version I²C Command

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

__init__()[source]

Constructor.

interpret_response(data)[source]

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 a Version object.

Return type:

Version

Raises:

I2cChecksumError – If a received CRC was wrong.

class sensirion_i2c_svm41.commands.wrapped.Svm41I2cCmdReadMeasuredValues[source]

Returns the new measurement results.

Note

This command is only available in measurement mode. The firmware updates the measurement values every second. Polling data with a faster sampling rate will return the same values. The first measurement is available 1 second after the start measurement command is issued. Any readout prior to this will return zero initialized values.

__init__()[source]

Constructor.

interpret_response(data)[source]

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 measured humidity, temperature, voc and nox air quality.

  • humidity (Humidity) - Humidity response object.

  • temperature (Temperature) - Temperature response object.

  • air_quality_voc (AirQualityVoc) - Air quality voc response object.

  • air_quality_nox (AirQualityNox) - Air quality nox response object.

Return type:

tuple

Raises:

I2cChecksumError – If a received CRC was wrong.

class sensirion_i2c_svm41.commands.wrapped.Svm41I2cCmdReadMeasuredValuesRaw[source]

Returns the new measurement results with raw values added.

Note

This command is only available in measurement mode. The firmware updates the measurement values every second. Polling data with a faster sampling rate will return the same values. The first measurement is available 1 second after the start measurement command is issued. Any readout prior to this will return zero initialized values.

__init__()[source]

Constructor.

interpret_response(data)[source]

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 measured air quality, humidity and temperature including the raw values without algorithm compensation. - humidity (Humidity) -

Humidity response object.

  • temperature (Temperature) - Temperature response object.

  • raw_voc_ticks (AirQualityVoc) - Raw VOC output ticks as read from the SGP sensor.

  • raw_nox_ticks (AirQualityNox) - Raw NOx output ticks as read from the SGP sensor.

Return type:

tuple

Raises:

I2cChecksumError – If a received CRC was wrong.

class sensirion_i2c_svm41.commands.wrapped.Svm41I2cCmdGetTemperatureOffsetForRhtMeasurements[source]

Get Temperature Offset For Rht Measurements I²C Command

Gets the T-Offset for the temperature compensation of the RHT algorithm.

__init__()[source]

Constructor.

interpret_response(data)[source]

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:

Temperature offset in degrees celsius.

Return type:

float

Raises:

I2cChecksumError – If a received CRC was wrong.

class sensirion_i2c_svm41.commands.wrapped.Svm41I2cCmdSetTemperatureOffsetForRhtMeasurements(t_offset)[source]

Set Temperature Offset For Rht Measurements I²C Command

Sets the T-Offset for the temperature compensation of the RHT algorithm.

__init__(t_offset)[source]

Constructor.

Parameters:

t_offset (float) – Temperature offset in degrees celsius.