Windows系统中PlatformIO-IDE开发环境配置

0 更新记录

2023-12-04: 配置PlatformIO IDE环境，记录安装过程。
2023-12-06: 更新问题 5-1 的解决情况。
2023-12-22: 更新问题 5-1 的解决情况。
TBD

1 安装前准备

参考PlatformIO IDE的安装文档，确保满足文档中要求的环境。对于Windows系统，只需要安装VSCode即可继续安装PlatformIO IDE。

1.1 设置代理

受限于网络情况，需要设置代理来顺利地下载PlatformIO需要的附件。根据官方文档中关于代理服务器的说明，有两种方法可以配置PlatformIO IDE的代理：

在VSCode的设置中配置：在设置中搜索proxy，设置http.proxy项，并且取消勾选http.proxyStrictSSL项
设置系统环境变量：设置环境变量HTTP_PROXY，HTTPS_PROXY和PLATFORMIO_SETTING_ENABLE_PROXY_STRICT_SSL

由于还需要设置其他环境变量，这里一并使用设置系统环境变量的方法设置代理。

# 设置代理（cmd）
setx HTTP_PROXY "http://127.0.0.1:7890/"
setx HTTPS_PROXY "http://127.0.0.1:7890/"
setx PLATFORMIO_SETTING_ENABLE_PROXY_STRICT_SSL "false"
# 查看设置的变量（需重新打开命令行窗口）
echo %HTTP_PROXY%

setx 命令功能是在在用户或系统环境创建或修改环境变量，默认创建当前用户变量。在命令最后指定/M参数可以创建系统环境变量，创建系统环境变量时需要以管理员身份运行终端。

set 命令设置终端的环境变量，此处不适用。

两个代理服务器变量的值内容相同，都是以http://开头。具体的服务器地址和端口根据自己的代理软件设置情况修改。

代理服务器地址端口号后要有/斜线。

1.2 设置PlatformIO Core的安装目录

PlatformIO Core安装目录会存储所有的开发平台包（包括工具链、框架、SDK、上传和调试工具等）、全局库以及其他 PlatformIO Core 服务数据。该目录的大小会随着已安装的开发平台的数量增多而不断变大。在Windows系统中，默认的安装目录是%HOMEPATH%\.platformio。如果不希望该目录在C盘用户目录占用过多空间，可以在安装前设置通过设置环境变量PLATFORMIO_CORE_DIR指定PlatformIO Core的安装目录。如果在设置前已安装PlatformIO Core，设置环境变量后删除原来的.platformio目录，重启PlatformIO IDE(VSCode)重新安装即可生效。

1 2	# 设置PlatformIO Core安装目录 setx PLATFORMIO_CORE_DIR "D:\PIO_Core"

设置的目录需要提前创建好，安装过程不会自动创建，如果没有创建环境变量指定的路径，会自动安装到%HOMEPATH%\.platformio默认目录。

2 安装PlatformIO IDE

2.1 安装VSCode插件

在VSCode拓展商店中搜索platformio ide，安装。

安装成功后侧栏会显示PlatformIO图标，点击该图标，插件会开始下载PlatformIO Core和内置的Python解释器。

即使本机已经配置有满足条件的Python3环境（Python > 3.6, PlatformIO IDE不支持conda环境#issue914），仍然建议使用IDE插件内置的Python。

2.2 修改插件设置

打开VSCode设置，搜索platformio，找到PlatformIO IDE插件设置。修改以下设置：

勾选Disable PIOHome Startup：启动时不自动启动PlatformIO Home，PIOHome 是PlatformIO的交互式用户界面。
编辑customPyPiIndexUrl：设置IDE内置的Python解释器的pip源：https://pypi.tuna.tsinghua.edu.cn/simple/

对应的设置json为：

1 2	"platformio-ide.disablePIOHomeStartup": true, "platformio-ide.customPyPiIndexUrl": "https://pypi.tuna.tsinghua.edu.cn/simple/"

其他设置保持默认即可，这里使用在线安装PlatformIO Core（由IDE插件自动安装），不需要指定customPATH；PIO Home在浏览器中的使用体验要好于在VSCode中直接打开，这里禁止PIO Home在VSCode中自动打开，需要使用时在终端中运行pio home，在弹出的浏览器中使用PIO Home功能。

2.3 打开PlatformIO IDE插件

