Development > Suggestions for the Arduino Project

Arduino 1.0 SoftwareSerial Documentation Needs Fixes

(1/3) > >>

In Arduino 1.0, the documentation for the SoftwareSerial library < > needs corrections:

1)  Documentation for read() says "Reads a character from the receive pin of the software serial port. This function waits for a character to arrive, reads it, and returns the character read. Data that arrives at other times is lost."

In fact, the software serial port is "reading" all of the time (after begin(...) or listen()) and putting the data into a buffer.  read() returns the next character in the buffer, or -1 if the buffer is empty.  There is no waiting and no lost data unless the buffer is full.

2)  Documentation for overflow() neglects to mention that overflow() has the side effect of clearing the overflow flag.  If overflow() returns true, the next call to overflow() will return false unless another character arrives in the meantime.

3)  Documentation for SoftwareSerial should mention that it inherits from Serial and Print, and thus Serial and Print public methods may be used as well.

Thanks for this  :)
I found point 1) a bit confusing so nice to have it clarified.
point 2) thats nice to know thanks.
point 3) does this mean that flush and peek can also be used (coming from Serial) not sure that Print offers

flush() and peek() are already offered by SoftwareSerial, they are just not documented.  That is part of the problem.
I am new to C++ and have not tried it, but I believe that, via SoftwareSerial, Stream will provide setTimeout, two versions of find, two version of findUntil, parseInt, parseFloat, readBytes, and readBytesUntil.  Print should provide 11 versions of print and 12 versions of println.  See Stream.h and Print.h for details.

Be aware that in all the last minute changes they did for 1.0 that they broke compatibility between HardwareSerial
and SoftwareSerial for flush().

So "as is" in 1.0, flush() on SoftwareSerial and HardwareSerial  do not do the same thing.
(They changed the flush() function in HardwareSerial, after they added it to SoftwareSerial)

flush() on SoftwareSerial purges all the received characters in the rx buffer.
flush() on HardwareSerial waits for all the characters in the tx buffer to be transmitted.

Pre 1.0 SoftwareSerial didn't have a flush()
Pre 1.0 HardwareSerial flush() purged the received characters.

On 1.0 there is no API call to purge the rx buffer on HardwareSerial.

IMO, a new API call should have been created to drain the tx buffer rather
than change the behavior of the exiting flush() api function.

-- bill


--- Quote ---IMO, a new API call should have been created to drain the tx buffer rather
than change the behavior of the exiting flush() api function.
--- End quote ---

I would (almost) agree. The basing on the Stream class, though, dictates that the flush() function operate in the same fashion as flush() on any stream. Typically, flushing a stream means that a send of the buffered data is forced, rather than waiting for the buffer to fill. This is now the behavior of flush() in the HardwareSerial class. The unfortunate thing is that there was already a function of that name in the HardwareSerial class, even though what it did was not what one typically expects flush to do.

If one looks at a lot of code posted on the forum, the current functionality of the flush() function is what most people expected the old functionality to do.


[0] Message Index

[#] Next page

Go to full version