-
Notifications
You must be signed in to change notification settings - Fork 13.3k
Reference: clarify Serial.setRxBufferSize description #7484
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
To summarize, do you wish to clarify doc with the following statements ?
|
Let me suggest: "Serial object works much the same way as on a regular Arduino. Apart from hardware FIFO (128 bytes for TX and RX) Serial has "The method Serial.setRxBufferSize(size_t size) allows to define the receiving buffer depth. It must be at least the size of the largest block of data you may need to buffer before reading. The default Edit: rephrased minimum size. |
There is indeed some sort of TX buffer; I saw it in action when I was playing with the Low Power Demo in December/January. I don't know if it's managed by the core or SDK, nor how large it is. I had to do Serial.flush() or the CPU wouldn't sleep in a couple of places. Backtrack the flush should show you the buffer. It may be a hardware buffer in the UART. |
It is indeed the hardware buffer. Edit: removed incorrect comment about flush(). |
I always thought (not sure where I got it from) the hardware buffer was only 128 bytes in size, both for reading and writing. |
@TD-er According to Esspressifs Technical Reference, Chapter 11, page 79:
In the rest of the chapter, receive and transmit buffers are described separately (e.g. buffer full and empty interrupt triggers can be set in the range of 0-127). Also, issues #1683 and #2237 refer to the implementation of the serial buffer for ESP8266. |
@wolfbert here's an update: "Serial object works much the same way as on a regular Arduino. Apart from hardware FIFO (128 bytes for TX and RX) Serial has a customizable RX buffer (default size 256 bytes, can be customized) in RAM. Both transmit and receive is interrupt-driven. "The method |
@d-a-v
Note that the two paragraphs are separated by a number of lines in the documentation. |
Transmit is not interrupt driven, it is blocking due to polling busy-wait, ref here. The Arduino AVR reference seems to be interrupt-driven, ref there. Rx is interrupt-driven, i.e.: there is a sw buffer that has a default size of 256 bytes, that gets filled when there are bytes incoming. If I remember correctly, the ISR is triggered under 2 conditions:
So that part is wrong in both current and proposed doc: Only Rx is interrupt driven.
However, both are blocking, so the behavior from the user's POV is pretty much the same as for Arduino, i.e.: it makes no difference that our implementation for Tx isn't interrupt driven.
Transmit, i.e.: write(), blocks when the Tx hw FIFO is full.
To reduce redundancy, I suggest along the lines of:
I suggest adding an example, e.g.: |
Fixes #7484 Clarify blocking case for write() Add flush() method. Missing ), clarifications
Basic Infos
Platform
Problem Description
https://arduino-esp8266.readthedocs.io/en/latest/reference.html#serial
Looking at uart.cpp, I can only find support for the RX buffer.
While this reflects the code, it is by no means the whole story. The RX buffer shadows the hardware FIFO. If the RX buffer size is set to 0, UART initialization will fail. After every 16 (or more) received (unread) characters, FIFO content will be moved to the RX buffer which wraps around. So you can buffer at most RX buffer size + 15 (possibly up to 128) characters. Therefore, any change in the buffer size must be carefully considered. In case the buffer is resized smaller after UART initialization, unread data may get truncated (and the overrun flag remains unchanged).
As an aside, if the 128 byte hardware FIFO buffer is sufficient for the application, the RX buffer wouldn't be needed (but that requires a change in the code, i.e. don't allocate RX buffer unless requested size > 128).
Edit: fixed link to documentation.
The text was updated successfully, but these errors were encountered: