Serial.readString()

Описание

Serial.readString() читает символы из последовательного буфера и собирает их в один объект String. Функция продолжает накапливать данные до тех пор, пока не истечёт таймаут ожидания — его можно настроить с помощью Serial.setTimeout(). По умолчанию таймаут составляет 1000 мс.

Важно понимать: функция не ориентируется на символы конца строки (\n или \r) как на признак завершения — она просто ждёт, пока не кончится время. Это отличает её от Serial.readStringUntil(), которая останавливается на конкретном символе-терминаторе.

Serial.readString() наследует от класса Stream.

Синтаксис

Serial.readString()

Параметры

Serial — объект последовательного порта. Это может быть Serial, а на платах с несколькими портами — Serial1, Serial2 и т. д. Список доступных портов для каждой платы смотрите на странице Serial.

Возвращает

String — объект типа String, содержащий все символы, прочитанные из последовательного буфера за время ожидания. Если за отведённое время данных не поступило, функция вернёт пустую строку.

Пример кода

В примере скетч ждёт строку из Serial Monitor, убирает пробельные символы в конце и сравнивает полученный текст с командой red.

void setup() {
  Serial.begin(9600);
}

void loop() {
  Serial.println("Enter data:");
  while (Serial.available() == 0) {}     //ожидание доступных данных
  String teststr = Serial.readString();  //читать до истечения таймаута
  teststr.trim();                        // удалить символы \r \n в конце строки
  if (teststr == "red") {
    Serial.println("A primary color");
  } else {
    Serial.println("Something else");
  }
}

Где применяется

• Чтение команд или коротких текстовых сообщений, отправленных через Serial Monitor.
• Приём данных от другого микроконтроллера или компьютера, когда заранее неизвестна длина пакета.
• Сбор строковых данных от GPS-модуля или другого UART-устройства для последующего разбора.
• Быстрое прототипирование: когда нужно просто «поймать» всё, что пришло, и разобраться с содержимым позже.

Практические замечания

• Блокирующее поведение. Функция блокирует выполнение скетча на время ожидания следующего символа. Если таймаут — 1 секунда, а данные уже закончились, программа может ждать ещё до секунды, прежде чем вернуть строку. Для чувствительных ко времени задач уменьшайте таймаут через Serial.setTimeout().
• Символы конца строки. Если отправитель добавляет \r или \n в конец строки (что делает, например, Serial Monitor с настройкой «Newline» или «Both NL & CR»), эти символы окажутся в возвращённой строке. Перед обработкой текста удалите их методом String.trim().
• Пустая строка при отсутствии данных. Если в буфере ничего нет и таймаут истёк, функция вернёт пустую String. Перед использованием результата проверяйте его длину: if (incoming.length() > 0).
• Переполнение буфера. Последовательный буфер по умолчанию невелик (64 байта на большинстве плат). Если данные поступают быстрее, чем readString() успевает их считать, часть символов может быть потеряна.
• Сравнение строк. Результат — объект String, поэтому сравнивайте его через == или equals(), а не через strcmp().
• Протоколы с разделителем. Если сообщение заканчивается конкретным символом, например '\n', часто удобнее использовать Serial.readStringUntil(): код будет понятнее, а ожидание — предсказуемее.

Примечания и предупреждения

Функция не завершается досрочно, если данные содержат символы конца строки. Возвращённый String может содержать символы возврата каретки (\r) и/или перевода строки (\n), если они были получены.