From 01edc0e51f5507e3129b74c8895573c80f99f711 Mon Sep 17 00:00:00 2001 From: Develo Date: Thu, 13 Aug 2020 16:41:57 -0400 Subject: [PATCH] Fix and add details to Serial doc (#7521) Fixes #7484 Clarify blocking case for write() Add flush() method. Missing ), clarifications --- doc/reference.rst | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/doc/reference.rst b/doc/reference.rst index 7b5a22907..75c267dd3 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -151,12 +151,31 @@ milliseconds is not recommended. Serial ------ -``Serial`` object works much the same way as on a regular Arduino. Apart -from hardware FIFO (128 bytes for TX and RX) ``Serial`` has -additional 256-byte TX and RX buffers. Both transmit and receive is -interrupt-driven. Write and read functions only block the sketch -execution when the respective FIFO/buffers are full/empty. Note that -the length of additional 256-bit buffer can be customized. +The ``Serial`` object works much the same way as on a regular Arduino. Apart +from the hardware FIFO (128 bytes for TX and RX), ``Serial`` has an +additional customizable 256-byte RX buffer. The size of this software buffer can +be changed by the user. It is suggested to use a bigger size at higher receive speeds. + +The ``::setRxBufferSize(size_t size)`` method changes the RX buffer size as needed. This +should be called before ``::begin()``. The size argument should be at least large enough +to hold all data received before reading. + +For transmit-only operation, the 256-byte RX buffer can be switched off to save RAM by +passing mode SERIAL_TX_ONLY to Serial.begin(). Other modes are SERIAL_RX_ONLY and +SERIAL_FULL (the default). + +Receive is interrupt-driven, but transmit polls and busy-waits. Blocking behavior is as follows: +The ``::write()`` call does not block if the number of bytes fits in the current space available +in the TX FIFO. The call blocks if the TX FIFO is full and waits until there is room before +writing more bytes into it, until all bytes are written. In other words, when the call returns, +all bytes have been written to the TX FIFO, but that doesn't mean that all bytes have been sent +out through the serial line yet. +The ``::read()`` call doesn't block, not even if there are no bytes available for reading. +The ``::readBytes()`` call blocks until the number of bytes read complies with the number of +bytes required by the argument passed in. +The ``::flush()`` call blocks waiting for the TX FIFO to be empty before returning. It is +recommended to call this to make sure all bytes have been sent before doing configuration changes +on the serial port (e.g. changing baudrate) or doing a board reset. ``Serial`` uses UART0, which is mapped to pins GPIO1 (TX) and GPIO3 (RX). Serial may be remapped to GPIO15 (TX) and GPIO13 (RX) by calling @@ -180,14 +199,13 @@ instead, call ``Serial1.setDebugOutput(true)``. You also need to use ``Serial.setDebugOutput(true)`` to enable output from ``printf()`` function. -The method ``Serial.setRxBufferSize(size_t size)`` allows to define the -receiving buffer depth. The default value is 256. - Both ``Serial`` and ``Serial1`` objects support 5, 6, 7, 8 data bits, odd (O), even (E), and no (N) parity, and 1 or 2 stop bits. To set the desired mode, call ``Serial.begin(baudrate, SERIAL_8N1)``, ``Serial.begin(baudrate, SERIAL_6E2)``, etc. - +Default configuration mode is SERIAL_8N1. Possibilities are SERIAL_[5678][NEO][12]. +Example: ``SERIAL_8N1`` means 8bits No parity 1 stop bit. + A new method has been implemented on both ``Serial`` and ``Serial1`` to get current baud rate setting. To get the current baud rate, call ``Serial.baudRate()``, ``Serial1.baudRate()``. Return a ``int`` of @@ -206,7 +224,7 @@ current speed. For example | ``Serial`` and ``Serial1`` objects are both instances of the ``HardwareSerial`` class. -| I've done this also for official ESP8266 `Software +| This is also done for official ESP8266 `Software Serial `__ library, see this `pull request `__.