API Documentation

STC42

Stc42Device

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

class sensirion_i2c_stc42.device.Stc42DeviceBase(channel)

Low level API implementation of STC42

__init__(channel)

property channel

read_product_info()

Read product type and serial number

Return product_number:

Return serial_number:

start_concentration_measurement(measurement_period)

Start measuring the hydrogen concentration

Parameters:

measurement_period –

Defines how the measurement shall be carried out:

• measurement_period = 0:

  A single shot measurement is done. The measurement value is available after a measure-time of about 75ms.

• measurement_period > 0: Once a measurement is started with measurement_period > 0, the sensor will repeatedly measure the gas concentration until the measurement is stopped or the sensor is power cycled. During this time, the measurement data can be read out using the read_measurement_ticks command.

  The value measurement_period gives an indication how fast new measurement data is available.

  In case measurement_period <= the measure-time the readout frequency is about ~10Hz. In case measurement_period > the measure-time the readout frequency is approximated with the formula:

  Readout frequency in Hz = 1000 / (measurement_period)

  The maximum value for measurement_period is 65536

Example:

sensor.start_concentration_measurement(1000)

read_measurement_ticks()

Read the measurement values from the sensor. Between the command start_concentration_measurement and the command read_measurement_ticks it is required to wait for the maximum value of measure-time ms and measurement_period ms. Otherwise the sensor will NACK the request. The same wait time needs to be observed between two successive calls to read_measurement_ticks.

Return gas_concentration:

The hydrogen concentration as ticks. The returned value can be converted into volume % in air using the following formula:

H2[vol% in air] = (gas_concentration - 2**14)/2**15 * scale_factor

Return temperature:

The temperature as ticks. The returned value can be converted into a temperature °C using the following formula:

T [°C] = -45 + 175*temperature/(2**16-1)

Return relative_humidity:

The relative humidity as ticks. The returned value can be converted into relative humidity % using the following formula:

RH % = -6 + 125*relative_humidity/(2**16-1)

Return ambient_pressure:

The ambient pressure in mBar. No further conversion is required.

Return error_flags:

Error information for current data reading.

Return scale_factor:

The first 12 bits contain the factor that needs to be applied to convert the raw value into the physical unit. The bits 12 to 15 contain information about the unit:

• 1 = %vol

• 2 = ‰vol

• 3 = hPa partial pressure

• 4 = mmHg partial pressure

Note

It is not required to read all values. The read can be stopped after each field

stop_measurement()

The sensor will stop measuring

compensate_temperature_with_sht41()

When using this option the STC4x will read temperature values from an SHT41A-AD1B sensor that is attached to the I²C master bus of the STC (Pin 9 and 1).

enable_manual_temperature_compensation()

Allows to write temperature values to the sensor

set_compensation_temperature_ticks(temperature_ticks)

Write a new temperature value to the sensor. The value is used as temperature compensation value until another value is written to the sensor.

Parameters:

temperature_ticks – Value to be used to compensate temperature as ticks.

Example:

sensor.set_compensation_temperature_ticks(26214)

compensate_humidity_with_sht41()

When using this option the STC4x will read relative humidity values from an SHT41A-AD1B sensor that is attached to the I²C master bus of the STC (Pin 9 and 1).

enable_manual_humidity_compensation()

Enables the option to adjust the readings for humidity impact using values written by application software.

set_compensation_humidity_ticks(relative_humidity_ticks)

Write a new relative humidity value to the sensor. The value is used as relative_humidity compensation value until another value is written to the sensor.

Parameters:

relative_humidity_ticks – Value to the as relative humidity compensation value as ticks

Example:

sensor.set_compensation_humidity_ticks(29359)

enable_manual_pressure_compensation()

Enables the option to adjust the readings for pressure impact using values written by application software.

set_compensation_pressure_mbar(pressure_mbar)

Write a new pressure value [mbar] to the sensor. The value is used as pressure compensation value until another value is written to the sensor.

Parameters:

pressure_mbar – Pressure compensation value

Example:

sensor.set_compensation_pressure_mbar(1013)

perform_forced_recalibration_ticks(gas_concentration)

Forced recalibration is used to improve the sensor output with a known reference value.

Before initiating forced recalibration, the sensor needs to be configured for proper compensation of ambient conditions (temperature, relative humidity and pressure). The effect of FRC takes place immediately after the command is executed and takes effect with the first subsequent measurement.

