AsyncUDP_Ethernet Library

---

---

Table of Contents

• Why do we need this AsyncUDP_Ethernet library
  • Features
  • Why Async is better
  • Currently supported Boards
• Changelog
• Prerequisites
• Installation
  • Use Arduino Library Manager
  • Manual Install
  • VS Code & PlatformIO
• HOWTO Fix Multiple Definitions Linker Error
• HOWTO Setting up the Async UDP Client
• Examples
  • 1. AsyncUDPClient
  • 2. AsyncUDPMulticastServer
  • 3. AsyncUdpNTPClient
  • 4. AsyncUdpSendReceive
  • 5. AsyncUDPServer
  • 6. multiFileProject
• Example AsyncUdpNTPClient
  • 1. File AsyncUdpNTPClient.ino
  • 2. File defines.h
• Debug Terminal Output Samples
  • 1. AsyncUdpNTPClient on ESP8266_NODEMCU_ESP12E with ESP8266_W5500 Ethernet
  • 2. AsyncUDPSendReceive on ESP8266_NODEMCU_ESP12E with ESP8266_W5500 Ethernet
  • 3. AsyncUdpNTPClient on ESP8266_NODEMCU_ESP12E with ESP8266_ENC28J60 Ethernet
• Debug
• Troubleshooting
• Issues
• TO DO
• DONE
• Contributions and Thanks
• Contributing
• License
• Copyright

---

---

Why do we need this AsyncUDP_Ethernet library

Features

This AsyncUDP_Ethernet library is a fully asynchronous UDP library, designed for a trouble-free, multi-connection network environment, for ESP8266 boards using W5x00 or ENC28J60 Ethernet using lwIP_w5100, lwIP_w5500 or lwIP_enc28j60 library.

The library is easy to use and includes support for Unicast, Broadcast and Multicast environments.

This library is based on, modified from:

1. Hristo Gochkov's ESPAsyncUDP

to apply the better and faster asynchronous feature of the powerful ESPAsyncUDP Library into ESP8266 boards using W5x00 or ENC28J60 Ethernet

Why Async is better

• Using asynchronous network means that you can handle more than one connection at the same time
• You are called once the request is ready and parsed
• When you send the response, you are immediately ready to handle other connections while the server is taking care of sending the response in the background
• Speed is OMG
• After connecting to a UDP server as an Async Client, you are immediately ready to handle other connections while the Client is taking care of receiving the UDP responding packets in the background.
• You are not required to check in a tight loop() the arrival of the UDP responding packets to process them.

Currently Supported Boards

1. ESP8266 boards using W5x00 or ENC28J60 Ethernet

---

---

Prerequisites

1. Arduino IDE 1.8.19+ for Arduino.
2. ESP8266 Core 3.0.2+ for ESP8266-based boards. .

---

Installation

The suggested way to install is to:

Use Arduino Library Manager

The best way is to use Arduino Library Manager. Search for AsyncUDP_Ethernet, then select / install the latest version. You can also use this link for more detailed instructions.

Manual Install

1. Navigate to AsyncUDP_Ethernet page.
2. Download the latest release AsyncUDP_Ethernet-main.zip.
3. Extract the zip file to AsyncUDP_Ethernet-main directory
4. Copy the whole AsyncUDP_Ethernet-main folder to Arduino libraries' directory such as ~/Arduino/libraries/.

VS Code & PlatformIO:

1. Install VS Code
2. Install PlatformIO
3. Install AsyncUDP_Ethernet library by using Library Manager. Search for AsyncUDP_Ethernet in Platform.io Author's Libraries
4. Use included platformio.ini file from examples to ensure that all dependent libraries will installed automatically. Please visit documentation for the other options and examples at Project Configuration File

---

---

HOWTO Fix Multiple Definitions Linker Error

The current library implementation, using xyz-Impl.h instead of standard xyz.cpp, possibly creates certain Multiple Definitions Linker error in certain use cases.

You can include this .hpp file

