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