sen66_i2c.h

/*
 * THIS FILE IS AUTOMATICALLY GENERATED
 *
 * Generator:     sensirion-driver-generator 1.0.1
 * Product:       sen66
 * Model-Version: 1.3.1
 */
/*
 * 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 SEN66_I2C_H
#define SEN66_I2C_H

#ifdef __cplusplus
extern "C" {
#endif

#include "sensirion_config.h"
#define SEN66_I2C_ADDR_6B 0x6b

typedef enum {
    SEN66_START_CONTINUOUS_MEASUREMENT_CMD_ID = 0x21,
    SEN66_STOP_MEASUREMENT_CMD_ID = 0x104,
    SEN66_GET_DATA_READY_CMD_ID = 0x202,
    SEN66_READ_MEASURED_VALUES_AS_INTEGERS_CMD_ID = 0x300,
    SEN66_READ_NUMBER_CONCENTRATION_VALUES_AS_INTEGERS_CMD_ID = 0x316,
    SEN66_READ_MEASURED_RAW_VALUES_CMD_ID = 0x405,
    SEN66_START_FAN_CLEANING_CMD_ID = 0x5607,
    SEN66_SET_TEMPERATURE_OFFSET_PARAMETERS_CMD_ID = 0x60b2,
    SEN66_SET_VOC_ALGORITHM_TUNING_PARAMETERS_CMD_ID = 0x60d0,
    SEN66_GET_VOC_ALGORITHM_TUNING_PARAMETERS_CMD_ID = 0x60d0,
    SEN66_SET_NOX_ALGORITHM_TUNING_PARAMETERS_CMD_ID = 0x60e1,
    SEN66_GET_NOX_ALGORITHM_TUNING_PARAMETERS_CMD_ID = 0x60e1,
    SEN66_SET_TEMPERATURE_ACCELERATION_PARAMETERS_CMD_ID = 0x6100,
    SEN66_SET_VOC_ALGORITHM_STATE_CMD_ID = 0x6181,
    SEN66_GET_VOC_ALGORITHM_STATE_CMD_ID = 0x6181,
    SEN66_PERFORM_FORCED_CO2_RECALIBRATION_CMD_ID = 0x6707,
    SEN66_SET_CO2_SENSOR_AUTOMATIC_SELF_CALIBRATION_CMD_ID = 0x6711,
    SEN66_GET_CO2_SENSOR_AUTOMATIC_SELF_CALIBRATION_CMD_ID = 0x6711,
    SEN66_SET_AMBIENT_PRESSURE_CMD_ID = 0x6720,
    SEN66_GET_AMBIENT_PRESSURE_CMD_ID = 0x6720,
    SEN66_SET_SENSOR_ALTITUDE_CMD_ID = 0x6736,
    SEN66_GET_SENSOR_ALTITUDE_CMD_ID = 0x6736,
    SEN66_ACTIVATE_SHT_HEATER_CMD_ID = 0x6765,
    SEN66_GET_PRODUCT_NAME_CMD_ID = 0xd014,
    SEN66_GET_SERIAL_NUMBER_CMD_ID = 0xd033,
    SEN66_READ_DEVICE_STATUS_CMD_ID = 0xd206,
    SEN66_READ_AND_CLEAR_DEVICE_STATUS_CMD_ID = 0xd210,
    SEN66_DEVICE_RESET_CMD_ID = 0xd304,
} SEN66_CMD_ID;

typedef union {
    struct {
        uint32_t reserved1 : 4;
        uint32_t fan_error : 1;
        uint32_t reserved2 : 1;
        uint32_t rht_error : 1;
        uint32_t gas_error : 1;
        uint32_t reserved3 : 1;
        uint32_t co2_2_error : 1;
        uint32_t reserved4 : 1;
        uint32_t pm_error : 1;
        uint32_t reserved5 : 1;
        uint32_t reserved6 : 8;
        uint32_t fan_speed_warning : 1;
    };
    uint32_t value;
} sen66_device_status;

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

/**
 * @brief sen66_signal_co2
 *
 * @param[in] co2_raw
 *
 * @return Measured CO2 in ppm.
 */
uint16_t sen66_signal_co2(uint16_t co2_raw);

