app_adc.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file app_adc.h
5 * @author BLE Driver Team
6 * @brief Header file containing functions prototypes of ADC app library.
7 *
8 ****************************************************************************************
9 * @attention
10 #####Copyright (c) 2019 GOODIX
11 All rights reserved.
12
13 Redistribution and use in source and binary forms, with or without
14 modification, are permitted provided that the following conditions are met:
15 * Redistributions of source code must retain the above copyright
16 notice, this list of conditions and the following disclaimer.
17 * Redistributions in binary form must reproduce the above copyright
18 notice, this list of conditions and the following disclaimer in the
19 documentation and/or other materials provided with the distribution.
20 * Neither the name of GOODIX nor the names of its contributors may be used
21 to endorse or promote products derived from this software without
22 specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 POSSIBILITY OF SUCH DAMAGE.
35 ****************************************************************************************
36 */
37
38 /** @addtogroup PERIPHERAL Peripheral Driver
39 * @{
40 */
41
42 /** @addtogroup APP_DRIVER APP DRIVER
43 * @{
44 */
45
46 /** @defgroup APP_ADC ADC
47 * @brief ADC APP module driver.
48 * @{
49 */
50
51
52 #ifndef _APP_ADC_H_
53 #define _APP_ADC_H_
54
55 #include "grx_hal.h"
56 #include "app_io.h"
57 #include "app_dma.h"
58 #include "app_drv_error.h"
59 #include "app_drv_config.h"
60
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64
65 #ifdef HAL_ADC_MODULE_ENABLED
66
67 /** @addtogroup APP_ADC_ENUM Enumerations
68 * @{
69 */
70
71 /**
72 * @brief ADC event Enumerations definition
73 */
74 typedef enum
75 {
76 APP_ADC_EVT_CONV_CPLT, /**< Conversion completed by ADC peripheral. */
77 } app_adc_evt_type_t;
78
79 /**@brief App adc state types. */
80 typedef enum
81 {
82 APP_ADC_INVALID = 0,
83 APP_ADC_ACTIVITY,
84 #ifdef APP_DRIVER_WAKEUP_CALL_FUN
85 APP_ADC_SLEEP,
86 #endif
87 } app_adc_state_t;
88
89 /**@brief App adc dma state types. */
90 typedef enum
91 {
92 APP_ADC_DMA_INVALID = 0,
93 APP_ADC_DMA_ACTIVITY,
94 } app_adc_dma_state_t;
95
96 /** @} */
97
98
99 /** @addtogroup APP_ADC_STRUCTURES Structures
100 * @{
101 */
102
103 /**
104 * @brief ADC pins Structures
105 */
106 typedef struct
107 {
108 app_io_type_t type; /**< Specifies the type of ADC IO. */
109 app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */
110 uint32_t pin; /**< Specifies the IO pins to be configured.
111 This parameter can be any value of @ref GR5xxx_pins. */
112 } app_adc_pin_t;
113
114 /**
115 * @brief ADC pins config Structures
116 */
117 typedef struct
118 {
119 app_adc_pin_t channel_p; /**< Set the configuration of ADC pin. */
120 app_adc_pin_t channel_n; /**< Set the configuration of ADC pin. */
121 app_adc_pin_t extern_ref; /**< Set the configuration of extern reference pin. */
122 } app_adc_pin_cfg_t;
123
124 /**
125 * @brief ADC DMA configuration Structures
126 */
127 typedef struct
128 {
129 dma_regs_t * dma_instance; /**< Specifies the dma instance of ADC. */
130 dma_channel_t dma_channel; /**< Specifies the dma channel of ADC. */
131 } app_adc_dma_cfg_t;
132
133 /**
134 * @brief ADC event structure definition
135 */
136 typedef struct
137 {
138 app_adc_evt_type_t type; /**< Type of event. */
139 } app_adc_evt_t;
140
141 /** @} */
142
143 /** @addtogroup APP_ADC_TYPEDEFS Type definitions
144 * @{
145 */
146 /**
147 * @brief ADC event callback definition
148 */
149 typedef void (*app_adc_evt_handler_t)(app_adc_evt_t *p_evt);
150
151 /** @} */
152
153 /** @addtogroup APP_ADC_STRUCTURES Structures
154 * @{
155 */
156
157 /**
158 * @brief ADC sample-node definition
159 */
160 typedef struct link_node
161 {
162 uint32_t channel; /**< Which channel to be sample; This parameter can be any value of ADC_INPUT_SOURCE:ADC_INPUT_SRC_IO0~ADC_INPUT_SRC_REF*/
163 uint16_t *p_buf; /**< Buffer pointer of current channel sample codes. Note:pointer must be 4-byte aligned as it is filled in datas by DMA */
164 uint32_t len; /**< Sample len codes on current channel. */
165 struct link_node *next; /**< Point to the next sample node. */
166 } app_adc_sample_node_t;
167
168 /**
169 * @brief ADC device structure definition
170 */
171 typedef struct
172 {
173 app_adc_evt_handler_t evt_handler; /**< ADC event callback definition. */
174 adc_handle_t handle; /**< ADC handle definition. */
175 app_adc_pin_cfg_t *p_pin_cfg; /**< ADC pins config Structures. */
176 dma_id_t dma_id; /**< DMA id definition. */
177 app_adc_state_t adc_state; /**< ADC state types. */
178 app_adc_dma_state_t adc_dma_state; /**< ADC dma state types. */
179 app_adc_sample_node_t *p_current_sample_node; /**< ADC current sampling node in multi-sample mode. */
180 app_adc_sample_node_t *p_first_sample_node; /**< ADC first sampling node in multi-sample mode. */
181 uint32_t multi_channel; /**< Remaining channel count. */
182 uint32_t multi_channel_total; /**< Total channel count. */
183 } adc_env_t;
184
185 /**
186 * @brief ADC parameters structure definition
187 */
188 typedef struct
189 {
190 app_adc_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified ADC module. */
191 app_adc_dma_cfg_t dma_cfg; /**< ADC DMA configuration. */
192 adc_init_t init; /**< ADC configuration parameters. */
193 adc_env_t adc_env; /**< ADC device structure definition. */
194 } app_adc_params_t;
195
196 /** @} */
197
198 /* Exported functions --------------------------------------------------------*/
199 /** @addtogroup APP_ADC_DRIVER_FUNCTIONS Functions
200 * @{
201 */
202
203 /**
204 ****************************************************************************************
205 * @brief Initialize the APP ADC DRIVER according to the specified parameters
206 * in the app_adc_params_t and app_adc_evt_handler_t.
207 * @note If DMA mode is set, you can use blocking mode. Conversely, if blocking mode
208 * is set, you can't use DMA mode.
209 *
210 * @param[in] p_params: Pointer to app_adc_params_t parameter which contains the
211 * configuration information for the specified ADC module.
212 * @param[in] evt_handler: ADC user callback function.
213 *
214 * @return Result of initialization.
215 ****************************************************************************************
216 */
217 uint16_t app_adc_init(app_adc_params_t *p_params, app_adc_evt_handler_t evt_handler);
218
219 /**
220 ****************************************************************************************
221 * @brief De-initialize the APP ADC DRIVER peripheral.
222 *
223 * @return Result of De-initialization.
224 ****************************************************************************************
225 */
226 uint16_t app_adc_deinit(void);
227
228 /**
229 ****************************************************************************************
230 * @brief Polling for conversion.
231 *
232 * @param[in] p_data: Pointer to data buffer which to storage ADC conversion results.
233 * @param[in] length: Length of data buffer.
234 * @param[in] timeout : Timeout duration
235 *
236 * @return Result of operation.
237 ****************************************************************************************
238 */
239 uint16_t app_adc_conversion_sync(uint16_t *p_data, uint32_t length, uint32_t timeout);
240
241 /**
242 ****************************************************************************************
243 * @brief DMA for conversion.
244 *
245 * @param[in] p_data: Pointer to data buffer which to storage ADC conversion results.
246 * @param[in] length: Length of data buffer, ranging between 0 and 4095.
247 * Note: Length must be aligned on a four-byte boundary.
248 *
249 * @return Result of operation.
250 ****************************************************************************************
251 */
252 uint16_t app_adc_conversion_async(uint16_t *p_data, uint32_t length);
253
254 /**
255 ****************************************************************************************
256 * @brief Convert the ADC conversion results to a voltage value(internal reference).
257 *
258 * @param[in] inbuf: Pointer to data buffer which storage ADC conversion results.
259 * @param[out] outbuf: Pointer to data buffer which to storage voltage results.
260 * @param[in] buflen: Length of data buffer.
261 *
262 * @return Result of operation.
263 ****************************************************************************************
264 */
265 uint16_t app_adc_voltage_intern(uint16_t *inbuf, double *outbuf, uint32_t buflen);
266
267 /**
268 ****************************************************************************************
269 * @brief Convert the ADC conversion results to a voltage value(external reference).
270 *
271 * @param[in] ref: slope of ADC.
272 * @param[in] inbuf: Pointer to data buffer which storage ADC conversion results.
273 * @param[out] outbuf: Pointer to data buffer which to storage voltage results.
274 * @param[in] buflen: Length of data buffer.
275 *
276 * @return Result of operation.
277 ****************************************************************************************
278 */
279 uint16_t app_adc_voltage_extern(double ref, uint16_t *inbuf, double *outbuf, uint32_t buflen);
280
281 #if (APP_DRIVER_CHIP_TYPE != APP_DRIVER_GR551X)
282 /**
283 ****************************************************************************************
284 * @brief Convert the ADC conversion results to temperature value.
285 *
286 * @param[in] inbuf: Pointer to data buffer which storage ADC conversion results.
287 * @param[out] outbuf: Pointer to data buffer which to storage voltage results.
288 * @param[in] buflen: Length of data buffer.
289 *
290 * @return Result of operation.
291 ****************************************************************************************
292 */
293 uint16_t app_adc_temperature_conv(uint16_t *inbuf, double *outbuf, uint32_t buflen);
294
295 /**
296 ****************************************************************************************
297 * @brief Convert the ADC conversion results to battery value.
298 *
299 * @param[in] inbuf: Pointer to data buffer which storage ADC codes.
300 * @param[out] outbuf: Pointer to data buffer which to storage conversion results.
301 * @param[in] buflen: Length of data buffer.
302 *
303 * @return Result of operation.
304 ****************************************************************************************
305 */
306 uint16_t app_adc_vbat_conv(uint16_t *inbuf, double *outbuf, uint32_t buflen);
307 #endif
308
309 /**
310 ****************************************************************************************
311 * @brief Return the ADC handle.
312 *
313 * @return Pointer to the ADC handle.
314 ****************************************************************************************
315 */
316 adc_handle_t *app_adc_get_handle(void);
317
318 /**
319 ****************************************************************************************
320 * @brief DMA for multi channels conversion; evt_handler in app_adc_init will callback when all channels finish.
321 *
322 * @param[in] p_begin_node: Pointer to the multi sample channels list node.
323 * @param[in] total_nodes: total sample channels.
324 *
325 * @return Result of operation.
326 ****************************************************************************************
327 */
328 uint16_t app_adc_multi_channel_conversion_async(app_adc_sample_node_t *p_begin_node, uint32_t total_nodes);
329
330 #if (APP_DRIVER_CHIP_TYPE == APP_DRIVER_GR5526X)
331 /**
332 ****************************************************************************************
333 * @brief Clear the ADC FIFO, filter the first two incorrect code values , and start the ADC clock.
334 *
335 * @return Result of operation.
336 ****************************************************************************************
337 */
338 uint16_t app_adc_clock_start(void);
339
340 /**
341 ****************************************************************************************
342 * @brief Get the ADC sampling code by polling, and convert sampling code of the specified length to the average voltage.
343 *
344 * @param[out] avg_voltage: Pointer to data which to storage average voltage results.
345 * @param[in] length: Length of the ADC sample values to be averaged.
346 *
347 * @return Result of operation.
348 ****************************************************************************************
349 */
350 uint16_t app_adc_get_avg_voltage(float *avg_voltage, uint32_t length);
351
352 #endif
353
354
355 /** @} */
356
357 #endif
358
359 #ifdef __cplusplus
360 }
361 #endif
362
363 #endif
364
365 /** @} */
366
367 /** @} */
368
369 /** @} */
370
app_adc_voltage_extern
uint16_t app_adc_voltage_extern(double ref, uint16_t *inbuf, double *outbuf, uint32_t buflen)
Convert the ADC conversion results to a voltage value(external reference).
APP_ADC_INVALID
@ APP_ADC_INVALID
Definition: app_adc.h:82
app_adc_evt_handler_t
void(* app_adc_evt_handler_t)(app_adc_evt_t *p_evt)
ADC event callback definition.
Definition: app_adc.h:149
APP_ADC_EVT_CONV_CPLT
@ APP_ADC_EVT_CONV_CPLT
Conversion completed by ADC peripheral.
Definition: app_adc.h:76
app_adc_pin_t::mux
app_io_mux_t mux
Specifies the Peripheral to be connected to the selected pins.
Definition: app_adc.h:109
app_adc_dma_cfg_t::dma_channel
dma_channel_t dma_channel
Specifies the dma channel of ADC.
Definition: app_adc.h:130
app_adc_multi_channel_conversion_async
uint16_t app_adc_multi_channel_conversion_async(app_adc_sample_node_t *p_begin_node, uint32_t total_nodes)
DMA for multi channels conversion; evt_handler in app_adc_init will callback when all channels finish...
adc_env_t::p_first_sample_node
app_adc_sample_node_t * p_first_sample_node
ADC first sampling node in multi-sample mode.
Definition: app_adc.h:180
app_adc_params_t::adc_env
adc_env_t adc_env
ADC device structure definition.
Definition: app_adc.h:193
adc_env_t::adc_state
app_adc_state_t adc_state
ADC state types.
Definition: app_adc.h:177
APP_ADC_DMA_INVALID
@ APP_ADC_DMA_INVALID
Definition: app_adc.h:92
adc_env_t
ADC device structure definition.
Definition: app_adc.h:172
app_adc_evt_t::type
app_adc_evt_type_t type
Type of event.
Definition: app_adc.h:138
app_io_type_t
app_io_type_t
GPIO type Enumerations definition.
Definition: app_io.h:147
adc_env_t::adc_dma_state
app_adc_dma_state_t adc_dma_state
ADC dma state types.
Definition: app_adc.h:178
app_adc_params_t
ADC parameters structure definition.
Definition: app_adc.h:189
app_adc_pin_t::pin
uint32_t pin
Specifies the IO pins to be configured.
Definition: app_adc.h:110
app_adc_dma_cfg_t
ADC DMA configuration Structures.
Definition: app_adc.h:128
APP_ADC_DMA_ACTIVITY
@ APP_ADC_DMA_ACTIVITY
Definition: app_adc.h:93
app_adc_state_t
app_adc_state_t
App adc state types.
Definition: app_adc.h:81
app_adc_params_t::pin_cfg
app_adc_pin_cfg_t pin_cfg
the pin configuration information for the specified ADC module.
Definition: app_adc.h:190
_ll_adc_init
LL ADC init Structure definition.
Definition: gr55xx_ll_adc.h:77
app_io.h
Header file containing functions prototypes of GPIO app library.
app_adc_evt_t
ADC event structure definition.
Definition: app_adc.h:137
app_adc_evt_type_t
app_adc_evt_type_t
ADC event Enumerations definition.
Definition: app_adc.h:75
app_adc_voltage_intern
uint16_t app_adc_voltage_intern(uint16_t *inbuf, double *outbuf, uint32_t buflen)
Convert the ADC conversion results to a voltage value(internal reference).
adc_env_t::evt_handler
app_adc_evt_handler_t evt_handler
ADC event callback definition.
Definition: app_adc.h:173
grx_hal.h
This file contains all the functions prototypes for the HAL module driver.
app_adc_sample_node_t
struct link_node app_adc_sample_node_t
ADC sample-node definition.
app_adc_conversion_sync
uint16_t app_adc_conversion_sync(uint16_t *p_data, uint32_t length, uint32_t timeout)
Polling for conversion.
_adc_handle
ADC handle Structure definition.
Definition: gr55xx_hal_adc.h:111
app_adc_pin_t::type
app_io_type_t type
Specifies the type of ADC IO.
Definition: app_adc.h:108
app_adc_pin_cfg_t::extern_ref
app_adc_pin_t extern_ref
Set the configuration of extern reference pin.
Definition: app_adc.h:121
link_node::next
struct link_node * next
Point to the next sample node.
Definition: app_adc.h:165
app_adc_params_t::init
adc_init_t init
ADC configuration parameters.
Definition: app_adc.h:192
link_node::len
uint32_t len
Sample len codes on current channel.
Definition: app_adc.h:164
link_node::p_buf
uint16_t * p_buf
Buffer pointer of current channel sample codes.
Definition: app_adc.h:163
APP_ADC_ACTIVITY
@ APP_ADC_ACTIVITY
Definition: app_adc.h:83
app_dma.h
Header file containing functions prototypes of DMA app library.
app_adc_deinit
uint16_t app_adc_deinit(void)
De-initialize the APP ADC DRIVER peripheral.
link_node
ADC sample-node definition.
Definition: app_adc.h:161
adc_env_t::p_pin_cfg
app_adc_pin_cfg_t * p_pin_cfg
ADC pins config Structures.
Definition: app_adc.h:175
link_node::channel
uint32_t channel
Which channel to be sample; This parameter can be any value of ADC_INPUT_SOURCE:ADC_INPUT_SRC_IO0~ADC...
Definition: app_adc.h:162
adc_env_t::multi_channel_total
uint32_t multi_channel_total
Total channel count.
Definition: app_adc.h:182
app_adc_pin_cfg_t::channel_n
app_adc_pin_t channel_n
Set the configuration of ADC pin.
Definition: app_adc.h:120
app_adc_get_handle
adc_handle_t * app_adc_get_handle(void)
Return the ADC handle.
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:255
adc_env_t::handle
adc_handle_t handle
ADC handle definition.
Definition: app_adc.h:174
adc_env_t::multi_channel
uint32_t multi_channel
Remaining channel count.
Definition: app_adc.h:181
app_adc_conversion_async
uint16_t app_adc_conversion_async(uint16_t *p_data, uint32_t length)
DMA for conversion.
app_adc_pin_cfg_t::channel_p
app_adc_pin_t channel_p
Set the configuration of ADC pin.
Definition: app_adc.h:119
adc_env_t::dma_id
dma_id_t dma_id
DMA id definition.
Definition: app_adc.h:176
app_drv_error.h
Header file of app driver error code.
app_drv_config.h
Header file of app driver config code.
app_adc_dma_cfg_t::dma_instance
dma_regs_t * dma_instance
Specifies the dma instance of ADC.
Definition: app_adc.h:129
app_adc_dma_state_t
app_adc_dma_state_t
App adc dma state types.
Definition: app_adc.h:91
dma_id_t
int16_t dma_id_t
DMA id definition.
Definition: app_dma.h:98
app_adc_pin_cfg_t
ADC pins config Structures.
Definition: app_adc.h:118
dma_channel_t
dma_channel_t
HAL DMA Channel Enumerations definition.
Definition: gr55xx_hal_dma.h:93
adc_env_t::p_current_sample_node
app_adc_sample_node_t * p_current_sample_node
ADC current sampling node in multi-sample mode.
Definition: app_adc.h:179
app_adc_params_t::dma_cfg
app_adc_dma_cfg_t dma_cfg
ADC DMA configuration.
Definition: app_adc.h:191
app_adc_pin_t
ADC pins Structures.
Definition: app_adc.h:107
app_adc_init
uint16_t app_adc_init(app_adc_params_t *p_params, app_adc_evt_handler_t evt_handler)
Initialize the APP ADC DRIVER according to the specified parameters in the app_adc_params_t and app_a...