WiFiUDP

Класс WiFiUDP

WiFiUDP — это класс для работы с протоколом UDP поверх Wi-Fi. С его помощью можно как отправлять пакеты на удалённый хост, так и принимать входящие пакеты на локальном порту. UDP не устанавливает постоянного соединения, поэтому обмен данными происходит быстро, но без гарантии доставки — это нужно учитывать при проектировании протокола.

Важно об ограничениях размера пакета: на платах с микроконтроллером AVR максимальный размер исходящего UDP-пакета составляет 72 байта. На остальных платах (ESP32, SAMD, Nano 33 IoT и др.) это ограничение значительно выше — 1446 байт.

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

• Передача данных с датчиков на сервер по локальной сети без накладных расходов TCP.
• Управление устройством через UDP-команды с компьютера или смартфона.
• Синхронизация времени через NTP (NTP-запросы строятся на UDP).
• Широковещательные сообщения в локальной сети (например, обнаружение устройств).

---

WiFiUDP

Описание

Создаёт экземпляр класса WiFi. Обычно объект объявляется глобально в начале скетча, до setup().

Синтаксис

Параметры

Нет

---

WiFiUDP.begin()

Описание

Инициализирует UDP-сокет и начинает прослушивание входящих пакетов на указанном локальном порту. Вызывать нужно после успешного подключения к Wi-Fi.

Синтаксис

WiFiUDP.begin(port);

Параметры

порт — номер локального UDP-порта для прослушивания (int).

Возвращает

1 — успешно, сокет открыт. 0 — нет свободных сокетов.

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

• Вызывайте WiFiUDP.begin() только после того, как WiFi.status() вернёт WL_CONNECTED.
• Если функция вернула 0, проверьте, не открыто ли уже слишком много сокетов в скетче.
• Порт должен быть свободен: не используйте один и тот же номер порта для нескольких сокетов одновременно.

---

WiFiUDP.available()

Описание

Возвращает количество байт, доступных для чтения в текущем входящем пакете. Данные уже находятся в буфере и готовы к обработке.

Важно: WiFiUDP.available() имеет смысл вызывать только после WiFiUDP.parsePacket() — иначе всегда вернёт 0, даже если пакеты приходят.

available() унаследован от служебного класса Stream.

Синтаксис

WiFiUDP.available()

Параметры

Нет

Возвращает

Число байт, доступных в текущем пакете. 0 — если parsePacket() ещё не вызывался или пакетов нет.

---

WiFiUDP.beginPacket()

Описание

Открывает пакет для записи и указывает адрес и порт получателя. Это первый шаг при отправке UDP-данных — без него write() работать не будет.

Адрес можно передать как строку с именем хоста (DNS будет разрешён автоматически) или как объект IPAddress.

Синтаксис

WiFiUDP.beginPacket(hostName, port);
WiFiUDP.beginPacket(hostIp, port);

Параметры

имя_хоста — доменное имя или строка с IP-адресом удалённого хоста. hostIp — IP-адрес получателя в виде 4-байтового объекта IPAddress. порт — UDP-порт получателя (int).

Возвращает

1 — пакет готов к записи. 0 — ошибка: неверный адрес или порт, либо нет доступных ресурсов.

---

WiFiUDP.endPacket()

Описание

Завершает формирование пакета и отправляет его получателю. Вызывается после того, как все данные записаны через WiFiUDP.write().

Пока endPacket() не вызван, данные остаются в буфере и никуда не уходят.

Синтаксис

WiFiUDP.endPacket();

Параметры

Нет

Возвращает

1 — пакет успешно отправлен. 0 — ошибка при отправке.

---

WiFiUDP.write()

Описание

Записывает данные в формируемый UDP-пакет. Вызов должен находиться между beginPacket() и endPacket(): beginPacket() открывает пакет, а endPacket() отправляет его.

Можно передать один байт или массив байт с указанием его длины.

Синтаксис

WiFiUDP.write(byte);
WiFiUDP.write(buffer, size);

Параметры

байт — один исходящий байт. буфер — массив байт для отправки. размер — количество байт из буфера для записи в пакет.

Возвращает