打开PlatformIO IDE插件，开始自动下载安装相关内容，此步骤耗时较长，代理配置正确且速度良好的情况下，大约需要1~3分钟。安装成功后提示重新加载或重启VSCode。

安装成功提示重载VSCode

3 安装后设置

3.1 安装`pio`命令

PlatformIO Core的一些设置需要使用pio命令，安装时并未自动添加到Path路径。pio命令的可执行文件安装位置在%PLATFORMIO_CORE_DIR%\penv\Scripts，其中PLATFORMIO_CORE_DIR为安装前指定的PlatformIO Core的安装目录。将这个目录添加到系统或用户Path环境变量中，可以在任意终端中使用pio命令。编辑Path环境变量建议使用图形界面操作，防止使用命令误操作覆盖原变量内容。

打开运行对话框（Win+R），输入sysdm.cpl，打开系统属性，进入高级选项卡，打开环境变量，双击Path进行编辑。添加pio命令所在路径%PLATFORMIO_CORE_DIR%\penv\Scripts。

编辑环境变量

添加完成后，重新打开一个命令行终端窗口，使用pio settings get测试，能正常列出PIO Core配置信息说明配置正常。否则可能需要重启电脑使环境变量生效。

PIO命令列出所有设置

pio命令的其他用法参考

3.2 设置默认项目目录

插件安装后新建项目的默认目录设置在当前用户的文档Documents目录，如需切换到其他目录，需要使用pio命令设置默认项目目录。

1 2	# 设置默认目录 pio settings set projects_dir "D:\PIOProjects"

PIO命令设置默认项目目录

方括号中以黄色字体显示的路径为默认路径。pio settings的其他设置项类似，如有修改，默认设置总是在当前设置后的方括号中显示。

3.3 恢复代理设置的环境变量

安装后应当恢复系统代理设置的环境变量，避免对其他程序产生影响。不过在首次创建项目和首次上传到开发板时仍需要下载一些资源，可以在创建项目、编译、下载整个流程运行成功后再恢复代理设置。恢复代理设置只需要清空或直接删除这三个环境变量即可。

# 恢复代理设置（cmd）
setx HTTP_PROXY ""
setx HTTPS_PROXY ""
setx PLATFORMIO_SETTING_ENABLE_PROXY_STRICT_SSL ""

4 构建使用Arduino框架的ESP32项目

4.1 新建项目

使用的硬件为ESP32-S3-WROOM-1-N16R8（8MB PSRAM + 16MB FLASH）开发板，由于此开发板不在PlatformIO的开发板库中，可以选用相近的硬件配置改造其配置文件支持此开发板。

在PIO Home中点击新建项目（New Project）

新建ESP32项目

项目名称 Name	开发板模型 Board	开发框架 Framework	项目路径 Location
esp32_demo	Espressif ESP32-S3-DevKitC-1-N8	Arduino	path/of/project

新建项目耗时较长，首次新建项目时，PIO会下载选定的开发框架所需的库和所选开发板模型所属的开发平台的工具链文件等。在当前项目中，这些文件约为1.9GB。下载这些文件时，仍需要按照安装PIO IED插件时的方法配置代理。

首次新建项目后，新建相同平台及相同框架下的项目则不再需要额外的下载，可以不配置代理。

如需新建其他平台或者其他框架下的项目，就需要下载新的库文件和工具链文件，需要再次配置代理以保证顺利下载。

选用esp32-s3-devkitc-1作为开发板模型新建，修改platformio.ini为：(参考文章)

[env:esp32s3]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino
; 指定为16MB的FLASH分区表
board_build.arduino.partitions = default_16MB.csv
; 指定FLASH和PSRAM的运行模式
board_build.arduino.memory_type = qio_opi
; 预定义宏，启用PSRAM
build_flags = -DBOARD_HAS_PSRAM
; 指定FLASH容量为16MB
board_upload.flash_size = 16MB

4.2 安装需要的第三方库

新版本的PlatformIO不建议使用全局方式安装库，并且直接在IDE中删除了安装到全局库的功能。在PIO Home中搜索到需要的库，只能添加到当前的项目中，库文件存储路径位于.pio\libdeps/<env-name>目录中。

搜索需要的第三方库

将库添加到项目中