/**
 * @brief Start a continuous measurement (interval 1s)
 *
 * Starts a continuous measurement. After starting the measurement, it takes
 * some time (~1.1s) until the first measurement results are available. You
 * could poll with the command "Get Data Ready" to check when the results are
 * ready to read. This command is only available in idle mode. If the device is
 * already in any measure mode, this command has no effect.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_start_continuous_measurement();

/**
 * @brief Stop the continuous measurement
 *
 * Stops the measurement and returns to idle mode. After sending this command,
 * wait at least 1000 ms before starting a new measurement. If the device is
 * already in idle mode, this command has no effect.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_stop_measurement();

/**
 * @brief Check if data is ready to be read out from the sensor
 *
 * This command can be used to check if new measurement results are ready to
 * read. The data ready flag is automatically reset after reading the
 * measurement values.
 *
 * @param[out] padding Padding byte, always 0x00.
 * @param[out] data_ready True (0x01) if data is ready, False (0x00) if not.
 * When no measurement is running, False will be returned.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_get_data_ready(uint8_t* padding, bool* data_ready);

/**
 * @brief read measured values as integers.
 *
 * Returns the measured values. The command "Get Data Ready" can be used to
 * check if new data is available since the last read operation. If no new data
 * is available, the previous values will be returned again. If no data is
 * available at all (e.g. measurement not running for at least one second), all
 * values will be at their upper limit (0xFFFF for uint16, 0x7FFF for int16).
 *
 * @param[out] mass_concentration_pm1p0 Value is scaled with factor 10: PM1.0
 * [µg/m³] = value / 10 *Note: If this value is unknown, 0xFFFF is returned.*
 * @param[out] mass_concentration_pm2p5 Value is scaled with factor 10: PM2.5
 * [µg/m³] = value / 10 *Note: If this value is unknown, 0xFFFF is returned.*
 * @param[out] mass_concentration_pm4p0 Value is scaled with factor 10: PM4.0
 * [µg/m³] = value / 10 *Note: If this value is unknown, 0xFFFF is returned.*
 * @param[out] mass_concentration_pm10p0 Value is scaled with factor 10: PM10.0
 * [µg/m³] = value / 10 *Note: If this value is unknown, 0xFFFF is returned.*
 * @param[out] ambient_humidity Value is scaled with factor 100: RH [%] = value
 * / 100 *Note: If this value is unknown, 0x7FFF is returned.*
 * @param[out] ambient_temperature Value is scaled with factor 200: T [°C] =
 * value / 200 *Note: If this value is unknown, 0x7FFF is returned.*
 * @param[out] voc_index Value is scaled with factor 10: VOC Index = value / 10
 * *Note: If this value is unknown, 0x7FFF is returned.*
 * @param[out] nox_index Value is scaled with factor 10: NOx Index = value / 10
 * *Note: If this value is unknown, 0x7FFF is returned. During the first 10..11
 * seconds after power-on or device reset, this value will be 0x7FFF as well.*
 * @param[out] co2 CO₂ concentration [ppm] *Note: If this value is unknown,
 * 0xFFFF is returned. During the first 5..6 seconds after power-on or device
 * reset, this value will be 0xFFFF as well.*
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_read_measured_values_as_integers(
    uint16_t* mass_concentration_pm1p0, uint16_t* mass_concentration_pm2p5,
    uint16_t* mass_concentration_pm4p0, uint16_t* mass_concentration_pm10p0,
    int16_t* ambient_humidity, int16_t* ambient_temperature, int16_t* voc_index,
    int16_t* nox_index, uint16_t* co2);

/**
 * @brief sen66_read_number_concentration_values_as_integers
 *
 * Returns the measured number concentration values. The command "Get Data
 * Ready" can be used to check if new data is available since the last read
 * operation. If no new data is available, the previous values will be returned
 * again. If no data is available at all (e.g. measurement not running for at
 * least one second), all values will be at their upper limit (0xFFFF for
 * uint16).
 *
 * @param[out] number_concentration_pm0p5 Value is scaled with factor 10: PM0.5
 * [particles/cm³] = value / 10 *Note: If this value is unknown, 0xFFFF is
 * returned.*
 * @param[out] number_concentration_pm1p0 Value is scaled with factor 10: PM1.0
 * [particles/cm³] = value / 10 *Note: If this value is unknown, 0xFFFF is
 * returned.*
 * @param[out] number_concentration_pm2p5 Value is scaled with factor 10: PM2.5
 * [particles/cm³] = value / 10 *Note: If this value is unknown, 0xFFFF is
 * returned.*
 * @param[out] number_concentration_pm4p0 Value is scaled with factor 10: PM4.0
 * [particles/cm³] = value / 10 *Note: If this value is unknown, 0xFFFF is
 * returned.*
 * @param[out] number_concentration_pm10p0 Value is scaled with factor 10:
 * PM10.0 [particles/cm³] = value / 10 *Note: If this value is unknown, 0xFFFF
 * is returned.*
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_read_number_concentration_values_as_integers(
    uint16_t* number_concentration_pm0p5, uint16_t* number_concentration_pm1p0,
    uint16_t* number_concentration_pm2p5, uint16_t* number_concentration_pm4p0,
    uint16_t* number_concentration_pm10p0);

/**
 * @brief sen66_read_measured_raw_values
 *
 * Returns the measured raw values. The command "Get Data Ready" can be used to
 * check if new data is available since the last read operation. If no new data
 * is available, the previous values will be returned again. If no data is
 * available at all (e.g. measurement not running for at least one second), all
 * values will be at their upper limit (0xFFFF for uint16, 0x7FFF for int16).
 *
 * @param[out] raw_humidity Value is scaled with factor 100: RH [%] = value /
 * 100 *Note: If this value is unknown, 0x7FFF is returned.*
 * @param[out] raw_temperature Value is scaled with factor 200: T [°C] = value /
 * 200 *Note: If this value is unknown, 0x7FFF is returned.*
 * @param[out] raw_voc Raw measured VOC ticks without scale factor. *Note: If
 * this value is unknown, 0xFFFF is returned.*
 * @param[out] raw_nox Raw measured NOx ticks without scale factor. *Note: If
 * this value is unknown, 0xFFFF is returned. During the first 10..11 seconds
 * after power-on or device reset, this value will be 0xFFFF as well.*
 * @param[out] raw_co2 Not interpolated CO₂ concentration [ppm] updated every
 * five seconds. *Note: If this value is unknown, 0xFFFF is returned. During the
 * first 5..6 seconds after power-on or device reset, this value will be 0xFFFF
 * as well.*
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_read_measured_raw_values(int16_t* raw_humidity,
                                       int16_t* raw_temperature,
                                       uint16_t* raw_voc, uint16_t* raw_nox,
                                       uint16_t* raw_co2);

/**
 * @brief sen66_start_fan_cleaning
 *
 * This command triggers fan cleaning. The fan is set to the maximum speed for
 * 10 seconds and then automatically stopped. Wait at least 10s after this
 * command before starting a measurement.
 *
 * @note This command is only available in idle mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_start_fan_cleaning();

/**
 * @brief sen66_set_temperature_offset_parameters
 *
 * This command allows to compensate temperature effects of the design-in at
 * customer side by applying custom temperature offsets to the ambient
 * temperature. The compensated ambient temperature is calculated as follows:
 * T_Ambient_Compensated = T_Ambient + (slope * T_Ambient) + offset Where slope
 * and offset are the values set with this command, smoothed with the specified
 * time constant. All temperatures (T_Ambient_Compensated, T_Ambient and offset)
 * are represented in °C. There are 5 temperature offset slots available that
 * all contribute additively to T_Ambient_Compensated. The default values for
 * the temperature offset parameters are all zero, meaning that
 * T_Ambient_Compensated is equal to T_Ambient by default. The parameters can be
 * changed in any state of the device, i.e. both in idle mode and in measure
 * mode.
 *
 * @param[in] offset Constant temperature offset scaled with factor 200 (T [°C]
 * = value / 200).
 * @param[in] slope Normalized temperature offset slope scaled with factor 10000
 * (applied factor = value / 10000).
 * @param[in] time_constant The time constant determines how fast the new slope
 * and offset will be applied. After the specified value in seconds, 63% of the
 * new slope and offset are applied. A time constant of zero means the new
 * values will be applied immediately (within the next measure interval of 1
 * second).
 * @param[in] slot The temperature offset slot to be modified. Valid values are
 * 0 .. 4. If the value is outside this range, the parameters will not be
 * applied.
 *
 * @note This configuration is volatile, i.e. the parameters will be reverted to
 * their default value of zero after a device reset.
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = sen66_set_temperature_offset_parameters(1, 10, 1, 0);
 *     if (local_error != NO_ERROR) {
 *         return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t sen66_set_temperature_offset_parameters(int16_t offset, int16_t slope,
                                                uint16_t time_constant,
                                                uint16_t slot);

/**
 * @brief sen66_set_voc_algorithm_tuning_parameters
 *
 * Sets the parameters to customize the VOC algorithm. This configuration is
 * volatile, i.e. the parameters will be reverted to their default values after
 * a device reset.
 *
 * @param[in] index_offset VOC index representing typical (average) conditions.
 * Allowed values are in range 1..250. The default value is 100.
 * @param[in] learning_time_offset_hours Time constant to estimate the VOC
 * algorithm offset from the history in hours. Past events will be forgotten
 * after about twice the learning time. Allowed values are in range 1..1000. The
 * default value is 12 hours.
 * @param[in] learning_time_gain_hours Time constant to estimate the VOC
 * algorithm gain from the history in hours. Past events will be forgotten after
 * about twice the learning time. Allowed values are in range 1..1000. The
 * default value is 12 hours.
 * @param[in] gating_max_duration_minutes Maximum duration of gating in minutes
 * (freeze of estimator during high VOC index signal). Set to zero to disable
 * the gating. Allowed values are in range 0..3000. The default value is 180
 * minutes
 * @param[in] std_initial Initial estimate for standard deviation. Lower value
 * boosts events during initial learning period, but may result in larger
 * device-to-device variations. Allowed values are in range 10..5000. The
 * default value is 50.
 * @param[in] gain_factor Gain factor to amplify or to attenuate the VOC index
 * output. Allowed values are in range 1..1000. The default value is 230.
 *
 * @note This command is available only in idle mode. In measure mode, this
 * command has no effect. In addition, it has no effect if at least one
 * parameter is outside the specified range.
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = sen66_set_voc_algorithm_tuning_parameters(100, 12, 12, 180,
 * 50, 230); if (local_error != NO_ERROR) { return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t sen66_set_voc_algorithm_tuning_parameters(
    int16_t index_offset, int16_t learning_time_offset_hours,
    int16_t learning_time_gain_hours, int16_t gating_max_duration_minutes,
    int16_t std_initial, int16_t gain_factor);

/**
 * @brief sen66_get_voc_algorithm_tuning_parameters
 *
 * Gets the parameters to customize the VOC algorithm.
 *
 * @param[out] index_offset VOC index representing typical (average) conditions.
 * @param[out] learning_time_offset_hours Time constant to estimate the VOC
 * algorithm offset from the history in hours. Past events will be forgotten
 * after about twice the learning time.
 * @param[out] learning_time_gain_hours Time constant to estimate the VOC
 * algorithm gain from the history in hours. Past events will be forgotten after
 * about twice the learning time.
 * @param[out] gating_max_duration_minutes Maximum duration of gating in minutes
 * (freeze of estimator during high VOC index signal). Zero disables the gating.
 * @param[out] std_initial Initial estimate for standard deviation. Lower value
 * boosts events during initial learning period, but may result in larger
 * device-to-device variations.
 * @param[out] gain_factor Gain factor to amplify or to attenuate the VOC index
 * output.
 *
 * @note This command is only available in idle mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_get_voc_algorithm_tuning_parameters(
    int16_t* index_offset, int16_t* learning_time_offset_hours,
    int16_t* learning_time_gain_hours, int16_t* gating_max_duration_minutes,
    int16_t* std_initial, int16_t* gain_factor);

/**
 * @brief sen66_set_nox_algorithm_tuning_parameters
 *
 * Sets the parameters to customize the NOx algorithm. This configuration is
 * volatile, i.e. the parameters will be reverted to their default values after
 * a device reset.
 *
 * @param[in] index_offset NOx index representing typical (average) conditions.
 * Allowed values are in range 1..250. The default value is 1.
 * @param[in] learning_time_offset_hours Time constant to estimate the NOx
 * algorithm offset from the history in hours. Past events will be forgotten
 * after about twice the learning time. Allowed values are in range 1..1000. The
 * default value is 12 hours.
 * @param[in] learning_time_gain_hours The time constant to estimate the NOx
 * algorithm gain from the history has no impact for NOx. This parameter is
 * still in place for consistency reasons with the VOC tuning parameters
 * command. This parameter must always be set to 12 hours.
 * @param[in] gating_max_duration_minutes Maximum duration of gating in minutes
 * (freeze of estimator during high NOx index signal). Set to zero to disable
 * the gating. Allowed values are in range 0..3000. The default value is 720
 * minutes.
 * @param[in] std_initial The initial estimate for standard deviation parameter
 * has no impact for NOx. This parameter is still in place for consistency
 * reasons with the VOC tuning parameters command. This parameter must always be
 * set to 50.
 * @param[in] gain_factor Gain factor to amplify or to attenuate the NOx index
 * output. Allowed values are in range 1..1000. The default value is 230.
 *
 * @note This command is available only in idle mode. In measure mode, this
 * command has no effect. In addition, it has no effect if at least one
 * parameter is outside the specified range.
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = sen66_set_nox_algorithm_tuning_parameters(1, 12, 12, 720,
 * 50, 230); if (local_error != NO_ERROR) { return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t sen66_set_nox_algorithm_tuning_parameters(
    int16_t index_offset, int16_t learning_time_offset_hours,
    int16_t learning_time_gain_hours, int16_t gating_max_duration_minutes,
    int16_t std_initial, int16_t gain_factor);

/**
 * @brief sen66_get_nox_algorithm_tuning_parameters
 *
 * Gets the parameters to customize the NOx algorithm.
 *
 * @param[out] index_offset NOx index representing typical (average) conditions.
 * @param[out] learning_time_offset_hours Time constant to estimate the NOx
 * algorithm offset from the history in hours. Past events will be forgotten
 * after about twice the learning time.
 * @param[out] learning_time_gain_hours The time constant to estimate the NOx
 * algorithm gain from the history has no impact for NOx. This parameter is
 * still in place for consistency reasons with the VOC tuning parameters
 * command.
 * @param[out] gating_max_duration_minutes Maximum duration of gating in minutes
 * (freeze of estimator during high NOx index signal). Zero disables the gating.
 * @param[out] std_initial The initial estimate for standard deviation has no
 * impact for NOx. This parameter is still in place for consistency reasons with
 * the VOC tuning parameters command.
 * @param[out] gain_factor Gain factor to amplify or to attenuate the NOx index
 * output.
 *
 * @note This command is available only in idle mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_get_nox_algorithm_tuning_parameters(
    int16_t* index_offset, int16_t* learning_time_offset_hours,
    int16_t* learning_time_gain_hours, int16_t* gating_max_duration_minutes,
    int16_t* std_initial, int16_t* gain_factor);

/**
 * @brief sen66_set_temperature_acceleration_parameters
 *
 * This command allows to set custom temperature acceleration parameters of the
 * RH/T engine. It overwrites the default temperature acceleration parameters of
 * the RH/T engine with custom values. This configuration is volatile, i.e. the
 * parameters will be reverted to their default values after a device reset.
 *
 * @param[in] k Filter constant K scaled with factor 10 (K = value / 10).
 * @param[in] p Filter constant P scaled with factor 10 (P = value / 10).
 * @param[in] t1 Time constant T1 scaled with factor 10 (T1 [s] = value / 10).
 * @param[in] t2 Time constant T2 scaled with factor 10 (T2 [s] = value / 10).
 *
 * @note The command is only available in idle mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = sen66_set_temperature_acceleration_parameters(1, 1, 1, 1);
 *     if (local_error != NO_ERROR) {
 *         return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t sen66_set_temperature_acceleration_parameters(uint16_t k, uint16_t p,
                                                      uint16_t t1, uint16_t t2);

/**
 * @brief sen66_set_voc_algorithm_state
 *
 * Sets the VOC algorithm state previously received with "Get VOC Algorithm
 * State" command. Allows restoration of the VOC algorithm state to resume
 * operation after a power cycle or device reset, skipping initial learning
 * phase. By default, the VOC Engine is reset, and the algorithm state is
 * retained if a measurement is stopped and started again. If the VOC algorithm
 * state shall be reset, a device reset, or a power cycle can be executed.
 *
 * @param[in] state VOC algorithm state to restore.
 *
 * @note This command is only available in idle mode and the state will be
 * applied only once when starting the next measurement. In measure mode, this
 * command has no effect.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_set_voc_algorithm_state(const uint8_t* state,
                                      uint16_t state_size);

/**
 * @brief sen66_get_voc_algorithm_state
 *
 * Gets the current VOC algorithm state. Allows to backup and restore the VOC
 * algorithm state to resume operation after a power cycle or device reset,
 * skipping initial learning phase. By default, the VOC Engine is reset and the
 * algorithm state  is retained if a measurement is stopped and started again.
 * If the VOC algorithm state shall be reset, a device reset or a power cycle
 * can be executed.
 *
 * @param[out] state Current VOC algorithm state.
 *
 * @note This command can be used either in measure mode or in idle mode (which
 * will then return the state at the time when the measurement was stopped). In
 * measure mode, the state can be read each measure interval to always have the
 * latest state available, even in case of a sudden power loss.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_get_voc_algorithm_state(uint8_t* state, uint16_t state_size);

/**
 * @brief Perform Forced CO₂ Recalibration
 *
 * Execute the forced recalibration (FRC) of the CO₂. See the datasheet of the
 * SCD4x sensor for details how the forced recalibration shall be used.
 *
 * @param[in] target_co2_concentration Target CO₂ concentration [ppm] of the
 * test setup.
 * @param[out] correction Correction value as received from the SCD [ppm CO₂].
 * FRC correction [ppm CO₂] is calculated as follows: FRC = return_value -
 * 0x8000 If the recalibration has failed this returned value is 0xFFFF.
 *
 * @note After power-on wait at least 1000 ms and after stopping a measurement
 * 600 ms before sending this command. This command is not available in measure
 * mode. The recalibration procedure will take about 500 ms to complete, during
 * which time no other functions can be executed.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t
sen66_perform_forced_co2_recalibration(uint16_t target_co2_concentration,
                                       uint16_t* correction);

/**
 * @brief sen66_set_co2_sensor_automatic_self_calibration
 *
 * Sets the status of the CO₂ sensor automatic self-calibration (ASC). The CO₂
 * sensor supports automatic self calibration (ASC) for long-term stability of
 * the CO₂ output. This feature can be enabled or disabled. By default it is
 * enabled. This configuration is volatile, i.e. the parameter will be reverted
 * to its default value after a device restart.
 *
 * @param[in] status Set to true (0x0001) to enable or false (0x0000) to disable
 * the automatic CO₂ measurement self calibration feature. High byte of uint16
 * is padding and always 0x00.
 *
 * @note This command is only available in idle mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = sen66_set_co2_sensor_automatic_self_calibration(0);
 *     if (local_error != NO_ERROR) {
 *         return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t sen66_set_co2_sensor_automatic_self_calibration(uint16_t status);

/**
 * @brief sen66_get_co2_sensor_automatic_self_calibration
 *
 * The CO₂ sensor supports automatic self calibration (ASC) for long-term
 * stability of the CO₂ output. This feature can be enabled or disabled. By
 * default it is enabled. This configuration is volatile, i.e. the parameter
 * will be reverted to its default value after a device restart.
 *
 * @param[out] padding Padding byte, always 0x00.
 * @param[out] status Is set true (0x01) if the automatic self calibration is
 * enabled or false (0x00) if the automatic self calibration is disabled.
 *
 * @note This command is only available in idle mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_get_co2_sensor_automatic_self_calibration(uint8_t* padding,
                                                        bool* status);

/**
 * @brief sen66_set_ambient_pressure
 *
 * The ambient pressure can be used for pressure compensation in the CO₂ sensor.
 * Setting an ambient pressure overrides any pressure compensation based on a
 * previously set sensor altitude. Use of this command is recommended for
 * applications experiencing significant ambient pressure changes to ensure CO₂
 * sensor accuracy. Valid input values are between 700 to 1'200 hPa. The default
 * value is 1013 hPa. This configuration is volatile, i.e. the parameter will be
 * reverted to its default value after a device restart.
 *
 * @param[in] ambient_pressure Ambient pressure [hPa] to be used for pressure
 * compensation.
 *
 * @note This command can be used in any state of the device, i.e. both in idle
 * mode and in measure mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = sen66_set_ambient_pressure(1013);
 *     if (local_error != NO_ERROR) {
 *         return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t sen66_set_ambient_pressure(uint16_t ambient_pressure);

/**
 * @brief sen66_get_ambient_pressure
 *
 * Gets the ambient pressure value. The ambient pressure can be used for
 * pressure compensation in the CO₂ sensor.
 *
 * @param[out] ambient_pressure Currently used ambient pressure [hPa] for
 * pressure compensation.
 *
 * @note This command can be used in any state of the device, i.e. both in idle
 * mode and in measure mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_get_ambient_pressure(uint16_t* ambient_pressure);

/**
 * @brief sen66_set_sensor_altitude
 *
 * The sensor altitude can be used for pressure compensation in the CO₂ sensor.
 * The default sensor altitude value is set to 0 meters above sea level. Valid
 * input values are between 0 and 3000m. This configuration is volatile, i.e.
 * the parameter will be reverted to its default value after a device reset.
 *
 * @param[in] altitude Sensor altitude [m], valid input between 0 and 3000m.
 *
 * @return error_code 0 on success, an error code otherwise.
 *
 * Example:
 * --------
 *
 * @code{.c}
 *
 *     int16_t local_error = 0;
 *     local_error = sen66_set_sensor_altitude(0);
 *     if (local_error != NO_ERROR) {
 *         return local_error;
 *     }
 *
 * @endcode
 *
 */
