1 /*
2 * Copyright (c) 2015 - 2018, Nordic Semiconductor ASA
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright notice, this
9 * list of conditions and the following disclaimer.
10 *
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 *
15 * 3. Neither the name of the copyright holder nor the names of its
16 * contributors may be used to endorse or promote products derived from this
17 * software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 * POSSIBILITY OF SUCH DAMAGE.
30 */
31
32 #ifndef NRFX_COMP_H__
33 #define NRFX_COMP_H__
34
35 #include <nrfx.h>
36 #include <hal/nrf_comp.h>
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 /**
43 * @defgroup nrfx_comp COMP driver
44 * @{
45 * @ingroup nrf_comp
46 * @brief Comparator (COMP) peripheral driver.
47 */
48
49 /**
50 * @brief Macro to convert the threshold voltage to an integer value
51 * (needed by the COMP_TH register).
52 *
53 * @param[in] vol Voltage to be changed to COMP_TH register value. This value
54 * must not be smaller than reference voltage divided by 64.
55 * @param[in] ref Reference voltage.
56 */
57 #define NRFX_VOLTAGE_THRESHOLD_TO_INT(vol, ref) \
58 (uint8_t)(((vol) > ((ref) / 64)) ? (NRFX_ROUNDED_DIV((vol) * 64,(ref)) - 1) : 0)
59
60 /**
61 * @brief COMP event handler function type.
62 * @param[in] event COMP event.
63 */
64 typedef void (* nrfx_comp_event_handler_t)(nrf_comp_event_t event);
65
66 /** @brief COMP shortcut masks. */
67 typedef enum
68 {
69 NRFX_COMP_SHORT_STOP_AFTER_CROSS_EVT = COMP_SHORTS_CROSS_STOP_Msk, /*!< Shortcut between the CROSS event and the STOP task. */
70 NRFX_COMP_SHORT_STOP_AFTER_UP_EVT = COMP_SHORTS_UP_STOP_Msk, /*!< Shortcut between the UP event and the STOP task. */
71 NRFX_COMP_SHORT_STOP_AFTER_DOWN_EVT = COMP_SHORTS_DOWN_STOP_Msk /*!< Shortcut between the DOWN event and the STOP task. */
72 } nrfx_comp_short_mask_t;
73
74 /** @brief COMP events masks. */
75 typedef enum
76 {
77 NRFX_COMP_EVT_EN_CROSS_MASK = COMP_INTENSET_CROSS_Msk, /*!< CROSS event (generated after VIN+ == VIN-). */
78 NRFX_COMP_EVT_EN_UP_MASK = COMP_INTENSET_UP_Msk, /*!< UP event (generated when VIN+ crosses VIN- while increasing). */
79 NRFX_COMP_EVT_EN_DOWN_MASK = COMP_INTENSET_DOWN_Msk, /*!< DOWN event (generated when VIN+ crosses VIN- while decreasing). */
80 NRFX_COMP_EVT_EN_READY_MASK = COMP_INTENSET_READY_Msk /*!< READY event (generated when the module is ready). */
81 } nrfx_comp_evt_en_mask_t;
82
83 /** @brief COMP configuration. */
84 typedef struct
85 {
86 nrf_comp_ref_t reference; /**< Reference selection. */
87 nrf_comp_ext_ref_t ext_ref; /**< External analog reference selection. */
88 nrf_comp_main_mode_t main_mode; /**< Main operation mode. */
89 nrf_comp_th_t threshold; /**< Structure holding THDOWN and THUP values needed by the COMP_TH register. */
90 nrf_comp_sp_mode_t speed_mode; /**< Speed and power mode. */
91 nrf_comp_hyst_t hyst; /**< Comparator hysteresis.*/
92 #if defined (COMP_ISOURCE_ISOURCE_Msk) || defined (__NRFX_DOXYGEN__)
93 nrf_isource_t isource; /**< Current source selected on analog input. */
94 #endif
95 nrf_comp_input_t input; /**< Input to be monitored. */
96 uint8_t interrupt_priority; /**< Interrupt priority. */
97 } nrfx_comp_config_t;
98
99 /** @brief COMP threshold default configuration. */
100 #define NRFX_COMP_CONFIG_TH \
101 { \
102 .th_down = NRFX_VOLTAGE_THRESHOLD_TO_INT(0.5, 1.8), \
103 .th_up = NRFX_VOLTAGE_THRESHOLD_TO_INT(1.5, 1.8) \
104 }
105
106 /** @brief COMP driver default configuration including the COMP HAL configuration. */
107 #if defined (COMP_ISOURCE_ISOURCE_Msk) || defined (__NRFX_DOXYGEN__)
108 #define NRFX_COMP_DEFAULT_CONFIG(_input) \
109 { \
110 .reference = (nrf_comp_ref_t)NRFX_COMP_CONFIG_REF, \
111 .main_mode = (nrf_comp_main_mode_t)NRFX_COMP_CONFIG_MAIN_MODE, \
112 .threshold = NRFX_COMP_CONFIG_TH, \
113 .speed_mode = (nrf_comp_sp_mode_t)NRFX_COMP_CONFIG_SPEED_MODE, \
114 .hyst = (nrf_comp_hyst_t)NRFX_COMP_CONFIG_HYST, \
115 .isource = (nrf_isource_t)NRFX_COMP_CONFIG_ISOURCE, \
116 .input = (nrf_comp_input_t)_input, \
117 .interrupt_priority = NRFX_COMP_CONFIG_IRQ_PRIORITY \
118 }
119 #else
120 #define NRFX_COMP_DEFAULT_CONFIG(_input) \
121 { \
122 .reference = (nrf_comp_ref_t)NRFX_COMP_CONFIG_REF, \
123 .main_mode = (nrf_comp_main_mode_t)NRFX_COMP_CONFIG_MAIN_MODE, \
124 .threshold = NRFX_COMP_CONFIG_TH, \
125 .speed_mode = (nrf_comp_sp_mode_t)NRFX_COMP_CONFIG_SPEED_MODE, \
126 .hyst = (nrf_comp_hyst_t)NRFX_COMP_CONFIG_HYST, \
127 .input = (nrf_comp_input_t)_input, \
128 .interrupt_priority = NRFX_COMP_CONFIG_IRQ_PRIORITY \
129 }
130 #endif
131
132 /**
133 * @brief Function for initializing the COMP driver.
134 *
135 * This function initializes the COMP driver, but does not enable the peripheral or any interrupts.
136 * To start the driver, call the function @ref nrfx_comp_start() after initialization.
137 *
138 * @param[in] p_config Pointer to the structure with initial configuration.
139 * @param[in] event_handler Event handler provided by the user.
140 * Must not be NULL.
141 *
142 * @retval NRFX_SUCCESS If initialization was successful.
143 * @retval NRFX_ERROR_INVALID_STATE If the driver has already been initialized.
144 * @retval NRFX_ERROR_BUSY If the LPCOMP peripheral is already in use.
145 * This is possible only if @ref nrfx_prs module
146 * is enabled.
147 */
148 nrfx_err_t nrfx_comp_init(nrfx_comp_config_t const * p_config,
149 nrfx_comp_event_handler_t event_handler);
150
151
152 /**
153 * @brief Function for uninitializing the COMP driver.
154 *
155 * This function uninitializes the COMP driver. The COMP peripheral and
156 * its interrupts are disabled, and local variables are cleaned. After this call, you must
157 * initialize the driver again by calling nrfx_comp_init() if you want to use it.
158 *
159 * @sa nrfx_comp_stop()
160 */
161 void nrfx_comp_uninit(void);
162
163 /**
164 * @brief Function for setting the analog input.
165 *
166 * @param[in] psel COMP analog pin selection.
167 */
168 void nrfx_comp_pin_select(nrf_comp_input_t psel);
169
170 /**
171 * @brief Function for starting the COMP peripheral and interrupts.
172 *
173 * Before calling this function, the driver must be initialized. This function
174 * enables the COMP peripheral and its interrupts.
175 *
176 * @param[in] comp_evt_en_mask Mask of events to be enabled. This parameter should be built as
177 * 'or' of elements from @ref nrfx_comp_evt_en_mask_t.
178 * @param[in] comp_shorts_mask Mask of shorts to be enabled. This parameter should be built as
179 * 'or' of elements from @ref nrfx_comp_short_mask_t.
180 *
181 * @sa nrfx_comp_init()
182 *
183 */
184 void nrfx_comp_start(uint32_t comp_evt_en_mask, uint32_t comp_shorts_mask);
185
186 /**@brief Function for stopping the COMP peripheral.
187 *
188 * Before calling this function, the driver must be enabled. This function disables the COMP
189 * peripheral and its interrupts.
190 *
191 * @sa nrfx_comp_uninit()
192 *
193 */
194 void nrfx_comp_stop(void);
195
196 /**
197 * @brief Function for copying the current state of the comparator result to the RESULT register.
198 *
199 * @retval 0 If the input voltage is below the threshold (VIN+ < VIN-).
200 * @retval 1 If the input voltage is above the threshold (VIN+ > VIN-).
201 */
202 uint32_t nrfx_comp_sample(void);
203
204 /**
205 * @brief Function for getting the address of a COMP task.
206 *
207 * @param[in] task COMP task.
208 *
209 * @return Address of the given COMP task.
210 */
nrfx_comp_task_address_get(nrf_comp_task_t task)211 __STATIC_INLINE uint32_t nrfx_comp_task_address_get(nrf_comp_task_t task)
212 {
213 return (uint32_t)nrf_comp_task_address_get(task);
214 }
215
216 /**
217 * @brief Function for getting the address of a COMP event.
218 *
219 * @param[in] event COMP event.
220 *
221 * @return Address of the given COMP event.
222 */
nrfx_comp_event_address_get(nrf_comp_event_t event)223 __STATIC_INLINE uint32_t nrfx_comp_event_address_get(nrf_comp_event_t event)
224 {
225 return (uint32_t)nrf_comp_event_address_get(event);
226 }
227
228
229 void nrfx_comp_irq_handler(void);
230
231
232 /** @} **/
233
234 #ifdef __cplusplus
235 }
236 #endif
237
238 #endif // NRFX_COMP_H__
239