极客油画

PlatformIO 命令行教程

PlatformIO Core 是一个跨平台的嵌入式开发工具链，通过命令行接口提供统一的开发体验。以下是完整的命令行操作指南。

一、安装 PlatformIO Core

1. 安装

通过官方脚本安装（推荐）

1
2

# 使用 Python 安装脚本
python -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py)"

或者使用uv命令来安装：

1

uv pip install platformio

2. 验证安装

1
2
3
4
5

# 查看版本信息
pio --version

# 查看帮助
pio --help

二、项目创建与初始化

1. 创建新项目

1
2
3
4
5
6
7
8

# 创建项目并指定开发板
pio project init --board <开发板型号>

# 示例：创建 ESP32 项目
pio project init --board esp32dev --framework arduino

# 示例：创建 STM32 项目
pio project init --board genericSTM32H7xx

2. 项目目录结构

项目根目录/
├── .pio/              # 编译产物和临时文件
├── src/               # 源代码目录
│   └── main.cpp      # 主程序文件
├── lib/               # 库文件目录
├── test/              # 测试代码目录
├── platformio.ini     # 项目配置文件
└── .gitignore         # Git 忽略文件

3. 查看支持的开发板

1
2
3
4
5
6

# 列出所有支持的开发板
pio boards

# 搜索特定开发板
pio boards uno
pio boards esp32

三、核心开发命令

1. 编译项目

1
2
3
4
5
6
7
8
9

# 编译当前项目（自动读取 platformio.ini）
pio run

# 指定环境编译（platformio.ini 中有多个环境时）
pio run -e <环境名>
pio run -e esp32dev

# 清理编译文件
pio run -t clean

2. 烧录固件

1
2
3
4
5
6
7
8
9

# 编译并烧录
pio run -t upload

# 仅烧录（不重新编译）
pio run -t upload -t nobuild

# 指定烧录端口
pio run --upload-port /dev/cu.usbmodemXXXX  # macOS
pio run --upload-port COM3                  # Windows

3. 串口监控

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 启动串口监控
pio device monitor

# 设置波特率
pio device monitor -b 115200

# 查看可用串口设备
pio device list

# 高级监控功能
pio device monitor -f time      # 启用时间戳
pio device monitor -f hexlify   # 十六进制显示

四、库管理命令

1. 库操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 搜索库
pio lib search <库名>
pio lib search "Adafruit SSD1306"

# 安装库
pio lib install <库名>
pio lib install "Adafruit SSD1306"

# 查看已安装库
pio lib list

# 更新库
pio lib update

# 卸载库
pio lib uninstall <库名>

2. 依赖管理（platformio.ini 配置示例）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

# 库依赖配置
lib_deps = 
    bblanchon/ArduinoJson@6.18.5        # 精确版本
    adafruit/Adafruit NeoPixel@^1.7.0   # 兼容版本
    file://../my_local_lib              # 本地库
    https://github.com/username/repo.git # Git仓库

五、多环境配置

1. platformio.ini 多环境示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

; 通用配置
[common]
build_flags = -DDEBUG
lib_deps = ArduinoJson

; Arduino Uno 配置
[env:uno]
platform = atmelavr
board = uno
framework = arduino
extends = common

; ESP32 开发配置
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
extends = common

; ESP32 生产配置
[env:esp32prod]
platform = espressif32
board = esp32dev
framework = arduino
build_flags = ${common.build_flags} -DRELEASE -Os
lib_ignore = ${common.lib_deps}

2. 多环境操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 编译所有环境
pio run

# 仅编译特定环境
pio run -e esp32dev

# 清理特定环境的构建缓存
pio run -t clean -e esp32prod

# 运行特定环境的单元测试
pio test -e esp32dev

六、高级功能

1. 调试功能

1
2
3
4
5
6
7
8

# 启动调试会话（需配置 platformio.ini）
pio debug

# platformio.ini 调试配置示例
[env:debug_env]
debug_tool = stlink
debug_port = /dev/ttyACM0
upload_protocol = stlink

2. 静态代码分析

1
2
3
4
5

# 运行代码检查
pio check

# 启用 Clang Tidy 分析
pio check --enable=clangtidy --flags="-checks=*"

3. 单元测试

1
2
3
4
5
6
7
8
9

# 运行所有测试
pio test

# 运行特定环境的测试
pio test -e native

# 生成测试覆盖率报告
pio test --environment native --coverage
# 报告位置：.pio/build/native/htmlcov/index.html

4. 远程开发

1
2
3
4
5

# 启动远程代理
pio remote agent start --name my-device

# 远程编译并调试
pio remote run --target debug --environment nodemcu-32s

5. 项目依赖锁定

1
2
3
4
5
6

# 生成依赖锁定文件
pio pkg lock

# 根据锁定文件安装依赖
pio pkg install --locked
# 锁定文件：platformio.lock

七、实用技巧

1. 并行编译优化

1
2
3

[env:myenv]
board = esp32dev
build_flags = -j4  # 启用4线程并行编译

效果：大型项目编译时间减少40-60%

2. 自定义构建脚本

创建 platformio-build.py 文件扩展构建流程：

1
2
3
4
5
6
7
8

from platformio.builder.tools.piolib import LibraryBuilder

def post_build(source, target, env):
    # 构建后自动生成版本信息文件
    with open("version.h", "w") as f:
        f.write(f'#define VERSION {env.GetProjectOption("version")}')
    
env.AddPostAction("$BUILD_DIR/program.bin", post_build)

3. IDE 项目生成

1
2
3
4

# 生成不同 IDE 的项目文件
pio project init --ide clion     # CLion
pio project init --ide eclipse   # Eclipse
pio project init --ide vscode    # VS Code

八、常用命令速查表

命令 功能说明
pio --version 查看版本信息
pio boards 列出所有支持的开发板
pio project init --board <id> 创建新项目
pio run 编译项目
pio run -t upload 编译并上传
pio run -t clean 清理编译产物
pio device list 列出连接的设备
pio device monitor 监控设备串口
pio lib search <name> 搜索库
pio lib install <name> 安装库
pio test 运行单元测试
pio check 静态代码分析
pio update 更新 PlatformIO 核心和库
pio home 在浏览器中打开 PlatformIO Home

九、最佳实践建议

  1. 版本控制：将 platformio.ini 和 src/ 目录纳入版本控制，忽略 .pio/ 和构建产物。
  2. 环境分离：使用多环境配置区分开发、测试和生产版本。
  3. 依赖锁定：在团队协作中使用 pio pkg lock 确保依赖一致性。
  4. CI/CD集成：在 GitHub Actions 等 CI 平台中集成 PlatformIO 命令实现自动化构建。
  5. 调试准备：提前配置好调试工具和协议，便于快速定位问题。

PlatformIO 命令行工具遵循 Unix 哲学，每个命令职责单一，可通过管道组合形成复杂自动化脚本，极大提高了嵌入式开发的效率和可维护性。

本文发表于 0001-01-01，最后修改于 0001-01-01。

本站永久域名「 jiavvc.top 」，也可搜索「 极客油画 」找到我。

上一篇 « 下一篇 »

赞赏支持

请我吃鸡腿 =^_^=

i ysf

云闪付

i wechat

微信

推荐阅读

位图

发表于2021-07-17， 阅读约1分钟

Untitled

发表于0001-01-01， 阅读约17分钟

Untitled

发表于0001-01-01， 阅读约2分钟

Big Image