ESP8266 Webserver: Getting query parameters

The objective of this post is to explain how to access query parameters passed in HTTP requests sent to a web server deployed in the ESP8266.

Introduction

The objective of this post is to explain how to access query parameters passed in HTTP requests sent to a web server deployed in the ESP8266.

Query parameters appear at the end of the path of the URL [1] and allow to pass additional information. The query parameters compose the query string and are separated from the path in the URL by a question mark (“?”) [1].

Each query parameter is specified in the format “ParameterName=ParameterValue”. If multiple parameters need to be passed, they should be separated with ampersands (“&”) [1].

So, an example of a URL with query parameters is shown bellow.

http://website.com/path?parameter1=value1&parameter2=value2

This can be used to pass some extra information to the ESP8266, which can be read by the handling functions of the web server.

Note that, through this tutorial, the terms query parameter and argument are used with the same meaning when referring to the values passed in the URL.

 

The code

The initializing part of the code is pretty much the same as we analysed in the previous post about setting a HTTP server in the ESP8266, so only a brief summary will be presented. We start by connecting to the WiFi network and then we define in which URLs our HTTP web server will be listening to incoming requests.

For each URL, we specify the handling function that will execute upon a request on that URL.

In this specific case, we will define 2 URLs. In the first one, we will be able to receive any number of query parameters with any name and value. Then, our handling function will build and return a message with them. The name of this URL will be genericArgs. Notice the capital “A”, which needs to be taken in consideration when accessing the URL, since it will be case sensitive.

The other URL will also receive any number of query parameters, but will look for a specific parameter name and output a “not found” message when it is not present.

We will analyze the handling functions for this 2 URLs later. Now, we can see bellow the full code to initialize the HTTP web server.

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

ESP8266WebServer server(80);   //Web server object. Will be listening in port 80 (default for HTTP)

void setup() {

Serial.begin(115200);
WiFi.begin(“YourSSID”, “YourPassword”); //Connect to the WiFi network

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

delay(500);
Serial.println(“Waiting to connect…”);

}

Serial.print(“IP address: “);
Serial.println(WiFi.localIP());  //Print the local IP to access the server

server.on(“/genericArgs”, handleGenericArgs); //Associate the handler function to the path
server.on(“/specificArgs”, handleSpecificArg);   //Associate the handler function to the path

server.begin();                                       //Start the server
Serial.println(“Server listening”);   

}

void loop() {

server.handleClient();    //Handling of incoming requests

}

Now we will analyse the code of the 2 handling functions for the URLs defined. Once again, the ESP8266WebServer library makes available easy to use functions to access the query parameters passed in the HTTP requests. The definition of the code of all the query parameter related functions is available here.

For the handler function that handles generic query parameters, we will first check how many of them were passed. To do so, we call the args method on the server object. This method will return the number of query parameters that were passed on the HTTP request that triggered the execution of the handling function.

String message = “Number of args received:”;
message += server.args();

Then, we will iterate by each parameter and print the name of the argument and the value.

We will use the argName method on the server object, which receives as a parameter an integer and will return the name of the argument in that position. The first query parameter is in position zero.

We will also use the arg method, which can also receive as a parameter an integer and returns the value of that parameter.

So, we build the for loop from 0 to the number of args – 1 (the first argument is in position zero) and append the name and value of the query parameter to our string.

for (int i = 0; i < server.args(); i++) {

message += “Arg nº” + (String)i + ” –> “;
message += server.argName(i) + “: “;
message += server.arg(i) + “\n”;

} 

Finally, we return the message built using the send method on the server object, as we did in the previous post. We return it as “text/plan” and with a HTTP OK code. 

server.send(200, “text/plain”, message);

The full code of the handling function is shown bellow.

void handleGenericArgs() { //Handler

String message = “Number of args received:”;
message += server.args();            //Get number of parameters
message += “\n”;                            //Add a new line

for (int i = 0; i < server.args(); i++) {

message += “Arg nº” + (String)i + ” –> “;   //Include the current iteration value
message += server.argName(i) + “: “;     //Get the name of the parameter
message += server.arg(i) + “\n”;              //Get the value of the parameter

} 

server.send(200, “text/plain”, message);       //Response to the HTTP request

}

Now, we will specify the function that looks for a particular parameter name and prints its value if found. In this case, we will be looking for an argument with name “Temperature”. Once again, we need to take in consideration that the argument name is case sensitive and thus if we pass “temperature” as parameter it will not be considered.

We will again call the arg method mentioned before, but this time it will receive as input argument a string containing the name of the query parameter we want to find. If not found, the function will return an empty string (corresponding to “”). If found, the function will return the value of the query parameter.

So, in our code, we will call the arg method, look for the returning value and build the returning string accordingly, to include in the response to the request. Finally, we return the response to the HTTP  with the send method, as we did in the previous handling function. The code for the whole function is shown bellow.

void handleSpecificArg() { 

String message = “”;

if (server.arg(“Temperature”)== “”){     //Parameter not found

message = “Temperature Argument not found”;

}else{     //Parameter found

message = “Temperature Argument = “;
message += server.arg(“Temperature”);     //Gets the value of the query parameter

}

server.send(200, “text/plain”, message);          //Returns the HTTP response

}

Important: When directly copying the code from the blog, a stray error may occur when trying to compile it on Arduino. In my case, this occurs because the editor assumes the wrong type of quotes. The easiest way to fix this, given the number of existing quotes, is to do a find and replace and put the correct quotes.

 

Final results

Once again, we can test our HTTP web server using a web browser such as Google Chrome. The first example, illustrated in figure 1, shows what happens when we access the “/genericArgs” URL without any query parameters.

Since we sent no parameters, the output indicates that the number of args received is zero.

Figure 1 – Result of accessing the /genericArgs URL without query parameters.

Figure 2 shows what happens if we access the same URL but now passing query parameters. In this case, we are sending 3 parameters, which represent a date. As can be seen, the output indicates that 3 args were received and then it lists the names and values of those args.

Figure 2 – Result of accessing the /genericArgs URL with 3 query parameters.

Figure 3 shows what happens if we access the /specificArg URL with a query parameter different from what we were looking for. In this case, we sent “Luminosity” instead of “Temperature”, so the answer to the HTTP request is that the “Temperature” argument is not found.

Figure 3 – Result of accessing the /specificArgs URL with the wrong query parameter.

Finally, as shown in figure 4, when we call this URL sending the correct query parameter, our handling function recognizes it and returns its value.

Figure 4 – Result of accessing the /specificArgs URL with the right query parameter.

Related posts

• ESP8266: Setting a simple HTTP webserver
• ESP8266 HTTP server: Serving HTML, Javascript and CSS

 

References

[1] http://www.ronstauffer.com/blog/understanding-a-url/

 

Technical details

• ESP8266 libraries: v2.3.0