Imagine you're pilot about to fly from SF to NYC. Before even getting to the runway, a pilot must confirm a preflight prior to take-off. Pilots make sure the flaps work, fuel is available with reserves, landing gear in order, and communications with Control are operational. Just like the pilot goes through "preflight" to ensure passenger safety during flight, Ubidots too suggests a "preflight" checklist before launching your IoT solution. Verifying your the device is able to reach the internet and send/receive data is the Ubidots preflight checklist ensuring your data travels efficiently and safely with Ubidots.
This preflight checklist is for the ESP8266 module as stand alone, but this doesn't mean you can't follow this guide if you are using the ESP8266 as Wi-Fi module for a microcontroller because the steps mentioned below are the same for any ESP8266. Of course the configurations per device are different but the setup process still the same :)
The ESP8266 as Wi-Fi module boots up in the serial modem mode as it's default configuration and communicates with your microcontroller through AT commands. When your device is properly connected with the microcontroller, verify the communication of the module with using AT commands.
Verify the communication with the module using the below AT command
Command ->
AT
If everything is working properly you will receive the response below:
Response ->
OK
If you are not able to receive a Response message, verify the connections to the module.
IMPORTANT NOTE 1: As previously mentioned, this check list is for the ESP8266 module as stand alone, but remember that the steps are always the same, the only difference is that you have to use AT commands. Reference this documentation for a list of all available AT commands for the ESP8266 module. Also, reference the Ubidots REST API reference to build the requests to be sent from the module.
NOTE 2: If you're using the ESP32 this guide will serve you well too. Simply change the library import codes provided in this guide from #include <ESP8266WiFi.h> to #include <WiFi.h> and confirm all preflight check.
Setting up the ESP8266 platform in the Arduino IDE
1. Download the Arduino IDE if you not already have it. Open the Arduino IDE, select Files -> Preferences and enter http://arduino.esp8266.com/stable/package_esp8266com_index.json into Additional Board Manager URLs field. You can add multiple URLs, separating them with commas
NOTE: If you're a Mac user, please note that Arduino and File contain different drop down functions compaired to Windows users. Also, you have to install the following driver to be able to upload your NodeMCU.
2. Open Boards Manager from Tools -> Board -> Boards Manager and install esp8266 platform. To simply find the correct device, search ESP8266 within the search bar.
3. Now that the ESP8266 platform is properly installed, select the ESP8266 board from Tools > Board menu.
Espressif ESP8266 Preflight Checklist:
1. Can you connect to WiFi?
Once you have successfully set up the module, you have to confirm that it can connect with a WiFi network. In order to verify this, upload the code below into the ESP8266 using the Arduino IDE. Don't forget assign the SSID Name and the SSID Password where indicated in the code.
/********************************
* Libraries included
*******************************/
#include <ESP8266WiFi.h>
/********************************
* Constants and objects
*******************************/
char const * SSID_NAME = "...."; // Put here your SSID name
char const * SSID_PASS = "...."; // Put here your password
/********************************
* Main Functions
*******************************/
void setup() {
Serial.begin(9600);
/* Connects to AP */
WiFi.begin(SSID_NAME, SSID_PASS);
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
WiFi.setAutoReconnect(true);
Serial.println("");
Serial.println(F("WiFi connected"));
Serial.println(F("IP address: "));
Serial.println(WiFi.localIP());
}
void loop() {
}
Once the code is successfully uploaded, open the Serial Monitor to visualize the status of the connection. You will received the message "WiFi Connected" and the IP address assigned to the module if connected.
2. Can you access the Internet from your device?
If the ESP8266 can connect to a WiFi network you're able to access to Internet and can make any HTTP request without problems. In order to verify if the module can access to Internet, make a simple request to GET the variables in your Ubidots account using the code below.
Paste and upload this code into your Arduino IDE and assign the SSID name, SSID password. Can't find your Ubidots Token? Click here.
#include <ESP8266WiFi.h>
const char* ssid = "...."; // Assign the SSID name
const char* password = "...."; // Assign the SSID password
const char* host = "industrial.api.ubidots.com";
const char* token = "...."; // Assign your Ubidots Token
void setup() {
Serial.begin(115200);
delay(10);
// We start by connecting to a WiFi network
Serial.println();
Serial.println();
Serial.print("Connecting to ");
Serial.println(ssid);
/* Explicitly set the ESP8266 to be a WiFi-client, otherwise, it by default,
would try to act as both a client and an access-point and could cause
network-issues with your other WiFi-devices on your WiFi-network. */
WiFi.mode(WIFI_STA);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
Serial.println("");
Serial.println("WiFi connected");
Serial.println("IP address: ");
Serial.println(WiFi.localIP());
}
int value = 0;
void loop() {
delay(5000);
++value;
Serial.print("connecting to ");
Serial.println(host);
// Use WiFiClient class to create TCP connections
WiFiClient client;
const int httpPort = 80;
if (!client.connect(host, httpPort)) {
Serial.println("connection failed");
return;
}
// We now create a URI for the request
String url = "/api/v1.6/variables?token=";
url += token;
Serial.print("Requesting URL: ");
Serial.println(url);
// This will send the request to the server
client.print(String("GET ") + url + " HTTP/1.1\r\n" +
"Host: " + host + "\r\n" +
"Connection: close\r\n\r\n");
unsigned long timeout = millis();
while (client.available() == 0) {
if (millis() - timeout > 5000) {
Serial.println(">>> Client Timeout !");
client.stop();
return;
}
}
// Read all the lines of the reply from server and print them to Serial
while(client.available()){
String line = client.readStringUntil('\r');
Serial.print(line);
}
Serial.println();
Serial.println("closing connection");
}
Once the code is upload properly into the module, open the serial monitor to visualize the server response. If everything is working properly you will receive a successful response (200 OK)
3. Are you familiar with HTTP?
It is important know what parameters you are working with when building an IoT solution. The World Wide Web's most valuable parameter is the HTTP communication What is HTTP? HTTP means HyperText Transfer Protocol, and is the underlying protocol used by the World Wide Web to communicate between users and website requests/actions. This protocol defines how messages are formatted and transmitted, and also defines what actions browsers and web servers will take in response to various command inputs from a user (i.e. a mouse click on a webpage). All HTTP requests contain 3 indentures - URL, Headers, and Body.
HTTP is a request/response protocol. For example, when you make a request for some file on a webpage (e.g. "Get me the file 'webside.html'" ), you are sending a request and the web server sends back the response ("here is the file"). This is the same process that the ESP8266 uses as well. The ESP8266 module is sending a GET request to the Ubidots' server to retrieve the variables setup in your Ubidots account. Once the request is sent, the server sends back the response with the status of the request and the response expected which, in this case, are the variables already created in your Ubidots account.
Now that you have an idea about HTTP, let's go down the rabbit whole a little further and explore the parameters needed to build an HTTP request: URL, Headers, and Body.
URL: As everyone knows an URL is the global address of documents and other resources on the World Wide Web. The URL is the most important piece of information included in any HTTP request because this determines where exactly in the Internet you will be sending data and who you will be communicating with. Simply, when you enter an URL into your browser you are sending an HTTP command to the web server which then recalls the correct website for you to view/interact with.
Headers: The headers allow the client to identify key parameters in your HTTP request. Headers identify clearly and quickly things like: field names, field values, and size limit. Ubidots allows their users to send data in a JSON format and it's important for the server to know what type of data the client is sending in order to verify the correct coding form. In this case, one common header when working with Ubidots is
Content-Type: application/json. Here we can see the fields are identifies as Content-Type as the header type and the data being sent is in a JSON format. Ubidots only accepts data in the JSON format.
Body: The body is simply the data to be transmitted in an HTTP request. It is important to mention that the body is only used for requests that transfer data to the server, such as POST and PUT, the body is not required when using GET methods.
4. Can you send an HTTP POST request from your device?
Now that your device is connected to WiFi and has access to Internet, it's time to send an HTTP POST request from your device to Ubidots.
The structure of a POST request to Ubidots should look replicate the following:
POST /api/v1.6/devices/{LABEL_DEVICE}/?token={TOKEN} HTTP/1.1
Host: industrial.api.ubidots.com
Content-Type: application/json
Content-Length: 41
{"temperature": 28.00, "humidity": 54.00}NOTE: Please reference Ubidots REST API reference for additional information about different structure requests available in Ubidots.
In order to post data to Ubidots, paste and upload the code below into your Arduino IDE assigning the SSID name, SSID password, and your Ubidots Token where indicated:
#include <ESP8266WiFi.h>
const char* ssid = "...."; // Assign the SSID name
const char* password = "...."; // Assign the SSID password
const char* host = "industrial.api.ubidots.com";
const char* device_label = "esp8266";
const char* token = "...."; // Assign your Ubidots Token
void setup() {
Serial.begin(115200);
delay(10);
// We start by connecting to a WiFi network
Serial.println();
Serial.println();
Serial.print("Connecting to ");
Serial.println(ssid);
/* Explicitly set the ESP8266 to be a WiFi-client, otherwise, it by default,
would try to act as both a client and an access-point and could cause
network-issues with your other WiFi-devices on your WiFi-network. */
WiFi.mode(WIFI_STA);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
Serial.println("");
Serial.println("WiFi connected");
Serial.println("IP address: ");
Serial.println(WiFi.localIP());
}
int value = 0;
void loop() {
delay(5000);
++value;
Serial.print("connecting to ");
Serial.println(host);
// Use WiFiClient class to create TCP connections
WiFiClient client;
const int httpPort = 80;
if (!client.connect(host, httpPort)) {
Serial.println("connection failed");
return;
}
// We now create a URI for the request
String url = "/api/v1.6/devices/";
url += device_label;
url += "/?token=";
url += token;
// We now create the body to be posted
String body = "{\"temperature\": 28.00, \"humidity\": 54.00}";
Serial.print("Requesting URL: ");
Serial.println(url);
// This will send the request to the server
client.print(String("POST ") + url + " HTTP/1.1\r\n" +
"Host: " + host + "\r\n" +
"Content-Type: application/json\r\n" +
"Content-Length: 41\r\n" +
"Connection: close\r\n\r\n" +
body + "\r\n\r\n");
unsigned long timeout = millis();
while (client.available() == 0) {
if (millis() - timeout > 5000) {
Serial.println(">>> Client Timeout !");
client.stop();
return;
}
}
// Read all the lines of the reply from server and print them to Serial
while(client.available()){
String line = client.readStringUntil('\r');
Serial.print(line);
}
Serial.println();
Serial.println("closing connection");
}
Once the code is upload properly into the module, open the serial monitor to visualize the server response. If everything running properly you will receive a successful response (200 OK) and the data will be posted to your Ubidots account. You can visualize this confirmation by accessing your Ubidots account to find a new device created and titled "esp8266":
Result
If you follow all the above steps to success, you can be confident your ESP8266 is operating properly and you are now ready to design personalized IoT applications with your ESP8622 and Ubidots.
This guide helps users with setup and early troubleshooting for the Espressif ESP8266 module. For more on Ubidots and the ESP8266, reference the below libraries for quick tips and tricks to take advantage of your ESP8266 model.
Happy hacking!