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_SAADC_H__ 33 #define NRFX_SAADC_H__ 34 35 #include <nrfx.h> 36 #include <hal/nrf_saadc.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** 43 * @defgroup nrfx_saadc SAADC driver 44 * @{ 45 * @ingroup nrf_saadc 46 * @brief Successive Approximation Analog-to-Digital Converter (SAADC) peripheral driver. 47 */ 48 49 /** 50 * @brief Value that should be set as high limit to disable limit detection. 51 */ 52 #define NRFX_SAADC_LIMITH_DISABLED (2047) 53 /** 54 * @brief Value that should be set as low limit to disable limit detection. 55 */ 56 #define NRFX_SAADC_LIMITL_DISABLED (-2048) 57 58 /** 59 * @brief Macro for setting @ref nrfx_saadc_config_t to default settings. 60 */ 61 #define NRFX_SAADC_DEFAULT_CONFIG \ 62 { \ 63 .resolution = (nrf_saadc_resolution_t)NRFX_SAADC_CONFIG_RESOLUTION, \ 64 .oversample = (nrf_saadc_oversample_t)NRFX_SAADC_CONFIG_OVERSAMPLE, \ 65 .interrupt_priority = NRFX_SAADC_CONFIG_IRQ_PRIORITY, \ 66 .low_power_mode = NRFX_SAADC_CONFIG_LP_MODE \ 67 } 68 69 /** 70 * @brief Macro for setting @ref nrf_saadc_channel_config_t to default settings 71 * in single ended mode. 72 * 73 * @param PIN_P Analog input. 74 */ 75 #define NRFX_SAADC_DEFAULT_CHANNEL_CONFIG_SE(PIN_P) \ 76 { \ 77 .resistor_p = NRF_SAADC_RESISTOR_DISABLED, \ 78 .resistor_n = NRF_SAADC_RESISTOR_DISABLED, \ 79 .gain = NRF_SAADC_GAIN1_6, \ 80 .reference = NRF_SAADC_REFERENCE_INTERNAL, \ 81 .acq_time = NRF_SAADC_ACQTIME_10US, \ 82 .mode = NRF_SAADC_MODE_SINGLE_ENDED, \ 83 .burst = NRF_SAADC_BURST_DISABLED, \ 84 .pin_p = (nrf_saadc_input_t)(PIN_P), \ 85 .pin_n = NRF_SAADC_INPUT_DISABLED \ 86 } 87 88 /** 89 * @brief Macro for setting @ref nrf_saadc_channel_config_t to default settings 90 * in differential mode. 91 * 92 * @param PIN_P Positive analog input. 93 * @param PIN_N Negative analog input. 94 */ 95 #define NRFX_SAADC_DEFAULT_CHANNEL_CONFIG_DIFFERENTIAL(PIN_P, PIN_N) \ 96 { \ 97 .resistor_p = NRF_SAADC_RESISTOR_DISABLED, \ 98 .resistor_n = NRF_SAADC_RESISTOR_DISABLED, \ 99 .gain = NRF_SAADC_GAIN1_6, \ 100 .reference = NRF_SAADC_REFERENCE_INTERNAL, \ 101 .acq_time = NRF_SAADC_ACQTIME_10US, \ 102 .mode = NRF_SAADC_MODE_DIFFERENTIAL, \ 103 .pin_p = (nrf_saadc_input_t)(PIN_P), \ 104 .pin_n = (nrf_saadc_input_t)(PIN_N) \ 105 } 106 107 /** 108 * @brief Analog-to-digital converter driver configuration structure. 109 */ 110 typedef struct 111 { 112 nrf_saadc_resolution_t resolution; ///< Resolution configuration. 113 nrf_saadc_oversample_t oversample; ///< Oversampling configuration. 114 uint8_t interrupt_priority; ///< Interrupt priority. 115 bool low_power_mode; ///< Indicates if low power mode is active. 116 } nrfx_saadc_config_t; 117 118 /** 119 * @brief Driver event types. 120 */ 121 typedef enum 122 { 123 NRFX_SAADC_EVT_DONE, ///< Event generated when the buffer is filled with samples. 124 NRFX_SAADC_EVT_LIMIT, ///< Event generated after one of the limits is reached. 125 NRFX_SAADC_EVT_CALIBRATEDONE ///< Event generated when the calibration is complete. 126 } nrfx_saadc_evt_type_t; 127 128 /** 129 * @brief Analog-to-digital converter driver done event data. 130 */ 131 typedef struct 132 { 133 nrf_saadc_value_t * p_buffer; ///< Pointer to buffer with converted samples. 134 uint16_t size; ///< Number of samples in the buffer. 135 } nrfx_saadc_done_evt_t; 136 137 /** 138 * @brief Analog-to-digital converter driver limit event data. 139 */ 140 typedef struct 141 { 142 uint8_t channel; ///< Channel on which the limit was detected. 143 nrf_saadc_limit_t limit_type; ///< Type of limit detected. 144 } nrfx_saadc_limit_evt_t; 145 146 /** 147 * @brief Analog-to-digital converter driver event structure. 148 */ 149 typedef struct 150 { 151 nrfx_saadc_evt_type_t type; ///< Event type. 152 union 153 { 154 nrfx_saadc_done_evt_t done; ///< Data for @ref NRFX_SAADC_EVT_DONE event. 155 nrfx_saadc_limit_evt_t limit; ///< Data for @ref NRFX_SAADC_EVT_LIMIT event. 156 } data; 157 } nrfx_saadc_evt_t; 158 159 /** 160 * @brief ADC event handler. 161 * 162 * @param[in] p_event Pointer to an ADC event. The event structure is allocated on 163 * the stack, so it is valid only within the context of 164 * the event handler. 165 */ 166 typedef void (* nrfx_saadc_event_handler_t)(nrfx_saadc_evt_t const * p_event); 167 168 /** 169 * @brief Function for initializing the SAADC. 170 * 171 * @param[in] p_config Pointer to the structure with initial configuration. 172 * @param[in] event_handler Event handler provided by the user. 173 * Must not be NULL. 174 * 175 * @retval NRFX_SUCCESS If initialization was successful. 176 * @retval NRFX_ERROR_INVALID_STATE If the driver is already initialized. 177 */ 178 nrfx_err_t nrfx_saadc_init(nrfx_saadc_config_t const * p_config, 179 nrfx_saadc_event_handler_t event_handler); 180 181 /** 182 * @brief Function for uninitializing the SAADC. 183 * 184 * This function stops all ongoing conversions and disables all channels. 185 */ 186 void nrfx_saadc_uninit(void); 187 188 189 /** 190 * @brief Function for getting the address of a SAMPLE SAADC task. 191 * 192 * @return Task address. 193 */ 194 uint32_t nrfx_saadc_sample_task_get(void); 195 196 /** 197 * @brief Function for initializing an SAADC channel. 198 * 199 * This function configures and enables the channel. 200 * 201 * @retval NRFX_SUCCESS If initialization was successful. 202 * @retval NRFX_ERROR_INVALID_STATE If the ADC was not initialized. 203 * @retval NRFX_ERROR_NO_MEM If the specified channel was already allocated. 204 */ 205 nrfx_err_t nrfx_saadc_channel_init(uint8_t channel, 206 nrf_saadc_channel_config_t const * const p_config); 207 208 209 /** 210 * @brief Function for uninitializing an SAADC channel. 211 * 212 * @retval NRFX_SUCCESS If uninitialization was successful. 213 * @retval NRFX_ERROR_BUSY If the ADC is busy. 214 */ 215 nrfx_err_t nrfx_saadc_channel_uninit(uint8_t channel); 216 217 /** 218 * @brief Function for starting SAADC sampling. 219 * 220 * @retval NRFX_SUCCESS If ADC sampling was triggered. 221 * @retval NRFX_ERROR_INVALID_STATE If ADC is in idle state. 222 */ 223 nrfx_err_t nrfx_saadc_sample(void); 224 225 /** 226 * @brief Blocking function for executing a single ADC conversion. 227 * 228 * This function selects the desired input, starts a single conversion, 229 * waits for it to finish, and returns the result. 230 * 231 * The function will fail if ADC is busy. 232 * 233 * @param[in] channel Channel. 234 * @param[out] p_value Pointer to the location where the result should be placed. 235 * 236 * @retval NRFX_SUCCESS If conversion was successful. 237 * @retval NRFX_ERROR_BUSY If the ADC driver is busy. 238 */ 239 nrfx_err_t nrfx_saadc_sample_convert(uint8_t channel, nrf_saadc_value_t * p_value); 240 241 /** 242 * @brief Function for issuing conversion of data to the buffer. 243 * 244 * This function is non-blocking. The application is notified about filling the buffer by the event 245 * handler. Conversion will be done on all enabled channels. If the ADC is in idle state, the 246 * function will set up Easy DMA for the conversion. The ADC will be ready for sampling and wait for 247 * the SAMPLE task. It can be triggered manually by the @ref nrfx_saadc_sample function or by PPI 248 * using the @ref NRF_SAADC_TASK_SAMPLE task. If one buffer is already set and the conversion is 249 * ongoing, calling this function will result in queuing the given buffer. The driver will start 250 * filling the issued buffer when the first one is completed. If the function is called again before 251 * the first buffer is filled or calibration is in progress, it will return with error. 252 * 253 * @param[in] buffer Result buffer. 254 * @param[in] size Buffer size in words. 255 * 256 * @retval NRFX_SUCCESS If conversion was successful. 257 * @retval NRFX_ERROR_BUSY If the driver already has two buffers set or calibration is in progress. 258 */ 259 nrfx_err_t nrfx_saadc_buffer_convert(nrf_saadc_value_t * buffer, uint16_t size); 260 261 /** 262 * @brief Function for triggering the ADC offset calibration. 263 * 264 * This function is non-blocking. The application is notified about completion by the event handler. 265 * Calibration will also trigger DONE and RESULTDONE events. 266 * 267 * The function will fail if ADC is busy or calibration is already in progress. 268 * 269 * @retval NRFX_SUCCESS If calibration was started successfully. 270 * @retval NRFX_ERROR_BUSY If the ADC driver is busy. 271 */ 272 nrfx_err_t nrfx_saadc_calibrate_offset(void); 273 274 /** 275 * @brief Function for retrieving the SAADC state. 276 * 277 * @retval true If the ADC is busy. 278 * @retval false If the ADC is ready. 279 */ 280 bool nrfx_saadc_is_busy(void); 281 282 /** 283 * @brief Function for aborting ongoing and buffered conversions. 284 * @note @ref NRFX_SAADC_EVT_DONE event will be generated if there is a conversion in progress. 285 * Event will contain number of words in the sample buffer. 286 */ 287 void nrfx_saadc_abort(void); 288 289 /** 290 * @brief Function for setting the SAADC channel limits. 291 * When limits are enabled and the result exceeds the defined bounds, the limit handler 292 * function is called. 293 * 294 * @param[in] channel SAADC channel number. 295 * @param[in] limit_low Lower limit (valid values from @ref NRFX_SAADC_LIMITL_DISABLED to 296 * @ref NRFX_SAADC_LIMITH_DISABLED). Conversion results below this value will 297 * trigger the handler function. Set to @ref NRFX_SAADC_LIMITL_DISABLED 298 * to disable this limit. 299 * @param[in] limit_high Upper limit (valid values from @ref NRFX_SAADC_LIMITL_DISABLED to 300 * @ref NRFX_SAADC_LIMITH_DISABLED). Conversion results above this value will 301 * trigger the handler function. Set to @ref NRFX_SAADC_LIMITH_DISABLED 302 * to disable this limit. 303 */ 304 void nrfx_saadc_limits_set(uint8_t channel, int16_t limit_low, int16_t limit_high); 305 306 307 void nrfx_saadc_irq_handler(void); 308 309 310 /** @} */ 311 312 #ifdef __cplusplus 313 } 314 #endif 315 316 #endif // NRFX_SAADC_H__ 317 318