1 /* 2 * Copyright (c) 2018 Peter Bigot Consulting, LLC 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** 8 * @file 9 * @brief Extended public API for CCS811 Indoor Air Quality Sensor 10 * 11 * Some capabilities and operational requirements for this sensor 12 * cannot be expressed within the sensor driver abstraction. 13 */ 14 15 #ifndef ZEPHYR_INCLUDE_DRIVERS_SENSOR_CCS811_H_ 16 #define ZEPHYR_INCLUDE_DRIVERS_SENSOR_CCS811_H_ 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 #include <zephyr/device.h> 23 #include <zephyr/drivers/sensor.h> 24 25 /* Status register fields */ 26 #define CCS811_STATUS_ERROR BIT(0) 27 #define CCS811_STATUS_DATA_READY BIT(3) 28 #define CCS811_STATUS_APP_VALID BIT(4) 29 #define CCS811_STATUS_FW_MODE BIT(7) 30 31 /* Error register fields */ 32 #define CCS811_ERROR_WRITE_REG_INVALID BIT(0) 33 #define CCS811_ERROR_READ_REG_INVALID BIT(1) 34 #define CCS811_ERROR_MEASMODE_INVALID BIT(2) 35 #define CCS811_ERROR_MAX_RESISTANCE BIT(3) 36 #define CCS811_ERROR_HEATER_FAULT BIT(4) 37 #define CCS811_ERROR_HEATER_SUPPLY BIT(5) 38 39 /* Measurement mode constants */ 40 #define CCS811_MODE_IDLE 0x00 41 #define CCS811_MODE_IAQ_1SEC 0x10 42 #define CCS811_MODE_IAQ_10SEC 0x20 43 #define CCS811_MODE_IAQ_60SEC 0x30 44 #define CCS811_MODE_IAQ_250MSEC 0x40 45 #define CCS811_MODE_MSK 0x70 46 47 /** @brief Information collected from the sensor on each fetch. */ 48 struct ccs811_result_type { 49 /** Equivalent carbon dioxide in parts-per-million volume (ppmv). */ 50 uint16_t co2; 51 52 /** 53 * Equivalent total volatile organic compounds in 54 * parts-per-billion volume. 55 */ 56 uint16_t voc; 57 58 /** Raw voltage and current measured by sensor. */ 59 uint16_t raw; 60 61 /** Sensor status at completion of most recent fetch. */ 62 uint8_t status; 63 64 /** 65 * Sensor error flags at completion of most recent fetch. 66 * 67 * Note that errors are cleared when read. 68 */ 69 uint8_t error; 70 }; 71 72 /** 73 * @brief Access storage for the most recent data read from the sensor. 74 * 75 * This content of the object referenced is updated by 76 * sensor_fetch_sample(), except for ccs811_result_type::mode which is 77 * set on driver initialization. 78 * 79 * @param dev Pointer to the sensor device 80 * 81 * @return a pointer to the result information. 82 */ 83 const struct ccs811_result_type *ccs811_result(const struct device *dev); 84 85 /** 86 * @brief Get information about static CCS811 state. 87 * 88 * This includes the configured operating mode as well as hardware and 89 * firmware versions. 90 */ 91 struct ccs811_configver_type { 92 uint16_t fw_boot_version; 93 uint16_t fw_app_version; 94 uint8_t hw_version; 95 uint8_t mode; 96 }; 97 98 /** 99 * @brief Fetch operating mode and version information. 100 * 101 * @param dev Pointer to the sensor device 102 * 103 * @param ptr Pointer to where the returned information should be stored 104 * 105 * @return 0 on success, or a negative errno code on failure. 106 */ 107 int ccs811_configver_fetch(const struct device *dev, 108 struct ccs811_configver_type *ptr); 109 110 /** 111 * @brief Fetch the current value of the BASELINE register. 112 * 113 * The BASELINE register encodes data used to correct sensor readings 114 * based on individual device configuration and variation over time. 115 * 116 * For proper management of the BASELINE register see AN000370 117 * "Baseline Save and Restore on CCS811". 118 * 119 * @param dev Pointer to the sensor device 120 * 121 * @return a non-negative 16-bit register value, or a negative errno 122 * code on failure. 123 */ 124 int ccs811_baseline_fetch(const struct device *dev); 125 126 /** 127 * @brief Update the BASELINE register. 128 * 129 * For proper management of the BASELINE register see AN000370 130 * "Baseline Save and Restore on CCS811". 131 * 132 * @param dev Pointer to the sensor device 133 * 134 * @param baseline the value to be stored in the BASELINE register. 135 * 136 * @return 0 if successful, negative errno code if failure. 137 */ 138 int ccs811_baseline_update(const struct device *dev, uint16_t baseline); 139 140 /** 141 * @brief Update the ENV_DATA register. 142 * 143 * Accurate calculation of gas levels requires accurate environment 144 * data. Measurements are only accurate to 0.5 Cel and 0.5 %RH. 145 * 146 * @param dev Pointer to the sensor device 147 * 148 * @param temperature the current temperature at the sensor 149 * 150 * @param humidity the current humidity at the sensor 151 * 152 * @return 0 if successful, negative errno code if failure. 153 */ 154 int ccs811_envdata_update(const struct device *dev, 155 const struct sensor_value *temperature, 156 const struct sensor_value *humidity); 157 158 #ifdef __cplusplus 159 } 160 #endif 161 162 #endif /* ZEPHYR_INCLUDE_DRIVERS_SENSOR_CCS811_H_ */ 163