Client¶
Let’s write a simple client program to access a single web page and display its contents on a serial monitor. This is typical operation performed by a client to access server’s API to retrieve specific information. For instance we may want to contact GitHub’s API to periodically check the number of open issues reported on esp8266/Arduino repository.
Table of Contents¶
- Introduction
- Get Connected to Wi-Fi
- Select a Server
- Instantiate the Client
- Get Connected to the Server
- Request the Data
- Read Reply from the Server
- Now to the Sketch
- Test it Live
- Test it More
- Conclusion
Introduction¶
This time we are going to concentrate just on retrieving a web page contents sent by a server, to demonstrate basic client’s functionality. Once you are able to retrieve information from a server, you should be able to phrase it and extract specific data you need.
Get Connected to Wi-Fi¶
We should start with connecting the module to an access point to obtain an access to internet. The code to provide this functionality has been already discussed in chapter Quick Start . Please refer to it for details.
Select a Server¶
Once connected to the network we should connect to the specific server. Web address of this server is declared in host character string as below.
const char* host = "www.example.com";
I have selected www.example.com domain name and you can select any other. Just check if you can access it using a web browser.
Instantiate the Client¶
Now we should declare a client that will be contacting the host (server):
Get Connected to the Server¶
In next line we will connect to the host and check the connection result. Note 80 , that is the standard port number used for web access.
if (client.connect(host, 80)) // we are connected to the host! > else // connection failure >
Request the Data¶
If connection is successful, we should send request the host to provide specific information we need. This is done using the HTTP GET request as in the following lines:
client.print(String("GET /") + " HTTP/1.1\r\n" + "Host: " + host + "\r\n" + "Connection: close\r\n" + "\r\n" );
Read Reply from the Server¶
Then, while connection by our client is still alive or while data are available to read ( while (client.connected() || client.available()) , see below) we can read line by line and print out server’s response:
while (client.connected() || client.available()) if (client.available()) String line = client.readStringUntil('\n'); Serial.println(line); > >
The inner if (client.available()) is checking if there are any data available from the server. If so, then they are printed out.
Data can be unavailable while the TCP connection is still alive. That means data could be later received.
Once server sends all requested data it will disconnect, then once all received data are read, program will exit the while loop.
Now to the Sketch¶
Complete sketch, including a case when contention to the server fails, is presented below.
#include const char* ssid = "********"; const char* password = "********"; const char* host = "www.example.com"; void setup() Serial.begin(115200); Serial.println(); Serial.printf("Connecting to %s ", ssid); WiFi.begin(ssid, password); while (WiFi.status() != WL_CONNECTED) delay(500); Serial.print("."); > Serial.println(" connected"); > void loop() WiFiClient client; Serial.printf("\n[Connecting to %s . ", host); if (client.connect(host, 80)) Serial.println("connected]"); Serial.println("[Sending a request]"); client.print(String("GET /") + " HTTP/1.1\r\n" + "Host: " + host + "\r\n" + "Connection: close\r\n" + "\r\n" ); Serial.println("[Response:]"); while (client.connected() || client.available()) if (client.available()) String line = client.readStringUntil('\n'); Serial.println(line); > > client.stop(); Serial.println("\n[Disconnected]"); > else Serial.println("connection failed!]"); client.stop(); > delay(5000); >
Test it Live¶
Upload sketch the module and open serial monitor. You should see a log similar to presented below.
First, after establishing Wi-Fi connection, you should see confirmation, that client connected to the server and send the request:
Connecting to sensor-net . connected [Connecting to www.example.com . connected] [Sending a request]
Then, after getting the request, server will first respond with a header that specifies what type of information will follow (e.g. Content-Type: text/html ), how long it is (like Content-Length: 1270 ), etc.:
[Response:] HTTP/1.1 200 OK Cache-Control: max-age=604800 Content-Type: text/html Date: Sat, 30 Jul 2016 12:30:45 GMT Etag: "359670651+ident" Expires: Sat, 06 Aug 2016 12:30:45 GMT Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT Server: ECS (ewr/15BD) Vary: Accept-Encoding X-Cache: HIT x-ec-custom-error: 1 Content-Length: 1270 Connection: close
End of header is marked with an empty line and then you should see the HTML code of requested web page.
(. )[Disconnected]Example Domain
This domain is established to be used for illustrative examples in documents. You may use this domain in examples without prior coordination or asking for permission.
More information.
Test it More¶
In case server’s web address is incorrect, or server is not accessible, you should see the following short and simple message on the serial monitor:
Connecting to sensor-net . connected [Connecting to www.wrong-example.com . connection failed!]
General client loop¶
Here is a general TCP sending / receiving loop:
while (client.available() || client.connected()) if (client.available()) // client.available() bytes are immediately available for reading // warning: reading them *allows* peer to send more, so they should // be read *only* when they can immediately be processed, see below // for flow control > if (client.connected()) if (client.availableForWrite() >= N) // TCP layer will be able to *bufferize* our N bytes, // and send them *asynchronously*, with by default // a small delay if those data are small // because Nagle is around (~200ms) // unless client.setNoDelay(true) was called. // // In any case client.write() will *never* block here > else // or we can send but it will take time because data are too // big to be asynchronously bufferized: TCP needs to receive // some ACKs to release its buffers. // That means that write() will block until it receives // authorization to send because we are not in a // multitasking environment // It is always OK to do this, client.availableForWrite() is // only needed when efficiency is a priority and when data // to send can wait where they currently are, especially // when they are in another tcp client. // Flow control: // It is also important to know that the ACKs we are sending // to remote are directly generated from client.read(). // It means that: // Not immediately reading available data can be good for // flow control and avoid useless memory filling/overflow by // preventing peer from sending more data, and slow down // incoming bandwidth // (tcp is really a nice and efficient beast) > > // this is necessary for long duration loops (harmless otherwise) yield(); >
Conclusion¶
With this simple example we have demonstrated how to set up a client program, connect it to a server, request a web page and retrieve it. Now you should be able to write your own client program for ESP8266 and move to more advanced dialogue with a server, like e.g. using HTTPS protocol with the Client Secure .
For more client examples please check
- WiFiClientBasic.ino — a simple sketch that sends a message to a TCP server
- WiFiClient.ino — this sketch sends data via HTTP GET requests to data.sparkfun.com service.
For the list of functions provided to manage clients, please refer to the Client Class :arrow_right: documentation.
© Copyright 2017, Ivan Grokhotkov Revision 951aeffa .