API Documentation

STC3x

STC3xI2cDevice

class sensirion_i2c_stc.stc3x.device.Stc3xI2cDevice(connection, slave_address=41)

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

__init__(connection, slave_address=41)

Constructs a new STC3x I²C device.

Parameters:

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

read_product_identifier()

Read the product identifier and sensor serial number.

Returns:The product number and serial number. Return type:tuple

set_bianry_gas(binary_gas)

Set Binary Gas

The STC3x measures the concentration of binary gas mixtures. It is important to note that the STC3x is not selective for gases, and it assumes that the binary gas is set correctly. The sensor can only give a correct concentration value when only the gases set with this command are present. When the system is reset, or wakes up from sleep mode, the sensor goes back to default mode, in which no binary gas is selected. This means that the binary gas must be reconfigured. When no binary gas is selected (default mode) the concentration measurement will return undefined results. This allows to detect unexpected sensor interruption (e.g. due to temporary power loss) and consequently reset the binary gas to the appropriate mixture.

Parameters:binary_gas (Stc31BinaryGas) – See section 3.3.2 in the corresponding datasheet for a list of available binary gases.

set_relative_humidity(relative_humidity_percent)

Set Relative Humidity

As mentioned in section 5.1 of the datasheet, the measurement principle of the concentration measurement is dependent on the humidity of the gas. With the set relative humidity command, the sensor uses internal algorithms to compensate the concentration results. When no value is written to the sensor after a soft reset, wake-up or power-up, a relative humidity of 0% is assumed. The value written to the sensor is used until a new value is written to the sensor

Parameters:relative_humidity_percent (float) – Relative humidity conditions.

set_temperature(temperature_degree_celsius)

Set Temperature

The concentration measurement requires a compensation of temperature. Per default, the sensor uses the internal temperature sensor to compensate the concentration results. However, when using the SHTxx, it is recommended to also use its temperature value, because it is more accurate. When no value is written to the sensor after a soft reset, wake-up or power-up, the internal temperature signal is used. The value written to the sensor is used until a new value is written to the sensor.

Parameters:temperature_degree_celsius (float) – Temperature conditions.

set_pressure(absolute_pressure)

Set Pressure

A pressure value can be written into the sensor, for density compensation of the gas concentration measurement. It is recommended to set the pressure level, if it differs significantly from 1013mbar. Pressure compensation is valid from 600mbar to 1200mbar. When no value is written to the sensor after a soft reset, wake-up or power-up, a pressure of 1013mbar is assumed. The value written is used until a new value is written to the sensor.

Parameters:absolute_pressure (int) – Ambient pressure condition in mbar (milli-bars)

measure_gas_concentration()

Measure Gas Concentration

The measurement of gas concentration is done in one measurement in a single shot, and takes less than 66ms. When measurement data is available, it can be read out by sending an I2C read header and reading out the data from the sensor. If no measurement data is available yet, the sensor will respond with a NACK on the I2C read header. In case the ‘Set temperature command’ has been used prior to the measurement command, the temperature value given out by the STC3x will be that one of the ‘Set temperature command’. When the ‘Set temperature command’ has not been used, the internal temperature value can be read out. During product development it is recommended to compare the internal temperature value of the STC3x and the temperature value of the SHTxx, to check whether both sensors are properly thermally coupled. The values must be within 0.7°C.

Note

The Gas concentration is a 16-bit unsigned integer. The temperature and byte 7 and 8 don’t need to be read out. The read sequence can be aborted after any byte by a NACK and a STOP condition. The measurement command should not be triggered more often than once a second.

Returns:

• gas_concentration (:py:class:sensirion_i2c_stc.stc3x.response_types.Stc3xGasConcentration) Gas concentration response object
• temperature (:py:class:sensirion_i2c_stc.stc3x.reasponse_types.Stc3xTemperature) Temperature response object.

Return type:tuple

perform_forced_recalibration(target_concentration)

Forced Recalibration

Forced recalibration (FRC) is used to improve the sensor output with a known reference value. See the Field Calibration Guide for more details. If no argument is given, the sensor will assume a default value of 0 vol%. This command will trigger a concentration measurement as described in 3.3.6 of the datasheet and therefore it will take the same measurement time.

Parameters:target_concentration (int) – Target concentration in vol%.

enable_automatic_self_calibration()

Enable Automatic Self Calibration

Enable the automatic self-calibration (ASC). The sensor can run in automatic self-calibration mode. This mode will enhance the accuracy for applications where the target gas is not present for the majority of the time. See the Field Calibration Guide for more details. This feature can be enabled or disabled by using the commands as shown below. The automatic self-calibration is optimized for a gas concentration measurement interval of 1s. Substantially different measurement intervals may decrease the self-calibration performance. The default state is disabled. Automatic self-calibration in combination with sleep mode requires a specific sequence of steps. See section 3.3.9 in the datasheet for more detailed instructions

