stc3x_i2c.h

/*
 * THIS FILE IS AUTOMATICALLY GENERATED
 *
 * Generator:     sensirion-driver-generator 0.38.1
 * Product:       stc3x
 * Model-Version: 1.0.0
 */
/*
 * Copyright (c) 2024, Sensirion AG
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * * Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 *
 * * Neither the name of Sensirion AG nor the names of its
 *   contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef STC3X_I2C_H
#define STC3X_I2C_H

#ifdef __cplusplus
extern "C" {
#endif

#include "sensirion_config.h"
#define STC31_C_I2C_ADDR_29 0x29
#define STC31_I2C_ADDR_29 0x29

// binary gas < 0x10
#define STC31_MEASUREMENT_DELAY_LOW 66
// binary gas >= 0x10
#define STC31_MEASUREMENT_DELAY_HIGH 110

typedef enum {
    STC3X_SET_BINARY_GAS_CMD_ID = 0x3615,
    STC3X_SET_RELATIVE_HUMIDITY_RAW_CMD_ID = 0x3624,
    STC3X_SET_TEMPERATURE_RAW_CMD_ID = 0x361e,
    STC3X_SET_PRESSURE_CMD_ID = 0x362f,
    STC3X_MEASURE_GAS_CONCENTRATION_RAW_CMD_ID = 0x3639,
    STC3X_FORCED_RECALIBRATION_CMD_ID = 0x3661,
    STC3X_ENABLE_AUTOMATIC_SELF_CALIBRATION_CMD_ID = 0x3fef,
    STC3X_DISABLE_AUTOMATIC_SELF_CALIBRATION_CMD_ID = 0x3f6e,
    STC3X_PREPARE_READ_STATE_CMD_ID = 0x3752,
    STC3X_READ_SENSOR_STATE_CMD_ID = 0xe133,
    STC3X_WRITE_SENSOR_STATE_CMD_ID = 0xe133,
    STC3X_APPLY_STATE_CMD_ID = 0x3650,
    STC3X_SELF_TEST_CMD_ID = 0x365b,
    STC3X_PREPARE_PRODUCT_IDENTIFIER_CMD_ID = 0x367c,
    STC3X_READ_PRODUCT_IDENTIFIER_CMD_ID = 0xe102,
    STC3X_ENTER_SLEEP_MODE_CMD_ID = 0x3677,
    STC3X_EXIT_SLEEP_MODE_CMD_ID = 0x0,
    STC3X_ENABLE_WEAK_FILTER_CMD_ID = 0x3fc8,
    STC3X_DISABLE_WEAK_FILTER_CMD_ID = 0x3f49,
    STC3X_ENABLE_STRONG_FILTER_CMD_ID = 0x3fd5,
    STC3X_DISABLE_STRONG_FILTER_CMD_ID = 0x3f54,
} STC3X_CMD_ID;

typedef union {
    struct {
        uint16_t memory_error : 2;
        uint16_t vdd_out_of_range : 1;
        uint16_t measurement_value_error : 6;
        uint16_t temperature_error : 1;
    };
    uint16_t value;
} stc3x_test_result_t;

/**
 * @brief Initialize i2c address of driver
 *
 * @param[in] i2c_address Used i2c address
 *
 */
void stc3x_init(uint8_t i2c_address);

/**
 * @brief stc3x_signal_temperature
 *
 * @param[in] raw_temperature
 *
 * @return
 */
float stc3x_signal_temperature(uint16_t raw_temperature);

/**
 * @brief stc3x_signal_gas_concentration
 *
 * @param[in] raw_gas_concentration
 *
 * @return
 */
float stc3x_signal_gas_concentration(uint16_t raw_gas_concentration);

