Quick Start with ESP8266 or ESP32 in the Arduino Ecosystem using PlatformIO IDE

6 min readDec 11, 2018

Want to make an IoT project, but don’t know how to start? Here is the answer.

NodeMCU is a five-dollar open-source IoT platform based on the ESP8266 Wi-Fi system on a chip. Version 3 runs on the ESP-12E (ESP8266MOD) module and it’s an easy-to-use development board equipped with analog and digital pins, a USB-to-serial adapter based on the CH340g module, and a micro USB socket.

By default, it runs Lua scripts, however, the Arduino ecosystem is more suitable for beginners because of the tons of information and libraries available. Or, if you’ve already started building a device with Arduino and need some Wi-Fi capabilities, it’d be easier to migrate your codebase to the ESP8266.

Regular coding for Arduino happens in the Arduino IDE, despite there is a more powerful solution: PlatformIO — a free and open-source ecosystem for IoT development. Here are some pros:

Faster compiling
Autocomplete
Powerful library manager
A convenient way to organize your code
IDE customization and plugins

Having these three whales: hardware, software ecosystem, and IDE — will help you to a quick start with IoT and go beyond :)

NodeMCU v3 (ESP8266)

The development board comes with built-in firmware providing the possibility to control the Wi-Fi chip with AT commands. Just unwrap your brand new NodeMCU board and plug it into your computer with a USB cable, it will blink with blue LED a couple of times.

It uses a CH340g chip to convert the serial interface to the USB, which means your computer needs drivers to work with the board. Windows 10 machines can automatically find and install appropriate drivers, but if you need here is a driver to download (WCH is a Chinese company that designed this chip).

To check that the board is working, we’ll pass some commands. You can use Serial Monitor from Arduino IDE or whatever serial terminal you like, for example, Bray’s Terminal.

Find the port detected and connect to it with the 9600 baud rate. Tap on the RST button to reset the development board and some “junk” should appear in the receive window:

Receive window after RST with 9600 baud rate

Play with baud rate (e.g. 38400, 115200) to get a line saying “ready”. My boards worked with 115200 by default:

Saying “ready” in the receive window with a 115200 baud rate

Switch to CR+LF line endings and send AT command, it should reply with OK message:

Now we can play with other commands such as:

AT+RST restarts the module
AT+GMR checks version information
AT+CWMODE?returns current mode: 1 — station, 2 — soft access point, 3 — station + soft AP
AT+CWMODE=3sets station + soft AP mode (restart module with AT+RST command after)
AT+CWJAP=”MyNetwork",”qwerty12" connects to MyNetwork with qwerty12 password, replies with WIFI CONNECTED and WIFI GOT IP messages after the connection is established
AT+CIFSR returns connection info

You can also establish a TCP connection with other devices in your network or find more commands in the ESP8266 AT Command Examples document. The board will say ERROR, if the command you sent is not supported.

PlatformIO

Let’s move on to the IDE. Proceed with the simple steps suggested on the PlatformIO website: Installation.

PlatformIO is a Visual Studio Code extension, so what you need is to install the VS Code and add the platformio-ide extension:

Give it time to do some installation magic, it’ll also pull the C/C++ extension (ms-vscode.cpptools), restart VS Code in the end and that’s it — you can code!

Code

Despite some tutorials saying it’s needed to erase/flash the board with appropriate tools, I found it unnecessary when working with PlatformIO. You are also not required to mess with the Arduino IDE board manager as well!

Just click on the PlatformIO icon on the left bar and select New Project:

Name your project, select NodeMCU 1.0 (ESP-12E Module) board and Arduino framework, use default project location or not:

Click on Finish and let it download all dependencies and build the project structure. Check the platformio.ini file:

It is the main configuration file you’ll be interested in: platform, board and framework parameters tell the PlatformIO compiler what to use to compile the project. You can also specify here project dependencies (libraries and versions), serial monitor baud rate, and many other things. More details are available here: Project Configuration File.

Let’s try to build the project, find the PlatformIO: Build button (checkmark icon) on the bottom bar, and click it to launch the build process. If everything is fine, you’ll get the same output in the terminal window:

Blink

I haven’t managed to make built-in LED work on my boards, but perhaps you’ll be luckier: it should be attached to the LED_BUILTIN pin. Let’s blink the world:

#include <Arduino.h>

void setup()
{
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop()
{
  digitalWrite(LED_BUILTIN, LOW);
  delay(500);
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
}

Click on the PlatformIO: Upload button (right arrow) to build and upload firmware to the board. Blue LED will blink until the process is completed.

External LED wiring scheme, if you need:

Wi-Fi connection

Now we can test Wi-Fi capabilities and find out how to add libraries. I suggest the WiFiManager library which provides a simple API to configure your module connection from the browser.

Go to the Libraries registry and search for wifimanager:

Click on the WifiManager by tzapu library and then on the Installation tab, it will show ways to require the library in your platformio.ini file:

Copy lib_deps = tzapu/WifiManager @ ^0.16.0 to theplatformio.ini file and modify the main.cpp code:

#include <Arduino.h>

#include <ESP8266WiFi.h>

#include <DNSServer.h>
#include <ESP8266WebServer.h>
#include <WiFiManager.h>

void setup()
{
  Serial.begin(9600);
  WiFiManager wifiManager;
  wifiManager.autoConnect("NodeMCU-Arduino-PlatformIO");
  Serial.println("Connected!");
}

void loop()
{
  Serial.println("Idle...");
  delay(1000);
}

Upload the project and open the PlatformIO: Serial Monitor window, it will initialize the Wi-Fi manager and start the HTTP server:

Go to Wi-Fi settings on your device and connect to the access point created by the board.

If it’s an Android device, you’ll be asked to “sign in to Wi-Fi network”. It’ll move you to the HTML page served by the module. If not, you can open a browser and type in AP IP address received in the Terminal window (192.168.4.1 here):

Type the SSID and password of your local network, click on Save, and check the Terminal window:

If the connection is successful, you’ll see the Idle message, which means the loop() function started its work. From that point, you’re good to go with the Internet capabilities you need in the Arduino-friendly environment!

The final project you can find on GitHub: https://github.com/loginov-rocks/ESP-Arduino-PlatformIO

Good luck with IoT projects!