ESP8266 WiFi Shield Hookup Guide

Contributors: jimblom

Using the ESP8266 AT Library

The example from the previous section -- and the others included with the library -- should go a long way towards demonstrating the usage of the SparkFun ESP8266 AT library. This section will document some of the more commonly-used functions. For more documentation check out the library's GitHub repository.

Initialization

You'll need to include two libraries at the top of any ESP8266-using Arduino sketch: <SparkFunESP8266WiFi.h> and <SoftwareSerial.h>:

language:c
#include <SoftwareSerial.h> // Include software serial library, ESP8266 library dependency
#include <SparkFunESP8266WiFi.h> // Include the ESP8266 AT library

In your setup(), to initialize the ESP8266 and make sure it's functioning, call esp8266.begin(). This function will return either true or false, indicating if communication was successful with the ESP8266.

language:c
if (esp8266.begin()) // Initialize the ESP8266 and check it's return status
    Serial.println("ESP8266 ready to go!"); // Communication and setup successful
else
    Serial.println("Unable to communicate with the ESP8266 :(");

esp8266.begin() must be called before any other ESP8266 function.

Setting Up WiFi

To connect your ESP8266 to the local WiFi network, call esp8266.connect(). This function has two parameters: a network SSID and password. For example:

language:c
int retVal;
retVal = esp8266.connect("myNetwork", "myNetworkPassword");
if (retVal < 0)
{
    Serial.print(F("Error connecting: "));
    Serial.println(retVal);
}

The connect() function will also return a value, indicating it's success. Any value greater than 0 indicates success. Any value less than 0 means there was some trouble connecting.

This function can take some time to complete -- the timeout in the library is set to 30 seconds.

After connecting, you can check your local IP address by calling esp8266.localIP(). This function will return a variable of type IPAddress.

language:c
IPAddress myIP = esp8266.localIP(); // Get the ESP8266's local IP
Serial.print(F("My IP is: ")); Serial.println(myIP);

TCP Client

Once you've connected to a network, you probably want to interact with the Internet! To use the ESP8266 as a TCP client, use the ESP8266Client class. First, create an object. You can have up to five simultaneous client's:

language:c
ESP8266Client client; // Create a client object

Once the client is created, you can call the connect() member function to connect to a destination server. This function requires two parameters: a destination server (IPAddress or String) and a destination port.

For example, to connect to sparkfun.com on port 80, after creating the client object call:

language:c
retVal = client.connect("sparkfun.com", 80); // Connect to sparkfun (HTTP port)
if (retVal > 0)
    Serial.println("Successfully connected!");

connect() will return a number greater than 0 on success, and a negative value if it fails.

Once you've connected to a server, you can use the standard stream functions to send and receive data. For example, to send an HTTP request use client.print()

language:c
client.print("GET / HTTP/1.1\nHost: example.com\nConnection: close\n\n");

Or to read what the server sends back, use client.available() and client.read():

language:c
while (client.available()) // While there's data available
    Serial.write(client.read()); // Read it and print to serial

Finally, to close a client connection, call client.stop().

The ESP8266 AT Library is capable of even more: you can set up a TCP server, turn the ESP8266 into an access point, for example. Load up one of the other examples in the library to give these other features a try.