// Can be included as many times as necessary, without `Multiple Definitions` Linker Error
#include "AsyncUDP_Ethernet.hpp"         //https://github.com/khoih-prog/AsyncUDP_Ethernet

in many files. But be sure to use the following .h file in just 1 .h, .cpp or .ino file, which must not be included in any other file, to avoid Multiple Definitions Linker Error

// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
#include "AsyncUDP_Ethernet.h"           //https://github.com/khoih-prog/AsyncUDP_Ethernet

Check the new multiFileProject example for a HOWTO demo.

Have a look at the discussion in Different behaviour using the src_cpp or src_h lib #80

---

---

HOWTO Setting up the Async UDP Client

#include <AsyncUDP_Ethernet.h>

IPAddress timeWindowsCom = IPAddress(13, 86, 101, 172);

#define NTP_REQUEST_PORT      123

const int NTP_PACKET_SIZE = 48;       // NTP timestamp is in the first 48 bytes of the message

byte packetBuffer[NTP_PACKET_SIZE];   // buffer to hold incoming and outgoing packets

// A UDP instance to let us send and receive packets over UDP
AsyncUDP Udp;

// send an NTP request to the time server at the given address
void createNTPpacket(void)
{
  ...
}

void sendNTPPacket(void)
{
  createNTPpacket();
  //Send unicast
  Udp.write(packetBuffer, sizeof(packetBuffer));
}

void parsePacket(AsyncUDPPacket packet)
{
  ...
}

void setup()
{
  ...
  
  //NTP requests are to port NTP_REQUEST_PORT = 123
  if (Udp.connect(timeWindowsCom, NTP_REQUEST_PORT))
  {
    // Setting up Async packet Handler
    Udp.onPacket([](AsyncUDPPacket packet)
    {
      parsePacket(packet);
    });
  }
}

void loop()
{
  sendNTPPacket();

  // wait 60 seconds before asking for the time again
  delay(60000);
}

---

---

Examples

1. AsyncUDPClient
2. AsyncUDPMulticastServer
3. AsyncUdpNTPClient
4. AsyncUdpSendReceive
5. AsyncUDPServer
6. multiFileProject

---

Example AsyncUdpNTPClient

1. File AsyncUdpNTPClient.ino

AsyncUDP_Ethernet/examples/AsyncUdpNTPClient/AsyncUdpNTPClient.ino