将库直接存放于项目目录中，虽然有利于项目之间保持隔离，也可以放心的对第三方库进行修改。但是对于不需要修改的库，每次新建项目都需要重新安装或者复制文件，或者在想要更新所有项目中的某个库时，便显得比较麻烦。目前PIO Core（CLI）还保留着安装全局库的命令，全局安装的路径为globallib-dir，默认路径为core_dir/lib，已被标记为DEPRECATED。全局安装库的命令为：

1	pio lib -g install "bblanchon/ArduinoJson@^6.21.3"

全局安装提示WARNING

可以看到，当前命令在下个版本中也会被移除，所以不在推荐使用这个方法安装全局库。

可选的“全局”安装方法可以参考官方文档中关于指定工具包的示例，使用file://或者symlink://方式导入存储在本地的自定义全局目录中的库，二者区别在于

file://：使用复制的方式将自定义全局库目录中的库文件复制到了.pio\libdeps/<env-name>目录中，修改全局库不影响当前项目的库；
symlink://：是对自定义全局库目录中的库文件进行引用，对全局库修改时，影响所有使用symlink://的项目。

使用导入库文件目录或者ZIP包的方式导入的库，在指定路径下必须包含library.json、platform.json或package.json等属性说明文件。
一般下载到的ZIP压缩包，会多一级目录，直接引用下载的压缩包会导致IDE不能识别。

可以利用symlink://方法让PlatformIO IDE使用Arduino IDE下载的库。

使用全局安装命令pio lib -g和使用导入本地文件的方式安装后，都可以在PIO Home中进行查看和管理，如果安装后没有刷新，需要重启PIO Home。

PIO编译时的库查找顺序：

lib_dir - own/private library storage per project
libdeps_dir - project dependency storage used by Library Management
“core_dir/lib” - global storage per all projects.
Library storages built into frameworks, SDKs.

4.3 设置串口

在platformio.ini文件中添加串口配置，设置可选项参考上传设置和串口监视器设置，设置的值可以参考Arduino IDE中同类型开发板的默认配置。

; Upload firmware to device
upload_port=COM3
upload_speed=921600
; Serial monitor
monitor_port=COM3
monitor_speed=115200

4.4 编译上传

Build：编译
Upload：上传（下载到开发板）。首次进行上传时，还需要下载几个用于处理文件系统的工具，可能仍然需要代理才能够流畅下载。
Clean：删除编译产生的文件
Full Clean：删除编译产生的文件和库文件，删除后库文件会重新下载，如果对第三方库进行了修改，要慎用此功能。

5 一些问题与解决方法

1.编译出现`CreateProcess: No such file or directory`错误

在某次Windows10的安装中，安装后编译出现错误：

1 2	xtensa-esp32s3-elf-gcc: error: CreateProcess: No such file or directory *** [.pio\build\esp32-s3-devkitc-1\FrameworkArduino\esp32-hal-rgb-led.c.o] Error 1

反复点击编译，编译能够逐渐进行，出现类似的几次错误（每次在不同的文件上出现找不到文件）后能够编译完成，并且正确的下载到开发板上运行。尝试重新安装VSCode，重新安装PlatformIO IDE插件，禁用除PlatformIO IDE和C/C++插件以外的所有插件，重新安装PlatformIO Core，重新下载开发平台工具包，修改Core目录（包括不同分区），修改项目目录（包括不同分区），以及搜索到的有关于命令长度超出Windows限制的相关issues中提及的方法，均不能修复这一问题。以相同步骤在相同版本的Windows10的虚拟机中再次安装，一切运行正常。此问题尚未找到原因，也未解决。

2023-12-06 更新：通过重装系统解决了这个问题……原因仍然未知。
2023-12-22 更新：突然又出现了这个问题，排查最近安装的软件发现可能是一个网盘（有同步盘功能）客户端导致的问题，怀疑是编译产生的文件会被同步盘占用导致后续编译过程找不到文件。卸载该软件后恢复正常。

2. 在VSCode中打开PIO Home卡在Loading

关闭VSCode，在任务管理器中结束所有和VSCode、PlatformIO、pio有关的应用和后台进程，重新打开VSCode。若无效则重启电脑。

PIO Home在浏览器中的使用体验要好于在VSCode中直接打开，更好的使用方式是在终端中运行pio home，在弹出的浏览器中使用PIO Home。

本文采用署名-非商业性使用-相同方式共享 4.0 国际许可协议，转载请注明出处。