Esp32/Components/driver/include/driver/uart.h
Go to the documentation of this file.
1 /*
2  uart.h - UART HAL
3 
4  Copyright (c) 2014 Ivan Grokhotkov. All rights reserved.
5  This file is part of the esp8266 core for Arduino environment.
6 
7  This library is free software; you can redistribute it and/or
8  modify it under the terms of the GNU Lesser General Public
9  License as published by the Free Software Foundation; either
10  version 2.1 of the License, or (at your option) any later version.
11 
12  This library is distributed in the hope that it will be useful,
13  but WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  Lesser General Public License for more details.
16 
17  You should have received a copy of the GNU Lesser General Public
18  License along with this library; if not, write to the Free Software
19  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 
21 */
22 
23 /*
24  * @author 21/8/2018 mikee47 <mike@sillyhouse.net>
25  *
26  * SerialBuffer class added to manage FIFO for both RX and TX
27  * Buffering is optional; if size is 0 will just use Hardware FIFOS (128 bytes each)
28  * For uart_write_xxx functions, if there is no space in the tx FIFO it will return a short count. It will not wait.
29  * Trivial check routines have been moved into this header as static inlines.
30  * Code is now C++ only; reference to this header has been removed from esp_systemapi.h uart structure should be
31  * treated as opaque and only accessed using the functions defined in this header.
32  * Callback is invoked on transmit completion.
33  *
34  * Note: uart_detach_all() should be called at startup, i.e. from user_init().
35  */
36 
37 #pragma once
38 
39 #if defined (__cplusplus)
40 extern "C" {
41 #endif
42 
43 #include <esp_systemapi.h>
44 #include_next <driver/uart.h>
45 
52 #define UART0 0
53 #define UART1 1
54 #define UART2 2
55 #define UART_NO -1
56 #define UART_PHYSICAL_COUNT UART_NUM_MAX
57 #define UART_COUNT UART_NUM_MAX
58 
59 // Options for `config` argument of uart_init
60 #define UART_NB_BIT_MASK 0B00001100
61 #define UART_NB_BIT_5 0B00000000
62 #define UART_NB_BIT_6 0B00000100
63 #define UART_NB_BIT_7 0B00001000
64 #define UART_NB_BIT_8 0B00001100
65 
66 #define UART_PARITY_MASK 0B00000011
67 #define UART_PARITY_NONE 0B00000000
68 #define UART_PARITY_EVEN 0B00000010
69 #define UART_PARITY_ODD 0B00000011
70 
71 #define UART_NB_STOP_BIT_MASK 0B00110000
72 #define UART_NB_STOP_BIT_0 0B00000000
73 #define UART_NB_STOP_BIT_1 0B00010000
74 #define UART_NB_STOP_BIT_15 0B00100000
75 #define UART_NB_STOP_BIT_2 0B00110000
76 
77 #define UART_5N1 ( UART_NB_BIT_5 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
78 #define UART_6N1 ( UART_NB_BIT_6 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
79 #define UART_7N1 ( UART_NB_BIT_7 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
80 #define UART_8N1 ( UART_NB_BIT_8 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
81 #define UART_5N2 ( UART_NB_BIT_5 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
82 #define UART_6N2 ( UART_NB_BIT_6 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
83 #define UART_7N2 ( UART_NB_BIT_7 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
84 #define UART_8N2 ( UART_NB_BIT_8 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
85 #define UART_5E1 ( UART_NB_BIT_5 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
86 #define UART_6E1 ( UART_NB_BIT_6 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
87 #define UART_7E1 ( UART_NB_BIT_7 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
88 #define UART_8E1 ( UART_NB_BIT_8 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
89 #define UART_5E2 ( UART_NB_BIT_5 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
90 #define UART_6E2 ( UART_NB_BIT_6 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
91 #define UART_7E2 ( UART_NB_BIT_7 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
92 #define UART_8E2 ( UART_NB_BIT_8 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
93 #define UART_5O1 ( UART_NB_BIT_5 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
94 #define UART_6O1 ( UART_NB_BIT_6 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
95 #define UART_7O1 ( UART_NB_BIT_7 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
96 #define UART_8O1 ( UART_NB_BIT_8 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
97 #define UART_5O2 ( UART_NB_BIT_5 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
98 #define UART_6O2 ( UART_NB_BIT_6 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
99 #define UART_7O2 ( UART_NB_BIT_7 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
100 #define UART_8O2 ( UART_NB_BIT_8 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
101 
107 };
109 
110 typedef uint8_t uart_options_t;
117 };
118 
119 #define UART_RX_FIFO_SIZE 0x80
120 #define UART_TX_FIFO_SIZE 0x80
121 
122 struct smg_uart_;
123 typedef struct smg_uart_ smg_uart_t;
124 
136 typedef void (*smg_uart_callback_t)(smg_uart_t* uart, uint32_t status);
137 
138 
139 /*
140  * Port notifications
141  */
142 
148 
151 
154 
157 
160 };
161 
167 
174 
175 
176 struct SerialBuffer;
177 
178 struct smg_uart_ {
179  uart_port_t uart_nr;
180  uint32_t baud_rate;
181  smg_uart_mode_t mode;
182  uint8_t options;
183  uint8_t rx_pin;
184  uint8_t tx_pin;
185  uint8_t rx_headroom;
186  uint16_t status;
187  struct SerialBuffer* rx_buffer;
188  struct SerialBuffer* tx_buffer;
190  void* param;
191 };
192 
193 
194 struct smg_uart_config {
195  uint8_t uart_nr;
196  uint8_t tx_pin;
197  uint8_t rx_pin;
198  smg_uart_mode_t mode;
199  uart_options_t options;
200  uint32_t baudrate;
201  uint32_t config;
202  size_t rx_size;
203  size_t tx_size;
204 };
205 
206 // @deprecated Use `uart_init_ex()` instead
207 smg_uart_t* smg_uart_init(uint8_t uart_nr, uint32_t baudrate, uint32_t config, smg_uart_mode_t mode, uint8_t tx_pin, size_t rx_size, size_t tx_size = 0);
208 
210 
211 void smg_uart_uninit(smg_uart_t* uart);
212 
214 {
215  return uart ? uart->uart_nr : -1;
216 }
217 
223 
230 
236 {
237  return uart ? uart->param : nullptr;
238 }
239 
244 static inline void smg_uart_set_options(smg_uart_t* uart, uart_options_t options)
245 {
246  if (uart)
247  uart->options = options;
248 }
249 
261 uint8_t IRAM_ATTR smg_uart_get_status(smg_uart_t* uart);
262 
263 static inline uart_options_t smg_uart_get_options(smg_uart_t* uart)
264 {
265  return uart ? uart->options : 0;
266 }
267 
268 void smg_uart_set_tx(smg_uart_t* uart, int tx_pin);
269 void smg_uart_set_pins(smg_uart_t* uart, int tx, int rx);
270 void smg_uart_swap(smg_uart_t* uart, int tx_pin);
271 
273 {
274  return uart && uart->mode != UART_RX_ONLY;
275 }
276 
278 {
279  return uart && uart->mode != UART_TX_ONLY;
280 }
281 
287 uint32_t smg_uart_set_baudrate_reg(int uart_nr, uint32_t baud_rate);
288 
294 uint32_t smg_uart_set_baudrate(smg_uart_t* uart, uint32_t baud_rate);
295 
300 uint32_t smg_uart_get_baudrate(smg_uart_t* uart);
301 
302 size_t smg_uart_resize_rx_buffer(smg_uart_t* uart, size_t new_size);
303 size_t smg_uart_rx_buffer_size(smg_uart_t* uart);
304 size_t smg_uart_resize_tx_buffer(smg_uart_t* uart, size_t new_size);
305 size_t smg_uart_tx_buffer_size(smg_uart_t* uart);
306 
307 
314 size_t smg_uart_write(smg_uart_t* uart, const void* buffer, size_t size);
315 
321 static inline size_t smg_uart_write_char(smg_uart_t* uart, char c)
322 {
323  return smg_uart_write(uart, &c, 1);
324 }
325 
332 size_t smg_uart_read(smg_uart_t* uart, void* buffer, size_t size);
333 
338 static inline int smg_uart_read_char(smg_uart_t* uart)
339 {
340  char c;
341  return smg_uart_read(uart, &c, 1) ? c : -1;
342 }
343 
350 int smg_uart_peek_char(smg_uart_t* uart);
351 
359 
360 /*
361  * @brief Find a character in the receive buffer
362  * @param uart
363  * @param char c character to search for
364  * @retval size_t position relative to start of buffer, -1 if not found
365  */
366 int smg_uart_rx_find(smg_uart_t* uart, char c);
367 
373 size_t smg_uart_rx_available(smg_uart_t* uart);
374 
376 size_t smg_uart_tx_free(smg_uart_t* uart);
377 
380 
385 void smg_uart_set_break(smg_uart_t* uart, bool state);
386 
392 void smg_uart_flush(smg_uart_t* uart, smg_uart_mode_t mode = UART_FULL);
393 
396 
397 void smg_uart_set_debug(int uart_nr);
398 int smg_uart_get_debug();
399 
404 
408 
411 #if defined (__cplusplus)
412 } // extern "C"
413 #endif
struct SerialBuffer * rx_buffer
Optional receive buffer.
Definition: Esp8266/Components/driver/include/driver/uart.h:186
smg_uart_t * smg_uart_init_ex(const smg_uart_config &cfg)
Both receive and transmit - will revert to TX only if RX not supported.
Definition: Esp32/Components/driver/include/driver/uart.h:104
Called to ensure all buffered data is output.
Definition: Esp32/Components/driver/include/driver/uart.h:159
static int smg_uart_read_char(smg_uart_t *uart)
read a received character
Definition: Esp32/Components/driver/include/driver/uart.h:338
uint8_t rx_headroom
Callback when rx_buffer free space <= headroom.
Definition: Esp8266/Components/driver/include/driver/uart.h:184
smg_uart_t * smg_uart_init(uint8_t uart_nr, uint32_t baudrate, uint32_t config, smg_uart_mode_t mode, uint8_t tx_pin, size_t rx_size, size_t tx_size=0)
uint8_t rx_pin
Definition: Esp8266/Components/driver/include/driver/uart.h:182
uint8_t uart_nr
Definition: Esp8266/Components/driver/include/driver/uart.h:178
#define __forceinline
Definition: sming_attr.h:13
void smg_uart_swap(smg_uart_t *uart, int tx_pin)
int smg_uart_peek_last_char(smg_uart_t *uart)
fetch last character read out of FIFO
uart_port_t uart_nr
Definition: Esp32/Components/driver/include/driver/uart.h:179
Called immediately before uart is closed and destroyed.
Definition: Esp32/Components/driver/include/driver/uart.h:150
Definition: Esp8266/Components/driver/include/driver/uart.h:193
bool smg_uart_set_notify(unsigned uart_nr, smg_uart_notify_callback_t callback)
Set the notification callback function.
Called when uart has been iniitialised successfully.
Definition: Esp32/Components/driver/include/driver/uart.h:147
uint16_t status
All status flags reported to callback since last uart_get_status() call.
Definition: Esp8266/Components/driver/include/driver/uart.h:185
smg_uart_option_bits_t
bit values for options argument of uart_init
Definition: Esp8266/Components/driver/include/driver/uart.h:113
bool smg_uart_tx_enabled(smg_uart_t *uart)
Definition: Esp8266/Components/driver/include/driver/uart.h:270
uint8_t smg_uart_disable_interrupts()
disable interrupts and return current interrupt state
void smg_uart_flush(smg_uart_t *uart, smg_uart_mode_t mode=UART_FULL)
discard any buffered data and reset hardware FIFOs
uint8_t rx_pin
Definition: Esp32/Components/driver/include/driver/uart.h:197
void * param
User-supplied callback parameter.
Definition: Esp8266/Components/driver/include/driver/uart.h:189
uint32_t smg_uart_set_baudrate(smg_uart_t *uart, uint32_t baud_rate)
set UART baud rate
void smg_uart_set_pins(smg_uart_t *uart, int tx, int rx)
smg_uart_t * smg_uart_get_uart(uint8_t uart_nr)
Get the uart structure for the given number.
enum smg_uart_mode_ smg_uart_mode_t
Definition: Esp32/Components/driver/include/driver/uart.h:108
uint8_t smg_uart_get_status(smg_uart_t *uart)
Get error flags and clear them.
Definition: Esp8266/Components/driver/include/driver/uart.h:177
void smg_uart_wait_tx_empty(smg_uart_t *uart)
static size_t smg_uart_write_char(smg_uart_t *uart, char c)
queue a single character for output
Definition: Esp32/Components/driver/include/driver/uart.h:321
size_t smg_uart_rx_available(smg_uart_t *uart)
determine available data which can be read
int smg_uart_get_debug()
size_t smg_uart_rx_buffer_size(smg_uart_t *uart)
uint32_t baud_rate
Definition: Esp8266/Components/driver/include/driver/uart.h:179
static void smg_uart_set_options(smg_uart_t *uart, uart_options_t options)
Set option flags.
Definition: Esp32/Components/driver/include/driver/uart.h:244
void smg_uart_restore_interrupts()
re-enable interrupts after calling uart_disable_interrupts()
size_t smg_uart_resize_rx_buffer(smg_uart_t *uart, size_t new_size)
void(* smg_uart_notify_callback_t)(smg_uart_t *uart, smg_uart_notify_code_t code)
Port notification callback function type.
Definition: Esp32/Components/driver/include/driver/uart.h:166
ISR invokes user callback function with no pre-processing.
Definition: Esp32/Components/driver/include/driver/uart.h:116
void(* smg_uart_callback_t)(smg_uart_t *uart, uint32_t status)
callback invoked directly from ISR
Definition: Esp32/Components/driver/include/driver/uart.h:136
Called before data is read from rx buffer.
Definition: Esp32/Components/driver/include/driver/uart.h:156
void smg_uart_set_debug(int uart_nr)
struct SerialBuffer * tx_buffer
Optional transmit buffer.
Definition: Esp8266/Components/driver/include/driver/uart.h:187
int smg_uart_rx_find(smg_uart_t *uart, char c)
smg_uart_notify_code_t
Indicates notification, parameters refer to uart_notify_info_t structure.
Definition: Esp8266/Components/driver/include/driver/uart.h:144
size_t smg_uart_tx_free(smg_uart_t *uart)
return free space in transmit buffer
uint8_t options
Definition: Esp8266/Components/driver/include/driver/uart.h:181
int smg_uart_peek_char(smg_uart_t *uart)
see what the next character in the rx buffer is
size_t smg_uart_tx_buffer_size(smg_uart_t *uart)
void smg_uart_set_tx(smg_uart_t *uart, int tx_pin)
uint8_t tx_pin
Definition: Esp8266/Components/driver/include/driver/uart.h:183
void smg_uart_uninit(smg_uart_t *uart)
smg_uart_mode_t mode
Definition: Esp8266/Components/driver/include/driver/uart.h:180
void smg_uart_set_break(smg_uart_t *uart, bool state)
Set or clear a break condition on the TX line.
size_t smg_uart_write(smg_uart_t *uart, const void *buffer, size_t size)
write a block of data
size_t smg_uart_read(smg_uart_t *uart, void *buffer, size_t size)
read a block of data
If buffers are full then uart_write() will wait for free space.
Definition: Esp32/Components/driver/include/driver/uart.h:115
int smg_uart_get_nr(smg_uart_t *uart)
Definition: Esp8266/Components/driver/include/driver/uart.h:211
Called after data has been written into tx buffer.
Definition: Esp32/Components/driver/include/driver/uart.h:153
smg_uart_callback_t callback
Optional User callback routine.
Definition: Esp8266/Components/driver/include/driver/uart.h:188
bool smg_uart_rx_enabled(smg_uart_t *uart)
Definition: Esp8266/Components/driver/include/driver/uart.h:275
smg_uart_mode_
values for mode argument of uart_init
Definition: Esp8266/Components/driver/include/driver/uart.h:102
void * smg_uart_get_callback_param(smg_uart_t *uart)
Get the callback parameter specified by uart_set_callback()
Definition: Esp8266/Components/driver/include/driver/uart.h:233
uint32_t smg_uart_get_baudrate(smg_uart_t *uart)
get the actual baud rate in use
size_t smg_uart_resize_tx_buffer(smg_uart_t *uart, size_t new_size)
Transmit only.
Definition: Esp32/Components/driver/include/driver/uart.h:106
Receive only.
Definition: Esp32/Components/driver/include/driver/uart.h:105
uint8_t uart_options_t
Definition: Esp32/Components/driver/include/driver/uart.h:110
uint32_t smg_uart_set_baudrate_reg(int uart_nr, uint32_t baud_rate)
set UART baud rate, given the UART number
void smg_uart_set_callback(smg_uart_t *uart, smg_uart_callback_t callback, void *param)
Set callback handler for serial port.
static uart_options_t smg_uart_get_options(smg_uart_t *uart)
Definition: Esp32/Components/driver/include/driver/uart.h:263