Serial.parseInt()

Описание

Serial.parseInt() сканирует входящий последовательный поток и возвращает первое найденное целое число. Функция блокирует выполнение программы до тех пор, пока не найдёт число или не истечёт таймаут (настраивается через Serial.setTimeout()).

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

Важно понимать поведение функции:

• Разбор прекращается, как только встречается нецифровой символ или истекает таймаут без новых символов.
• Если до истечения таймаута не было прочитано ни одной допустимой цифры, функция возвращает 0.

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

Синтаксис

Функцию можно вызвать в трёх формах:

• Serial.parseInt()
• Serial.parseInt(lookahead)
• Serial.parseInt(lookahead, ignore)

Параметры

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

lookahead: определяет, как функция ведёт себя с символами, которые не являются частью числа. Тип данных: LookaheadMode. Допустимые значения:

• SKIP_ALL — всё, что не является цифрой или знаком минус, просто пропускается при поиске числа. Это поведение по умолчанию: функция «проматывает» мусор и находит первое число в потоке.
• SKIP_NONE — ничего не пропускается. Если первый символ в буфере не является началом числа, функция немедленно возвращает 0, не трогая поток.
• SKIP_WHITESPACE — пропускаются только пробельные символы: пробел, табуляция (\t), перевод строки (\n) и возврат каретки (\r). Любой другой нецифровой символ останавливает разбор.

ignore: символ, который нужно игнорировать при разборе числа. Типичный пример — разделитель тысяч: если передать ',', то строка "1,234" будет прочитана как 1234. Тип данных: char.

Возвращает

Первое найденное целое число. Тип данных: long.

Если число не найдено до истечения таймаута, возвращается 0 — это нормальное поведение, а не признак ошибки. Учитывайте это при обработке результата.

Пример кода

Следующий код извлекает первое допустимое целое число из входящего последовательного сообщения:

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

  Serial.println("Enter a integer number:");  // попробуйте со смешанной фразой, например "The size of the box is 5 mm"
}

void loop() {
  if (Serial.available()) {
    int number = Serial.parseInt();
    if (number != 0) {
      Serial.print("You entered: ");
      Serial.println(number);
    }
  }
}

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

• Управление через Serial Monitor: пользователь вводит числовое значение (например, яркость светодиода или угол сервопривода), скетч считывает его через Serial.parseInt().
• Разбор простых текстовых команд: если протокол содержит числа, разделённые пробелами или запятыми, функция позволяет быстро извлечь каждое из них последовательными вызовами.
• Получение данных от другого устройства: микроконтроллер или компьютер отправляет числовые параметры в текстовом виде, Arduino их считывает без ручного разбора строки.
• Интерактивная настройка параметров: ввод порогов, задержек или коэффициентов прямо во время работы устройства без перепрошивки.

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

• Блокирующее поведение: функция ждёт данных. Если поток пуст, программа зависнет на время таймаута. Для неблокирующей работы проверяйте Serial.available() перед вызовом.
• Таймаут по умолчанию — 1 секунда. Изменить его можно через Serial.setTimeout(). При коротком таймауте функция может вернуть 0, если данные поступают медленно.
• Знак минус поддерживается: функция корректно читает отрицательные числа вроде -42.
• Режим SKIP_ALL по умолчанию удобен для простых случаев, но может «съесть» лишние символы из потока. Если важен точный контроль над буфером, используйте SKIP_NONE или SKIP_WHITESPACE.
• Возврат нуля не всегда ошибка: если функция вернула 0, это может означать как реальный ноль в данных, так и таймаут без цифр. Если нужно различать эти случаи, используйте Serial.peek() перед вызовом, чтобы убедиться, что в буфере есть данные.