diff --git a/doc/reference.rst b/doc/reference.rst index 7b5a22907..bf99de421 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 `__.