Outline ![]()
Files ![]()
loading...
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
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
/*
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include "esp_err.h"
#include "esp_intr_alloc.h"
#include "soc/soc_caps.h"
#include "freertos/FreeRTOS.h"
#include "freertos/queue.h"
#include "hal/uart_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/* @brief When calling `uart_set_pin`, instead of GPIO number, `UART_PIN_NO_CHANGE`
* can be provided to keep the currently allocated pin.
*/
#define UART_PIN_NO_CHANGE (-1)
#define UART_FIFO_LEN _Pragma ("GCC warning \"'UART_FIFO_LEN' macro is deprecated, please use 'UART_HW_FIFO_LEN' instead\"") SOC_UART_FIFO_LEN ///< Length of the HP UART HW FIFO
#if (SOC_UART_LP_NUM >= 1)
#define UART_HW_FIFO_LEN(uart_num) ((uart_num < SOC_UART_HP_NUM) ? SOC_UART_FIFO_LEN : SOC_LP_UART_FIFO_LEN) ///< Length of the UART HW FIFO
#else
#define UART_HW_FIFO_LEN(uart_num) SOC_UART_FIFO_LEN ///< Length of the UART HW FIFO
#endif
#define UART_BITRATE_MAX SOC_UART_BITRATE_MAX ///< Maximum configurable bitrate
/**
* @brief UART configuration parameters for uart_param_config function
*/
typedef struct {
int baud_rate; /*!< UART baud rate*/
uart_word_length_t data_bits; /*!< UART byte size*/
uart_parity_t parity; /*!< UART parity mode*/
uart_stop_bits_t stop_bits; /*!< UART stop bits*/
uart_hw_flowcontrol_t flow_ctrl; /*!< UART HW flow control mode (cts/rts)*/
uint8_t rx_flow_ctrl_thresh; /*!< UART HW RTS threshold*/
union {
uart_sclk_t source_clk; /*!< UART source clock selection */
#if (SOC_UART_LP_NUM >= 1)
lp_uart_sclk_t lp_source_clk; /*!< LP_UART source clock selection */
#endif
};
struct {
uint32_t allow_pd: 1; /*!< If set, driver allows the power domain to be powered off when system enters sleep mode.
This can save power, but at the expense of more RAM being consumed to save register context. */
uint32_t backup_before_sleep: 1; /*!< @deprecated, same meaning as allow_pd */
} flags; /*!< Configuration flags */
} uart_config_t;
/**
* @brief UART interrupt configuration parameters for uart_intr_config function
*/
typedef struct {
uint32_t intr_enable_mask; /*!< UART interrupt enable mask, choose from UART_XXXX_INT_ENA_M under UART_INT_ENA_REG(i), connect with bit-or operator*/
uint8_t rx_timeout_thresh; /*!< UART timeout interrupt threshold (unit: time of sending one byte)*/
uint8_t txfifo_empty_intr_thresh; /*!< UART TX empty interrupt threshold.*/
uint8_t rxfifo_full_thresh; /*!< UART RX full interrupt threshold.*/
} uart_intr_config_t;
/**
* @brief UART event types used in the ring buffer
*/
typedef enum {
UART_DATA, /*!< UART data event*/
UART_BREAK, /*!< UART break event*/
UART_BUFFER_FULL, /*!< UART RX buffer full event*/
UART_FIFO_OVF, /*!< UART FIFO overflow event*/
UART_FRAME_ERR, /*!< UART RX frame error event*/
UART_PARITY_ERR, /*!< UART RX parity event*/
UART_DATA_BREAK, /*!< UART TX data and break event*/
UART_PATTERN_DET, /*!< UART pattern detected */
#if SOC_UART_SUPPORT_WAKEUP_INT
UART_WAKEUP, /*!< UART wakeup event */
#endif
UART_EVENT_MAX, /*!< UART event max index*/
} uart_event_type_t;
/**
* @brief Event structure used in UART event queue
*/
typedef struct {
uart_event_type_t type; /*!< UART event type */
size_t size; /*!< UART data size for UART_DATA event*/
bool timeout_flag; /*!< UART data read timeout flag for UART_DATA event (no new data received during configured RX TOUT)*/
/*!< If the event is caused by FIFO-full interrupt, then there will be no event with the timeout flag before the next byte coming.*/
} uart_event_t;
typedef intr_handle_t uart_isr_handle_t;
/**
* @brief Install UART driver and set the UART to the default configuration.
*
* UART ISR handler will be attached to the same CPU core that this function is running on.
*
* @note Rx_buffer_size should be greater than UART_HW_FIFO_LEN(uart_num). Tx_buffer_size should be either zero or greater than UART_HW_FIFO_LEN(uart_num).
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param rx_buffer_size UART RX ring buffer size.
* @param tx_buffer_size UART TX ring buffer size.
* If set to zero, driver will not use TX buffer, TX function will block task until all data have been sent out.
* @param queue_size UART event queue size/depth.
* @param uart_queue UART event queue handle (out param). On success, a new queue handle is written here to provide
* access to UART events. If set to NULL, driver will not use an event queue.
* @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred)
* ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. Do not set ESP_INTR_FLAG_IRAM here
* (the driver's ISR handler is not located in IRAM)
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_driver_install(uart_port_t uart_num, int rx_buffer_size, int tx_buffer_size, int queue_size, QueueHandle_t* uart_queue, int intr_alloc_flags);
/**
* @brief Uninstall UART driver.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_driver_delete(uart_port_t uart_num);
/**
* @brief Checks whether the driver is installed or not
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
*
* @return
* - true driver is installed
* - false driver is not installed
*/
bool uart_is_driver_installed(uart_port_t uart_num);
/**
* @brief Set UART data bits.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param data_bit UART data bits
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_set_word_length(uart_port_t uart_num, uart_word_length_t data_bit);
/**
* @brief Get the UART data bit configuration.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param data_bit Pointer to accept value of UART data bits.
*
* @return
* - ESP_FAIL Parameter error
* - ESP_OK Success, result will be put in (*data_bit)
*/
esp_err_t uart_get_word_length(uart_port_t uart_num, uart_word_length_t* data_bit);
/**
* @brief Set UART stop bits.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param stop_bits UART stop bits
*
* @return
* - ESP_OK Success
* - ESP_FAIL Fail
*/
esp_err_t uart_set_stop_bits(uart_port_t uart_num, uart_stop_bits_t stop_bits);
/**
* @brief Get the UART stop bit configuration.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param stop_bits Pointer to accept value of UART stop bits.
*
* @return
* - ESP_FAIL Parameter error
* - ESP_OK Success, result will be put in (*stop_bit)
*/
esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t* stop_bits);
/**
* @brief Set UART parity mode.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param parity_mode the enum of uart parity configuration
*
* @return
* - ESP_FAIL Parameter error
* - ESP_OK Success
*/
esp_err_t uart_set_parity(uart_port_t uart_num, uart_parity_t parity_mode);
/**
* @brief Get the UART parity mode configuration.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param parity_mode Pointer to accept value of UART parity mode.
*
* @return
* - ESP_FAIL Parameter error
* - ESP_OK Success, result will be put in (*parity_mode)
*
*/
esp_err_t uart_get_parity(uart_port_t uart_num, uart_parity_t* parity_mode);
/**
* @brief Get the frequency of a clock source for the HP UART port
*
* @param sclk Clock source
* @param[out] out_freq_hz Output of frequency, in Hz
*
* @return
* - ESP_ERR_INVALID_ARG: if the clock source is not supported
* - otherwise ESP_OK
*/
esp_err_t uart_get_sclk_freq(uart_sclk_t sclk, uint32_t* out_freq_hz);
/**
* @brief Set UART baud rate.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param baudrate UART baud rate.
*
* @return
* - ESP_FAIL Parameter error
* - ESP_OK Success
*/
esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baudrate);
/**
* @brief Get the UART baud rate configuration.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param baudrate Pointer to accept value of UART baud rate
*
* @return
* - ESP_FAIL Parameter error
* - ESP_OK Success, result will be put in (*baudrate)
*
*/
esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t* baudrate);
/**
* @brief Set UART line inverse mode
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param inverse_mask Choose the wires that need to be inverted. Using the ORred mask of `uart_signal_inv_t`
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_set_line_inverse(uart_port_t uart_num, uint32_t inverse_mask);
/**
* @brief Set hardware flow control.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param flow_ctrl Hardware flow control mode
* @param rx_thresh Threshold of Hardware RX flow control (0 ~ UART_HW_FIFO_LEN(uart_num)).
* Only when UART_HW_FLOWCTRL_RTS is set, will the rx_thresh value be set.
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_set_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t flow_ctrl, uint8_t rx_thresh);
/**
* @brief Set software flow control.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1)
* @param enable switch on or off
* @param rx_thresh_xon low water mark
* @param rx_thresh_xoff high water mark
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_set_sw_flow_ctrl(uart_port_t uart_num, bool enable, uint8_t rx_thresh_xon, uint8_t rx_thresh_xoff);
/**
* @brief Get the UART hardware flow control configuration.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param flow_ctrl Option for different flow control mode.
*
* @return
* - ESP_FAIL Parameter error
* - ESP_OK Success, result will be put in (*flow_ctrl)
*/
esp_err_t uart_get_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t* flow_ctrl);
/**
* @brief Clear UART interrupt status
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param clr_mask Bit mask of the interrupt status to be cleared.
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_clear_intr_status(uart_port_t uart_num, uint32_t clr_mask);
/**
* @brief Set UART interrupt enable
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param enable_mask Bit mask of the enable bits.
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_enable_intr_mask(uart_port_t uart_num, uint32_t enable_mask);
/**
* @brief Clear UART interrupt enable bits
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param disable_mask Bit mask of the disable bits.
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_disable_intr_mask(uart_port_t uart_num, uint32_t disable_mask);
/**
* @brief Enable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_enable_rx_intr(uart_port_t uart_num);
/**
* @brief Disable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_disable_rx_intr(uart_port_t uart_num);
/**
* @brief Disable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)
*
* @param uart_num UART port number
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_disable_tx_intr(uart_port_t uart_num);
/**
* @brief Enable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param enable 1: enable; 0: disable
* @param thresh Threshold of TX interrupt, 0 ~ UART_HW_FIFO_LEN(uart_num)
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_enable_tx_intr(uart_port_t uart_num, int enable, int thresh);
/**
* @brief Assign signals of a UART peripheral to GPIO pins
*
* @note If the GPIO number configured for a UART signal matches one of the
* IOMUX signals for that GPIO, the signal will be connected directly
* via the IOMUX. Otherwise the GPIO and signal will be connected via
* the GPIO Matrix. For example, if on an ESP32 the call
* `uart_set_pin(0, 1, 3, -1, -1)` is performed, as GPIO1 is UART0's
* default TX pin and GPIO3 is UART0's default RX pin, both will be
* connected to respectively U0TXD and U0RXD through the IOMUX, totally
* bypassing the GPIO matrix.
* The check is performed on a per-pin basis. Thus, it is possible to have
* RX pin binded to a GPIO through the GPIO matrix, whereas TX is binded
* to its GPIO through the IOMUX.
*
* @note It is possible to configure TX and RX to share the same IO (single wire mode),
* but please be aware of output conflict, which could damage the pad.
* Apply open-drain and pull-up to the pad ahead of time as a protection,
* or the upper layer protocol must guarantee no output from two ends at the same time.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param tx_io_num UART TX pin GPIO number.
* @param rx_io_num UART RX pin GPIO number.
* @param rts_io_num UART RTS pin GPIO number.
* @param cts_io_num UART CTS pin GPIO number.
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_set_pin(uart_port_t uart_num, int tx_io_num, int rx_io_num, int rts_io_num, int cts_io_num);
/**
* @brief Manually set the UART RTS pin level.
* @note UART must be configured with hardware flow control disabled.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param level 1: RTS output low (active); 0: RTS output high (block)
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_set_rts(uart_port_t uart_num, int level);
/**
* @brief Manually set the UART DTR pin level.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param level 1: DTR output low; 0: DTR output high
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_set_dtr(uart_port_t uart_num, int level);
/**
* @brief Set UART idle interval after tx FIFO is empty
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param idle_num idle interval after tx FIFO is empty(unit: the time it takes to send one bit
* under current baudrate)
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_set_tx_idle_num(uart_port_t uart_num, uint16_t idle_num);
/**
* @brief Set UART configuration parameters.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param uart_config UART parameter settings
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_param_config(uart_port_t uart_num, const uart_config_t *uart_config);
/**
* @brief Configure UART interrupts.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param intr_conf UART interrupt settings
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_intr_config(uart_port_t uart_num, const uart_intr_config_t *intr_conf);
/**
* @brief Wait until UART TX FIFO is empty.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param ticks_to_wait Timeout, count in RTOS ticks
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
* - ESP_ERR_TIMEOUT Timeout
*/
esp_err_t uart_wait_tx_done(uart_port_t uart_num, TickType_t ticks_to_wait);
/**
* @brief Send data to the UART port from a given buffer and length.
*
* This function will not wait for enough space in TX FIFO. It will just fill the available TX FIFO and return when the FIFO is full.
* @note This function should only be used when UART TX buffer is not enabled.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param buffer data buffer address
* @param len data length to send
*
* @return
* - (-1) Parameter error
* - OTHERS (>=0) The number of bytes pushed to the TX FIFO
*/
int uart_tx_chars(uart_port_t uart_num, const char* buffer, uint32_t len);
/**
* @brief Send data to the UART port from a given buffer and length,
*
* If the UART driver's parameter 'tx_buffer_size' is set to zero:
* This function will not return until all the data have been sent out, or at least pushed into TX FIFO.
*
* Otherwise, if the 'tx_buffer_size' > 0, this function will return after copying all the data to tx ring buffer,
* UART ISR will then move data from the ring buffer to TX FIFO gradually.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param src data buffer address
* @param size data length to send
*
* @return
* - (-1) Parameter error
* - OTHERS (>=0) The number of bytes pushed to the TX FIFO
*/
int uart_write_bytes(uart_port_t uart_num, const void* src, size_t size);
/**
* @brief Send data to the UART port from a given buffer and length,
*
* If the UART driver's parameter 'tx_buffer_size' is set to zero:
* This function will not return until all the data and the break signal have been sent out.
* After all data is sent out, send a break signal.
*
* Otherwise, if the 'tx_buffer_size' > 0, this function will return after copying all the data to tx ring buffer,
* UART ISR will then move data from the ring buffer to TX FIFO gradually.
* After all data sent out, send a break signal.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param src data buffer address
* @param size data length to send
* @param brk_len break signal duration(unit: the time it takes to send one bit at current baudrate)
*
* @return
* - (-1) Parameter error
* - OTHERS (>=0) The number of bytes pushed to the TX FIFO
*/
int uart_write_bytes_with_break(uart_port_t uart_num, const void* src, size_t size, int brk_len);
/**
* @brief UART read bytes from UART buffer
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param buf pointer to the buffer.
* @param length data length
* @param ticks_to_wait sTimeout, count in RTOS ticks
*
* @return
* - (-1) Error
* - OTHERS (>=0) The number of bytes read from UART buffer
*/
int uart_read_bytes(uart_port_t uart_num, void* buf, uint32_t length, TickType_t ticks_to_wait);
/**
* @brief Alias of uart_flush_input.
* UART ring buffer flush. This will discard all data in the UART RX buffer.
* @note Instead of waiting the data sent out, this function will clear UART rx buffer.
* In order to send all the data in tx FIFO, we can use uart_wait_tx_done function.
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_flush(uart_port_t uart_num);
/**
* @brief Clear input buffer, discard all the data is in the ring-buffer.
* @note In order to send all the data in tx FIFO, we can use uart_wait_tx_done function.
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_flush_input(uart_port_t uart_num);
/**
* @brief UART get RX ring buffer cached data length
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param size Pointer of size_t to accept cached data length
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_get_buffered_data_len(uart_port_t uart_num, size_t* size);
/**
* @brief UART get TX ring buffer free space size
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param size Pointer of size_t to accept the free space size
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_get_tx_buffer_free_size(uart_port_t uart_num, size_t *size);
/**
* @brief UART disable pattern detect function.
* Designed for applications like 'AT commands'.
* When the hardware detects a series of one same character, the interrupt will be triggered.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_disable_pattern_det_intr(uart_port_t uart_num);
/**
* @brief UART enable pattern detect function.
* Designed for applications like 'AT commands'.
* When the hardware detect a series of one same character, the interrupt will be triggered.
*
* @param uart_num UART port number.
* @param pattern_chr character of the pattern.
* @param chr_num number of the character, 8bit value.
* @param chr_tout timeout of the interval between each pattern characters, 16bit value, unit is the baud-rate cycle you configured.
* When the duration is more than this value, it will not take this data as at_cmd char.
* @param post_idle idle time after the last pattern character, 16bit value, unit is the baud-rate cycle you configured.
* When the duration is less than this value, it will not take the previous data as the last at_cmd char
* @param pre_idle idle time before the first pattern character, 16bit value, unit is the baud-rate cycle you configured.
* When the duration is less than this value, it will not take this data as the first at_cmd char.
*
* @return
* - ESP_OK Success
* - ESP_FAIL Parameter error
*/
esp_err_t uart_enable_pattern_det_baud_intr(uart_port_t uart_num, char pattern_chr, uint8_t chr_num, int chr_tout, int post_idle, int pre_idle);
/**
* @brief Return the nearest detected pattern position in buffer.
* The positions of the detected pattern are saved in a queue,
* this function will dequeue the first pattern position and move the pointer to next pattern position.
* @note If the RX buffer is full and flow control is not enabled,
* the detected pattern may not be found in the rx buffer due to overflow.
*
* The following APIs will modify the pattern position info:
* uart_flush_input, uart_read_bytes, uart_driver_delete, uart_pop_pattern_pos
* It is the application's responsibility to ensure atomic access to the pattern queue and the rx data buffer
* when using pattern detect feature.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @return
* - (-1) No pattern found for current index or parameter error
* - others the pattern position in rx buffer.
*/
int uart_pattern_pop_pos(uart_port_t uart_num);
/**
* @brief Return the nearest detected pattern position in buffer.
* The positions of the detected pattern are saved in a queue,
* This function do nothing to the queue.
* @note If the RX buffer is full and flow control is not enabled,
* the detected pattern may not be found in the rx buffer due to overflow.
*
* The following APIs will modify the pattern position info:
* uart_flush_input, uart_read_bytes, uart_driver_delete, uart_pop_pattern_pos
* It is the application's responsibility to ensure atomic access to the pattern queue and the rx data buffer
* when using pattern detect feature.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @return
* - (-1) No pattern found for current index or parameter error
* - others the pattern position in rx buffer.
*/
int uart_pattern_get_pos(uart_port_t uart_num);
/**
* @brief Allocate a new memory with the given length to save record the detected pattern position in rx buffer.
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1).
* @param queue_length Max queue length for the detected pattern.
* If the queue length is not large enough, some pattern positions might be lost.
* Set this value to the maximum number of patterns that could be saved in data buffer at the same time.
* @return
* - ESP_ERR_NO_MEM No enough memory
* - ESP_ERR_INVALID_STATE Driver not installed
* - ESP_FAIL Parameter error
* - ESP_OK Success
*/
esp_err_t uart_pattern_queue_reset(uart_port_t uart_num, int queue_length);
/**
* @brief UART set communication mode
*
* @note This function must be executed after uart_driver_install(), when the driver object is initialized.
* @param uart_num Uart number to configure, the max port number is (UART_NUM_MAX -1).
* @param mode UART UART mode to set
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_set_mode(uart_port_t uart_num, uart_mode_t mode);
/**
* @brief Set uart threshold value for RX fifo full
* @note If application is using higher baudrate and it is observed that bytes
* in hardware RX fifo are overwritten then this threshold can be reduced
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1)
* @param threshold Threshold value above which RX fifo full interrupt is generated
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_INVALID_STATE Driver is not installed
*/
esp_err_t uart_set_rx_full_threshold(uart_port_t uart_num, int threshold);
/**
* @brief Set uart threshold values for TX fifo empty
*
* @param uart_num UART port number, the max port number is (UART_NUM_MAX -1)
* @param threshold Threshold value below which TX fifo empty interrupt is generated
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_INVALID_STATE Driver is not installed
*/
esp_err_t uart_set_tx_empty_threshold(uart_port_t uart_num, int threshold);
/**
* @brief UART set threshold timeout for TOUT feature
*
* @param uart_num Uart number to configure, the max port number is (UART_NUM_MAX -1).
* @param tout_thresh This parameter defines timeout threshold in uart symbol periods. The maximum value of threshold is 126.
* tout_thresh = 1, defines TOUT interrupt timeout equal to transmission time of one symbol (~11 bit) on current baudrate.
* If the time is expired the UART_RXFIFO_TOUT_INT interrupt is triggered. If tout_thresh == 0,
* the TOUT feature is disabled.
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_ERR_INVALID_STATE Driver is not installed
*/
esp_err_t uart_set_rx_timeout(uart_port_t uart_num, const uint8_t tout_thresh);
/**
* @brief Returns collision detection flag for RS485 mode
* Function returns the collision detection flag into variable pointed by collision_flag.
* *collision_flag = true, if collision detected else it is equal to false.
* This function should be executed when actual transmission is completed (after uart_write_bytes()).
*
* @param uart_num Uart number to configure the max port number is (UART_NUM_MAX -1).
* @param collision_flag Pointer to variable of type bool to return collision flag.
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_get_collision_flag(uart_port_t uart_num, bool* collision_flag);
/**
* @brief Set the number of RX pin signal edges for light sleep wakeup
*
* UART can be used to wake up the system from light sleep. This feature works
* by counting the number of positive edges on RX pin and comparing the count to
* the threshold. When the count exceeds the threshold, system is woken up from
* light sleep. This function allows setting the threshold value.
*
* Stop bit and parity bits (if enabled) also contribute to the number of edges.
* For example, letter 'a' with ASCII code 97 is encoded as 0100001101 on the wire
* (with 8n1 configuration), start and stop bits included. This sequence has 3
* positive edges (transitions from 0 to 1). Therefore, to wake up the system
* when 'a' is sent, set wakeup_threshold=3.
*
* The character that triggers wakeup is not received by UART (i.e. it can not
* be obtained from UART FIFO). Depending on the baud rate, a few characters
* after that will also not be received. Note that when the chip enters and exits
* light sleep mode, APB frequency will be changing. To ensure that UART has
* correct Baud rate all the time, it is necessary to select a source clock which has
* a fixed frequency and remains active during sleep. For the supported clock sources
* of the chips, please refer to `uart_sclk_t` or `soc_periph_uart_clk_src_legacy_t`
*
* @note in ESP32, the wakeup signal can only be input via IO_MUX (i.e.
* GPIO3 should be configured as function_1 to wake up UART0,
* GPIO9 should be configured as function_5 to wake up UART1), UART2
* does not support light sleep wakeup feature.
*
* @param uart_num UART number, the max port number is (UART_NUM_MAX -1).
* @param wakeup_threshold number of RX edges for light sleep wakeup, value is 3 .. 0x3ff.
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if uart_num is incorrect or wakeup_threshold is
* outside of [3, 0x3ff] range.
*/
esp_err_t uart_set_wakeup_threshold(uart_port_t uart_num, int wakeup_threshold);
/**
* @brief Get the number of RX pin signal edges for light sleep wakeup.
*
* See description of uart_set_wakeup_threshold for the explanation of UART
* wakeup feature.
*
* @param uart_num UART number, the max port number is (UART_NUM_MAX -1).
* @param[out] out_wakeup_threshold output, set to the current value of wakeup
* threshold for the given UART.
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG if out_wakeup_threshold is NULL
*/
esp_err_t uart_get_wakeup_threshold(uart_port_t uart_num, int* out_wakeup_threshold);
/**
* @brief Wait until UART tx memory empty and the last char send ok (polling mode).
*
* @param uart_num UART number
*
* * @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_FAIL Driver not installed
*/
esp_err_t uart_wait_tx_idle_polling(uart_port_t uart_num);
/**
* @brief Configure TX signal loop back to RX module, just for the test usage.
*
* @param uart_num UART number
* @param loop_back_en Set true to enable the loop back function, else set it false.
*
* * @return
* - ESP_OK on success
* - ESP_ERR_INVALID_ARG Parameter error
* - ESP_FAIL Driver not installed
*/
esp_err_t uart_set_loop_back(uart_port_t uart_num, bool loop_back_en);
/**
* @brief Configure behavior of UART RX timeout interrupt.
*
* When always_rx_timeout is true, timeout interrupt is triggered even if FIFO is full.
* This function can cause extra timeout interrupts triggered only to send the timeout event.
* Call this function only if you want to ensure timeout interrupt will always happen after a byte stream.
*
* @param uart_num UART number
* @param always_rx_timeout_en Set to false enable the default behavior of timeout interrupt,
* set it to true to always trigger timeout interrupt.
*
*/
void uart_set_always_rx_timeout(uart_port_t uart_num, bool always_rx_timeout_en);
#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.