API Documentation

STC3X

Stc3xDevice

The class Stc3xDeviceBase implements the low level interface of the sensor. The class Stc3xDevice extends the Stc3xDeviceBase. It provides additional functions to ease the use of the sensor.

class sensirion_i2c_stc3x.device.Stc3xDeviceBase(channel)

Low level API implementation of STC3X

__init__(channel)

property channel

set_binary_gas(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 –

See section 3.3.2 in the corresponding datasheet for a list of available binary gases.

STC31-C:

• 0x0010: CO₂ in N₂ for range in 0 to 100 vol%

• 0x0011: CO₂ in air for range in 0 to 100 vol%

• 0x0012: CO₂ in N₂ for range in 0 to 40 vol%

• 0x0013: CO₂ in air for range in 0 to 40 vol%

STC31:

• 0x0000: CO₂ in N₂ for range in 0 to 100 vol%

• 0x0001: CO₂ in air for range in 0 to 100 vol%

• 0x0002: CO₂ in N₂ for range in 0 to 25 vol%

• 0x0003: CO₂ in air for range in 0 to 25 vol%

Example

sensor.set_binary_gas(19)

set_relative_humidity_raw(relative_humidity_ticks)

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_ticks – Convert %RH to value by: RH * (2^16 - 1) / 100

Example

sensor.set_relative_humidity_raw(32768)

set_temperature_raw(temperature_ticks)

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_ticks – Convert °C to value by: T * 200

set_pressure(absolue_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

absolue_pressure – Ambient pressure in mbar (milli-bars)

measure_gas_concentration_raw()

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.

Return gas_ticks

Gas concentration. Convert to vol % by 100 * (value - 2^14) / 2^15

Return temperature_ticks

Temperature. Convert to °C by value / 200

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.

forced_recalibration(reference_concentration)

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

reference_concentration – Reference concentration

Example

sensor.forced_recalibration(0)

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

prepare_read_state()

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

Note

See section 3.3.9 of the datasheet for detailed instructions.

read_sensor_state()

Read out the sensor state. The 30 bytes must be stored on the microcontroller to be written back to the sensor after exiting sleep mode.

Return state

Current sensor state

Note

See section 3.3.9 of the datasheet for detailed instructions.

write_sensor_state(state)

Write the sensor state. The 30 bytes must be stored on the microcontroller to be written back to the sensor after exiting sleep mode.

Parameters

state – Current sensor state

Note

See section 3.3.9 of the datasheet for detailed instructions.

apply_state()

The sensor will apply the written state data.

Note

See section 3.3.9 of the datasheet for detailed instructions.

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

• 0-1: Memory error

• 2: VDD out of range

• 3-8: Measurement value error

• 9: Difference between externally supplied temperature (see 2.3.4) and internally measured temperatures exceeds the accuracy specifications.

In case of a successful self-test the sensor returns 0x0000 with correct CRC.

Return self_test_output

Self test result. Error code or 0x0000 on success.

prepare_product_identifier()

Prepare for reading the product identifier and sensor serial number.

read_product_identifier()

Read the product identifier and sensor serial number.

Return product_number

32-bit unique product and revision number. The number is listed below: STC31: 0x08010301

Return serial_number_high

Higher 32-bit of the 64-bit unique serial number

Return serial_number_low

Lower 32-bit of the 64-bit unique serial number

Note

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

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.

Note

Only available in idle mode

exit_sleep_mode()

Exit the sleep 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.

enable_weak_filter()

The STC31 has two built-in noise filters that run an exponential smoothing over the past measurement points. By default, no filter is applied to the data. If weak smoothing is desired, the following command(s) must be executed once upon starting the sensor. When enabled, the weak filter is applied for all subsequent concentration measurements.

Note

• Both filters can be activated at the same time (chained) for stronger smoothing.

• FRC can only benefit from this filtering if sufficient measurement points have been taken before executing the FRC.

• The response time (specified in section 1.2) will increase if a noise filter is applied.

• Filtering will not function if the sensor is put to sleep between each concentration measurement, asthe last output value is lost.

disable_weak_filter()

disable the weak smoothing filter

enable_strong_filter()

The STC31 has two built-in noise filters that run an exponential smoothing over the past measurement points. By default, no filter is applied to the data. If strong smoothing is desired, the following command(s) must be executed once upon starting the sensor. When enabled, the strong filter is applied for all subsequent concentration measurements.

Note

• Both filters can be activated at the same time (chained) for stronger smoothing.

• FRC can only benefit from this filtering if sufficient measurement points have been taken before executing the FRC.

• The response time (specified in section 1.2) will increase if a noise filter is applied.

• Filtering will not function if the sensor is put to sleep between each concentration measurement, asthe last output value is lost.

disable_strong_filter()

disable the strong smoothing filter

class sensirion_i2c_stc3x.device.Stc3xDevice(channel)

Driver class implementation of STC3X

stc3x

Access to base class

__init__(channel)

set_relative_humidity(relative_humidity)

The measurement principle of the concentration measurement is dependent on the humidity of the gas. The new low cross sensitivity mode reduces this sensitivity by smart internal compensation to a minimum. If possible, it is still recommended to compensate for relative humidity and to update the compensation input whenever the relative humidity changes. With the set relative humidity command, the sensor uses the set humidity in the gas model to compensate the concentration results.

Parameters

relative_humidity – Relative humidity in percent %.

set_temperature(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. The temperature compensation input should be updated whenever the temperature changes.

Parameters

temperature – Temperature in degree celsius.

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.

Return co2_concentration

Return temperature

get_sensor_state()

The sensor stores settings like the Gas Mode or reference values of FRC and ASC in volatile memory. These are not retained when the sensor loses power and must be stored externally to be sent to the sensor after each power cycle. To store the state externally use the methods get_sensor_state and set_sensor_state.

The sensor state contains the following information: - Selected binary gas index. - ON or OFF flag and offset value to apply to the sensor’s output for the automatic self-calibration. - Offset value to apply to the sensor’s output used in forced recalibration. - Compensation inputs: last supplied values of temperature, humidity and pressure

Return state

Current sensor state

set_sensor_state(sensor_state)

The sensor stores settings like the Gas Mode or reference values of FRC and ASC in volatile memory. These are not retained when the sensor loses power and must be stored externally to be sent to the sensor after each power cycle. To store the state externally use the methods get_sensor_state and set_sensor_state.

The sensor state contains the following information: - Selected binary gas index. - ON or OFF flag and offset value to apply to the sensor’s output for the automatic self-calibration. - Offset value to apply to the sensor’s output used in forced recalibration. - Compensation inputs: last supplied values of temperature, humidity and pressure

Parameters

sensor_state –

get_product_id()

Get the 32-bit product identifier and 64-bit sensor serial number. Please check the datasheet to get the expected product identifier for your STC31.

Return product_id

Return serial_number

Commands

The transfer classes specify the data that is transferred between host and sensor. The generated transfer classes are used by the driver class and not intended for direct use.

class sensirion_i2c_stc3x.commands.TestResultT(int_value: int = 0)

memory_error = BitField(offset=0, width=2)

vdd_out_of_range = BitField(offset=2, width=1)

measurement_value_error = BitField(offset=3, width=6)

temperature_error = BitField(offset=9, width=1)

class sensirion_i2c_stc3x.commands.SetBinaryGas(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.

CMD_ID = 13845

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.SetRelativeHumidityRaw(relative_humidity_ticks)

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

CMD_ID = 13860

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.SetTemperatureRaw(temperature_ticks)

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.

CMD_ID = 13854

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.SetPressure(absolue_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.

CMD_ID = 13871

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.MeasureGasConcentrationRawFast

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.

CMD_ID = 13881

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

rx = <sensirion_driver_adapters.rx_tx_data.RxData object>

class sensirion_i2c_stc3x.commands.MeasureGasConcentrationRawSlow

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.

CMD_ID = 13881

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

rx = <sensirion_driver_adapters.rx_tx_data.RxData object>

class sensirion_i2c_stc3x.commands.ForcedRecalibration(reference_concentration)

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.

CMD_ID = 13921

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.EnableAutomaticSelfCalibration

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

CMD_ID = 16367

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.DisableAutomaticSelfCalibration

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.

CMD_ID = 16238

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.PrepareReadState

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

CMD_ID = 14162

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.ReadSensorState

Read out the sensor state. The 30 bytes must be stored on the microcontroller to be written back to the sensor after exiting sleep mode.

CMD_ID = 57651

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

rx = <sensirion_driver_adapters.rx_tx_data.RxData object>

class sensirion_i2c_stc3x.commands.WriteSensorState(state)

Write the sensor state. The 30 bytes must be stored on the microcontroller to be written back to the sensor after exiting sleep mode.

CMD_ID = 57651

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.ApplyState

The sensor will apply the written state data.

CMD_ID = 13904

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.SelfTest

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

• 0-1: Memory error

• 2: VDD out of range

• 3-8: Measurement value error

• 9: Difference between externally supplied temperature (see 2.3.4) and internally measured temperatures exceeds the accuracy specifications.

In case of a successful self-test the sensor returns 0x0000 with correct CRC.

CMD_ID = 13915

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

rx = <sensirion_driver_adapters.rx_tx_data.RxData object>

class sensirion_i2c_stc3x.commands.PrepareProductIdentifier

Prepare for reading the product identifier and sensor serial number.

CMD_ID = 13948

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.ReadProductIdentifier

Read the product identifier and sensor serial number.

CMD_ID = 57602

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

rx = <sensirion_driver_adapters.rx_tx_data.RxData object>

class sensirion_i2c_stc3x.commands.EnterSleepMode

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.

CMD_ID = 13943

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.ExitSleepMode

Exit the sleep 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.

CMD_ID = 0

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.EnableWeakFilter

The STC31 has two built-in noise filters that run an exponential smoothing over the past measurement points. By default, no filter is applied to the data. If weak smoothing is desired, the following command(s) must be executed once upon starting the sensor. When enabled, the weak filter is applied for all subsequent concentration measurements.

CMD_ID = 16328

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.DisableWeakFilter

disable the weak smoothing filter

CMD_ID = 16201

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.EnableStrongFilter

The STC31 has two built-in noise filters that run an exponential smoothing over the past measurement points. By default, no filter is applied to the data. If strong smoothing is desired, the following command(s) must be executed once upon starting the sensor. When enabled, the strong filter is applied for all subsequent concentration measurements.

CMD_ID = 16341

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc3x.commands.DisableStrongFilter

disable the strong smoothing filter

CMD_ID = 16212

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

Result Types

The signal classes specify transformations of the raw sensor signals into a meaningful units. The generated signal types are used by the driver class and not intended for direct use.

class sensirion_i2c_stc3x.result_types.SignalTemperature(raw_temperature)

property value

class sensirion_i2c_stc3x.result_types.SignalGasConcentration(raw_gas_concentration)

property value