Connecting an ESP8266-based module to the Cloud using Arduino

Part I — PlatformIO

This is the first article in a series about using the ESP8266 chip to communicate with the Cloud4RPi service.

Requirements

• A programmable ESP8266-based module with a USB-UART adapter (for instance, NodeMCU DevKit).
• PlatformIO.
• Visual Studio Code or Atom text editor (for PlatformIO IDE).
• cloud4rpi-esp-arduino library.
• Cloud4RPi web service.

Why PlatfromIO ?

In this project, we use the PlatformIO IDE instead of a traditional Arduino IDE. The PlatformIO is an open-source IoT ecosystem, whose IDE is based on two of the most powerful modern code editors.

The main advantage of the PlatformIO is its ability to support multiple hardware platforms in a single project (the full list of available platforms).

The PlatformIO IDE allows you to compile code, upload the output, and communicate with your board using a Serial Port in a single window.

The official documentation provides detailed instructions for Visual Studio Code and Atom editors.

Creating a PlatformIO Project

1. Open PlatformIO Home and use select New Project.
2. Select your board (if you cannot find your board, select any ESP8266-based board, for instance, NodeMCU 1.0)
3. Select the Arduino framework and click Finish.

The generated platformio.ini file looks as follows:

[env:nodemcuv2]
platform = espressif8266
board = nodemcuv2
framework = arduino

Cloud4RPi Client Library Installation

You can find possible installation options on the PlatformIO Libraries Registry in the library’s Installation section.

You can open this page in PlatformIO IDE and find cloud4rpi-esp-arduino on the Libraries page:

This page contains information including examples, GitHub Repository link, installation options, etc.

Project Configuration

1. Add the Cloud4RPi library to the project dependencies in the platformio.ini file:

[env:nodemcuv2]
; ...

lib_deps =
    cloud4rpi-esp-arduino

2. Add the required build flags to increase MQTT messages’ maximum length and enable the debugging information output:

build_flags =
; Required for PubSub library
-D MQTT_MAX_PACKET_SIZE=1024
-D MQTT_MAX_TRANSFER_SIZE=128
; Enables the verbose output to Serial
-D CLOUD4RPI_DEBUG=1

Writing the Code

Connecting to Wi-Fi

First, you should add a function that connects to the Internet and maintains this connection. You can use the following code for this:

// ...
#include <ESP8266WiFi.h>
char wifiSSID[] = "__SSID__";
char wifiPassword[] = "__PASSWORD__";

void ensureWiFiConnection() {
    if (WiFi.status() != WL_CONNECTED) {
        WiFi.begin(wifiSSID, wifiPassword);
        while (WiFi.status() != WL_CONNECTED) {
            Serial.println("Connecting to Wi-Fi...");
            delay(2000);
        }
        Serial.print("Connected! IP: ");
        Serial.println(WiFi.localIP());
    }
}

void setup() {
    Serial.begin(9600);
    ensureWiFiConnection();
}

void loop() {
    ensureWiFiConnection();
}

Remember to change the connection parameters to your actual Wi-Fi network data before compiling the code.

Connecting to Cloud4RPi

1. Obtain a personal Device Token from cloud4rpi.io to access the service from your device.
2. Create the Cloud4RPi class instance. The constructor accepts the Device Token as a parameter.
3. Pass the WiFiClient instance to it using the begin() method so that the Cloud4RPi client can use the Internet connection.
4. Call the ensureConnection() method to connect to the cloud service via the MQTT protocol.

// ...
#include <Cloud4RPi.h>
const String deviceToken = "__YOUR_DEVICE_TOKEN__";

Cloud4RPi c4r(deviceToken);
WiFiClient wifiClient;

void setup() {
    // ...
    c4r.begin(wifiClient);
    if (c4r.ensureConnection()) {
        c4r.printLogo();    
    }
}

The printLogo() method sends the ASCII-art logo to the serial port, which means the library is successfully initialized and the cloud connection is established.

Running the Code

Now we are ready to compile the firmware and flash it onto the board’s memory chip.

You can compile a project using the Build button in the PlatformIO IDE, or by executing the run command in the terminal (learn details).

You should switch your board to flashing mode to upload firmware. Refer to your board’s documentation to learn how to enter flashing mode. In general, you should power the ESP8266 chip with its GPIO0 pin pulled down to GND. The drivers for a USB-UART adapter are also required. For instance, you can find the NodeMCU board’s CP2102 adapter drivers on the Silicon Labs official website if they did not install automatically.

Connect the board in flashing mode, make sure the new serial port appeared in your system, and use the Upload button to start flashing your new firmware. A successful upload looks like this:

Next, open the Serial Monitor to see your program’s output. You should have the similar output if everything works correctly:

You can get the code and the configuration files from this gist.

Conclusion

This article describes how to prepare an environment for a new cloud4rpi-enabled project. In the coming articles, we are going to describe how to connect sensors, send the data and debugging information to the cloud service, control a device from the cloud by processing the received commands, etc.

Looking forward to your questions and comments.