说在前面

最近刷 DFRobot 论坛时，又重温了铁熊老师的一些文章，其中有一个系列：“用 Arduino 玩转掌控板”让我觉得这是一种学习掌控板的新方式。

整个系列的文章从基础到深入，从理论到项目安排的非常好。铁熊老师是在 2020 年完成的这个系列，自然使用的掌控板还是掌控板2.0 ，正巧最近不知道应该拿掌控板3.0 做些什么，手上也没什么特别着急的项目，就动了给掌控板3.0 搭建 Arduino 环境的想法。

值得庆幸的是，掌控板3.0 官方文档里已经提供了搭建 Arduino 环境最基础的教程和配置包，这为我的探索节省了大量的时间（我专门试了一下，ESP32S3 Dev Module 根本用不了，刷入后无法正常启动），本篇文章也就不重复造轮子了，在搭建开发环境方面主要就围绕文档所写的方案来，但是我会补充更多我在其中的经历，为你分享我在其中遇到的一些问题，以及我是如何解决的，希望你看的开心 o(￣▽￣)ブ

本篇文章假设你已经正确配置了 VSCode 和 Python3 环境，本篇文章使用 Windows 11 进行环境配置。

安装 PlatformIO

简单介绍

PlatformIO 是一个集成开发环境，本质上它没有自创任何实质功能，你可以理解为，它是一个快递包装盒，包装了两种开发框架（Arduino 和 ESP-IDF），包装了编译器，包装了调试器，以及更多。

在下文中，为了方便书写和理解，我将使用缩写 PIO 来代替部分 PlatformIO。

访问 PIO 官网你可以知道其以插件的形式支持了很多 IDE/文本编辑器，比如下面这些：

Atom
CLion
CodeBlocks
Qt Creator
Sublime Text
Vim
Visual Studio

提一嘴，PIO 的官网拥有一些不便评论的政治方面的标语，请自行忽略，至少我只想一心搞技术 (￣﹃￣)

不过这一回我所使用的环境是 VSCode，这算是一个比较轻量级的文本编辑器（值得一提的是它使用 Electron 构建，所以好像也并不怎么轻量）

Arduino 应该不需要我多说了，这是一款开源电子原型平台。如果你还需要更多关于 PIO 和 Arduino 的介绍，可以自行使用搜索引擎，也可以去掌控板3.0文档 - 掌控板C/C++编程 6.1 概述阅读相关内容（这一段我怀疑是用 LLM 写的，不过写的还不错 (￣﹃￣)）

安装插件（包括自动配置 PIO Core 部分）

在 VSCode 侧边栏打开拓展页，搜索 PlatformIO 进行安装，注意认准发布者为 PlatformIO 的那一款插件。

这一步安装起来问题应该不会太大，在安装完插件后，会自动开始准备 Python 环境和 PIO Core，如果这一步等待时间很长，可以尝试按以下方式给这个特别环境下的 Pip 换源：

特别环境下 Pip 换源

为什么说是特别环境呢，因为 PlatformIO 使用自己的 Python 虚拟环境。

打开 %USERPROFILE%\.platformio\penv\pip.conf，将原先内容覆盖成以下内容：

