The documentation on Arduino's website shows SoftwareSerial::read() as returning a char.
No it doesn't. There is nothing in the documentation that tells you the return type. There is only an example where the returned value is assigned to a char
variable. That doesn't mean that it returns a char - it just means that whatever data type it does return can be invisibly cast to a char
by the compiler.
The header shows that the method returns an int.
Indeed it does. That is because that is what it returns.
The cpp definition shows SoftwareSerial::read() returning the value from a buffer array of uint8_t values.
Yes, because the valid data that it deals with is 8 bits in size. Just because it handles 8 bit "valid" data doesn't mean that that's all it ever wants to return. The "no data available" return value of -1 is obviously not something that is stored in the data. It's a status, not data.
Why would the interface return an int instead of a uint8_t?
Because a uint8_t
cannot encompass all the functionality stated in the "Returns" section:
the character read, or -1 if none is available
You can't return -1 in a uint8_t
.
Why do the Arduino docs show it as returning a char?
It doesn't - as I mentioned above. It makes no claims at all about the returned data type.
Is it safe to send/receive 8-bits at a time using this library?
Yes. It performs serial data transfers using 8-N-1 by default. That's 8 data bits, no parity, and one stop bit.
It's this kind of confusion with return types and bytes and integers and things that make people ask why they keep getting ÿÿÿÿÿÿ on the serial monitor. That's -1 cast as a char. I.e., "no data available" but they ignore that and treat everything returned as a char
- most probably because the Arduino documentation shows an overly simplified example that ignores the possibility of a -1 being returned and treats everything as a char
.
IMHO much of the Arduino documentation is somewhat sub-par and should not be taken literally - only as a rough guide for what is available. The same goes for much of their example code and projects.