Esp8266/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 
51 #define UART0 0
52 #define UART1 1
53 #define UART2 2
54 #define UART_NO -1
55 #define UART_PHYSICAL_COUNT 2
56 #define UART_COUNT 3
57 
58 // Options for `config` argument of uart_init
59 #define UART_NB_BIT_MASK 0B00001100
60 #define UART_NB_BIT_5 0B00000000
61 #define UART_NB_BIT_6 0B00000100
62 #define UART_NB_BIT_7 0B00001000
63 #define UART_NB_BIT_8 0B00001100
64 
65 #define UART_PARITY_MASK 0B00000011
66 #define UART_PARITY_NONE 0B00000000
67 #define UART_PARITY_EVEN 0B00000010
68 #define UART_PARITY_ODD 0B00000011
69 
70 #define UART_NB_STOP_BIT_MASK 0B00110000
71 #define UART_NB_STOP_BIT_0 0B00000000
72 #define UART_NB_STOP_BIT_1 0B00010000
73 #define UART_NB_STOP_BIT_15 0B00100000
74 #define UART_NB_STOP_BIT_2 0B00110000
75 
76 #define UART_5N1 ( UART_NB_BIT_5 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
77 #define UART_6N1 ( UART_NB_BIT_6 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
78 #define UART_7N1 ( UART_NB_BIT_7 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
79 #define UART_8N1 ( UART_NB_BIT_8 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
80 #define UART_5N2 ( UART_NB_BIT_5 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
81 #define UART_6N2 ( UART_NB_BIT_6 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
82 #define UART_7N2 ( UART_NB_BIT_7 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
83 #define UART_8N2 ( UART_NB_BIT_8 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
84 #define UART_5E1 ( UART_NB_BIT_5 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
85 #define UART_6E1 ( UART_NB_BIT_6 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
86 #define UART_7E1 ( UART_NB_BIT_7 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
87 #define UART_8E1 ( UART_NB_BIT_8 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
88 #define UART_5E2 ( UART_NB_BIT_5 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
89 #define UART_6E2 ( UART_NB_BIT_6 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
90 #define UART_7E2 ( UART_NB_BIT_7 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
91 #define UART_8E2 ( UART_NB_BIT_8 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
92 #define UART_5O1 ( UART_NB_BIT_5 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
93 #define UART_6O1 ( UART_NB_BIT_6 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
94 #define UART_7O1 ( UART_NB_BIT_7 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
95 #define UART_8O1 ( UART_NB_BIT_8 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
96 #define UART_5O2 ( UART_NB_BIT_5 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
97 #define UART_6O2 ( UART_NB_BIT_6 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
98 #define UART_7O2 ( UART_NB_BIT_7 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
99 #define UART_8O2 ( UART_NB_BIT_8 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
100 
106 };
108 
109 typedef uint8_t uart_options_t;
116 };
117 
118 #define UART_RX_FIFO_SIZE 0x80
119 #define UART_TX_FIFO_SIZE 0x80
120 
121 struct smg_uart_;
122 typedef struct smg_uart_ smg_uart_t;
123 
135 typedef void (*smg_uart_callback_t)(smg_uart_t* uart, uint32_t status);
136 
137 
138 /*
139  * Port notifications
140  */
141 
147 
150 
153 
156 
159 };
160 
166 
173 
174 
175 struct SerialBuffer;
176 
177 struct smg_uart_ {
178  uint8_t uart_nr;
179  uint32_t baud_rate;
180  smg_uart_mode_t mode;
181  uint8_t options;
182  uint8_t rx_pin;
183  uint8_t tx_pin;
184  uint8_t rx_headroom;
186  struct SerialBuffer* rx_buffer;
187  struct SerialBuffer* tx_buffer;
189  void* param;
190 };
191 
192 
194  uint8_t uart_nr;
195  uint8_t tx_pin;
196  smg_uart_mode_t mode;
197  uart_options_t options;
198  uint32_t baudrate;
199  uint32_t config;
200  size_t rx_size;
201  size_t tx_size;
202 };
203 
204 // @deprecated Use `uart_init_ex()` instead
205 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);
206 
208 
209 void smg_uart_uninit(smg_uart_t* uart);
210 
212 {
213  return uart ? uart->uart_nr : -1;
214 }
215 
221 
228 
234 {
235  return uart ? uart->param : nullptr;
236 }
237 
242 static inline void smg_uart_set_options(smg_uart_t* uart, uart_options_t options)
243 {
244  if (uart)
245  uart->options = options;
246 }
247 
259 uint8_t IRAM_ATTR smg_uart_get_status(smg_uart_t* uart);
260 
261 static inline uart_options_t smg_uart_get_options(smg_uart_t* uart)
262 {
263  return uart ? uart->options : 0;
264 }
265 
266 void smg_uart_swap(smg_uart_t* uart, int tx_pin);
267 void smg_uart_set_tx(smg_uart_t* uart, int tx_pin);
268 void smg_uart_set_pins(smg_uart_t* uart, int tx, int rx);
269 
271 {
272  return uart && uart->mode != UART_RX_ONLY;
273 }
274 
276 {
277  return uart && uart->mode != UART_TX_ONLY;
278 }
279 
285 uint32_t smg_uart_set_baudrate_reg(int uart_nr, uint32_t baud_rate);
286 
292 uint32_t smg_uart_set_baudrate(smg_uart_t* uart, uint32_t baud_rate);
293 
298 uint32_t smg_uart_get_baudrate(smg_uart_t* uart);
299 
300 size_t smg_uart_resize_rx_buffer(smg_uart_t* uart, size_t new_size);
301 size_t smg_uart_rx_buffer_size(smg_uart_t* uart);
302 size_t smg_uart_resize_tx_buffer(smg_uart_t* uart, size_t new_size);
303 size_t smg_uart_tx_buffer_size(smg_uart_t* uart);
304 
305 
312 size_t smg_uart_write(smg_uart_t* uart, const void* buffer, size_t size);
313 
319 static inline size_t smg_uart_write_char(smg_uart_t* uart, char c)
320 {
321  return smg_uart_write(uart, &c, 1);
322 }
323 
330 size_t smg_uart_read(smg_uart_t* uart, void* buffer, size_t size);
331 
336 static inline int smg_uart_read_char(smg_uart_t* uart)
337 {
338  char c;
339  return smg_uart_read(uart, &c, 1) ? c : -1;
340 }
341 
348 int smg_uart_peek_char(smg_uart_t* uart);
349 
357 
358 /*
359  * @brief Find a character in the receive buffer
360  * @param uart
361  * @param char c character to search for
362  * @retval size_t position relative to start of buffer, -1 if not found
363  */
364 int smg_uart_rx_find(smg_uart_t* uart, char c);
365 
371 size_t smg_uart_rx_available(smg_uart_t* uart);
372 
374 size_t smg_uart_tx_free(smg_uart_t* uart);
375 
378 
383 void smg_uart_set_break(smg_uart_t* uart, bool state);
384 
390 void smg_uart_flush(smg_uart_t* uart, smg_uart_mode_t mode = UART_FULL);
391 
392 void smg_uart_set_debug(int uart_nr);
393 int smg_uart_get_debug();
394 
398 void smg_uart_start_isr(smg_uart_t* uart);
399 
404 {
405  extern void smg_uart_detach(int);
406  if (uart != nullptr) {
407  smg_uart_detach(uart->uart_nr);
408  }
409 }
410 
414 void smg_uart_detach(int uart_nr);
415 
419 void smg_uart_detach_all();
420 
421 
426 
430 
433 #if defined (__cplusplus)
434 } // extern "C"
435 #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: Esp8266/Components/driver/include/driver/uart.h:103
Called to ensure all buffered data is output.
Definition: Esp8266/Components/driver/include/driver/uart.h:158
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
Called immediately before uart is closed and destroyed.
Definition: Esp8266/Components/driver/include/driver/uart.h:149
Definition: Esp8266/Components/driver/include/driver/uart.h:193
size_t rx_size
Definition: Esp8266/Components/driver/include/driver/uart.h:200
bool smg_uart_set_notify(unsigned uart_nr, smg_uart_notify_callback_t callback)
Set the notification callback function.
Called when uart has been initialised successfully.
Definition: Esp8266/Components/driver/include/driver/uart.h:146
static void smg_uart_set_options(smg_uart_t *uart, uart_options_t options)
Set option flags.
Definition: Esp8266/Components/driver/include/driver/uart.h:242
uart_options_t options
Definition: Esp8266/Components/driver/include/driver/uart.h:197
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
smg_uart_mode_t mode
Whether to enable receive, transmit or both.
Definition: Esp8266/Components/driver/include/driver/uart.h:196
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
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: Esp8266/Components/driver/include/driver/uart.h:107
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)
uint8_t uart_nr
Definition: Esp8266/Components/driver/include/driver/uart.h:194
size_t smg_uart_rx_available(smg_uart_t *uart)
determine available data which can be read
int smg_uart_get_debug()
static uart_options_t smg_uart_get_options(smg_uart_t *uart)
Definition: Esp8266/Components/driver/include/driver/uart.h:261
size_t smg_uart_rx_buffer_size(smg_uart_t *uart)
uint32_t baud_rate
Definition: Esp8266/Components/driver/include/driver/uart.h:179
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)
uint8_t tx_pin
Specify 2 for alternate pin, otherwise defaults to pin 1.
Definition: Esp8266/Components/driver/include/driver/uart.h:195
void(* smg_uart_notify_callback_t)(smg_uart_t *uart, smg_uart_notify_code_t code)
Port notification callback function type.
Definition: Esp8266/Components/driver/include/driver/uart.h:165
ISR invokes user callback function with no pre-processing.
Definition: Esp8266/Components/driver/include/driver/uart.h:115
void(* smg_uart_callback_t)(smg_uart_t *uart, uint32_t status)
callback invoked directly from ISR
Definition: Esp8266/Components/driver/include/driver/uart.h:135
Called before data is read from rx buffer.
Definition: Esp8266/Components/driver/include/driver/uart.h:155
void smg_uart_set_debug(int uart_nr)
size_t tx_size
Definition: Esp8266/Components/driver/include/driver/uart.h:201
void smg_uart_stop_isr(smg_uart_t *uart)
disable interrupts for a UART
Definition: Esp8266/Components/driver/include/driver/uart.h:403
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
void smg_uart_detach(int uart_nr)
detach a UART interrupt service routine
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)
static int smg_uart_read_char(smg_uart_t *uart)
read a received character
Definition: Esp8266/Components/driver/include/driver/uart.h:336
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: Esp8266/Components/driver/include/driver/uart.h:114
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: Esp8266/Components/driver/include/driver/uart.h:152
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
void smg_uart_detach_all()
detach all UART interrupt service routines
size_t smg_uart_resize_tx_buffer(smg_uart_t *uart, size_t new_size)
Transmit only.
Definition: Esp8266/Components/driver/include/driver/uart.h:105
uint32_t config
UART CONF0 register bits.
Definition: Esp8266/Components/driver/include/driver/uart.h:199
Receive only.
Definition: Esp8266/Components/driver/include/driver/uart.h:104
uint8_t uart_options_t
Definition: Esp8266/Components/driver/include/driver/uart.h:109
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.
uint32_t baudrate
Requested baudrate; actual baudrate may differ.
Definition: Esp8266/Components/driver/include/driver/uart.h:198
void smg_uart_start_isr(smg_uart_t *uart)
enable interrupts for a UART
static size_t smg_uart_write_char(smg_uart_t *uart, char c)
queue a single character for output
Definition: Esp8266/Components/driver/include/driver/uart.h:319