1 2	[global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple

保存，关闭 VSCode 窗口，注意在此之后打开任务管理器，关闭所有 Python 相关进程，彻底结束下载。

如果还是不行？

如果在做完换源这一步之后依旧等待很长时间没有动静，你可以试试使用网上一些小伙伴们提供的离线包或者命令行安装 PIO Core 的方式，篇幅问题，这里不重新赘述。

这一步完成后

VSCode 窗口下应该自动打开 PIO Home 页面，就像这样：

准备开发框架和工具链

在使用官方配置文件之前，我们需要先自己准备开发框架和工具链。在掌控板3.0下我们需要这些：

framework-arduinoespressif32
toolchain-riscv32-esp
toolchain-xtensa-esp32s3

当然，或许还有与这些存在依赖关系的一些未列出的工具链，但这些是最核心的。

Labplus 支持了使用 PIO 对掌控板3.0 进行开发，但支持方式有些奇怪。他们并未把配置文件提交给 PIO，这意味着我们需要自己找到配置文件放置的文件夹然后把它们放进去。这一点在官方文档里已经指明了。

但是有些小伙伴找了一圈根本没有找到这些文件夹，这其实就是没有自行准备开发框架和工具链。这一点在官方文档里面就一句话：让你先按照下面的章节创建一个 ESP32-S3 项目。

本质上这就是在为你自己准备开发框架和工具链，因为在你根据已有配置创建一个 PIO 项目时，PIO 会根据这个配置文件指明的内容下载和配置这些依赖，以我们掌控板3.0 的 PIO 配置为例：

{
  "build": {
    "arduino": {
      "ldscript": "esp32s3_out.ld",
      "memory_type": "qio_qspi",
      "partitions": "default_16MB.csv"
    },
    "core": "esp32",
    "extra_flags": [
      "-DARDUINO_ESP32_S3R8N16",
      "-DBOARD_HAS_PSRAM",
      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
    "f_cpu": "240000000L",
    "f_flash": "80000000L",
    "flash_mode": "qio",
    "hwids": [
      [
        "0x303A",
        "0x1001"
      ]
    ],
    "mcu": "esp32s3",
    "variant": "mpython_V3_ESP32S3"
  },
  "connectivity": [
    "bluetooth",
    "wifi"
  ],
  "debug": {
    "openocd_target": "esp32s3.cfg"
  },
  "frameworks": [
    "arduino",
    "espidf"
  ],
  "name": "mpython_esp32s3_v3",
  "upload": {
    "flash_size": "16MB",
    "maximum_ram_size": 327680,
    "maximum_size": 16777216,
    "require_upload_port": true,
    "speed": 460800
  },
  "url": "https://www.mpython.cn/",
  "vendor": "mpython"
}

可以看到这其中指明了设备所使用的 MCU，上传参数，Flash 访问模式，能使用的开发框架等等。

官方文档中的逻辑有点不明确，不妨按照我给出的步骤来做

安装芯片包

这一步可能不是必要的，具体我记不清了，可以先尝试打开 %USERPROFILE%\.platformio\platforms\espressif32\boards，若目录存在且不为空，请直接跳转到下一个步骤

打开 PIO Home（侧边栏点击 PIO 图标，在 QUICK ACCESS -> PIO Home 中选择 Open），点击 Platfroms，安装 Espressif 32，这一步应该不会太艰难，需要耐心等待，若十分钟依旧无结果，可以尝试科学上网。

这一步之后你会得到一两个工具链，但这不是这一步我们的目的，我们的目的是为了 %USERPROFILE%\.platformio\platforms\espressif32\boards 目录

偷梁换柱 - 获得开发框架和工具链

回到 PIO Home，点击 New Project，选择一个包含 ESP32-S3 字样的开发板并完成项目创建

其实写这篇文章的时候我想到既然我们已经准备好了 %USERPROFILE%\.platformio\platforms\espressif32\boards 目录，可以先把配置文件（.json）放进去，再选择这个配置文件创建项目。但这种方法我没有试过，可以尝试一下。

若你成功的熬过来等待，进入了项目，那么恭喜你你一步登天了 (^///^)，请直接去到“放置配置文件”章节。

但是，我猜你大概率会卡在这里，因为我和我几个朋友都在这里卡过一回。

很奇怪，我第一回玩 PIO 的时候很顺畅的就过了，后来官方没法配置文件我懒得折腾了就把 PIO 的相关目录删掉了，再重新来配置到这里的时候就卡住了

另外一位就更惨了，他第一回就卡着了，卡了整整一天，开了一天的科学上网…

手动配置

事已至此坐以待毙是没有用的，我那一回第一时间想到的就是 手动配置。怎么个配置法呢？我找到了这样一篇文章：

（文章链接我找不到了 ¯_(ツ)_/¯）

算了我来说，这篇文章大概讲了一下如何获取到这些本该从国内访问非常慢的国外服务器下载的工具链，这里我在那篇短文的基础上做一些实战环境下的补充

我们以最重要的部分：开发框架 framework-arduinoespressif32 为例：

在 PIO Registry 上找到 framework-arduinoespressif32，链接：platformio/framework-arduinoespressif32: Arduino Wiring-based Framework for the Espressif ESP32, ESP32-S and ESP32-C series of SoCs

然后我们就能看到 PIO 比较贱的一面了：没错，这里只展示，不给你打包好的项目供你下载

有些小伙伴就要说了，这旁边不给了你 Repository 地址吗？你说得对但是 PIO 非要展示自己的独立属性，它打乱了与原本仓库 Releases 对应的版本号（其实是 PIO 重新封包了）。又有小伙伴要说了，PIO 不算是给了每个被打乱版本号后的版本的 Release Notes 地址吗，看起来是如此，点进去一看：

好一个 404 Release Notes，给了，但没有完全给。

看起来得自己摸索 PIO 的这个版本号和 ESP 官方版本号之间的关系了。

最新版的这个版本号有点独特：3.20017.241212+sha.dcc1105b，明眼人一下就能看出来这后面还带了个哈希，果不其然顺着哈希我一下子就找到了这个版本对应的 Commit：

https://github.com/espressif/arduino-esp32/tree/dcc1105b

我们用 Git 将其 Clone 到本地，当然你直接下载整个仓库（仅此分支）也可，然后将项目文件夹命名为 framework-arduinoespressif32，再将其移动至 %USERPROFILE%\.platformio\packages 目录下。

这样还不能解决问题，还记得我刚才说 PIO 进行了重新封包吗，其实就是在原项目的根目录下加上了一个 .piopm 识别文件，用于 PIO 对该开发框架/工具链进行识别，判断其内容，版本号等信息。

这东西我实在是不知道去哪里找了，其实你可以去翻翻 PIO 的源代码，说不定你可以看到它是从哪里下载这些包的，但是我觉得这样太麻烦了（其实是当时没想到写文章的时候才想到），但是我又找了一圈也没找到有关 .piopm 的文章，所以我通过各种手段搞来了一份 toolchain-xtensa-esp32 的 .piopm 用作参考，来给我手动下载的这些库加上可供 PIO 识别的 .piopm 文件。经过一些尝试，下面这一份 .piopm 是可以用作 framework-arduinoespressif32 给 PIO 验证身份的：

{"type": "tool", "name": "framework-arduinoespressif32", "version": "3.20017.0", "spec": {"owner": "platformio", "id": 8070, "name": "framework-arduinoespressif32", "requirements": null, "uri": null}}

好像忘记格式化了，能用就行 (‾◡◝)

注意事项

配置好这个之后，你应该再以类似的步骤去配置剩下上面列出的工具链，这里有很多重复内容我就不赘述了（如果有需要让我再回来写也行），下面就一些特别要强调的事提一嘴：

虽然未经验证掌控板3.0 的配置文件所指向的开发框架和工具链是否有特殊的版本限制，但我还是建议你使用以下版本的开发框架和工具链：

framework-arduinoespressif32 @ 3.20017.0
toolchain-riscv32-esp @ 8.4.0+2021r2-patch5
toolchain-xtensa-esp32s3 @ 8.4.0+2021r2-patch5

暂不清楚 PIO 是通过 .piopm 中的哪一个字段来识别一个开发框架或工具链的，但是我还是建议你使用以下我已经验证过的 .piopm 文件：

framework-arduinoespressif32 @ 3.20017.0

{"type": "tool", "name": "framework-arduinoespressif32", "version": "3.20017.0", "spec": {"owner": "platformio", "id": 8070, "name": "framework-arduinoespressif32", "requirements": null, "uri": null}}

toolchain-riscv32-esp @ 8.4.0+2021r2-patch5

1	{"type": "tool", "name": "toolchain-riscv32-esp", "version": "8.4.0+2021r2-patch5", "spec": {"owner": "espressif", "id": 12551, "name": "toolchain-riscv32-esp", "requirements": null, "uri": null}}

toolchain-xtensa-esp32s3 @ 8.4.0+2021r2-patch5

{"type": "tool", "name": "toolchain-xtensa-esp32s3", "version": "8.4.0+2021r2-patch5", "spec": {"owner": "espressif", "id": 12550, "name": "toolchain-xtensa-esp32s3", "requirements": null, "uri": null}}

当然，如果你有通过正常渠道（PIO Core）下载得到的 .piopm 文件，请先优先考虑它们，不过你需要注意版本号的异同

PIO 重新封包版本号与原本 Github 仓库 Releases 版本号的对应关系：

framework-arduinoespressif32 @ 3.20017.0 -> dcc1105b

这是一个特例，该版本号对应的不是一个 Releases，而是一个 Commit

toolchain-riscv32-esp @ 8.4.0+2021r2-patch5 -> esp-2021r2-patch5

toolchain-xtensa-esp32s3 @ 8.4.0+2021r2-patch5 -> esp-2021r2-patch5

下载 toolchain-riscv32-esp 和 toolchain-xtensa-esp32s3 注意区分一下，这俩在同一个仓库里，容易搞混

放置配置文件

胜利的曙光就在眼前了，这一步很简单

首先，点击链接下载配置文件

解压这个 .rar 文件，将 mpython_esp32s3_r8n16.json 复制一份至 %USERPROFILE%\.platformio\platforms\espressif32\boards 目录下

然后将文件夹 mpython_V3_ESP32S3 复制一份至 %USERPROFILE%\.platformio\packages\framework-arduinoespressif32\variants 目录下

打开任务管理器，关闭所有 Python 相关进程，彻底结束下载。重启 VSCode。

创建第一个掌控板3.0 Arduino 项目

打开 PIO Home，点击 New Project，在弹出的 Project Wizard 窗口中进行如下操作：选择 Board 项为 mpython_esp32s3_v3，填写 Name 项为符合要求的任意值，选择 Framework 项为 Arduino，点击 Finish 按钮，等待创建完成。此时创建应该会非常迅速，若五分钟后没有明显变化，请对照前文步骤检查环境配置是否正确。

若需要自定义项目文件夹路径，取消勾选 Project Wizard 中的 Use default location 即可

创建项目完成后，PIO 会自动打开工作区窗口。打开 scr/main.cpp，写入以下内容：


#include <Arduino.h>

void setup() {
  Serial.begin(115200);
}

void loop() {
  Serial.println("Hello HandPy V3");
  delay(1000);
}

顺便提一嘴，在 PIO Arduino 环境下不能省略头文件

保存更改后，尝试点击 VSCode 工具栏的 “→” 按钮（PlatformIO: Upload）,PIO 会开始编译和烧录流程，待编译和烧录完成后，再点击串口按钮（PlatformIO: Serial Monitor）,将会打开串口监视器，此时你应该看到监视器中在不停输出 Hello HandPy V3（每次输出间隔1秒）。

如果在编译过程中报错，请检查你编写的程序是否存在问题。若没有，请尝试最小化测试（比如只简单在串口监视器输出一行内容），若依旧存在问题，你应该试试对照前文步骤检查环境配置是否正确。若在烧录过程中报错，请检查设备连接是否正确。

这里需要特别说明的是，如果在烧录过程中出现了 esp32 failed uploading: uploading error: exit status 2 错误，你应该尝试在同时按下板载按键 A，板载按键 B后再按下掌控板背面的 Reset 键，最后松开板载按键，使 ESP32-S3 以 Joint Download Boot 模式启动。

为什么要同时按下板载按键 A 和 B 呢？因为在掌控板3.0 上，这两个按钮的引脚极为特殊，分别为 GPIO0 和 GPIO46，它们是 ESP32-S3 芯片的 Strapping 且刚刚好用来控制芯片启动模式。显然，板载按键在按下时是低电平状态，而进入 Joint Download Boot 模式的方法就是使 GPIO0 和 GPIO46 都处于低电平状态。

需要注意的是，Strapping 会在芯片复位时使用其各自的默认值。GPIO0 的默认值是 1，这显然是符合预期的，因为板载按键未被按下时也为高电平。但是 GPIO46 的默认值为 0，这显然不符合预期：在实际测试中，如果以一般方式（pinMode(46, INPUT)）初始化该引脚，无论你是否按下其对应的板载按键 B，该引脚的值始终为 0，这样的错误是灾难性的。因此，在初始化该引脚时，应当使用 pinMode(46, INPUT_PULLUP) 将其拉高，这样才可在程序中正常使用板载按键 B（会有小伙伴看到这吗，但是这的确很重要＠_＠）。

说在最后

正文到这里就结束了，我基本上将我配置环境中遇到的一些问题及我的解决方案都写在这里了（有些也许我忘记了，所以没写），希望这能对你提供一些帮助。本人技艺不精，如果你在看我的文章的过程中发现了严重的错误/不准确的表述，或者你对于文章中的某些观点有着更好的见解、对某些步骤有着更好的解决方案，可以在下方的评论区与大家讨论。

我还尝试了在该环境下移植 LVGL V9.3，目前已可以正常运行，没有大的问题，如果有时间我会尝试写文章来总结一下配置方法（马上开学了，我不知道还有没有时间）。

总之，希望你还看的开心。

使用 PlatformIO 为 掌控板3.0 搭建 Arduino 开发环境