/** * Copyright (c) 2017 - 2019, Nordic Semiconductor ASA * * All rights reserved. * * Redistribution and use in source and binary forms, with or without modification, * are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, this * list of conditions and the following disclaimer. * * 2. Redistributions in binary form, except as embedded into a Nordic * Semiconductor ASA integrated circuit in a product or a software update for * such product, 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. * * 3. Neither the name of Nordic Semiconductor ASA nor the names of its * contributors may be used to endorse or promote products derived from this * software without specific prior written permission. * * 4. This software, with or without modification, must only be used with a * Nordic Semiconductor ASA integrated circuit. * * 5. Any software provided in binary form under this license must not be reverse * engineered, decompiled, modified and/or disassembled. * * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA 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 CCS811_H #define CCS811_H #include "nrf_twi_sensor.h" #include "ccs811_internal.h" #ifdef __cplusplus extern "C" { #endif /** * @brief Possible sensor addresses. */ #define CCS811_BASE_ADDRESS_LOW 0x5AU #define CCS811_BASE_ADDRESS_HIGH 0x5BU // Minimum nrf_twi_sensor message buffer size and nrf_twi_mngr queue length. #define CCS811_MIN_QUEUE_SIZE 6 // Hardware ID register value #define CCS811_HARDWARE_ID 0x81 /** * @brief Sensor driver usage. * * Sensor instance has to be defined first in global context using @ref CCS811_INSTANCE_DEF. * After that it has to be initialized using @ref ccs811_init. * At this point sensor instance is ready and all other functions can be used. * * Configuration functions schedule TWI operation using @ref nrf_twi_sensor module. * After calling function, setting will be automatically send to sensor when TWI bus is free. * * There are designated functions to read status sensor registers e.g. @ref ccs811_status_read * As parameters they receive function to be called after register is read, and pointer where * register value should be stored. From that value specific parameters can be extracted * using @ref NRF_TWI_SENSOR_REG_VAL_GET macro. * Example: * bool drdy = NRF_TWI_SENSOR_REG_VAL_GET(status, CCS811_DATA_READY_MASK, CCS811_DATA_READY_POS); * * Other functions are self-explanatory or have description on their usage. */ /** * @brief Drive mode setting. */ typedef enum { CCS811_MODE_0,//!< CCS811_MODE_0 - Idle CCS811_MODE_1,//!< CCS811_MODE_1 - Constant power, measure every second. CCS811_MODE_2,//!< CCS811_MODE_2 - Pulse heating mode, measure every 10 seconds. CCS811_MODE_3,//!< CCS811_MODE_3 - Low power pulse heating mode, measure every 60 seconds. CCS811_MODE_4 //!< CCS811_MODE_4 - Constant power, measure every 250ms, only raw data. } ccs811_drive_mode_t; /** * @brief Last byte read from algorithm data. * * Used with @ref ccs811_alg_data_read function, defines to which byte data should be read. */ typedef enum { CCS811_LAST_ECO2 = 2, CCS811_LAST_TVOC = 4, CCS811_LAST_STATUS, CCS811_LAST_ERROR_ID, CCS811_LAST_RAW = 8 } ccs811_last_data_byte_t; /** * @brief Structure for holding algorithm data. */ typedef struct { uint16_t eco2; //!< eC02 value in ppm. uint16_t tvoc; //!< TVOC value in ppb. uint8_t status; //!< Status register data. uint8_t error_id; //!< Error register data. uint16_t raw; //!< Raw data. } ccs811_alg_data_t; /** * @brief Data callback prototype. * * @param[in] result Return code from TWI manager and underlying drivers. * @param[in] p_data Pointer to sensor data. */ typedef void (* ccs811_data_callback_t)(ret_code_t result, ccs811_alg_data_t * p_data); /** * @brief Macro that creates sensor instance. * * @param[in] _ccs811_inst_name Sensor instance name. * @param[in] _p_twi_sensor Pointer to common TWI sensor instance. * @param[in] _sensor_address Sensor base address. */ #define CCS811_INSTANCE_DEF(_ccs811_inst_name, _p_twi_sensor, _sensor_address) \ CCS811_INTERNAL_INSTANCE_DEF(_ccs811_inst_name, _p_twi_sensor, _sensor_address) /** * @brief Function initializing ccs811 sensor * * TWI manager queue length has to be at least CCS811_MIN_QUEUE_SIZE * * @param[in] p_instance Pointer to sensor instance created by macro * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_write */ ret_code_t ccs811_init(ccs811_instance_t const * p_instance); /** * @brief Function for setting drive mode. * * @param[in] p_instance Pointer to sensor instance. * @param[in] mode Drive mode. * @param[in] drdy_en Enable data ready pin. * @param[in] thr_en Enable threshold. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_write */ ret_code_t ccs811_drive_mode_set(ccs811_instance_t const * p_instance, ccs811_drive_mode_t mode, bool drdy_en, bool thr_en); /** * @brief Function for reading sensor data. * * @param[in] p_instance Pointer to sensor instance. * @param[in] user_cb Function to be called after data read. * @param[out] p_alg_data Pointer to structure holding sensor algorithm data. * @param[in] last Last byte to read. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_reg_read */ ret_code_t ccs811_alg_data_read(ccs811_instance_t const * p_instance, ccs811_data_callback_t user_cb, ccs811_alg_data_t * p_alg_data, ccs811_last_data_byte_t last); /** * @brief Function for processing algorithm data * * @param[in/out] p_alg_data Pointer to read data to be processed. */ void ccs811_alg_data_process(ccs811_alg_data_t * p_alg_data); /** * @brief Function for setting environment temperature. * * @param[in] p_instance Pointer to sensor instance. * @param[in] temp_value Temperature value (-25 to 100 degree celsius). * @param[in] temp_fraction Temperature fraction. * @param[in] hum_percent Humidity percent. * @param[in] hum_fraction Humidity fraction. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_write */ ret_code_t ccs811_env_set(ccs811_instance_t const * p_instance, int8_t temp_value, uint16_t temp_fraction, uint8_t hum_percent, uint16_t hum_fraction); /** * @brief Function for threshold configuration * * @param[in] p_instance Pointer to sensor instance. * @param[in] l_to_m Low to medium threshold. * @param[in] m_to_h Medium to high threshold. * @param[in] hysteresis Hysteresis. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_write */ ret_code_t ccs811_thr_cfg(ccs811_instance_t const * p_instance, uint16_t l_to_m, uint16_t m_to_h, uint8_t hysteresis); /** * @brief Function for reading baseline. * * @param[in] p_instance Pointer to sensor instance. * @param[in] user_cb Function to be called after baseline read. * @param[out] baseline Baseline value, single uint16_t. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_reg_read */ ret_code_t ccs811_baseline_read(ccs811_instance_t const * p_instance, nrf_twi_sensor_reg_cb_t user_cb, uint16_t * p_baseline); /** * @brief Function for setting baseline. * * @param[in] p_instance Pointer to sensor instance. * @param[in] baseline Baseline value. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_write */ ret_code_t ccs811_baseline_set(ccs811_instance_t const * p_instance, uint16_t baseline); /** * @brief Function commencing software reset. * * @param[in] p_instance Pointer to sensor instance. * * @note To use sensor after reset, it has to be initialized again using @ref ccs811_init function. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_write */ ret_code_t ccs811_sw_reset(ccs811_instance_t const * p_instance); /** * @brief Function for reading status register. * * @param[in] p_instance Pointer to sensor instance. * @param[in] user_cb Function to be called after register is read. * @param[out] p_reg_val Pointer to register value, single uint8_t. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_reg_read */ __STATIC_INLINE ret_code_t ccs811_status_read(ccs811_instance_t const * p_instance, nrf_twi_sensor_reg_cb_t user_cb, uint8_t * p_reg_val); /** * @brief Function for reading hardware id register. * * @param[in] p_instance Pointer to sensor instance. * @param[in] user_cb Function to be called after register is read. * @param[out] p_reg_val Pointer to register value, single uint8_t. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_reg_read */ __STATIC_INLINE ret_code_t ccs811_hw_id_read(ccs811_instance_t const * p_instance, nrf_twi_sensor_reg_cb_t user_cb, uint8_t * p_reg_val); /** * @brief Function for reading error id register. * * @param[in] p_instance Pointer to sensor instance. * @param[in] user_cb Function to be called after register is read. * @param[out] p_reg_val Pointer to register value, single uint8_t. * * @return Return error code from nrf_twi_sensor @ref nrf_twi_sensor_reg_read */ __STATIC_INLINE ret_code_t ccs811_error_read(ccs811_instance_t const * p_instance, nrf_twi_sensor_reg_cb_t user_cb, uint8_t * p_reg_val); #ifdef __cplusplus } #endif #endif // CCS811_H