Lines 12 to 202 in 8db69d3

	#include "defines.h"
	#include <time.h>
	#include <Ticker.h>
	// 0.ca.pool.ntp.org
	IPAddress timeServerIP = IPAddress(208, 81, 1, 244);
	// time.nist.gov
	//IPAddress timeServerIP = IPAddress(132, 163, 96, 1);
	#define NTP_REQUEST_PORT 123
	//char timeServer[] = "time.nist.gov"; // NTP server
	char timeServer[] = "0.ca.pool.ntp.org";
	const int NTP_PACKET_SIZE = 48; // NTP timestamp is in the first 48 bytes of the message
	byte packetBuffer[NTP_PACKET_SIZE]; // buffer to hold incoming and outgoing packets
	// A UDP instance to let us send and receive packets over UDP
	AsyncUDP Udp;
	// 600s = 10 minutes to not flooding, 60s in testing
	#define UDP_REQUEST_INTERVAL 60
	void sendNTPPacket();
	// Repeat forever, millis() resolution
	Ticker sendUDPRequest;
	// send an NTP request to the time server at the given address
	void createNTPpacket(void)
	{
	Serial.println("============= createNTPpacket =============");
	// set all bytes in the buffer to 0
	memset(packetBuffer, 0, NTP_PACKET_SIZE);
	// Initialize values needed to form NTP request
	// (see URL above for details on the packets)
	packetBuffer[0] = 0b11100011; // LI, Version, Mode
	packetBuffer[1] = 0; // Stratum, or type of clock
	packetBuffer[2] = 6; // Polling Interval
	packetBuffer[3] = 0xEC; // Peer Clock Precision
	// 8 bytes of zero for Root Delay & Root Dispersion
	packetBuffer[12] = 49;
	packetBuffer[13] = 0x4E;
	packetBuffer[14] = 49;
	packetBuffer[15] = 52;
	}
	void parsePacket(AsyncUDPPacket packet)
	{
	struct tm ts;
	char buf[80];
	memcpy(packetBuffer, packet.data(), sizeof(packetBuffer));
	Serial.print("Received UDP Packet Type: ");
	Serial.println(packet.isBroadcast() ? "Broadcast" : packet.isMulticast() ? "Multicast" : "Unicast");
	Serial.print("From: ");
	Serial.print(packet.remoteIP());
	Serial.print(":");
	Serial.print(packet.remotePort());
	Serial.print(", To: ");
	Serial.print(packet.localIP());
	Serial.print(":");
	Serial.print(packet.localPort());
	Serial.print(", Length: ");
	Serial.print(packet.length());
	Serial.println();
	unsigned long highWord = word(packetBuffer[40], packetBuffer[41]);
	unsigned long lowWord = word(packetBuffer[42], packetBuffer[43]);
	// combine the four bytes (two words) into a long integer
	// this is NTP time (seconds since Jan 1 1900):
	unsigned long secsSince1900 = highWord << 16 | lowWord;
	Serial.print(F("Seconds since Jan 1 1900 = "));
	Serial.println(secsSince1900);
	// now convert NTP time into )everyday time:
	Serial.print(F("Epoch/Unix time = "));
	// Unix time starts on Jan 1 1970. In seconds, that's 2208988800:
	const unsigned long seventyYears = 2208988800UL;
	// subtract seventy years:
	unsigned long epoch = secsSince1900 - seventyYears;
	time_t epoch_t = epoch; //secsSince1900 - seventyYears;
	// print Unix time:
	Serial.println(epoch);
	// print the hour, minute and second:
	Serial.print(F("The UTC/GMT time is ")); // UTC is the time at Greenwich Meridian (GMT)
	ts = *localtime(&epoch_t);
	strftime(buf, sizeof(buf), "%a %Y-%m-%d %H:%M:%S %Z", &ts);
	Serial.println(buf);
	}
	void sendNTPPacket()
	{
	createNTPpacket();
	//Send unicast
	Udp.write(packetBuffer, sizeof(packetBuffer));
	}
	void initEthernet()
	{
	SPI.begin();
	SPI.setClockDivider(SPI_CLOCK_DIV4);
	SPI.setBitOrder(MSBFIRST);
	SPI.setDataMode(SPI_MODE0);
	#if !USING_DHCP
	eth.config(localIP, gateway, netMask, gateway);
	#endif
	eth.setDefault();
	if (!eth.begin())
	{
	Serial.println("No Ethernet hardware ... Stop here");
	while (true)
	{
	delay(1000);
	}
	}
	else
	{
	Serial.print("Connecting to network : ");
	while (!eth.connected())
	{
	Serial.print(".");
	delay(1000);
	}
	}
	Serial.println();
	#if USING_DHCP
	Serial.print("Ethernet DHCP IP address: ");
	#else
	Serial.print("Ethernet Static IP address: ");
	#endif
	Serial.println(eth.localIP());
	}
	void setup()
	{
	Serial.begin(115200);
	while (!Serial && millis() < 5000);
	delay(200);
	Serial.print("\nStart AsyncUdpNTPClient on ");
	Serial.print(BOARD_NAME);
	Serial.print(" with ");
	Serial.println(SHIELD_TYPE);
	Serial.println(ASYNC_UDP_ETHERNET_VERSION);
	initEthernet();
	//NTP requests are to port NTP_REQUEST_PORT = 123
	if (Udp.connect(timeServerIP, NTP_REQUEST_PORT))
	//if (Udp.connect(timeServer, NTP_REQUEST_PORT))
	{
	Serial.println("UDP connected");
	Udp.onPacket([](AsyncUDPPacket packet)
	{
	parsePacket(packet);
	});
	}
	sendNTPPacket();
	sendUDPRequest.attach(UDP_REQUEST_INTERVAL, sendNTPPacket);
	}
	void loop()
	{
	}