Note

The sensor will apply automatic self-calibration

disable_automatic_self_calibration()

Disable Automatic Self Calibration

Disable the automatic self-calibration (ASC). The sensor can run in automatic self-calibration mode. This mode will enhance the accuracy for applications where the target gas is not present for the majority of the time. See the Field Calibration Guide for more details. This feature can be enabled or disabled by using the commands as shown below. The default state is disabled.

Note

The sensor will not apply automatic self-calibration. This is the default state of the sensor.

read_state()

Read out the sensor state.

Note

See section 3.3.9 of the datasheet for detailed instructions.

Returns:Current sensor state Return type:list(int)

apply_state(state)

Write the sensor state as read out earlier.

Note

See section 3.3.9 of the datasheet for detailed instructions.

Parameters:state (list(int)) – Previously sensor state to set and apply.

perform_self_test()

Self Test

The sensor will run an on-chip self-test. A successful self-test will return zero. The 16-bit result of a sensor self-test is a combination of possible error states, encoded as bits (starting with lsb).

Returns:0 means no malfunction detected Return type:int

enable_sleep_mode()

Enter Sleep Mode

Put sensor into sleep mode. In sleep mode the sensor uses the minimum amount of current. The mode can only be entered from idle mode, i.e. when the sensor is not measuring. This mode is particularly useful for battery operated devices. To minimize the current in this mode, the complexity of the sleep mode circuit has been reduced as much as possible, which is mainly reflected by the way the sensor exits the sleep mode. The sleep command can be sent after the result have been read out and the sensor is in idle mode. The sensor exits the sleep mode and enters the idle mode when it receives the valid I2C address and a write bit (‘0’). Note that the I2C address is not acknowledged. It is possible to poll the sensor to see whether the sensor has received the address and has woken up. This takes maximum 12ms.

Note

Only available in idle mode

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

STC3xI2cCommand

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdBase(command, tx_data, rx_length, read_delay, timeout, post_processing_time=0.0)

STC3x I²C base command.

__init__(command, tx_data, rx_length, read_delay, timeout, post_processing_time=0.0)

Constructs a new STC3x I²C command.

Parameters:

• command (int/None) – The command ID to be sent to the device. None means that no command will be sent, i.e. only tx_data (if not None) will be sent. No CRC is added to these bytes since the command ID usually already contains a CRC.
• tx_data (bytes-like/list/None) – Bytes to be extended with CRCs and then sent to the I²C device. None means that no write header will be sent at all (if command is None too). An empty list means to send the write header (even if command is None), but without data following it.
• rx_length (int/None) – Number of bytes to be read from the I²C device, including CRC bytes. None means that no read header is sent at all. Zero means to send the read header, but without reading any data.
• read_delay (float) – Delay (in Seconds) to be inserted between the end of the write operation and the beginning of the read operation. This is needed if the device needs some time to prepare the RX data, e.g. if it has to perform a measurement. Set to 0.0 to indicate that no delay is needed, i.e. the device does not need any processing time.
• timeout (float) – Timeout (in Seconds) to be used in case of clock stretching. If the device stretches the clock longer than this value, the transceive operation will be aborted with a timeout error. Set to 0.0 to indicate that the device will not stretch the clock for this command.
• post_processing_time (float) – Maximum time in seconds the device needs for post processing of this command until it is ready to receive the next command. For example after a device reset command, the device might need some time until it is ready again. Usually this is 0.0s, i.e. no post processing is needed.

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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdSetBinaryGas(binary_gas)

Set Binary Gas I²C Command

The STC3x measures the concentration of binary gas mixtures. It is important to note that the STC3x is not selective for gases, and it assumes that the binary gas is set correctly. The sensor can only give a correct concentration value when only the gases set with this command are present. When the system is reset, or wakes up from sleep mode, the sensor goes back to default mode, in which no binary gas is selected. This means that the binary gas must be reconfigured. When no binary gas is selected (default mode) the concentration measurement will return undefined results. This allows to detect unexpected sensor interruption (e.g. due to temporary power loss) and consequently reset the binary gas to the appropriate mixture.

__init__(binary_gas)

Constructor.

Parameters:binary_gas (int) – See section 3.3.2 in the corresponding datasheet for a list of available binary gases. See Stc31BinaryGas

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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdSetRelativeHumidity(relative_humidity_percent)

Set Relative Humidity I²C Command