FRC must only be performed when a well-known accurate reference concentration value is available, e.g. in a production facility where only air is present. Sensors can be permanently compromised if FRC is performed with a parameter gas_concentration that largely deviates from the actual gas concentrations. For the best possible performance, the FRC should be executed close to the median operating temperature, humidity, pressure, and concentration of the end application.

Typical applications for FRC:

• After soldering and assembly

• Before commissioning a product

• Before starting a measurement series

The forced recalibration requires that the command start_concentration_measurement was called before with measurement_period > 0. The command is only started if the error-bits i2c_error, vdd_out_of_range and memory_access_error are not set.

Parameters:

gas_concentration –

The tick value is obtained by the form the formula:

H₂[vol % in air] * 2**15 / scale_factor + 2**14

Therefore, to compensate to a H₂ concentration in Air with 0 % H₂ we need to set the value to 16384.

Example:

sensor.perform_forced_recalibration_ticks(16384)

enable_automatic_self_calibration()

Enable automatic self calibration

The sensor runs by default in Automatic Self-Calibration mode. This mode will enhance the accuracy for applications where the target gas is not present for most of the time and is mandatory for long term use. This feature can be disabled and enabled with the following commands.

disable_automatic_self_calibration()

Disable automatic self calibration

Allows to disable automatic self calibration.

enter_sleep_mode()

The enter_sleep_mode command sets the sensor to sleep mode through the I2C interface. The written relative humidity, temperature, and pressure compensation values as well as the ASC state will be retained while in sleep mode.

enable_low_power_mode()

Enable the low power mode of the sensor and aktivates interrupt pin.

exit_low_power_mode()

Exit the low power mode of the sensor

set_alert_upper_threshold(uppper_threshold_ticks)

Set the upper threshold for interrupt trigger.

Parameters:

uppper_threshold_ticks – The value of upper trigger threshold in ticks.

Example:

sensor.set_alert_upper_threshold(19660)

set_alert_lower_threshold(lower_threshold_ticks)

Set the lower threshold for interrupt trigger.

Parameters:

lower_threshold_ticks – The value of lower trigger threshold in ticks.

Example:

sensor.set_alert_lower_threshold(13107)

class sensirion_i2c_stc42.device.Stc42Device(channel)

Driver class implementation of STC42

stc42

Access to base class

__init__(channel)

read_measurements()

Read measurement values and convert them to the appropriate physical units.

Return hydrogen:

H₂ in [vol % in air]

Return temperature:

Temperature in [°C]

Return humidity:

Relative humidity in [%]

Return ambient_pressure:

Ambient pressure in [mBar]

Return error_flags:

Error flags for the read data

perform_forced_recalibration(h2, scale_factor)

Perform an FRC with argument H₂ in [vol % in air].

Parameters:

• h2 – H₂ in [vol % in air]

• scale_factor

set_compensation_temperature(t)

Set the temperature compensation with argument T [°C]

Parameters:

t – Temperature T [°C]

set_compensation_humidity(rh)

Set the humidity compensation with argument RH [%]

Parameters:

rh – Relative humidity RH [%]

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_stc42.commands.ScaleFactorType(int_value: int = 0, **kwargs)

scale_factor = (0, 12)

unit = (12, 4)

class sensirion_i2c_stc42.commands.ReadErrorFlags(int_value: int = 0, **kwargs)

padding = (0, 8)

i2c_error = (8, 1)

dew_point_out_of_range = (9, 1)

measurement_to_low = (10, 1)

vdd_out_of_range = (11, 1)

eeprom_access_error = (12, 1)

memory_access_error = (13, 1)

asc_baseline_out_of_range = (14, 1)

asc_baseline_warning = (15, 1)

class sensirion_i2c_stc42.commands.ReadProductInfo

Read product type and serial number

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_stc42.commands.StartConcentrationMeasurement(measurement_period)

Start measuring the hydrogen concentration

CMD_ID = 8530

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.ReadMeasurementTicks

Read the measurement values from the sensor. Between the command start_concentration_measurement and the command read_measurement_ticks it is required to wait for the maximum value of measure-time ms and measurement_period ms. Otherwise the sensor will NACK the request. The same wait time needs to be observed between two successive calls to read_measurement_ticks.

CMD_ID = 60421

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