/**
 * @brief Set relative humidity for internal compensation of gas concentration.
 *
 * 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.
 *
 * @param[in] relative_humidity Relative humidity in percent %.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_set_relative_humidity(float relative_humidity);

/**
 * @brief Set temperature for internal compensation of gas concentration.
 *
 * 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.
 *
 * @param[in] temperature Temperature in degree celsius.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_set_temperature(float temperature);

/**
 * @brief measure CO2 gas concentration in vol%.
 *
 * 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.
 *
 * @param[out] co2_concentration
 * @param[out] temperature
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_measure_gas_concentration(float* co2_concentration,
                                        float* temperature);

/**
 * @brief Prepare and read 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
 *
 * @param[out] state Current sensor state
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_get_sensor_state(uint8_t* state, uint16_t state_size);

/**
 * @brief write and apply 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
 *
 * @param[in] sensor_state
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_set_sensor_state(const uint8_t* sensor_state,
                               uint16_t sensor_state_size);

/**
 * @brief prepare and read product identifier and serial number
 *
 * 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.
 *
 * @param[out] product_id
 * @param[out] serial_number
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_get_product_id(uint32_t* product_id, uint64_t* serial_number);

/**
 * @brief stc3x_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.
 *
 * @param[in] 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%
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = stc3x_set_binary_gas(19);
 *     if (local_error != NO_ERROR) {
 *         return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t stc3x_set_binary_gas(uint16_t binary_gas);

/**
 * @brief stc3x_set_relative_humidity_raw
 *
 * 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
 *
 * @param[in] relative_humidity_ticks Convert %RH to value by: RH * (2^16 - 1) /
 * 100
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = stc3x_set_relative_humidity_raw(32768);
 *     if (local_error != NO_ERROR) {
 *         return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t stc3x_set_relative_humidity_raw(uint16_t relative_humidity_ticks);

/**
 * @brief stc3x_set_temperature_raw
 *
 * 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.
 *
 * @param[in] temperature_ticks Convert °C to value by: T * 200
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_set_temperature_raw(uint16_t temperature_ticks);

/**
 * @brief stc3x_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.
 *
 * @param[in] absolue_pressure Ambient pressure in mbar (milli-bars)
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_set_pressure(uint16_t absolue_pressure);

/**
 * @brief stc3x_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.
 *
 * @param[out] gas_ticks Gas concentration. Convert to vol % by 100 * (value -
 * 2^14) / 2^15
 * @param[out] 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.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_measure_gas_concentration_raw(uint16_t* gas_ticks,
                                            uint16_t* temperature_ticks);

/**
 * @brief stc3x_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.
 *
 * @param[in] reference_concentration Reference concentration
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = stc3x_forced_recalibration(0);
 *     if (local_error != NO_ERROR) {
 *         return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t stc3x_forced_recalibration(uint16_t reference_concentration);

/**
 * @brief stc3x_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
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_enable_automatic_self_calibration();

/**
 * @brief stc3x_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.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_disable_automatic_self_calibration();

/**
 * @brief stc3x_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.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_prepare_read_state();

/**
 * @brief stc3x_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.
 *
 * @param[out] state Current sensor state
 *
 * @note See section 3.3.9 of the datasheet for detailed instructions.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_read_sensor_state(uint8_t* state, uint16_t state_size);

/**
 * @brief stc3x_write_sensor_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.
 *
 * @param[in] state Current sensor state
 *
 * @note See section 3.3.9 of the datasheet for detailed instructions.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_write_sensor_state(const uint8_t* state, uint16_t state_size);

/**
 * @brief stc3x_apply_state
 *
 * The sensor will apply the written state data.
 *
 * @note See section 3.3.9 of the datasheet for detailed instructions.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_apply_state();

/**
 * @brief stc3x_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.
 *
 * @param[out] self_test_output Self test result. Error code or 0x0000 on
 * success.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_self_test(stc3x_test_result_t* self_test_output);

/**
 * @brief stc3x_prepare_product_identifier
 *
 * Prepare for reading the product identifier and sensor serial number.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_prepare_product_identifier();

/**
 * @brief stc3x_read_product_identifier
 *
 * Read the product identifier and sensor serial number.
 *
 * @param[out] product_number 32-bit unique product and revision number. The
 * number is listed below: STC31: 0x08010301
 * @param[out] serial_number_high Higher 32-bit of the 64-bit unique serial
 * number
 * @param[out] serial_number_low Lower 32-bit of the 64-bit unique serial number
 *
 * @note Make sure to call 'prepare product identifier' immediately before.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_read_product_identifier(uint32_t* product_number,
                                      uint32_t* serial_number_high,
                                      uint32_t* serial_number_low);

/**
 * @brief stc3x_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
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_enter_sleep_mode();

/**
 * @brief stc3x_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.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_exit_sleep_mode();

/**
 * @brief Enable weak filter with a smoothing factor of 1/2.5
 *
 * 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.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_enable_weak_filter();

/**
 * @brief stc3x_disable_weak_filter
 *
 * disable the weak smoothing filter
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_disable_weak_filter();

/**
 * @brief enable strong filter with smoothing factor of 1/7.5
 *
 * 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.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_enable_strong_filter();

/**
 * @brief stc3x_disable_strong_filter
 *
 * disable the strong smoothing filter
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t stc3x_disable_strong_filter();

#ifdef __cplusplus
}
#endif
#endif  // STC3X_I2C_H