scd4x_i2c.h

00001 /*
00002  * THIS FILE IS AUTOMATICALLY GENERATED AND MUST NOT BE EDITED MANUALLY!
00003  *
00004  * I2C-Generator: 0.2.0
00005  * Yaml Version: 0.1.0
00006  * Template Version: 0.2.1
00007  */
00008 /*
00009  * Copyright (c) 2021, Sensirion AG
00010  * All rights reserved.
00011  *
00012  * Redistribution and use in source and binary forms, with or without
00013  * modification, are permitted provided that the following conditions are met:
00014  *
00015  * * Redistributions of source code must retain the above copyright notice, this
00016  *   list of conditions and the following disclaimer.
00017  *
00018  * * Redistributions in binary form must reproduce the above copyright notice,
00019  *   this list of conditions and the following disclaimer in the documentation
00020  *   and/or other materials provided with the distribution.
00021  *
00022  * * Neither the name of Sensirion AG nor the names of its
00023  *   contributors may be used to endorse or promote products derived from
00024  *   this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00027  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00028  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00029  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
00030  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00031  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00032  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00033  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00034  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00035  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  */
00038 
00039 #ifndef SCD4X_I2C_H
00040 #define SCD4X_I2C_H
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 #include "sensirion_config.h"
00047 
00048 /**
00049  * scd4x_start_periodic_measurement() - start periodic measurement, signal
00050  * update interval is 5 seconds.
00051  *
00052  * @note This command is only available in idle mode.
00053  *
00054  * @return 0 on success, an error code otherwise
00055  */
00056 int16_t scd4x_start_periodic_measurement(void);
00057 
00058 /**
00059  * scd4x_read_measurement_ticks() - read sensor output. The measurement data can
00060  * only be read out once per signal update interval as the buffer is emptied
00061  * upon read-out. If no data is available in the buffer, the sensor returns a
00062  * NACK. To avoid a NACK response the get_data_ready_status can be issued to
00063  * check data status. The I2C master can abort the read transfer with a NACK
00064  * followed by a STOP condition after any data byte if the user is not
00065  * interested in subsequent data.
00066  *
00067  * @note This command is only available in measurement mode. The firmware
00068  * updates the measurement values depending on the measurement mode.
00069  *
00070  * @param co2 CO₂ concentration in ppm
00071  *
00072  * @param temperature Convert value to °C by: -45 °C + 175 °C * value/2^16
00073  *
00074  * @param humidity Convert value to %RH by: 100%RH * value/2^16
00075  *
00076  * @return 0 on success, an error code otherwise
00077  */
00078 int16_t scd4x_read_measurement_ticks(uint16_t* co2, uint16_t* temperature,
00079                                      uint16_t* humidity);
00080 
00081 /**
00082  * scd4x_read_measurement() - read sensor output and convert.
00083  * See @ref scd4x_read_measurement_ticks() for more details.
00084  *
00085  * @note This command is only available in measurement mode. The firmware
00086  * updates the measurement values depending on the measurement mode.
00087  *
00088  * @param co2 CO₂ concentration in ppm
00089  *
00090  * @param temperature_m_deg_c Temperature in milli degrees celsius (°C * 1000)
00091  *
00092  * @param humidity_m_percent_rh Relative humidity in milli percent RH
00093  * (%RH * 1000)
00094  *
00095  * @return 0 on success, an error code otherwise
00096  */
00097 int16_t scd4x_read_measurement(uint16_t* co2, int32_t* temperature_m_deg_c,
00098                                int32_t* humidity_m_percent_rh);
00099 
00100 /**
00101  * scd4x_stop_periodic_measurement() - Stop periodic measurement and return to
00102  * idle mode for sensor configuration or to safe energy.
00103  *
00104  * @note This command is only available in measurement mode.
00105  *
00106  * @return 0 on success, an error code otherwise
00107  */
00108 int16_t scd4x_stop_periodic_measurement(void);
00109 
00110 /**
00111  * scd4x_get_temperature_offset_ticks() - The temperature offset represents the
00112  * difference between the measured temperature by the SCD4x and the actual
00113  * ambient temperature. Per default, the temperature offset is set to 4°C.
00114  *
00115  * @note Only available in idle mode.
00116  *
00117  * @param t_offset Temperature offset. Convert value to °C by: 175 * value /
00118  * 2^16
00119  *
00120  * @return 0 on success, an error code otherwise
00121  */
00122 int16_t scd4x_get_temperature_offset_ticks(uint16_t* t_offset);
00123 
00124 /**
00125  * scd4x_get_temperature_offset() - The temperature offset represents the
00126  * difference between the measured temperature by the SCD4x and the actual
00127  * ambient temperature. Per default, the temperature offset is set to 4°C.
00128  *
00129  * @note Only available in idle mode.
00130  *
00131  * @param t_offset_m_deg_c Temperature offset in milli degrees Celsius.
00132  *
00133  * @return 0 on success, an error code otherwise
00134  */
00135 int16_t scd4x_get_temperature_offset(int32_t* t_offset_m_deg_c);
00136 
00137 /**
00138  * scd4x_set_temperature_offset_ticks() - Setting the temperature offset of the
00139  * SCD4x inside the customer device correctly allows the user to leverage the RH
00140  * and T output signal. Note that the temperature offset can depend on various
00141  * factors such as the SCD4x measurement mode, self-heating of close components,
00142  * the ambient temperature and air flow. Thus, the SCD4x temperature offset
00143  * should  be determined inside the customer device under its typical operation
00144  * and in thermal equilibrium.
00145  *
00146  * @note Only available in idle mode.
00147  *
00148  * @param t_offset Temperature offset. Convert °C to value by: T * 2^16 / 175.
00149  *
00150  * @return 0 on success, an error code otherwise
00151  */
00152 int16_t scd4x_set_temperature_offset_ticks(uint16_t t_offset);
00153 
00154 /**
00155  * scd4x_set_temperature_offset() - Setting the temperature offset of the SCD4x
00156  * inside the customer device correctly allows the user to leverage the RH and T
00157  * output signal. Note that the temperature offset can depend on various factors
00158  * such as the SCD4x measurement mode, self-heating of close components, the
00159  * ambient temperature and air flow. Thus, the SCD4x temperature offset should
00160  * be determined inside the customer device under its typical operation and in
00161  * thermal equilibrium.
00162  *
00163  * @note Only available in idle mode.
00164  *
00165  * @param t_offset_m_deg_c Temperature offset in milli degrees Celsius.
00166  *
00167  * @return 0 on success, an error code otherwise
00168  */
00169 int16_t scd4x_set_temperature_offset(int32_t t_offset_m_deg_c);
00170 
00171 /**
00172  * scd4x_get_sensor_altitude() - Get configured sensor altitude in meters above
00173  * sea level. Per default, the sensor altitude is set to 0 meter above
00174  * sea-level.
00175  *
00176  * @note Only available in idle mode.
00177  *
00178  * @param sensor_altitude Sensor altitude in meters.
00179  *
00180  * @return 0 on success, an error code otherwise
00181  */
00182 int16_t scd4x_get_sensor_altitude(uint16_t* sensor_altitude);
00183 
00184 /**
00185  * scd4x_set_sensor_altitude() - Set sensor altitude in meters above sea level.
00186  * Note that setting a sensor altitude to the sensor overrides any pressure
00187  * compensation based on a previously set ambient pressure.
00188  *
00189  * @note Only available in idle mode.
00190  *
00191  * @param sensor_altitude Sensor altitude in meters.
00192  *
00193  * @return 0 on success, an error code otherwise
00194  */
00195 int16_t scd4x_set_sensor_altitude(uint16_t sensor_altitude);
00196 
00197 /**
00198  * scd4x_set_ambient_pressure() - The set_ambient_pressure command can be sent
00199  * during periodic measurements to enable continuous pressure compensation. Note
00200  * that setting an ambient pressure to the sensor overrides any pressure
00201  * compensation based on a previously set sensor altitude.
00202  *
00203  * @note Available during measurements.
00204  *
00205  * @param ambient_pressure Ambient pressure in hPa. Convert value to Pa by:
00206  * value * 100.
00207  *
00208  * @return 0 on success, an error code otherwise
00209  */
00210 int16_t scd4x_set_ambient_pressure(uint16_t ambient_pressure);
00211 
00212 /**
00213  * scd4x_perform_forced_recalibration() - To successfully conduct an accurate
00214 forced recalibration, the following steps need to be carried out:
00215 1. Operate the SCD4x in a periodic measurement mode for > 3 minutes in an
00216 environment with homogenous and constant CO₂ concentration.
00217 2. Stop periodic measurement. Wait 500 ms.
00218 3. Subsequently issue the perform_forced_recalibration command and optionally
00219 read out the baseline correction. A return value of 0xffff indicates that the
00220 forced recalibration failed.
00221  *
00222  * @param target_co2_concentration Target CO₂ concentration in ppm.
00223  *
00224  * @param frc_correction FRC correction value in CO₂ ppm or 0xFFFF if the
00225 command failed. Convert value to CO₂ ppm with: value - 0x8000
00226  *
00227  * @return 0 on success, an error code otherwise
00228  */
00229 int16_t scd4x_perform_forced_recalibration(uint16_t target_co2_concentration,
00230                                            uint16_t* frc_correction);
00231 
00232 /**
00233  * scd4x_get_automatic_self_calibration() - By default, the ASC is enabled.
00234  *
00235  * @param asc_enabled 1 if ASC is enabled, 0 if ASC is disabled
00236  *
00237  * @return 0 on success, an error code otherwise
00238  */
00239 int16_t scd4x_get_automatic_self_calibration(uint16_t* asc_enabled);
00240 
00241 /**
00242  * scd4x_set_automatic_self_calibration() - By default, the ASC is enabled.
00243  *
00244  * @param asc_enabled 1 to enable ASC, 0 to disable ASC
00245  *
00246  * @return 0 on success, an error code otherwise
00247  */
00248 int16_t scd4x_set_automatic_self_calibration(uint16_t asc_enabled);
00249 
00250 /**
00251  * scd4x_start_low_power_periodic_measurement() - Start low power periodic
00252  * measurement, signal update interval is 30 seconds.
00253  *
00254  * @note This command is only available in idle mode.
00255  *
00256  * @return 0 on success, an error code otherwise
00257  */
00258 int16_t scd4x_start_low_power_periodic_measurement(void);
00259 
00260 /**
00261  * scd4x_get_data_ready_status() - Check whether new measurement data is
00262  * available for read-out.
00263  *
00264  * @param data_ready If last 11 bits are 0 data not ready, else data ready
00265  *
00266  * @return 0 on success, an error code otherwise
00267  */
00268 int16_t scd4x_get_data_ready_status(uint16_t* data_ready);
00269 
00270 /**
00271  * scd4x_persist_settings() - Configuration settings such as the temperature
00272  * offset, sensor altitude and the ASC enabled/disabled parameter are by default
00273  * stored in the volatile memory (RAM) only and will be lost after a
00274  * power-cycle. The persist_settings command stores the current configuration in
00275  * the EEPROM of the SCD4x, making them resistant to power-cycling. To avoid
00276  * unnecessary wear of the EEPROM, the persist_settings command should only be
00277  * sent when persistence is required and if actual changes to the configuration
00278  * have been made. Note that field calibration history (i.e. FRC and ASC) is
00279  * stored in the EEPROM automatically.
00280  *
00281  * @note
00282  *
00283  * @return 0 on success, an error code otherwise
00284  */
00285 int16_t scd4x_persist_settings(void);
00286 
00287 /**
00288  * scd4x_get_serial_number() - Reading out the serial number can be used to
00289  * identify the chip and to verify the presence of the sensor. The get serial
00290  * number command returns 3 words.  Together, the 3 words constitute a unique
00291  * serial number with a length of 48 bits (big endian format).
00292  *
00293  * @param serial_0 First word of the 48 bit serial number
00294  *
00295  * @param serial_1 Second word of the 48 bit serial number
00296  *
00297  * @param serial_2 Third word of the 48 bit serial number
00298  *
00299  * @return 0 on success, an error code otherwise
00300  */
00301 int16_t scd4x_get_serial_number(uint16_t* serial_0, uint16_t* serial_1,
00302                                 uint16_t* serial_2);
00303 
00304 /**
00305  * scd4x_perform_self_test() - The perform_self_test feature can be used as an
00306  * end-of-line test to confirm sensor functionality.
00307  *
00308  * @param sensor_status 0 means no malfunction detected
00309  *
00310  * @return 0 on success, an error code otherwise
00311  */
00312 int16_t scd4x_perform_self_test(uint16_t* sensor_status);
00313 
00314 /**
00315  * scd4x_perform_factory_reset() - Initiates the reset of all configurations
00316  * stored in the EEPROM and erases the FRC and ASC algorithm history.
00317  *
00318  * @return 0 on success, an error code otherwise
00319  */
00320 int16_t scd4x_perform_factory_reset(void);
00321 
00322 /**
00323  * scd4x_reinit() - The reinit command reinitializes the sensor by reloading
00324  * user settings from EEPROM. Before sending the reinit command, the stop
00325  * measurement command must be issued. If reinit command does not trigger the
00326  * desired re-initialization, a power-cycle should be applied to the SCD4x.
00327  *
00328  * @note Only available in idle mode.
00329  *
00330  * @return 0 on success, an error code otherwise
00331  */
00332 int16_t scd4x_reinit(void);
00333 
00334 /**
00335  * scd4x_measure_single_shot() - On-demand measurement of CO₂ concentration,
00336  * relative humidity and temperature. The sensor output is read with the
00337  * read_measurement command.
00338  *
00339  * @note Only available in idle mode.
00340  *
00341  * @return 0 on success, an error code otherwise
00342  */
00343 int16_t scd4x_measure_single_shot(void);
00344 
00345 /**
00346  * scd4x_measure_single_shot_rht_only() - On-demand measurement of relative
00347  * humidity and temperature only.
00348  *
00349  * @note Only available in idle mode.
00350  *
00351  * @return 0 on success, an error code otherwise
00352  */
00353 int16_t scd4x_measure_single_shot_rht_only(void);
00354 
00355 /**
00356  * scd4x_power_down() - Put the sensor from idle to sleep mode to reduce current
00357  * consumption.
00358  *
00359  * @note Only available in idle mode.
00360  *
00361  * @return 0 on success, an error code otherwise
00362  */
00363 int16_t scd4x_power_down(void);
00364 
00365 /**
00366  * scd4x_wake_up() - Wake up sensor from sleep mode to idle mode.
00367  *
00368  * @note Only available in sleep mode.
00369  *
00370  * @return 0 on success, an error code otherwise
00371  */
00372 int16_t scd4x_wake_up(void);
00373 
00374 #ifdef __cplusplus
00375 }
00376 #endif
00377 
00378 #endif /* SCD4X_I2C_H */