As mentioned in section 5.1 of the datasheet, the measurement principle of the concentration measurement is dependent on the humidity of the gas. With the set relative humidity command, the sensor uses internal algorithms to compensate the concentration results. When no value is written to the sensor after a soft reset, wake-up or power-up, a relative humidity of 0% is assumed. The value written to the sensor is used until a new value is written to the sensor

__init__(relative_humidity_percent)

Constructor.

Parameters:relative_humidity_percent (float) – Relative humidity conditions.

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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdSetTemperature(temperature_degree_celsius)

Set Temperature I²C Command

The concentration measurement requires a compensation of temperature. Per default, the sensor uses the internal temperature sensor to compensate the concentration results. However, when using the SHTxx, it is recommended to also use its temperature value, because it is more accurate. When no value is written to the sensor after a soft reset, wake-up or power-up, the internal temperature signal is used. The value written to the sensor is used until a new value is written to the sensor.

__init__(temperature_degree_celsius)

Constructor.

Parameters:temperature_degree_celsius (float) – Temperature conditions.

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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdSetPressure(absolue_pressure)

Set Pressure I²C Command

A pressure value can be written into the sensor, for density compensation of the gas concentration measurement. It is recommended to set the pressure level, if it differs significantly from 1013mbar. Pressure compensation is valid from 600mbar to 1200mbar. When no value is written to the sensor after a soft reset, wake-up or power-up, a pressure of 1013mbar is assumed. The value written is used until a new value is written to the sensor.

__init__(absolue_pressure)

Constructor.

Parameters:absolue_pressure (int) – Ambient pressure in mbar (milli-bars)

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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdMeasureGasConcentration

Measure Gas Concentration I²C Command

The measurement of gas concentration is done in one measurement in a single shot, and takes less than 66ms. When measurement data is available, it can be read out by sending an I2C read header and reading out the data from the sensor. If no measurement data is available yet, the sensor will respond with a NACK on the I2C read header. In case the ‘Set temperature command’ has been used prior to the measurement command, the temperature value given out by the STC3x will be that one of the ‘Set temperature command’. When the ‘Set temperature command’ has not been used, the internal temperature value can be read out. During product development it is recommended to compare the internal temperature value of the STC3x and the temperature value of the SHTxx, to check whether both sensors are properly thermally coupled. The values must be within 0.7°C.

Note

The Gas concentration is a 16-bit unsigned integer. The temperature and byte 7 and 8 don’t need to be read out. The read sequence can be aborted after any byte by a NACK and a STOP condition. The measurement command should not be triggered more often than once a second.

__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:

• gas_concentration (:py:class:sensirion_i2c_stc.stc3x.response_types.Stc3xGasConcentration) Gas concentration response object
• temperature (:py:class:sensirion_i2c_stc.stc3x.reasponse_types.Stc3xTemperature) Temperature response object.

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

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdForcedRecalibration(reference_concentration_vol_percent)

Forced Recalibration I²C Command

Forced recalibration (FRC) is used to improve the sensor output with a known reference value. See the Field Calibration Guide for more details. If no argument is given, the sensor will assume a default value of 0 vol%. This command will trigger a concentration measurement as described in 3.3.6 of the datasheet and therefore it will take the same measurement time.

__init__(reference_concentration_vol_percent)

Constructor.

Parameters:reference_concentration_vol_percent (int) – Reference concentration

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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdEnableAutomaticSelfCalibration

Enable Automatic Self Calibration I²C Command

Enable the automatic self-calibration (ASC). The sensor can run in automatic self-calibration mode. This mode will enhance the accuracy for applications where the target gas is not present for the majority of the time. See the Field Calibration Guide for more details. This feature can be enabled or disabled by using the commands as shown below. The automatic self-calibration is optimized for a gas concentration measurement interval of 1s. Substantially different measurement intervals may decrease the self-calibration performance. The default state is disabled. Automatic self-calibration in combination with sleep mode requires a specific sequence of steps. See section 3.3.9 in the datasheet for more detailed instructions

Note

The sensor will apply automatic self-calibration

__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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdDisableAutomaticSelfCalibration

Disable Automatic Self Calibration I²C Command

Disable the automatic self-calibration (ASC). The sensor can run in automatic self-calibration mode. This mode will enhance the accuracy for applications where the target gas is not present for the majority of the time. See the Field Calibration Guide for more details. This feature can be enabled or disabled by using the commands as shown below. The default state is disabled.

Note

The sensor will not apply automatic self-calibration. This is the default state of the sensor.

__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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdPrepareReadState

Prepare Read State I²C Command

The sensor will prepare its current state to be read out.

Note

See section 3.3.9 of the datasheet for detailed instructions.

__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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdGetSensorState

Get Sensor State I²C Command

Read out the sensor state.

__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 sensor state Return type:list(int) Raises:I2cChecksumError – If a received CRC was wrong.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdSetSensorState(state)

Set Sensor State I²C Command

Write the sensor state as read out earlier.

__init__(state)

Constructor.

Parameters:state (list(int)) – Current sensor state

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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdApplyState

Apply State I²C Command

The sensor will apply the written state data.

Note

See section 3.3.9 of the datasheet for detailed instructions.

__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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdSelfTest

Self Test I²C Command

The sensor will run an on-chip self-test. A successful self-test will return zero. The 16-bit result of a sensor self-test is a combination of possible error states, encoded as bits (starting with lsb).

__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:Self test result. Error code or 0x0000 on success. Return type:int Raises:I2cChecksumError – If a received CRC was wrong.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdEnterSleepMode

Enter Sleep Mode I²C Command

Put sensor into sleep mode. In sleep mode the sensor uses the minimum amount of current. The mode can only be entered from idle mode, i.e. when the sensor is not measuring. This mode is particularly useful for battery operated devices. To minimize the current in this mode, the complexity of the sleep mode circuit has been reduced as much as possible, which is mainly reflected by the way the sensor exits the sleep mode. The sleep command can be sent after the result have been read out and the sensor is in idle mode. The sensor exits the sleep mode and enters the idle mode when it receives the valid I2C address and a write bit (‘0’). Note that the I2C address is not acknowledged. It is possible to poll the sensor to see whether the sensor has received the address and has woken up. This takes maximum 12ms.

Note

Only available in idle mode

__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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdPrepareProductIdentifier

Prepare Product Identifier I²C Command

Prepare for reading the product identifier and sensor serial number.

__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.

class sensirion_i2c_stc.stc3x.commands.Stc3xI2cCmdReadProductIdentifier

Read Product Identifier I²C Command

Read the product identifier and sensor serial number.

Note

Make sure to call ‘prepare product identifier’ immediately before.

__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:

• product_number (int) - 32-bit unique product and revision number. The number is listed below: STC31: 0x08010301
• serial_number (unsigned long long) 64-bit unique serial number

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

Data Types

class sensirion_i2c_stc.stc3x.data_types.Stc31BinaryGas

An enum containing all available binary gas configuratinos for the STC31 Sensor.

Co2InNo2Range100 = 0

CO2 in N2 Range: 0 to 100 vol%

Co2InAirRange100 = 1

CO2 in air Range: 0 to 100 vol%

Co2InNo2Range25 = 2

CO2 in N2 Range: 0 to 25 vol%

Co2InAirRange25 = 3

CO2 in air Range: 0 to 25 vol%

class sensirion_i2c_stc.stc3x.data_types.Stc3xRelativeHumidityConditionPercent(relative_humidity_percent)

Represents a relative humidity condition in percent.

With the ticks you can access the raw data as sent to the device.

Parameters:relative_humidity_percent (float) – The relative humidity in percent.

__init__(relative_humidity_percent)

Creates an instance from the configured condition.

percent_rh

The configured condition in percent.

ticks

The ticks (int) to pass to the device.

class sensirion_i2c_stc.stc3x.data_types.Stc3xTemperatureConditionDegC(degree_celsius)

Represents a temperature condition in degree celsius.

With the ticks you can access the raw data as sent to the device.

Parameters:degree_celsius (float) – The temperature as degree celsius

__init__(degree_celsius)

Creates an instance from the configured condition.

degrees_celsius

The temperature condition in °C.

degrees_fahrenheit

The temperature condition in °F.

ticks

The ticks (int) to pass to the device.

class sensirion_i2c_stc.stc3x.data_types.Stc3xReferenceConcentration(vol_percent)

Represents a reference gas concentration.

With the ticks you can access the raw data delivered to the device.

Parameters:vol_percent (float) – The gas concentration in vol%.

__init__(vol_percent)

Creates an instance from the provided raw data.

vol_percent

The concentration in vol%.

ticks

The ticks (int) as received from the device.

Response Types

class sensirion_i2c_stc.stc3x.response_types.Stc3xTemperature(ticks)

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.

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

__init__(ticks)

Creates an instance from the received raw data.

ticks

The ticks (int) as received from the device.

degrees_celsius

The converted temperature in °C.

degrees_fahrenheit

The converted temperature in °F.

class sensirion_i2c_stc.stc3x.response_types.Stc3xGasConcentration(ticks)

Represents a measurement response for the gas concentration.

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

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

__init__(ticks)

Creates an instance from the received raw data.

ticks

The ticks (int) as received from the device.

vol_percent

The converted concentration in vol%.