From 39524baeb30cc4797fdbb3dbeab1b81f061f6b9f Mon Sep 17 00:00:00 2001 From: Develo Date: Wed, 12 Aug 2020 18:24:00 -0400 Subject: [PATCH 1/5] Fixes #7484 --- doc/reference.rst | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/doc/reference.rst b/doc/reference.rst index 7b5a229073..bf99de4217 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -151,12 +151,25 @@ 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 buffer can be switched off 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. Both are +blocking: +The ``::write()`` call blocks if the TX FIFO is full and waits until there is room +in the FIFO before writing more bytes into it. +The ``::read()`` call does not block 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. ``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 +193,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 +218,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 `__. From db8d82c1556ad0b48619b64dcba37eee958b2d18 Mon Sep 17 00:00:00 2001 From: Develo Date: Thu, 13 Aug 2020 14:37:27 -0400 Subject: [PATCH 2/5] Update reference.rst Clarify blocking case for write() --- doc/reference.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/reference.rst b/doc/reference.rst index bf99de4217..69bffcb30e 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -165,11 +165,13 @@ to Serial.begin(). Other modes are SERIAL_RX_ONLY and SERIAL_FULL (the default). Receive is interrupt-driven, but transmit polls and busy-waits. Both are blocking: -The ``::write()`` call blocks if the TX FIFO is full and waits until there is room -in the FIFO before writing more bytes into it. +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. In other words, when the call returns, all bytes have been written +to the FIFO, but that doesn't mean that all bytes have been sent out through the serial line yet. The ``::read()`` call does not block 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 ``::readBytes()`` call blocks until the number of bytes read complies with the number of +bytes required by the argument passed in. ``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 From 69549ad2b4d61dd93630f3d7dad9421e444a2d08 Mon Sep 17 00:00:00 2001 From: Develo Date: Thu, 13 Aug 2020 15:17:47 -0400 Subject: [PATCH 3/5] Update reference.rst Add flush() method. --- doc/reference.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/reference.rst b/doc/reference.rst index 69bffcb30e..ffe2334aee 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -172,6 +172,9 @@ to the FIFO, but that doesn't mean that all bytes have been sent out through the The ``::read()`` call does not block 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 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 From 3c76e76ae0ef004e098d91ea7af721518e0be100 Mon Sep 17 00:00:00 2001 From: Develo Date: Thu, 13 Aug 2020 16:08:48 -0400 Subject: [PATCH 4/5] Update reference.rst Missing ), clarifications --- doc/reference.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/reference.rst b/doc/reference.rst index ffe2334aee..5b86114211 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -156,25 +156,25 @@ 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 +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 buffer can be switched off by passing mode SERIAL_TX_ONLY -to Serial.begin(). Other modes are SERIAL_RX_ONLY and SERIAL_FULL (the default). +For transmit-only operation, the buffer can be switched off o 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. Both are -blocking: +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. In other words, when the call returns, all bytes have been written -to the FIFO, but that doesn't mean that all bytes have been sent out through the serial line yet. -The ``::read()`` call does not block if there are no bytes available for reading. +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 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. +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 From 083a8875eac989484b776690028befb5a7ef35cc Mon Sep 17 00:00:00 2001 From: Develo Date: Thu, 13 Aug 2020 16:17:13 -0400 Subject: [PATCH 5/5] Update reference.rst --- doc/reference.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/reference.rst b/doc/reference.rst index 5b86114211..75c267dd35 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -160,8 +160,9 @@ The ``::setRxBufferSize(size_t size)`` method changes the RX buffer size as need 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 buffer can be switched off o save RAM by passing mode -SERIAL_TX_ONLY to Serial.begin(). Other modes are SERIAL_RX_ONLY and SERIAL_FULL (the default). +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