Outline ![]()
Files ![]()
loading (1/5)...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
/*
* SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include <stdint.h>
#include <stdbool.h>
#include "esp_err.h"
#include "hal/pcnt_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Type of PCNT unit handle
*/
typedef struct pcnt_unit_t *pcnt_unit_handle_t;
/**
* @brief Type of PCNT channel handle
*/
typedef struct pcnt_chan_t *pcnt_channel_handle_t;
/**
* @brief PCNT watch event data
*/
typedef struct {
int watch_point_value; /*!< Watch point value that triggered the event */
pcnt_unit_zero_cross_mode_t zero_cross_mode; /*!< Zero cross mode */
} pcnt_watch_event_data_t;
/**
* @brief PCNT watch event callback prototype
*
* @note The callback function is invoked from an ISR context, so it should meet the restrictions of not calling any blocking APIs when implementing the callback.
* e.g. must use ISR version of FreeRTOS APIs.
*
* @param[in] unit PCNT unit handle
* @param[in] edata PCNT event data, fed by the driver
* @param[in] user_ctx User data, passed from `pcnt_unit_register_event_callbacks()`
* @return Whether a high priority task has been woken up by this function
*/
typedef bool (*pcnt_watch_cb_t)(pcnt_unit_handle_t unit, const pcnt_watch_event_data_t *edata, void *user_ctx);
/**
* @brief Group of supported PCNT callbacks
* @note The callbacks are all running under ISR environment
* @note When CONFIG_PCNT_ISR_IRAM_SAFE is enabled, the callback itself and functions callbed by it should be placed in IRAM.
*/
typedef struct {
pcnt_watch_cb_t on_reach; /*!< Called when PCNT unit counter reaches any watch point or step notify*/
} pcnt_event_callbacks_t;
/**
* @brief PCNT unit configuration
*/
typedef struct {
int low_limit; /*!< Low limitation of the count unit, should be lower than 0 */
int high_limit; /*!< High limitation of the count unit, should be higher than 0 */
int intr_priority; /*!< PCNT interrupt priority,
if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3) */
struct {
uint32_t accum_count: 1; /*!< Whether to accumulate the count value when overflows at the high/low limit */
#if SOC_PCNT_SUPPORT_STEP_NOTIFY
uint32_t en_step_notify_up: 1; /*!< Enable step notify in the positive direction */
uint32_t en_step_notify_down: 1; /*!< Enable step notify in the negative direction */
#endif // SOC_PCNT_SUPPORT_STEP_NOTIFY
} flags; /*!< Extra flags */
} pcnt_unit_config_t;
/**
* @brief PCNT channel configuration
*/
typedef struct {
int edge_gpio_num; /*!< GPIO number used by the edge signal, input mode with pull up enabled. Set to -1 if unused */
int level_gpio_num; /*!< GPIO number used by the level signal, input mode with pull up enabled. Set to -1 if unused */
struct {
uint32_t invert_edge_input: 1; /*!< Invert the input edge signal */
uint32_t invert_level_input: 1; /*!< Invert the input level signal */
uint32_t virt_edge_io_level: 1; /*!< Virtual edge IO level, 0: low, 1: high. Only valid when edge_gpio_num is set to -1 */
uint32_t virt_level_io_level: 1; /*!< Virtual level IO level, 0: low, 1: high. Only valid when level_gpio_num is set to -1 */
uint32_t io_loop_back: 1; /*!< For debug/test, the signal output from the GPIO will be fed to the input path as well.
Note that this flag is deprecated, will be removed in IDF v6.0.
Instead, you can configure the output mode by calling gpio_config() first, and then do PCNT channel configuration. Necessary configurations for the IO to be used as the PCNT input will be appended. */
} flags; /*!< Channel config flags */
} pcnt_chan_config_t;
/**
* @brief PCNT glitch filter configuration
*/
typedef struct {
uint32_t max_glitch_ns; /*!< Pulse width smaller than this threshold will be treated as glitch and ignored, in the unit of ns */
} pcnt_glitch_filter_config_t;
/**
* @brief Create a new PCNT unit, and return the handle
*
* @note The newly created PCNT unit is put in the init state.
*
* @param[in] config PCNT unit configuration
* @param[out] ret_unit Returned PCNT unit handle
* @return
* - ESP_OK: Create PCNT unit successfully
* - ESP_ERR_INVALID_ARG: Create PCNT unit failed because of invalid argument (e.g. high/low limit value out of the range)
* - ESP_ERR_NO_MEM: Create PCNT unit failed because out of memory
* - ESP_ERR_NOT_FOUND: Create PCNT unit failed because all PCNT units are used up and no more free one
* - ESP_FAIL: Create PCNT unit failed because of other error
*/
esp_err_t pcnt_new_unit(const pcnt_unit_config_t *config, pcnt_unit_handle_t *ret_unit);
/**
* @brief Delete the PCNT unit handle
*
* @note A PCNT unit can't be in the enable state when this function is invoked.
* See also `pcnt_unit_disable()` for how to disable a unit.
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @return
* - ESP_OK: Delete the PCNT unit successfully
* - ESP_ERR_INVALID_ARG: Delete the PCNT unit failed because of invalid argument
* - ESP_ERR_INVALID_STATE: Delete the PCNT unit failed because the unit is not in init state or some PCNT channel is still in working
* - ESP_FAIL: Delete the PCNT unit failed because of other error
*/
esp_err_t pcnt_del_unit(pcnt_unit_handle_t unit);
/**
* @brief Set glitch filter for PCNT unit
*
* @note This function should be called when the PCNT unit is in the init state (i.e. before calling `pcnt_unit_enable()`)
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @param[in] config PCNT filter configuration, set config to NULL means disabling the filter function
* @return
* - ESP_OK: Set glitch filter successfully
* - ESP_ERR_INVALID_ARG: Set glitch filter failed because of invalid argument (e.g. glitch width is too big)
* - ESP_ERR_INVALID_STATE: Set glitch filter failed because the unit is not in the init state
* - ESP_FAIL: Set glitch filter failed because of other error
*/
esp_err_t pcnt_unit_set_glitch_filter(pcnt_unit_handle_t unit, const pcnt_glitch_filter_config_t *config);
#if SOC_PCNT_SUPPORT_CLEAR_SIGNAL
/**
* @brief PCNT clear signal configuration
*/
typedef struct {
int clear_signal_gpio_num; /*!< GPIO number used by the clear signal, the default active level is high, input mode with pull down enabled */
struct {
uint32_t invert_clear_signal: 1; /*!< Invert the clear input signal and set input mode with pull up */
uint32_t io_loop_back: 1; /*!< For debug/test, the signal output from the GPIO will be fed to the input path as well.
Note that this flag is deprecated, will be removed in IDF v6.0.
Instead, you can configure the output mode by calling gpio_config() first, and then do PCNT channel configuration. Necessary configurations for the IO to be used as the PCNT input will be appended. */
} flags; /*!< clear signal config flags */
} pcnt_clear_signal_config_t;
/**
* @brief Set clear signal for PCNT unit
*
* @note The function of clear signal is the same as `pcnt_unit_clear_count()`. High-level Active
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @param[in] config PCNT clear signal configuration, set config to NULL means disabling the clear signal
* @return
* - ESP_OK: Set clear signal successfully
* - ESP_ERR_INVALID_ARG: Set clear signal failed because of invalid argument
* - ESP_ERR_INVALID_STATE: Set clear signal failed because set clear signal repeatedly or disable clear signal before set it
* - ESP_FAIL: Set clear signal failed because of other error
*/
esp_err_t pcnt_unit_set_clear_signal(pcnt_unit_handle_t unit, const pcnt_clear_signal_config_t *config);
#endif // SOC_PCNT_SUPPORT_CLEAR_SIGNAL
/**
* @brief Enable the PCNT unit
*
* @note This function will transit the unit state from init to enable.
* @note This function will enable the interrupt service, if it's lazy installed in `pcnt_unit_register_event_callbacks()`.
* @note This function will acquire the PM lock if it's lazy installed in `pcnt_unit_set_glitch_filter()`.
* @note Enable a PCNT unit doesn't mean to start it. See also `pcnt_unit_start()` for how to start the PCNT counter.
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @return
* - ESP_OK: Enable PCNT unit successfully
* - ESP_ERR_INVALID_ARG: Enable PCNT unit failed because of invalid argument
* - ESP_ERR_INVALID_STATE: Enable PCNT unit failed because the unit is already enabled
* - ESP_FAIL: Enable PCNT unit failed because of other error
*/
esp_err_t pcnt_unit_enable(pcnt_unit_handle_t unit);
/**
* @brief Disable the PCNT unit
*
* @note This function will do the opposite work to the `pcnt_unit_enable()`
* @note Disable a PCNT unit doesn't mean to stop it. See also `pcnt_unit_stop()` for how to stop the PCNT counter.
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @return
* - ESP_OK: Disable PCNT unit successfully
* - ESP_ERR_INVALID_ARG: Disable PCNT unit failed because of invalid argument
* - ESP_ERR_INVALID_STATE: Disable PCNT unit failed because the unit is not enabled yet
* - ESP_FAIL: Disable PCNT unit failed because of other error
*/
esp_err_t pcnt_unit_disable(pcnt_unit_handle_t unit);
/**
* @brief Start the PCNT unit, the counter will start to count according to the edge and/or level input signals
*
* @note This function should be called when the unit is in the enable state (i.e. after calling `pcnt_unit_enable()`)
* @note This function is allowed to run within ISR context
* @note This function will be placed into IRAM if `CONFIG_PCNT_CTRL_FUNC_IN_IRAM` is on, so that it's allowed to be executed when Cache is disabled
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @return
* - ESP_OK: Start PCNT unit successfully
* - ESP_ERR_INVALID_ARG: Start PCNT unit failed because of invalid argument
* - ESP_ERR_INVALID_STATE: Start PCNT unit failed because the unit is not enabled yet
* - ESP_FAIL: Start PCNT unit failed because of other error
*/
esp_err_t pcnt_unit_start(pcnt_unit_handle_t unit);
/**
* @brief Stop PCNT from counting
*
* @note This function should be called when the unit is in the enable state (i.e. after calling `pcnt_unit_enable()`)
* @note The stop operation won't clear the counter. Also see `pcnt_unit_clear_count()` for how to clear pulse count value.
* @note This function is allowed to run within ISR context
* @note This function will be placed into IRAM if `CONFIG_PCNT_CTRL_FUNC_IN_IRAM`, so that it is allowed to be executed when Cache is disabled
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @return
* - ESP_OK: Stop PCNT unit successfully
* - ESP_ERR_INVALID_ARG: Stop PCNT unit failed because of invalid argument
* - ESP_ERR_INVALID_STATE: Stop PCNT unit failed because the unit is not enabled yet
* - ESP_FAIL: Stop PCNT unit failed because of other error
*/
esp_err_t pcnt_unit_stop(pcnt_unit_handle_t unit);
/**
* @brief Clear PCNT pulse count value to zero
*
* @note It's recommended to call this function after adding a watch point by `pcnt_unit_add_watch_point()`, so that the newly added watch point is effective immediately.
* @note This function is allowed to run within ISR context
* @note This function will be placed into IRAM if `CONFIG_PCNT_CTRL_FUNC_IN_IRAM`, so that it's allowed to be executed when Cache is disabled
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @return
* - ESP_OK: Clear PCNT pulse count successfully
* - ESP_ERR_INVALID_ARG: Clear PCNT pulse count failed because of invalid argument
* - ESP_FAIL: Clear PCNT pulse count failed because of other error
*/
esp_err_t pcnt_unit_clear_count(pcnt_unit_handle_t unit);
/**
* @brief Get PCNT count value
*
* @note This function is allowed to run within ISR context
* @note This function will be placed into IRAM if `CONFIG_PCNT_CTRL_FUNC_IN_IRAM`, so that it's allowed to be executed when Cache is disabled
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @param[out] value Returned count value
* @return
* - ESP_OK: Get PCNT pulse count successfully
* - ESP_ERR_INVALID_ARG: Get PCNT pulse count failed because of invalid argument
* - ESP_FAIL: Get PCNT pulse count failed because of other error
*/
esp_err_t pcnt_unit_get_count(pcnt_unit_handle_t unit, int *value);
/**
* @brief Set event callbacks for PCNT unit
*
* @note User registered callbacks are expected to be runnable within ISR context
* @note The first call to this function needs to be before the call to `pcnt_unit_enable`
* @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL.
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @param[in] cbs Group of callback functions
* @param[in] user_data User data, which will be passed to callback functions directly
* @return
* - ESP_OK: Set event callbacks successfully
* - ESP_ERR_INVALID_ARG: Set event callbacks failed because of invalid argument
* - ESP_ERR_INVALID_STATE: Set event callbacks failed because the unit is not in init state
* - ESP_FAIL: Set event callbacks failed because of other error
*/
esp_err_t pcnt_unit_register_event_callbacks(pcnt_unit_handle_t unit, const pcnt_event_callbacks_t *cbs, void *user_data);
/**
* @brief Add a watch point for PCNT unit, PCNT will generate an event when the counter value reaches the watch point value
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @param[in] watch_point Value to be watched
* @return
* - ESP_OK: Add watch point successfully
* - ESP_ERR_INVALID_ARG: Add watch point failed because of invalid argument (e.g. the value to be watched is out of the limitation set in `pcnt_unit_config_t`)
* - ESP_ERR_INVALID_STATE: Add watch point failed because the same watch point has already been added
* - ESP_ERR_NOT_FOUND: Add watch point failed because no more hardware watch point can be configured
* - ESP_FAIL: Add watch point failed because of other error
*/
esp_err_t pcnt_unit_add_watch_point(pcnt_unit_handle_t unit, int watch_point);
/**
* @brief Remove a watch point for PCNT unit
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @param[in] watch_point Watch point value
* @return
* - ESP_OK: Remove watch point successfully
* - ESP_ERR_INVALID_ARG: Remove watch point failed because of invalid argument
* - ESP_ERR_INVALID_STATE: Remove watch point failed because the watch point was not added by `pcnt_unit_add_watch_point()` yet
* - ESP_FAIL: Remove watch point failed because of other error
*/
esp_err_t pcnt_unit_remove_watch_point(pcnt_unit_handle_t unit, int watch_point);
/**
* @brief Add a step notify for PCNT unit, PCNT will generate an event when the incremental(can be positive or negative) of counter value reaches the step interval
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @param[in] step_interval PCNT step notify interval value
* @return
* - ESP_OK: Add step notify successfully
* - ESP_ERR_INVALID_ARG: Add step notify failed because of invalid argument (e.g. the value incremental to be watched is out of the limitation set in `pcnt_unit_config_t`)
* - ESP_ERR_INVALID_STATE: Add step notify failed because the step notify has already been added
* - ESP_FAIL: Add step notify failed because of other error
*/
esp_err_t pcnt_unit_add_watch_step(pcnt_unit_handle_t unit, int step_interval);
/**
* @brief Remove a step notify for PCNT unit
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @return
* - ESP_OK: Remove step notify successfully
* - ESP_ERR_INVALID_ARG: Remove step notify failed because of invalid argument
* - ESP_ERR_INVALID_STATE: Remove step notify failed because the step notify was not added by `pcnt_unit_add_watch_step()` yet
* - ESP_FAIL: Remove step notify failed because of other error
*/
esp_err_t pcnt_unit_remove_watch_step(pcnt_unit_handle_t unit);
/**
* @brief Create PCNT channel for specific unit, each PCNT has several channels associated with it
*
* @note This function should be called when the unit is in init state (i.e. before calling `pcnt_unit_enable()`)
*
* @param[in] unit PCNT unit handle created by `pcnt_new_unit()`
* @param[in] config PCNT channel configuration
* @param[out] ret_chan Returned channel handle
* @return
* - ESP_OK: Create PCNT channel successfully
* - ESP_ERR_INVALID_ARG: Create PCNT channel failed because of invalid argument
* - ESP_ERR_NO_MEM: Create PCNT channel failed because of insufficient memory
* - ESP_ERR_NOT_FOUND: Create PCNT channel failed because all PCNT channels are used up and no more free one
* - ESP_ERR_INVALID_STATE: Create PCNT channel failed because the unit is not in the init state
* - ESP_FAIL: Create PCNT channel failed because of other error
*/
esp_err_t pcnt_new_channel(pcnt_unit_handle_t unit, const pcnt_chan_config_t *config, pcnt_channel_handle_t *ret_chan);
/**
* @brief Delete the PCNT channel
*
* @param[in] chan PCNT channel handle created by `pcnt_new_channel()`
* @return
* - ESP_OK: Delete the PCNT channel successfully
* - ESP_ERR_INVALID_ARG: Delete the PCNT channel failed because of invalid argument
* - ESP_FAIL: Delete the PCNT channel failed because of other error
*/
esp_err_t pcnt_del_channel(pcnt_channel_handle_t chan);
/**
* @brief Set channel actions when edge signal changes (e.g. falling or rising edge occurred).
* The edge signal is input from the `edge_gpio_num` configured in `pcnt_chan_config_t`.
* We use these actions to control when and how to change the counter value.
*
* @param[in] chan PCNT channel handle created by `pcnt_new_channel()`
* @param[in] pos_act Action on posedge signal
* @param[in] neg_act Action on negedge signal
* @return
* - ESP_OK: Set edge action for PCNT channel successfully
* - ESP_ERR_INVALID_ARG: Set edge action for PCNT channel failed because of invalid argument
* - ESP_FAIL: Set edge action for PCNT channel failed because of other error
*/
esp_err_t pcnt_channel_set_edge_action(pcnt_channel_handle_t chan, pcnt_channel_edge_action_t pos_act, pcnt_channel_edge_action_t neg_act);
/**
* @brief Set channel actions when level signal changes (e.g. signal level goes from high to low).
* The level signal is input from the `level_gpio_num` configured in `pcnt_chan_config_t`.
* We use these actions to control when and how to change the counting mode.
*
* @param[in] chan PCNT channel handle created by `pcnt_new_channel()`
* @param[in] high_act Action on high level signal
* @param[in] low_act Action on low level signal
* @return
* - ESP_OK: Set level action for PCNT channel successfully
* - ESP_ERR_INVALID_ARG: Set level action for PCNT channel failed because of invalid argument
* - ESP_FAIL: Set level action for PCNT channel failed because of other error
*/
esp_err_t pcnt_channel_set_level_action(pcnt_channel_handle_t chan, pcnt_channel_level_action_t high_act, pcnt_channel_level_action_t low_act);
#ifdef __cplusplus
}
#endif
Details ![]()
Show: from Types: Columns: ![]( "Show Project Names")
![]( "Show Locations")
![]( "Show Referring Symbols")
![]( "Show Scope")
This file uses the notable symbols shown below. Click anywhere in the file to view more details.