Главная chevron_right Функции chevron_right Связь chevron_right Serial.findUntil()

Serial.findUntil()

Serial.findUntil() читает буфер последовательного порта и возвращает true, если строка target найдена раньше, чем строка-терминатор terminal или истёк таймаут.

Полная статья

Описание

Serial.findUntil() читает входящие данные из буфера последовательного порта и ищет в них заданную строку (target). Поиск прекращается в одном из трёх случаев: целевая строка найдена, встретилась строка-терминатор (terminal), или истёк таймаут потока. Это удобно, когда нужно разобрать ответ внешнего устройства — например, модема или GPS-модуля — и заранее известно, какая строка означает конец полезного блока данных.

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

Синтаксис

Используйте следующую функцию для поиска заданного цель строку до тех пор, пока не будет найдена терминатор.

Serial.findUntil(target, terminal)

Параметры

Функция допускает следующие объекты и параметры:

  • Serial: объект последовательного порта. См. список доступных последовательных портов для каждой платы на странице Serial.
  • target: строка для поиска. Разрешенные типы данных: char.
  • terminal: терминальная строка в поиске. Разрешенные типы данных: char.

Важно: оба параметра — target и terminal — передаются как массив char (C-строка с нулевым символом на конце), а не как объект String.

Возвращает

Функция возвращает true если целевая строка найдена до терминатор, иначе false. Тип данных: bool.

Другими словами: true означает успех — target обнаружен в потоке раньше, чем terminal. Если первым встретился terminal, или данные так и не пришли до истечения таймаута, функция вернёт false.

Пример кода

Следующий код ожидает целевую строку OK предстать перед терминатором CANCEL:

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

  Serial.println("Type a message. Looking for 'OK', but will stop if 'CANCEL' appears.");
}

void loop() {
  if (Serial.available()) {
    // Ищем "OK", но останавливаемся раньше, если встретится "CANCEL"
    if (Serial.findUntil("OK", "CANCEL")) {
      Serial.println("Found OK before CANCEL!");
    } else {
      Serial.println("Did not find OK (CANCEL appeared first or timed out).");
    }
  }

  delay(1000);
}

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

  • Парсинг AT-команд. Модемы и Wi-Fi-модули (например, ESP8266 в режиме AT) возвращают строки вида OK или ERROR. findUntil() позволяет ждать нужного ответа и сразу останавливаться, если пришла строка об ошибке.
  • Протоколы с разделителями. Если устройство шлёт данные в формате значение\n, можно искать конкретное значение, используя \n как terminal.
  • Проверка наличия подстроки в потоке. Когда нужно убедиться, что в ответе есть определённое слово, прежде чем продолжить выполнение скетча.

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

  • Функция блокирует выполнение до тех пор, пока не найдёт target, не встретит terminal или не истечёт таймаут потока. По умолчанию таймаут равен 1000 мс; изменить его можно через Serial.setTimeout().
  • Данные из буфера не возвращаются. findUntil() только сигнализирует об успехе или неудаче, но не отдаёт прочитанные байты. Если содержимое буфера нужно сохранить, используйте Serial.readBytesUntil() или Serial.readStringUntil().
  • Регистр имеет значение. Поиск чувствителен к регистру: строка "ok" не совпадёт с "OK".
  • Пустой terminal. Если передать пустую строку (""), функция будет работать как обычный Serial.find() — остановится только при нахождении target или по таймауту.
  • Отладка через Serial Monitor. Если функция постоянно возвращает false, проверьте скорость порта (Serial.begin()), убедитесь, что устройство действительно отправляет данные, и при необходимости увеличьте таймаут.

Полезные материалы