ESP32: mDNS address resolution

In this tutorial we will learn how to use mDNS to resolve the address of a HTTP web server hosted by the ESP32. The tests from this tutorial were done using a DFRobot’s ESP32 module integrated in a ESP32 development board.

In this tutorial we will learn how to use mDNS to resolve the address of a HTTP web server hosted by the ESP32.

For this example, I’m assuming the use of the HTTP async web server library, which was covered in detail on this previous tutorial. The mentioned tutorial explains how to install the library and how to get started using it.

In order to reach the ESP32 server, we need to know its IP address and, in most examples we have covered so far, we print that address to the console and then we use it in our browser.

Nonetheless, in more realistic scenarios, printing the IP address might not be an option. Thus, mDNS is a protocol that allows to make the resolution of locally defined names to IPs without the need for dedicated infra-structures (such as a DNS server) [1]. You can read the specification of the protocol here.

In other words, we can use a name instead of an IP in the URL to access the browser, and mDNS will allow to resolve this name into an IP address.

This protocol operates over multicast UDP [2]. Note that the “m” from mDNS stands for “multicast” [1].

It’s important to take in consideration that the device that is reaching the server also needs mDNS. I’ve tested with a Windows 10 machine and it is able to perform the resolution of the address. On older operating systems you might need to install additional software to be able to do the resolution.

Note that we don’t need to install any additional library for mDNS since it is already included with the Arduino core. The code shown here is based on the examples from the Arduino core, which I recommend you to check.

The tests from this tutorial were done using a DFRobot’s ESP32 module integrated in a ESP32 development board.

If you prefer a video version of this tutorial, please check my YouTube channel below:

The code

We will start the code by the library includes. We will need to include the ESPmDNS.h library, so we have access to the mDNS related functionalities.

Additionally, we will need the WiFi.h, to be able to connect the ESP32 to a WiFi network, and the ESPAsyncWebServer.h, so we can setup a HTTP web server to run on the ESP32.

#include <ESPmDNS.h>
#include <WiFi.h>
#include <ESPAsyncWebServer.h>

Then we will declare two variables to hold the WiFi network credentials: network name and password.

const char* ssid = "yourNetworkName";
const char* password =  "yourNetworkPass";

We will also define a variable of class AsyncWebServer, which we will use to configure our server. As input of the constructor of this class we need to pass the number of the port where the ESP32 will be listening to incoming requests. We will use port 80, which is the default HTTP port.

AsyncWebServer server(80);

Moving on to the Arduino setup, we will start by opening a serial connection and then we will connect the ESP32 to the WiFi network, using the credentials previously defined.

Serial.begin(115200);
 
WiFi.begin(ssid, password);
 
while (WiFi.status() != WL_CONNECTED) {
  delay(1000);
  Serial.println("Connecting to WiFi..");
}

Then we will take care of setting up the mDNS responder. To do so, we simply need to call the begin method on the MDNS extern variable. This variable is an object of class MDNSResponder that becomes available when we include the ESPmDNS.h library.

As input of the begin method, we need to pass a string with the hostname that we want to be resolved to the address of the ESP32. We will set this name to “esp32“.

As output, the begin method returns a Boolean value indicating if the setup procedure was successful or not. We will use that value for error checking.

if(!MDNS.begin("esp32")) {
     Serial.println("Error starting mDNS");
     return;
}

If this setup occurs successfully, then we will take care of setting up the HTTP server. We will configure a route called “/hello” that will listen to HTTP GET requests and return a simple “Hello World” message.

server.on("/hello", HTTP_GET, [](AsyncWebServerRequest *request){
    request->send(200, "text/plain", "Hello World");
});

To finalize, we simply need to call the begin method on our server object, to make it ready to listen to incoming request. The full setup function can be seen below and already includes the call to the begin method.

void setup(){
  Serial.begin(115200);
 
  WiFi.begin(ssid, password);
 
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("Connecting to WiFi..");
  }

  if(!MDNS.begin("esp32")) {
     Serial.println("Error starting mDNS");
     return;
  }
 
  Serial.println(WiFi.localIP());
 
  server.on("/hello", HTTP_GET, [](AsyncWebServerRequest *request){
    request->send(200, "text/plain", "Hello World");
  });
 
  server.begin();
}

Since we are working with an asynchronous web server, it means we don’t need to poll any object periodically in the Arduino main loop. Thus, for our example, it can be left empty.

void loop(){}

The final code can be seen below.

#include <ESPmDNS.h>
#include <WiFi.h>
#include <ESPAsyncWebServer.h>
 
const char* ssid = "yourNetworkName";
const char* password =  "yourNetworkPass";
 
AsyncWebServer server(80);
 
void setup(){
  Serial.begin(115200);
 
  WiFi.begin(ssid, password);
 
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("Connecting to WiFi..");
  }

  if(!MDNS.begin("esp32")) {
     Serial.println("Error starting mDNS");
     return;
  }
 
  Serial.println(WiFi.localIP());
 
  server.on("/hello", HTTP_GET, [](AsyncWebServerRequest *request){
    request->send(200, "text/plain", "Hello World");
  });
 
  server.begin();
}
 
void loop(){}

Testing the code

To test the code, simply compile it and upload it to your device using the Arduino IDE. When the procedure finishes, open the Serial monitor and wait for the IP address of the server to be printed. Note that we won’t need it to access the server, we are just printing it to confirm a local address was assigned to the ESP32.

Then, open a web browser of your choice and type the following in the address bar:

http://esp32.local/hello

After accessing the previous URL, the browser should reach the server and receive as output the “Hello World” message we have defined in the code. You can check the expected result in figure 1.

Message returned by the ESP32 server.
Figure 1 – Message returned by the ESP32 server.

References

[1] https://tools.ietf.org/html/rfc6762

[2] https://stackoverflow.com/questions/11835782/how-exactly-does-mdns-resolve-addresses

Leave a Reply

%d bloggers like this: