From d6e38f0abd2e1bf796a32e8b1a24d37fdc7daaf8 Mon Sep 17 00:00:00 2001 From: Krzysztof Date: Thu, 25 Aug 2016 05:01:05 +0200 Subject: [PATCH] ESP8266WiFi library documentation (#2388) * New section with ESP8266WiFi library documentation * ESP8266WiFi library documentation 1. Introduction - example, diagnostic, doxygen 2. Station - examples, new doc 3. Soft Access Point - examples, new doc 4. Scan - examples, new doc 5. Client - examples, ref. Arduino, setNoDelay, list of functions 6. Client Secure - examples, loadCertificate, setCertificate, list of functions 7. Server- examples, ref. Arduino, setNoDelay, list of functions 8. UDP - examples, ref. Arduino, Multicast UDP 9. Generic - examples, onEvent, WiFiEventHandler, persistent, mode, list of functions * Fixed numbered list --- doc/esp8266wifi/client-class.md | 65 ++ doc/esp8266wifi/client-examples.md | 256 ++++++++ doc/esp8266wifi/client-secure-class.md | 81 +++ doc/esp8266wifi/client-secure-examples.md | 172 +++++ doc/esp8266wifi/generic-class.md | 85 +++ doc/esp8266wifi/generic-examples.md | 138 ++++ .../pictures/client-example-domain.png | Bin 0 -> 23465 bytes .../client-secure-check-fingerprint.png | Bin 0 -> 18877 bytes .../pictures/doxygen-class-index.png | Bin 0 -> 29062 bytes .../doxygen-esp8266wifi-documentation.png | Bin 0 -> 81405 bytes .../doxygen-example-station-begin.png | Bin 0 -> 24536 bytes .../doxygen-example-station-hostname.png | Bin 0 -> 10284 bytes .../pictures/doxygen-example-udp-begin.png | Bin 0 -> 5157 bytes .../esp8266-arduino-build-status-json.png | Bin 0 -> 66286 bytes .../esp8266-arduino-build-status-travisci.png | Bin 0 -> 63709 bytes .../pictures/esp8266-client-secure.png | Bin 0 -> 130598 bytes doc/esp8266wifi/pictures/esp8266-client.png | Bin 0 -> 126462 bytes doc/esp8266wifi/pictures/esp8266-server.png | Bin 0 -> 115806 bytes .../pictures/esp8266-soft-access-point.png | Bin 0 -> 96750 bytes .../esp8266-station-soft-access-point.png | Bin 0 -> 120621 bytes doc/esp8266wifi/pictures/esp8266-station.png | Bin 0 -> 109389 bytes .../pictures/server-browser-output.png | Bin 0 -> 8438 bytes .../pictures/udp-packet-sender.png | Bin 0 -> 147307 bytes .../pictures/wifi-simple-connect-terminal.png | Bin 0 -> 11845 bytes doc/esp8266wifi/readme.md | 318 ++++++++++ doc/esp8266wifi/scan-class.md | 267 ++++++++ doc/esp8266wifi/scan-examples.md | 261 ++++++++ doc/esp8266wifi/server-class.md | 54 ++ doc/esp8266wifi/server-examples.md | 253 ++++++++ doc/esp8266wifi/soft-access-point-class.md | 211 ++++++ doc/esp8266wifi/soft-access-point-examples.md | 134 ++++ doc/esp8266wifi/station-class.md | 600 ++++++++++++++++++ doc/esp8266wifi/station-examples.md | 205 ++++++ doc/esp8266wifi/udp-class.md | 41 ++ doc/esp8266wifi/udp-examples.md | 198 ++++++ doc/libraries.md | 20 +- 36 files changed, 3341 insertions(+), 18 deletions(-) create mode 100644 doc/esp8266wifi/client-class.md create mode 100644 doc/esp8266wifi/client-examples.md create mode 100644 doc/esp8266wifi/client-secure-class.md create mode 100644 doc/esp8266wifi/client-secure-examples.md create mode 100644 doc/esp8266wifi/generic-class.md create mode 100644 doc/esp8266wifi/generic-examples.md create mode 100644 doc/esp8266wifi/pictures/client-example-domain.png create mode 100644 doc/esp8266wifi/pictures/client-secure-check-fingerprint.png create mode 100644 doc/esp8266wifi/pictures/doxygen-class-index.png create mode 100644 doc/esp8266wifi/pictures/doxygen-esp8266wifi-documentation.png create mode 100644 doc/esp8266wifi/pictures/doxygen-example-station-begin.png create mode 100644 doc/esp8266wifi/pictures/doxygen-example-station-hostname.png create mode 100644 doc/esp8266wifi/pictures/doxygen-example-udp-begin.png create mode 100644 doc/esp8266wifi/pictures/esp8266-arduino-build-status-json.png create mode 100644 doc/esp8266wifi/pictures/esp8266-arduino-build-status-travisci.png create mode 100644 doc/esp8266wifi/pictures/esp8266-client-secure.png create mode 100644 doc/esp8266wifi/pictures/esp8266-client.png create mode 100644 doc/esp8266wifi/pictures/esp8266-server.png create mode 100644 doc/esp8266wifi/pictures/esp8266-soft-access-point.png create mode 100644 doc/esp8266wifi/pictures/esp8266-station-soft-access-point.png create mode 100644 doc/esp8266wifi/pictures/esp8266-station.png create mode 100644 doc/esp8266wifi/pictures/server-browser-output.png create mode 100644 doc/esp8266wifi/pictures/udp-packet-sender.png create mode 100644 doc/esp8266wifi/pictures/wifi-simple-connect-terminal.png create mode 100644 doc/esp8266wifi/readme.md create mode 100644 doc/esp8266wifi/scan-class.md create mode 100644 doc/esp8266wifi/scan-examples.md create mode 100644 doc/esp8266wifi/server-class.md create mode 100644 doc/esp8266wifi/server-examples.md create mode 100644 doc/esp8266wifi/soft-access-point-class.md create mode 100644 doc/esp8266wifi/soft-access-point-examples.md create mode 100644 doc/esp8266wifi/station-class.md create mode 100644 doc/esp8266wifi/station-examples.md create mode 100644 doc/esp8266wifi/udp-class.md create mode 100644 doc/esp8266wifi/udp-examples.md diff --git a/doc/esp8266wifi/client-class.md b/doc/esp8266wifi/client-class.md new file mode 100644 index 000000000..8be1d4720 --- /dev/null +++ b/doc/esp8266wifi/client-class.md @@ -0,0 +1,65 @@ +--- +title: ESP8266WiFi Client Class +--- + +[ESP8266WiFi Library :back:](readme.md#client) + + +## Client Class + +Methods documented for [Client](https://www.arduino.cc/en/Reference/WiFiClientConstructor) in [Arduino](https://github.com/arduino/Arduino) + +1. [WiFiClient()](https://www.arduino.cc/en/Reference/WiFiClient) +2. [connected()](https://www.arduino.cc/en/Reference/WiFiClientConnected) +3. [connect()](https://www.arduino.cc/en/Reference/WiFiClientConnect) +4. [write()](https://www.arduino.cc/en/Reference/WiFiClientWrite) +5. [print()](https://www.arduino.cc/en/Reference/WiFiClientPrint) +6. [println()](https://www.arduino.cc/en/Reference/WiFiClientPrintln) +7. [available()](https://www.arduino.cc/en/Reference/WiFiClientAvailable) +8. [read()](https://www.arduino.cc/en/Reference/WiFiClientRead) +9. [flush()](https://www.arduino.cc/en/Reference/WiFiClientFlush) +10. [stop()](https://www.arduino.cc/en/Reference/WiFIClientStop) + + +Methods and properties described further down are specific to ESP8266. They are not covered in [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) documentation. Before they are fully documented please refer to information below. + + +### setNoDelay + +```cpp +setNoDelay(nodelay) +``` + +With `nodelay` set to `true`, this function will to disable [Nagle algorithm](https://en.wikipedia.org/wiki/Nagle%27s_algorithm). + +This algorithm is intended to reduce TCP/IP traffic of small packets sent over the network by combining a number of small outgoing messages, and sending them all at once. The downside of such approach is effectively delaying individual messages until a big enough packet is assembled. + +*Example:* +```cpp +clinet.setNoDelay(true); +``` + + +### Other Function Calls + +```cpp +uint8_t status () +virtual size_t write (const uint8_t *buf, size_t size) +size_t write_P (PGM_P buf, size_t size) +size_t write (Stream &stream) +size_t write (Stream &stream, size_t unitSize) __attribute__((deprecated)) +virtual int read (uint8_t *buf, size_t size) +virtual int peek () +virtual size_t peekBytes (uint8_t *buffer, size_t length) +size_t peekBytes (char *buffer, size_t length) +virtual operator bool () +IPAddress remoteIP () +uint16_t remotePort () +IPAddress localIP () +uint16_t localPort () +bool getNoDelay () +``` +Documentation for the above functions is not yet prepared. + + +For code samples please refer to separate section with [examples :arrow_right:](client-examples.md) dedicated specifically to the Client Class. diff --git a/doc/esp8266wifi/client-examples.md b/doc/esp8266wifi/client-examples.md new file mode 100644 index 000000000..a38ff37af --- /dev/null +++ b/doc/esp8266wifi/client-examples.md @@ -0,0 +1,256 @@ +--- +title: ESP8266WiFi Client Class - Sketch Examples +--- + +[ESP8266WiFi Library :back:](readme.md#client) + + +## 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](https://github.com/esp8266/Arduino/issues) repository. + + +## Table of Contents + * [Introduction](#introduction) + * [Get Connected to Wi-Fi](#get-connected-to-wi-fi) + * [Select a Server](#select-a-server) + * [Instantiate the Client](#instantiate-the-client) + * [Get Connected to the Server](#get-connected-to-the-server) + * [Request the Data](#request-the-data) + * [Read Reply from the Server](#read-reply-from-the-server) + * [Now to the Sketch](#now-to-the-sketch) + * [Test it Live](#test-it-live) + * [Test it More](#test-it-more) + * [Conclusion](#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](readme.md#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. + +```cpp +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. + +![alt text](pictures/client-example-domain.png "A web page to be retreived by the clinet program") + + +### Instantiate the Client + +Now we should declare a client that will be contacting the host (server): + +```cpp +WiFiClient client; +``` + + +### 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. + +```cpp +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](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) request as in the following lines: + +```cpp +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 (`while (client.connected())`, see below) we can read line by line and print out server's response: + +```cpp +while (client.connected()) +{ + 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. + +Once server sends all requested data it will disconnect and program will exit the `while` loop. + + +### Now to the Sketch + +Complete sketch, including a case when contention to the server fails, is presented below. + +```cpp +#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()) + { + 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. + +``` + + + + Example Domain + + + + +