int16_t sen66_set_sensor_altitude(uint16_t altitude);

/**
 * @brief sen66_get_sensor_altitude
 *
 * Gets the current sensor altitude. The sensor altitude can be used for
 * pressure compensation in the CO₂ sensor.
 *
 * @param[out] altitude Current sensor altitude [m].
 *
 * @note This command is only available in idle mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_get_sensor_altitude(uint16_t* altitude);

/**
 * @brief Activate SHT Heater
 *
 * This command allows to use the inbuilt heater in SHT sensor to reverse creep
 * at high humidity. This command activates the SHT sensor heater with 200mW for
 * 1s. The heater is then automatically deactivated again. Wait at least 20s
 * after this command before starting a measurement to get coherent temperature
 * values (heating consequence to disappear).
 *
 * @note This command is only available in idle mode.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_activate_sht_heater();

/**
 * @brief sen66_get_product_name
 *
 * Gets the product name from the device.
 *
 * @param[out] product_name Null-terminated ASCII string containing the product
 * name. Up to 32 characters can be read from the device.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_get_product_name(uint8_t* product_name,
                               uint16_t product_name_size);

/**
 * @brief sen66_get_serial_number
 *
 * Gets the serial number from the device.
 *
 * @param[out] serial_number Null-terminated ASCII string containing the serial
 * number. Up to 32 characters can be read from the device.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_get_serial_number(uint8_t* serial_number,
                                uint16_t serial_number_size);

/**
 * @brief sen66_read_device_status
 *
 * Reads the current device status. Use this command to get detailed information
 * about the device status. The device status is encoded in flags. Each device
 * status flag represents a single bit in a 32-bit integer value. If more than
 * one error is present, the device status register value is the sum of the
 * corresponding flag values. For details about the available flags, refer to
 * the device status flags documentation in the data sheet.
 *
 * @param[out] device_status Device status (32 flags as an integer value). For
 * details, please refer to the device status flags documentation in the
 * datasheet.
 *
 * @note The status flags of type "Error" are sticky, i.e. they are not cleared
 * automatically even if the error condition no longer exists. So they can only
 * be cleared manually with the command "Read And Clear Device Status" or with a
 * device reset. All other flags are not sticky, i.e. they are cleared
 * automatically if the trigger condition disappears.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_read_device_status(sen66_device_status* device_status);

/**
 * @brief sen66_read_and_clear_device_status
 *
 * Reads the current device status (like command 0xD206 "Read Device Status")
 * and afterwards clears all flags.
 *
 * @param[out] device_status Device status (32 flags as an integer value)
 * **before** clearing it. For details, please refer to the device status flags
 * documentation.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_read_and_clear_device_status(sen66_device_status* device_status);

/**
 * @brief sen66_device_reset
 *
 * Executes a reset on the device. This has the same effect as a power cycle.
 *
 * @return error_code 0 on success, an error code otherwise.
 */
int16_t sen66_device_reset();

#ifdef __cplusplus
}
#endif
#endif  // SEN66_I2C_H