rx = <sensirion_driver_adapters.rx_tx_data.RxData object>

class sensirion_i2c_stc42.commands.StopMeasurement

The sensor will stop measuring

CMD_ID = 16377

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.CompensateTemperatureWithSht41

When using this option the STC4x will read temperature values from an SHT41A-AD1B sensor that is attached to the I²C master bus of the STC (Pin 9 and 1).

CMD_ID = 9753

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.EnableManualTemperatureCompensation

Allows to write temperature values to the sensor

CMD_ID = 9746

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.SetCompensationTemperatureTicks(temperature_ticks)

Write a new temperature value to the sensor. The value is used as temperature compensation value until another value is written to the sensor.

CMD_ID = 57344

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.CompensateHumidityWithSht41

When using this option the STC4x will read relative humidity values from an SHT41A-AD1B sensor that is attached to the I²C master bus of the STC (Pin 9 and 1).

CMD_ID = 9815

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.EnableManualHumidityCompensation

Enables the option to adjust the readings for humidity impact using values written by application software.

CMD_ID = 9802

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.SetCompensationHumidityTicks(relative_humidity_ticks)

Write a new relative humidity value to the sensor. The value is used as relative_humidity compensation value until another value is written to the sensor.

CMD_ID = 57355

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.EnableManualPressureCompensation

Enables the option to adjust the readings for pressure impact using values written by application software.

CMD_ID = 9880

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.SetCompensationPressureMbar(pressure_mbar)

Write a new pressure value [mbar] to the sensor. The value is used as pressure compensation value until another value is written to the sensor.

CMD_ID = 57366

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.PerformForcedRecalibrationTicks(gas_concentration)

Forced recalibration is used to improve the sensor output with a known reference value.

Before initiating forced recalibration, the sensor needs to be configured for proper compensation of ambient conditions (temperature, relative humidity and pressure). The effect of FRC takes place immediately after the command is executed and takes effect with the first subsequent measurement.

FRC must only be performed when a well-known accurate reference concentration value is available, e.g. in a production facility where only air is present. Sensors can be permanently compromised if FRC is performed with a parameter gas_concentration that largely deviates from the actual gas concentrations. For the best possible performance, the FRC should be executed close to the median operating temperature, humidity, pressure, and concentration of the end application.

Typical applications for FRC:

• After soldering and assembly

• Before commissioning a product

• Before starting a measurement series

The forced recalibration requires that the command start_concentration_measurement was called before with measurement_period > 0. The command is only started if the error-bits i2c_error, vdd_out_of_range and memory_access_error are not set.

CMD_ID = 57373

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.EnableAutomaticSelfCalibration

Enable automatic self calibration

The sensor runs by default in Automatic Self-Calibration mode. This mode will enhance the accuracy for applications where the target gas is not present for most of the time and is mandatory for long term use. This feature can be disabled and enabled with the following commands.

CMD_ID = 16262

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.DisableAutomaticSelfCalibration

Disable automatic self calibration

Allows to disable automatic self calibration.

CMD_ID = 16135

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.EnterSleepMode

The enter_sleep_mode command sets the sensor to sleep mode through the I2C interface. The written relative humidity, temperature, and pressure compensation values as well as the ASC state will be retained while in sleep mode.

CMD_ID = 14048

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.EnableLowPowerMode

Enable the low power mode of the sensor and aktivates interrupt pin.

CMD_ID = 16272

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.SetAlertUpperThreshold(uppper_threshold_ticks)

Set the upper threshold for interrupt trigger.

CMD_ID = 12167

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.SetAlertLowerThreshold(lower_threshold_ticks)

Set the lower threshold for interrupt trigger.

CMD_ID = 10124

pack()

tx = <sensirion_driver_adapters.rx_tx_data.TxData object>

class sensirion_i2c_stc42.commands.ExitLowPowerMode

Exit the low power mode of the sensor

CMD_ID = 16145

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_stc42.result_types.SignalHydrogen(hydrogen_ticks, scale_factor)

Convert raw measurement value to hydrogen value.

property value

class sensirion_i2c_stc42.result_types.SignalTemperature(temperature_ticks)

Convert temperature ticks to temperature celsius

property value

class sensirion_i2c_stc42.result_types.SignalRelativeHumidity(relative_humidity_ticks)

Convert relative humidity ticks to relative humidity %

property value