Почему SoftwareSerial::read() возвращает int?

Stream объявляет read как возвращающий int (смотрите в hardware/arduino/avr/cores/arduino/Stream.h). SoftwareSerial наследуется от Stream, поэтому они должны переопределить это объявление, иначе было бы два метода read(), один из которых возвращает int и один возвращает uint8_t. Поскольку SoftwareSerial::read() вернет только int от 0 до 255, что соответствует uint8_t, проблем нет.

Что касается документации по Arduino, вы получаете то, за что платите :)

В документации на веб-сайте Arduino показано, что SoftwareSerial::read() возвращает символ.

Нет. В документации нет ничего, что говорило бы вам о типе возвращаемого значения. Есть только пример, когда возвращаемое значение присваивается переменной char. Это не означает, что он возвращает char — это просто означает, что любой возвращаемый тип данных может быть незаметно преобразован компилятором в char.

Заголовок показывает, что метод возвращает целое число.

Это действительно так. Это потому, что это то, что он возвращает.

Определение cpp показывает, что SoftwareSerial::read() возвращает значение из буферного массива значений uint8_t.

Да, потому что действительные данные, с которыми он работает, имеют размер 8 бит. Тот факт, что он обрабатывает 8-битные «действительные» данные, не означает, что это все, которые он когда-либо хочет вернуть. Возвращаемое значение «нет доступных данных» равное -1, очевидно, не является чем-то, что хранится в данных. Это статус, а не данные.

---

Почему интерфейс возвращает int вместо uint8_t?

Поскольку uint8_t не может включать в себя все функции, указанные в разделе "Возвраты":

прочитанный символ или -1, если он недоступен

Вы не можете вернуть -1 в uint8_t.

Почему в документации Arduino указано, что он возвращает символ?

Как я уже упоминал выше, это не так. Он вообще не претендует на возвращаемый тип данных.

Безопасно ли отправлять/получать 8 бит за раз с помощью этой библиотеки?

Да. Он выполняет последовательную передачу данных, используя 8-N-1 по умолчанию. Это 8 бит данных, без четности и один стоповый бит.

---

Именно такая путаница с возвращаемыми типами, байтами, целыми числами и другими вещами заставляет людей задаваться вопросом, почему они продолжают получать ÿÿÿÿÿÿ на последовательном мониторе. Это -1 бросок как символ. То есть «нет доступных данных», но они игнорируют это и рассматривают все возвращаемое как char — скорее всего, потому, что документация Arduino показывает чрезмерно упрощенный пример, который игнорирует возможность возврата -1 и обрабатывает все как char.

ИМХО, большая часть документации Arduino несколько не соответствует стандарту и не должна восприниматься буквально — только как приблизительное руководство по тому, что доступно. То же самое касается большей части их примеров кода и проектов.