Today I want to share my experience setting up a development environment for the ESP8266 (specifically the ESP-12E module) using PlatformIO. If you’re transitioning from Arduino IDE or just getting started with microcontroller development, PlatformIO offers a more robust and flexible environment with better dependency management.
Setting Up PlatformIO
The first step was creating a proper platformio.ini configuration file. This file defines the board, framework, libraries, and other project settings:
[env:esp12e]
platform = espressif8266
board = esp12e
framework = arduino
monitor_speed = 9600
lib_deps =
adafruit/Adafruit GFX Library @ ^1.11.5
adafruit/Adafruit SSD1306 @ ^2.5.7
adafruit/Adafruit BusIO @ ^1.14.1
knolleary/PubSubClient @ ^2.8
; ESP8266WiFi is included in the espressif8266 platformThis configuration:
- Targets the ESP-12E board
- Uses the Arduino framework for familiar coding
- Sets the serial monitor speed to 9600 baud
- Includes libraries for an OLED display and MQTT communication
Creating a Test Program
Before diving into more complex code, I created a simple LED blink test to verify my setup was working correctly. In PlatformIO, the main code goes in src/main.cpp:
#include <Arduino.h>
// Built-in LED pin for ESP-12E (NodeMCU)
// Note: On most ESP-12E modules, the built-in LED is on GPIO2 (D4)
// and it's active LOW (turns on when pin is LOW)
const int LED_PIN = LED_BUILTIN; // Usually GPIO2 on ESP-12E
void setup() {
// Initialize serial communication
Serial.begin(9600);
Serial.println("ESP-12E LED Blink Test");
// Initialize LED pin as an output
pinMode(LED_PIN, OUTPUT);
}
void loop() {
// Turn the LED on (Note: LOW is on for ESP-12E built-in LED)
digitalWrite(LED_PIN, LOW);
Serial.println("LED ON");
delay(1000); // Wait for 1 second
// Turn the LED off
digitalWrite(LED_PIN, HIGH);
Serial.println("LED OFF");
delay(1000); // Wait for 1 second
}
This simple program toggles the built-in LED every second and sends status messages via serial communication.
Uploading the Code
Initially, I had trouble with the PlatformIO command-line interface. The pio command wasn’t recognized in my terminal. After some research, I found I needed to properly install the PlatformIO CLI:
pip install -U platformio
With PlatformIO properly installed, I could upload the code using:
pio run -t upload
The terminal output looked something like this:
Processing esp12e (platform: espressif8266; board: esp12e; framework: arduino) ---------------------------------------------------------------------------------- Verbose mode can be enabled via `-v, --verbose` option CONFIGURATION: https://docs.platformio.org/page/boards/espressif8266/esp12e.html PLATFORM: Espressif 8266 (4.2.1) > ESP-12E HARDWARE: ESP8266 80MHz, 80KB RAM, 4MB Flash PACKAGES: - framework-arduinoespressif8266 3.30102.0 (3.1.2) - tool-esptool 1.413.0 (4.13) - tool-esptoolpy 1.30000.201119 (3.0.0) - toolchain-xtensa 2.100300.220621 (10.3.0) LDF: Library Dependency Finder -> https://bit.ly/configure-pio-ldf LDF Modes: Finder ~ chain, Compatibility ~ soft Found 32 compatible libraries Scanning dependencies... No dependencies Building in release mode Compiling .pio/build/esp12e/src/main.cpp.o Linking .pio/build/esp12e/firmware.elf Building .pio/build/esp12e/firmware.bin Calculating size .pio/build/esp12e/firmware.elf text data bss dec hex filename 262736 2672 28512 293920 47c20 .pio/build/esp12e/firmware.elf Checking program size Advanced Memory Usage is available via "PlatformIO Home > Project Inspect" RAM: [===== ] 45.5% (used 37184 bytes from 81920 bytes) Flash: [==== ] 39.9% (used 265408 bytes from 1044464 bytes) Configuring upload protocol... AVAILABLE: espota, esptool CURRENT: upload_protocol = esptool Looking for upload port... Auto-detected: /dev/ttyUSB0 Uploading .pio/build/esp12e/firmware.bin esptool.py v3.0 - ESP8266 ROM Bootloader Utility Serial port /dev/ttyUSB0 Connecting.... Chip is ESP8266EX Features: WiFi Crystal is 26MHz MAC: 5c:cf:7f:xx:xx:xx Uploading stub... Running stub... Stub running... Configuring flash size... Auto-detected Flash size: 4MB Compressed 265408 bytes to 195473... Writing at 0x00000000... (7 %) Writing at 0x00004000... (15 %) Writing at 0x00008000... (23 %) Writing at 0x0000c000... (30 %) Writing at 0x00010000... (38 %) Writing at 0x00014000... (46 %) Writing at 0x00018000... (53 %) Writing at 0x0001c000... (61 %) Writing at 0x00020000... (69 %) Writing at 0x00024000... (76 %) Writing at 0x00028000... (84 %) Writing at 0x0002c000... (92 %) Writing at 0x00030000... (100 %) Wrote 265408 bytes (195473 compressed) at 0x00000000 in 17.3 seconds (effective 122.7 kbit/s)... Hash of data verified. Hard resetting via RTS pin... =============================================== [SUCCESS] Took 22.08 seconds
Accessing the Serial Monitor
After uploading the code, I needed to monitor the serial output to verify the program was running correctly. PlatformIO makes this easy with a simple command:
pio device monitor
The terminal output showed the LED status messages:
--- Terminal on /dev/cu.usbserial-1110 | 9600 8-N-1 --- Available filters and text transformations: colorize, debug, default, direct, esp8266_exception_decoder, hexlify, log2file, nocontrol, printable, send_on_enter, time --- More details at https://bit.ly/pio-monitor-filters --- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H LED OFF LED ON LED OFF LED ON LED OFF LED ON LED OFF LED ON LED OFF
This confirmed that my ESP-12E was properly programmed and running the test code.
Useful PlatformIO Commands
Throughout this process, I found several PlatformIO commands particularly helpful:
# List all available serial devices pio device list # Build the project without uploading pio run # Clean the project (remove compiled files) pio run -t clean # Upload the compiled firmware pio run -t upload # Monitor serial output pio device monitor # Build, upload and start monitoring in one command pio run -t upload && pio device monitor
Conclusion
Setting up PlatformIO for ESP8266 development was straightforward once I understood the basic workflow. The platformio.ini file provides a clear, version-controlled way to manage project dependencies, and the command-line interface offers powerful tools for building and uploading code.
The simple LED blink test confirmed that everything was working correctly, providing a solid foundation for more complex projects. Whether you’re building a home automation system, IoT device, or just experimenting with microcontrollers, PlatformIO offers a robust development environment that grows with your needs.