При передаче одного байта — 1 (один байт записан в пакет). При передаче буфера — количество фактически записанных байт.

---

WiFiUDP.parsePacket()

Описание

Проверяет, есть ли входящий UDP-пакет, и если есть — подготавливает его к чтению. Возвращает размер пакета в байтах.

parsePacket() нужно вызывать перед WiFiUDP.read() и WiFiUDP.available() — без этого шага прочитать данные не получится. Типичный паттерн: вызвать parsePacket() в loop(), и если результат больше нуля — читать данные.

Синтаксис

UDP.parsePacket();

Параметры

Нет

Возвращает

Размер доступного пакета в байтах. 0 — входящих пакетов нет.

---

WiFiUDP.peek()

Описание

Возвращает следующий байт из входящего пакета, не извлекая его из буфера. Повторные вызовы peek() будут возвращать одно и то же значение. Следующий вызов read() вернёт тот же байт и продвинет позицию в буфере.

Функция унаследована от класса Stream.

Синтаксис

WiFiUDP.peek()

Параметры

Нет

Возвращает

Следующий байт (или символ) в буфере. -1 — если буфер пуст или пакет не был получен.

---

WiFiUDP.read()

Описание

Читает данные из входящего UDP-пакета. Без аргументов возвращает следующий байт из буфера. С аргументами — считывает несколько байт в указанный массив.

Как и available(), эту функцию нужно вызывать только после WiFiUDP.parsePacket(), иначе данных для чтения не будет.

Синтаксис

WiFiUDP.read();
WiFiUDP.read(buffer, len);

Параметры

буфер — массив (char*) для сохранения принятых данных. len — максимальное количество байт для чтения (int).

Возвращает

Один символ (char) — при вызове без аргументов. Количество прочитанных байт — при вызове с буфером. -1 — если буфер недоступен или пакет не был получен.

---

WiFiUDP.flush()

Описание

Сбрасывает все байты, которые были записаны в буфер, но ещё не прочитаны. Используется для очистки буфера входящих данных.

WiFiUDP.flush() унаследован от служебного класса Stream.

Синтаксис

WiFiUDP.flush()

Параметры

Нет

Возвращает

Нет

---

WiFiUDP.stop()

Описание

Закрывает UDP-сокет и освобождает все ресурсы, связанные с текущей сессией. После вызова WiFiUDP.stop() необходимо снова вызвать WiFiUDP.begin(), чтобы возобновить приём пакетов.

Синтаксис

WiFiUDP.stop()

Параметры

Нет

Возвращает

Нет

---

WiFiUDP.remoteIP()

Описание

Возвращает IP-адрес отправителя последнего принятого пакета. Вызывать нужно после WiFiUDP.parsePacket() — только тогда эта информация актуальна.

Полезно, когда устройство принимает пакеты от разных источников и нужно знать, кто именно прислал данные, чтобы, например, отправить ответ.

Синтаксис

WiFiUDP.remoteIP();

Параметры

Нет

Возвращает

IP-адрес хоста, отправившего текущий входящий пакет (4 байта, тип IPAddress).

---

WiFiUDP.remotePort()

Описание

Возвращает UDP-порт отправителя последнего принятого пакета. Как и WiFiUDP.remoteIP(), имеет смысл вызывать только после UDP.parsePacket().

Синтаксис

UDP.remotePort();

Параметры

Нет

Возвращает

Номер порта хоста, отправившего текущий входящий пакет.

---

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

• Типовой цикл приёма данных: вызвать parsePacket() → проверить результат → читать через read() или available(). Пропуск parsePacket() — самая частая причина того, что read() ничего не возвращает.
• При отправке данных всегда соблюдайте порядок: beginPacket() → write() → endPacket(). Вызов write() вне этой последовательности не даст результата.
• Если endPacket() вернул 0, проверьте Wi-Fi-соединение и правильность IP-адреса и порта получателя.
• Помните об ограничении размера пакета на AVR-платах (72 байта): если нужно передать больше данных, разбивайте их на несколько пакетов.
• Для отладки удобно выводить remoteIP() и remotePort() в Serial Monitor — так легко убедиться, что пакеты приходят от ожидаемого источника.