2. File defines.h

AsyncUDP_Ethernet/examples/AsyncUdpNTPClient/defines.h

Lines 12 to 74 in 8db69d3

	#ifndef defines_h
	#define defines_h
	#if defined(ESP8266)
	#define LED_ON LOW
	#define LED_OFF HIGH
	#else
	#error Only ESP8266
	#endif
	#define _AWS_ETHERNET_LOGLEVEL_ 1
	//////////////////////////////////////////////////////////
	#define USING_W5500 true
	#define USING_W5100 false
	#define USING_ENC28J60 false
	#include <SPI.h>
	#define CSPIN 16 // 5
	#if USING_W5500
	#include "W5500lwIP.h"
	#define SHIELD_TYPE "ESP8266_W5500 Ethernet"
	Wiznet5500lwIP eth(CSPIN);
	#elif USING_W5100
	#include <W5100lwIP.h>
	#define SHIELD_TYPE "ESP8266_W5100 Ethernet"
	Wiznet5100lwIP eth(CSPIN);
	#elif USING_ENC28J60
	#include <ENC28J60lwIP.h>
	#define SHIELD_TYPE "ESP8266_ENC28J60 Ethernet"
	ENC28J60lwIP eth(CSPIN);
	#else
	// default if none selected
	#include "W5500lwIP.h"
	Wiznet5500lwIP eth(CSPIN);
	#endif
	#include <WiFiClient.h> // WiFiClient (-> TCPClient)
	using TCPClient = WiFiClient;
	//////////////////////////////////////////////////////////
	#define USING_DHCP true
	#if !USING_DHCP
	IPAddress localIP(192, 168, 2, 222);
	IPAddress gateway(192, 168, 2, 1);
	IPAddress netMask(255, 255, 255, 0);
	#endif
	#include <AsyncUDP_Ethernet.h> // https://github.com/khoih-prog/AsyncUDP_Ethernet
	#endif //defines_h

---

---

Debug Terminal Output Samples

1. AsyncUdpNTPClient on ESP8266_NODEMCU_ESP12E with ESP8266_W5500 Ethernet

This is terminal debug output when running AsyncUdpNTPClient on ESP8266_NODEMCU_ESP12E with ESP8266_W5500 Ethernet. It connects to NTP Server "0.ca.pool.ntp.org" (IPAddress(208, 81, 1, 244)) using AsyncUDP_Ethernet library, and requests NTP time every 60s. The packet is then received and processed asynchronously to print current UTC/GMT time.

Start AsyncUdpNTPClient on ESP8266_NODEMCU_ESP12E with ESP8266_W5500 Ethernet
AsyncUDP_Ethernet v1.2.1
Connecting to network : ..
Ethernet DHCP IP address: 192.168.2.188
UDP connected
============= createNTPpacket =============
Received UDP Packet Type: Unicast
From: 208.81.1.244:123, To: 192.168.2.188:56234, Length: 48
Seconds since Jan 1 1900 = 3858990229
Epoch/Unix time = 1650001429
The UTC/GMT time is Fri 2022-04-15 05:43:49 GMT
============= createNTPpacket =============
Received UDP Packet Type: Unicast
From: 208.81.1.244:123, To: 192.168.2.188:56234, Length: 48
Seconds since Jan 1 1900 = 3858990289
Epoch/Unix time = 1650001489
The UTC/GMT time is Fri 2022-04-15 05:44:49 GMT

---

2. AsyncUDPSendReceive on ESP8266_NODEMCU_ESP12E with ESP8266_W5500 Ethernet

This is terminal debug output when running AsyncUDPSendReceive on ESP8266_NODEMCU_ESP12E with ESP8266_W5500 Ethernet. It connects to NTP Server "time.nist.gov" (IPAddress(208, 81, 1, 244)) using AsyncUDP_Ethernet library, and requests NTP time every 60s. The packet is then received and processed asynchronously to print current UTC/GMT time.

