HardwareSerial.h
Go to the documentation of this file.
1 /****
2  * Sming Framework Project - Open Source framework for high efficiency native ESP8266 development.
3  * Created 2015 by Skurydin Alexey
4  * http://github.com/SmingHub/Sming
5  * All files of the Sming Core are provided under the LGPL v3 license.
6  *
7  * HardwareSerial.h
8  *
9  ****/
10 
16 #pragma once
17 
18 #include <cstdint>
19 #include <Delegate.h>
21 #include <BitManipulations.h>
22 #include <driver/uart.h>
23 
24 #define UART_ID_0 0
25 #define UART_ID_1 1
26 
27 #define NUMBER_UARTS UART_COUNT
28 
29 #define SERIAL_PIN_DEFAULT UART_PIN_DEFAULT
30 
31 class HardwareSerial;
32 
46 using StreamDataReceivedDelegate = Delegate<void(Stream& source, char arrivedChar, uint16_t availableCharsCount)>;
47 
52 
53 // clang-format off
54 #define SERIAL_CONFIG_MAP(XX) \
55  XX(5N1) XX(6N1) XX(7N1) XX(8N1) XX(5N2) XX(6N2) XX(7N2) XX(8N2) XX(5E1) XX(6E1) XX(7E1) XX(8E1) \
56  XX(5E2) XX(6E2) XX(7E2) XX(8E2) XX(5O1) XX(6O1) XX(7O1) XX(8O1) XX(5O2) XX(6O2) XX(7O2) XX(8O2)
57 // clang-format on
58 
59 enum class SerialFormat {
60 #define XX(x) Fmt##x = UART_##x,
62 #undef XX
63 };
64 
65 #define XX(x) static constexpr SerialFormat SERIAL_##x{SerialFormat::Fmt##x};
67 #undef XX
68 
70 enum class SerialMode {
71  Full = UART_FULL,
72  RxOnly = UART_RX_ONLY,
73  TxOnly = UART_TX_ONLY,
74 };
75 
79 
80 #ifndef DEFAULT_RX_BUFFER_SIZE
81 #define DEFAULT_RX_BUFFER_SIZE 256
82 #endif
83 
84 #ifndef DEFAULT_TX_BUFFER_SIZE
85 #define DEFAULT_TX_BUFFER_SIZE 0
86 #endif
87 
88 #define SERIAL_STATUS_MAP(XX) \
89  XX(BreakDetected, "Break condition detected on receive line") \
90  XX(Overflow, "Receive buffer overflowed") \
91  XX(FramingError, "Receive framing error") \
92  XX(ParityError, "Parity check failed on received data")
93 
95 enum class SerialStatus {
96 #define XX(tag, comment) tag,
98 #undef XX
99 };
100 
101 #define XX(tag, comment) static constexpr SerialStatus eSERS_##tag{SerialStatus::tag};
103 #undef XX
104 
107 {
108 public:
113  HardwareSerial(int uartPort) : uartNr(uartPort)
114  {
115  }
116 
117  void setPort(int uartPort)
118  {
119  end();
120  uartNr = uartPort;
121  }
122 
123  int getPort()
124  {
125  return uartNr;
126  }
127 
132  bool begin(uint32_t baud = 9600)
133  {
134  return begin(baud, SERIAL_8N1, SERIAL_FULL, SERIAL_PIN_DEFAULT);
135  }
136 
146  bool begin(uint32_t baud, SerialFormat format)
147  {
148  return begin(baud, format, SERIAL_FULL, SERIAL_PIN_DEFAULT);
149  }
150 
161  bool begin(uint32_t baud, SerialFormat format, SerialMode mode)
162  {
163  return begin(baud, format, mode, 1);
164  }
165 
175  bool begin(uint32_t baud, SerialFormat format, SerialMode mode, uint8_t txPin, uint8_t rxPin = SERIAL_PIN_DEFAULT);
176 
180  void end();
181 
187  size_t setRxBufferSize(size_t size);
188 
194  size_t setTxBufferSize(size_t size);
195 
202  void setTxWait(bool wait)
203  {
204  bitWrite(options, UART_OPT_TXWAIT, wait);
205  smg_uart_set_options(uart, options);
206  }
207 
213  void swap()
214  {
215  swap(1);
216  }
217 
222  void swap(uint8_t tx_pin)
223  {
224  smg_uart_swap(uart, tx_pin);
225  }
226 
235  void setTx(uint8_t tx_pin)
236  {
237  smg_uart_set_tx(uart, tx_pin);
238  }
239 
247  void pins(uint8_t tx, uint8_t rx)
248  {
249  smg_uart_set_pins(uart, tx, rx);
250  }
251 
255  int available() override
256  {
257  return (int)smg_uart_rx_available(uart);
258  }
259 
264  int read() override
265  {
266  return smg_uart_read_char(uart);
267  }
268 
276  uint16_t readMemoryBlock(char* buf, int max_len) override
277  {
278  return smg_uart_read(uart, buf, max_len);
279  }
280 
281  bool seek(int len) override
282  {
283  return false;
284  }
285 
286  bool isFinished() override
287  {
288  return false;
289  }
290 
295  int peek() override
296  {
297  return smg_uart_peek_char(uart);
298  }
299 
305  {
306  smg_uart_flush(uart, smg_uart_mode_t(mode));
307  }
308 
312  void flush() override // Stream
313  {
314  smg_uart_wait_tx_empty(uart);
315  }
316 
317  using Stream::write;
318 
324  size_t write(const uint8_t* buffer, size_t size) override
325  {
326  return smg_uart_write(uart, buffer, size);
327  }
328 
333  void systemDebugOutput(bool enabled);
334 
342  void commandProcessing(bool reqEnable) SMING_DEPRECATED
343  {
344  }
345 
350  bool onDataReceived(StreamDataReceivedDelegate dataReceivedDelegate)
351  {
352  this->HWSDelegate = dataReceivedDelegate;
353  return updateUartCallback();
354  }
355 
360  bool onTransmitComplete(TransmitCompleteDelegate transmitCompleteDelegate)
361  {
362  this->transmitComplete = transmitCompleteDelegate;
363  return updateUartCallback();
364  }
365 
372  __forceinline void setUartCallback(smg_uart_callback_t callback, void* param = nullptr)
373  {
374  smg_uart_set_callback(uart, callback, param);
375  }
376 
381  bool isTxEnabled()
382  {
383  return smg_uart_tx_enabled(uart);
384  }
385 
390  bool isRxEnabled()
391  {
392  return smg_uart_rx_enabled(uart);
393  }
394 
399  uint32_t baudRate()
400  {
401  return smg_uart_get_baudrate(uart);
402  }
403 
409  uint32_t setBaudRate(uint32_t baudrate)
410  {
411  return smg_uart_set_baudrate(uart, baudrate);
412  }
413 
417  operator bool() const
418  {
419  return uart != nullptr;
420  }
421 
427  int indexOf(char c) override
428  {
429  return smg_uart_rx_find(uart, c);
430  }
431 
436  smg_uart_t* getUart()
437  {
438  return uart;
439  }
440 
446  unsigned getStatus();
447 
448 private:
449  int uartNr = UART_NO;
450  TransmitCompleteDelegate transmitComplete = nullptr;
451  StreamDataReceivedDelegate HWSDelegate = nullptr;
452  smg_uart_t* uart = nullptr;
453  uart_options_t options = _BV(UART_OPT_TXWAIT);
454  size_t txSize = DEFAULT_TX_BUFFER_SIZE;
455  size_t rxSize = DEFAULT_RX_BUFFER_SIZE;
456  volatile uint16_t statusMask = 0;
457  volatile uint16_t callbackStatus = 0;
458  volatile bool callbackQueued = false;
459 
465  static void IRAM_ATTR staticCallbackHandler(smg_uart_t* uart, uint32_t status);
466  static void staticOnStatusChange(void* param);
467  void invokeCallbacks();
468 
473  bool updateUartCallback();
474 };
475 
485 extern HardwareSerial Serial;
486 
Base Stream class.
Definition: Wiring/Stream.h:32
bool isTxEnabled()
Checks if the current UART can transmit(print) information.
Definition: HardwareSerial.h:381
static constexpr SerialMode SERIAL_RX_ONLY
Definition: HardwareSerial.h:77
int available() override
Get quantity characters available from serial input.
Definition: HardwareSerial.h:255
bool begin(uint32_t baud, SerialFormat format)
Initialise and set its configuration.
Definition: HardwareSerial.h:146
bool begin(uint32_t baud=9600)
Initialise the serial port.
Definition: HardwareSerial.h:132
SerialStatus
Notification and error status bits.
Definition: HardwareSerial.h:95
void setTx(uint8_t tx_pin)
Toggle between use of GPIO1 and GPIO2 as TX on UART 0.
Definition: HardwareSerial.h:235
#define _BV(bit)
Definition: BitManipulations.h:10
void systemDebugOutput(bool enabled)
Configure serial port for system debug output and redirect output from debugf.
Hardware serial class.
Definition: HardwareSerial.h:106
bool onDataReceived(StreamDataReceivedDelegate dataReceivedDelegate)
Set handler for received data.
Definition: HardwareSerial.h:350
bool isRxEnabled()
Checks if the current UART can receive information.
Definition: HardwareSerial.h:390
static constexpr SerialMode SERIAL_TX_ONLY
Definition: HardwareSerial.h:78
int peek() override
Read a character from serial port without removing from input buffer.
Definition: HardwareSerial.h:295
size_t write(const uint8_t *buffer, size_t size) override
write multiple characters to serial port
Definition: HardwareSerial.h:324
void commandProcessing(bool reqEnable)
Configure serial port for command processing.
Definition: HardwareSerial.h:342
#define XX(x)
Definition: HardwareSerial.h:101
uint16_t readMemoryBlock(char *buf, int max_len) override
Read a block of characters from serial port.
Definition: HardwareSerial.h:276
HardwareSerial(int uartPort)
Create instance of a hardware serial port object.
Definition: HardwareSerial.h:113
size_t setTxBufferSize(size_t size)
Sets transmit buffer size.
void setTxWait(bool wait)
Governs write behaviour when UART transmit buffers are full.
Definition: HardwareSerial.h:202
bool seek(int len) override
Move read cursor.
Definition: HardwareSerial.h:281
void swap(uint8_t tx_pin)
Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX.
Definition: HardwareSerial.h:222
#define SERIAL_PIN_DEFAULT
Definition: HardwareSerial.h:29
uint32_t setBaudRate(uint32_t baudrate)
Attempt to set the requested baud rate.
Definition: HardwareSerial.h:409
void setPort(int uartPort)
Definition: HardwareSerial.h:117
SerialFormat
Definition: HardwareSerial.h:59
#define DEFAULT_RX_BUFFER_SIZE
Definition: HardwareSerial.h:81
smg_uart_t * getUart()
Returns a pointer to the internal uart object. Use with care.
Definition: HardwareSerial.h:436
void setUartCallback(smg_uart_callback_t callback, void *param=nullptr)
Set callback ISR for received data.
Definition: HardwareSerial.h:372
bool isFinished() override
Check if all data has been read.
Definition: HardwareSerial.h:286
XX(tag, comment)
int getPort()
Definition: HardwareSerial.h:123
HardwareSerial Serial
Global instance of serial port UART0.
bool onTransmitComplete(TransmitCompleteDelegate transmitCompleteDelegate)
Set handler for received data.
Definition: HardwareSerial.h:360
size_t setRxBufferSize(size_t size)
Sets receiving buffer size.
bool begin(uint32_t baud, SerialFormat format, SerialMode mode)
Initialise, set its configuration and mode.
Definition: HardwareSerial.h:161
int read() override
Read a character from serial port.
Definition: HardwareSerial.h:264
void end()
De-inits the current UART if it is already used.
int indexOf(char c) override
Returns the location of the searched character.
Definition: HardwareSerial.h:427
#define DEFAULT_TX_BUFFER_SIZE
Definition: HardwareSerial.h:85
virtual size_t write(uint8_t c)=0
Writes a single character to output stream.
#define bitWrite(value, bit, bitvalue)
Definition: BitManipulations.h:21
uint32_t baudRate()
Get the current baud rate.
Definition: HardwareSerial.h:399
#define SERIAL_STATUS_MAP(XX)
Definition: HardwareSerial.h:88
SerialMode
values equivalent to uart_mode_t
Definition: HardwareSerial.h:70
static constexpr SerialMode SERIAL_FULL
Definition: HardwareSerial.h:76
void clear(SerialMode mode=SERIAL_FULL)
Clear the serial port transmit/receive buffers.
Definition: HardwareSerial.h:304
void pins(uint8_t tx, uint8_t rx)
Sets the transmission and receiving PINS.
Definition: HardwareSerial.h:247
#define SERIAL_CONFIG_MAP(XX)
Definition: HardwareSerial.h:54
void flush() override
Flush all pending data to the serial port.
Definition: HardwareSerial.h:312
unsigned getStatus()
Get status error flags and clear them.
#define SMING_DEPRECATED
Definition: sming_attr.h:36
Base class for read/write stream.
Definition: ReadWriteStream.h:19
void swap()
Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX.
Definition: HardwareSerial.h:213