PlatformIO Reference

Complete reference for PlatformIO embedded development.

---

1. Installation

# Install via pip
pip install platformio

# Or via installer script
curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -o get-platformio.py
python3 get-platformio.py

---

2. Project Structure

project/
├── platformio.ini        # Project configuration
├── src/
│   └── main.cpp         # Main source file
├── include/             # Header files
├── lib/                 # Project-specific libraries
├── test/                # Unit tests
└── .pio/                # Build output (gitignored)

---

3. Configuration (platformio.ini)

Basic Structure

; Global options
[platformio]
default_envs = esp32dev
src_dir = src
include_dir = include

; Environment definition
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino

Common Platforms

Platform	Board Examples	Frameworks
espressif32	esp32dev, esp32-s3-devkitc-1	arduino, espidf
espressif8266	esp12e, d1_mini	arduino
ststm32	nucleo_f446re, bluepill_f103c8	arduino, stm32cube
raspberrypi	pico	arduino
atmelavr	uno, nanoatmega328	arduino

ESP32 Examples

; ESP32 with Arduino
[env:esp32-arduino]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
upload_speed = 921600
lib_deps = 
    bblanchon/ArduinoJson@^7.0.0

; ESP32-S3 with PSRAM
[env:esp32s3]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino
board_build.mcu = esp32s3
board_build.f_cpu = 240000000L
build_flags = 
    -DBOARD_HAS_PSRAM
    -mfix-esp32-psram-cache-issue

; ESP32 with ESP-IDF
[env:esp32-idf]
platform = espressif32
board = esp32dev
framework = espidf
monitor_speed = 115200
board_build.partitions = partitions.csv

STM32 Examples

; Nucleo F446RE
[env:nucleo_f446re]
platform = ststm32
board = nucleo_f446re
framework = arduino
upload_protocol = stlink

; Blue Pill
[env:bluepill]
platform = ststm32
board = bluepill_f103c8
framework = arduino
upload_protocol = stlink

RP2040 Examples

; Raspberry Pi Pico
[env:pico]
platform = raspberrypi
board = pico
framework = arduino

; Pico W with WiFi
[env:picow]
platform = raspberrypi
board = rpipicow
framework = arduino

---

4. CLI Commands

Building

# Build default environment
pio run

# Build specific environment
pio run -e esp32dev

# Build with verbose output
pio run -v

# Clean build
pio run -t clean

# Full clean (remove .pio)
pio run -t cleanall

Uploading

# Build and upload
pio run -t upload

# Upload to specific environment
pio run -e esp32dev -t upload

# Upload using specific port
pio run -t upload --upload-port /dev/ttyUSB0

Serial Monitor

# Start monitor
pio device monitor

# With specific baud rate
pio device monitor -b 115200

# With specific port
pio device monitor -p /dev/ttyUSB0

# Monitor with filters
pio device monitor --filter esp32_exception_decoder

Testing

# Run all tests
pio test

# Run tests for specific environment
pio test -e native

# Run specific test
pio test -f test_foo

# Verbose test output
pio test -v

Device Management

# List connected devices
pio device list

# List available boards
pio boards

# Search boards
pio boards esp32

Library Management

# Search libraries
pio pkg search "json"

# Install library
pio pkg install --library "bblanchon/ArduinoJson"

# Install specific version
pio pkg install --library "bblanchon/ArduinoJson@^7.0.0"

# List installed libraries
pio pkg list

# Update libraries
pio pkg update

---

5. Build Flags

Common Flags

build_flags = 
    -DDEBUG                    ; Define DEBUG macro
    -DVERSION=\"1.0.0\"        ; String define (escaped quotes)
    -I include/extra           ; Additional include path
    -Wall                      ; Enable all warnings
    -Wextra                    ; Extra warnings
    -O2                        ; Optimization level

ESP32-Specific

build_flags = 
    -DCORE_DEBUG_LEVEL=3       ; Debug output level (0-5)
    -DBOARD_HAS_PSRAM          ; Enable PSRAM
    -DCONFIG_ASYNC_TCP_RUNNING_CORE=1

Conditional Flags

build_flags = 
    ${env.build_flags}         ; Inherit from parent
    $BUILD_FLAGS               ; From environment variable

---

6. Library Dependencies

Syntax

lib_deps = 
    ; Library by owner/name
    bblanchon/ArduinoJson@^7.0.0
    
    ; Library by name only
    Adafruit Unified Sensor
    
    ; GitHub repository
    https://github.com/me/mylib.git
    
    ; Specific branch/tag
    https://github.com/me/mylib.git#develop
    
    ; Local library
    file:///path/to/library

Version Constraints

lib_deps = 
    library@1.2.3              ; Exact version
    library@^1.2.3             ; Compatible (>=1.2.3 <2.0.0)
    library@~1.2.3             ; Approximate (>=1.2.3 <1.3.0)
    library@>=1.0.0            ; Minimum version

---

7. Multiple Environments

Shared Configuration

[env]
; Shared across all environments
monitor_speed = 115200
lib_deps = 
    bblanchon/ArduinoJson@^7.0.0

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino

[env:esp32s3]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino
build_flags = 
    -DBOARD_HAS_PSRAM

Platform-Specific Overrides

[env:debug]
extends = env:esp32dev
build_type = debug
build_flags = 
    -DDEBUG=1
    -g3

[env:release]
extends = env:esp32dev
build_type = release
build_flags = 
    -DNDEBUG
    -O2

---

8. Testing

Test Structure

test/
├── test_main.cpp           ; Native tests
├── test_embedded/
│   └── test_gpio.cpp      ; On-device tests
└── unity.h                 ; Unity test framework (included)

Test File

#include <unity.h>

void setUp(void) {
    // Runs before each test
}

void tearDown(void) {
    // Runs after each test
}

void test_addition(void) {
    TEST_ASSERT_EQUAL(4, 2 + 2);
}

void test_string(void) {
    TEST_ASSERT_EQUAL_STRING("hello", "hello");
}

int main(int argc, char **argv) {
    UNITY_BEGIN();
    RUN_TEST(test_addition);
    RUN_TEST(test_string);
    UNITY_END();
}

Native Testing

[env:native]
platform = native
test_framework = unity

---

9. Debugging

Configuration

[env:debug]
platform = espressif32
board = esp32dev
framework = arduino
debug_tool = esp-prog
debug_init_break = tbreak setup

Debug Commands

# Start debugger
pio debug

# Start with GDB
pio debug --interface=gdb

---

10. Custom Scripts

Extra Scripts

[env:esp32dev]
extra_scripts = 
    pre:scripts/pre_build.py
    post:scripts/post_build.py

Script Example

# scripts/pre_build.py
Import("env")

def before_build(source, target, env):
    print("Before build!")

env.AddPreAction("buildprog", before_build)

---

11. Common Issues

Issue	Solution
Upload failed	Check port, try lower upload_speed
Library not found	Use full owner/name format
Build error	Clean with pio run -t clean
Wrong board	Verify board ID with pio boards

---

Note: PlatformIO supports 1000+ boards. Use pio boards <search> to find your board.