Start AsyncUDPSendReceive on ESP8266_NODEMCU_ESP12E with ESP8266_W5500 Ethernet
AsyncUDP_Ethernet v1.2.1
Connecting to network : .
Ethernet DHCP IP address: 192.168.2.188

Starting connection to server...
UDP connected
============= createNTPpacket =============
Received UDP Packet Type: Unicast
From: 208.81.1.244:123, To: 192.168.2.188:63199, Length: 48
Seconds since Jan 1 1900 = 3859022269
Epoch/Unix time = 1650033469
The UTC/GMT time is Fri 2022-04-15 14:37:49 GMT
============= sendACKPacket =============

---

3. AsyncUdpNTPClient on ESP8266_NODEMCU_ESP12E with ESP8266_ENC28J60 Ethernet

This is terminal debug output when running AsyncUdpNTPClient on ESP8266_NODEMCU_ESP12E with ESP8266_ENC28J60 Ethernet. It connects to NTP Server "0.ca.pool.ntp.org" (IPAddress(208, 81, 1, 244)) using AsyncUDP_Ethernet library, and requests NTP time every 60s. The packet is then received and processed asynchronously to print current UTC/GMT time.

Start AsyncUdpNTPClient on ESP8266_NODEMCU_ESP12E with ESP8266_W5500 Ethernet
AsyncUDP_Ethernet v1.2.1
Connecting to network : ..
Ethernet DHCP IP address: 192.168.2.188
UDP connected
============= createNTPpacket =============
Received UDP Packet Type: Unicast
From: 208.81.1.244:123, To: 192.168.2.188:56234, Length: 48
Seconds since Jan 1 1900 = 3858990229
Epoch/Unix time = 1650001429
The UTC/GMT time is Fri 2022-04-15 05:43:49 GMT
============= createNTPpacket =============
Received UDP Packet Type: Unicast
From: 208.81.1.244:123, To: 192.168.2.188:56234, Length: 48
Seconds since Jan 1 1900 = 3858990289
Epoch/Unix time = 1650001489
The UTC/GMT time is Fri 2022-04-15 05:44:49 GMT

---

---

Debug

Debug is enabled by default on Serial. To disable, use level 0

#define ASYNC_UDP_ETHERNET_DEBUG_PORT      Serial

// Use from 0 to 4. Higher number, more debugging messages and memory usage.
#define _ASYNC_UDP_ETHERNET_LOGLEVEL_      0

You can also change the debugging level from 0 to 4

#define ASYNC_UDP_ETHERNET_DEBUG_PORT      Serial

// Use from 0 to 4. Higher number, more debugging messages and memory usage.
#define _ASYNC_UDP_ETHERNET_LOGLEVEL_      4

---

Troubleshooting

If you get compilation errors, more often than not, you may need to install a newer version of Arduino IDE, the Arduino STM32 core or depending libraries.

Sometimes, the library will only work if you update the STM32 core to the latest version because I am always using the latest cores /libraries.

---

---

Issues

Submit issues to: AsyncUDP_Ethernet issues

---

TO DO

1. Fix bug. Add enhancement

---

DONE

1. Initial porting and coding for ESP8266 using W5x00 or ENC28J60 Ethernet using lwIP_w5100, lwIP_w5500 or lwIP_enc28j60 library.
2. Add more examples.
3. Add debugging features.

---

---

Contributions and Thanks

1. Based on and modified from Hristo Gochkov's ESPAsyncUDP. Many thanks to Hristo Gochkov for good ESPAsyncUDP Library

⭐️⭐️ Hristo Gochkov

---

Contributing

If you want to contribute to this project:

• Report bugs and errors
• Ask for enhancements
• Create issues and pull requests
• Tell other people about this library

---

License

• The library is licensed under GPLv3

---

Copyright

• Copyright (c) 2016- Hristo Gochkov
• Copyright (c) 2022- Khoi Hoang