Serial.readStringUntil()

Описание

readStringUntil() читает символы из последовательного буфера и накапливает их в строку типа String. Чтение продолжается до тех пор, пока не встретится заданный символ-терминатор или не истечёт таймаут (см. Serial.setTimeout()). Это удобный способ разобрать входящий поток на отдельные «куски», разделённые каким-либо символом — например, запятой, точкой с запятой или символом новой строки.

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

Синтаксис

Serial.readStringUntil(terminator)

Параметры

• Serial — объект последовательного порта. Список портов, доступных на конкретной плате, смотри на странице Serial.
• terminator — символ, на котором нужно остановить чтение. Допустимый тип данных: `char`.

Возвращает

Функция возвращает объект `String` — всё, что было прочитано из буфера до символа-терминатора или до истечения таймаута. Сам терминатор в строку не включается и удаляется из буфера.

Если символ-терминатор так и не встретился до истечения таймаута, функция вернёт уже прочитанные символы. Если за время ожидания не пришло ни одного символа, результатом будет пустая строка.

Пример кода

Следующий код читает данные из последовательного порта до получения символа новой строки ('\n'):

void setup() {
  Serial.begin(9600);
  while (!Serial);

  Serial.println("Enter a word and press Enter:");
}

void loop() {
  if (Serial.available()) {
    String input = Serial.readStringUntil('\n');  // Читать до символа новой строки
    Serial.print("You entered: ");
    Serial.println(input);
  }
}

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

• Разбор команд из Serial Monitor — пользователь вводит строку и нажимает Enter; readStringUntil('\n') возвращает введённый текст без символа перевода строки.
• Парсинг CSV-данных — если внешнее устройство шлёт значения через запятую, можно последовательно вызывать readStringUntil(',') для каждого поля.
• Протоколы с разделителями — любые текстовые протоколы, где сообщения заканчиваются фиксированным символом (;, #, > и т.д.).
• Чтение ответов от AT-модемов и GPS-модулей — строки NMEA или AT-ответы удобно читать построчно с терминатором '\n'.

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

• Блокирующее поведение. Функция ждёт данных и не возвращает управление до тех пор, пока не найдёт терминатор или не истечёт таймаут. По умолчанию таймаут равен 1000 мс. Если ваш скетч должен реагировать на другие события, это важно учитывать.
• Таймаут. Изменить время ожидания можно через setTimeout. Слишком короткий таймаут приведёт к тому, что медленно поступающие данные будут обрезаться; слишком длинный — к «зависанию» программы в ожидании.
• Терминатор удаляется из буфера. После вызова функции символ-терминатор уже не будет доступен при следующем чтении — он потребляется автоматически.
• Таймаут без терминатора. Если данные пришли, но терминатор так и не появился, функция вернёт то, что успела прочитать до таймаута. Это частая причина «обрезанных» сообщений: проверьте, что отправитель действительно посылает терминатор.
• Тип параметра terminator. Передавайте символ в одинарных кавычках: '\n', ',', ';'. Не путайте с двойными кавычками — "\n" имеет тип const char*, а не char.
• Работа с String. Возвращаемый объект String можно сразу сравнивать, преобразовывать в число (toInt(), toFloat()) или выводить обратно в порт — это удобно для быстрого прототипирования, но на платах с малым объёмом ОЗУ (Uno, Nano) активное использование String может привести к фрагментации памяти.

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

Символ-терминатор извлекается из буфера, но в возвращаемую строку не входит. Если терминатор не был найден до истечения таймаута, функция возвращает уже прочитанные символы; если данных не было, возвращается пустая строка.