platformio

PlatformIO 参考

PlatformIO 嵌入式开发完整参考。

---

1. 安装

# 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/
├── 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. 配置（platformio.ini）

基本结构

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

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

常见平台

平台	开发板示例	框架
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 示例

; 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 示例

; 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 示例

; 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 命令

构建

# 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

上传

# 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

串行监视器

# 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

测试

# 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

设备管理

# List connected devices
pio device list

# List available boards
pio boards

# Search boards
pio boards esp32

库管理

# 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 = 
    -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 专用

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

条件标志

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

---

6. 库依赖项

语法

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

版本约束

lib_deps = 
    [email protected]              ; 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. 多个环境

共享配置

[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

特定平台的覆盖配置

[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. 测试

测试结构

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

测试文件

#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();
}

原生测试

[env:native]
platform = native
test_framework = unity

---

9. 调试

配置

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

调试命令

# Start debugger
pio debug

# Start with GDB
pio debug --interface=gdb

---

10. 自定义脚本

额外脚本

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

脚本示例

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

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

env.AddPreAction("buildprog", before_build)

---

11. 常见问题

问题	解决方案
上传失败	检查端口，尝试降低 upload_speed
找不到库	使用完整的 owner/name 格式
构建错误	使用 pio run -t clean 清理
开发板错误	使用 pio boards 验证开发板 ID

---

注意： PlatformIO 支持 1000 多种开发板。使用 pio boards <search> 查找你的开发板。