ESP8266 Webserver: Resolving an address with mDNS

The objective of this post is to explain how to add mDNS address resolving to a ESP8266 HTTP server.

Introduction

The objective of this post is to explain how to add mDNS address resolving to a ESP8266 HTTP server, using the ESP8266 libraries for the Arduino IDE.

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]. The protocol works over multicast UDP [2].

The big advantage of mDNS is that we don’t need to know the IP address assigned to the ESP8266 to access the HTTP webserver running on it. On top of that, we don’t need to deploy a dedicated server just to do the resolution of names into IPs.

So, we can just define that the ESP8266 will be listening on something like “myesp.local” and we can just access the server in a web browser by typing http://myesp.local/path instead of having to know the IP address. Besides this enhancement, the HTTP web server will work the same as it did before.

In order for this example to work, the machine that is accessing the ESP8266 web server also needs to support mDNS. Otherwise, it won’t be able to send the query needed to receive the resolved IP.

So, if you are working on a Windows machine, you need to install Bounjour, and if on a Linux machine, you need to install Avahi [3]. I’ve tested the code with success on a Windows 8.1 machine with Bonjour installed.

 

The code

Most of the code will be similar to the one explained in this previous post about setting a simple HTTP server on the ESP8266.

So, we start by including the libraries necessary to connect to a WiFi network and to set the HTTP server.

#include <ESP8266WiFi.h>
#include <ESP8266WebServer.h>

Additionally, we will include the library needed for all the mDNS functionality. You can check the implementation here.

#include <ESP8266mDNS.h>

As usual, we will initialize our web server object listening on port 80 (default HTTP port).

ESP8266WebServer server(80);

Since most of the code is similar to what we have been doing in the previous tutorials, we will focus on the mDNS part. So, to start the mDNS resolver, we just need to call the begin method on an extern variable called MDNS.

This MDNS extern variable is an object of class MDNSResponder, which makes available all the functionality needed for the resolution of addresses. Nevertheless, the good part is that we don’t need to know the low level details since they are handled for us in an easy to use interface.

Bellow is the call to the mentioned begin method. We pass as the constructor the host name that will be used in the URL. Just take in consideration that the host name can’t have a length greater than 63 characters [4].

MDNS.begin(“myesp”));

The complete setup function is shown bellow. We first start by connecting to a WiFi network and only then start the MDNS functionality. Since the begin method returns false when some problem occur, we check for that value to infer if everything starts fine.

We then associate a handling function called handleRoot (we will define it latter) to the “/” path, so it is executed when a HTTP request is done to that URL.

Finally, we call the begin method on the server object to start the HTTP server.

void setup(){

Serial.begin(115200);   //Start serial connection
WiFi.begin(“YourNetworkName”, “YourNetworkPassword”); //Connect to WiFi network

while (WiFi.status() != WL_CONNECTED) {  //Wait for the connection to the WiFi network 

delay(500);
Serial.print(“.”);

}

if (MDNS.begin(“myesp”)) {  //Start mDNS

Serial.println(“MDNS started”);

}

server.on(“/”, handleRoot);  //Associate handler function to path

server.begin();                           //Start server
Serial.println(“HTTP server started”);

}

To handle the actual incoming of HTTP requests, we need to call the handleClient method on the server object, on the main loop function.

void loop(){

server.handleClient();  

}

Finally, we declare the handling function for the “/” path. In this case, we will just return a hello message to the client.

void handleRoot() {

server.send(200, “text/plain”, “Hello resolved by mDNS!”);

}

Important: If you are getting the opposite result on the LED in the on and off URLs, this may mean that the LED of your board is in an active low configuration (which is the case of the NodeMCU). In other words, the board is wired in a way that when the microcontroller output pin is in a LOW state, the LED turns on, and when it is in a HIGH state, the LED turns off.

 

Testing the code

To test if everything is working correctly, just open a web browser and type:

http://myesp.local/

You should get the output message shown in figure 1, which we defined in the handling function.

Figure 1 – ESP8266 web server response.

Note that the .local is implicitly added for us and it shouldn’t be specified in the begin method we called earlier.

Related posts

• ESP8266: Setting a simple HTTP webserver
• ESP8266: uploading code from Arduino IDE
• ESP8266: Connecting to a WiFi Network

 

References

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

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

[3] https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266mDNS

[4] https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266mDNS/ESP8266mDNS.cpp#L157

 

Technical details

ESP8266 libraries: v2.3.0