【单片机】基于Arduino cli和VS Code配置开发环境，彻底抛弃Arduino IDE

0 前言

  之前有在电脑上基于VS Code配置Arduino环境，大致方法就是在安装Arduino IDE的前提下在VS Code上下载一个插件并配置好Arduino IDE的路径即可，总的来说还是非常简单的。但是今天按照记忆中的方法配置的时候出现了一个弹窗：

经过反复试验，发现如果要像以前一样基于Arduino IDE来配置的话，只能忽略掉这个设置，不能点击“Use bundled arduino-cli”，否则会出问题。

  本来这个问题差不多就解决了，但是可恶的是这个弹出每次刷新窗口都会弹出来，特别讨厌。于是花了一点时间，把和arduino-cli的相关资料都仔细看了一遍，惊讶地发现这个arduino-cli特别牛逼！配置开发环境只需要它就足够了，可以完全不依赖Arduino IDE的！，这篇教程简单介绍如何在VS Code中基于arduino-cli来配置Arduino框架开发环境。

网上也有一些类似的教程，但不够细致和明确，这里从原理出发，总结一篇比较细致的教程，内容较多，请耐心观看。

1 VS Code的优势和Arduino IDE的劣势

  如果是使用Arduino IDE，只需要去官网下载，然后无脑安装即可，非常简单。但使用VS Code，却需要相对麻烦的配置。但付出总是有回报的，这里简单聊聊VS Code的优势和Arduino IDE的劣势。

先看看收益再决定要不要花时间。

• VS Code界面比Arduino IDE好看，这个毋庸置疑
• VS Code可以溯源代码，这个对于理解第三方库来说要方便不少
• VS Code智能提示（IntelliSence）让码代码工作量大减

2 前期准备

• 已有VSCode并懂其基本工作原理，会基本使用
• 不用下载Arduino IDE，如果下载了，完全可以卸载【但建议保留好下载的开发板SDK之类的文件】

3 Arduino cli

3.1 Arduino cli是什么

  首先我们先来了解这个cli是什么东西。所谓cli，即Command Line Interface，是与gui（Graphic User Interface）相对，即使用命令行来实现图形界面点击按钮可完成的功能。它是官方在2018年发布的一个集成的工具，把和Arduino相关的嵌入式开发过程，如编译和下载，管理库和板子SDK等都集成到这一个工具当中。（当然，它本身是不具有编译和下载的功能的，只是调用其他工具来进行操作）这样可以实现只用这一个工具就能构建整个项目，功能非常强大。
  而且这个工具是跨平台的，并且可以很方便地集成到各种流行的编辑器中，如VS Code和Eclipse等

有兴趣的可以看看官网给出的介绍

3.2 下载与安装

  Arduino cli这个工具更新非常快，基本几天一个版本，所以建议去官方GitHub下载：https://github.com/arduino/arduino-cli/releases

  Arduino cli是单个执行文件，可以下载压缩包然后放在电脑中的某个位置。但这里建议下载后缀为.msi的文件，这样在安装时会自动将安装路径添加到环境变量，比较省事。

安装好之后检验一下是否安装成功：

arduino-cli -h #or --help

如果没出现报错就证明安装成功了。

上图画红色下划线的是比较重要的指令，后面会用到

3.3 基本使用

  这里简单介绍两个使用技巧。

• 快速查询帮助指令
  如果不知道某个命令后面有哪些“子命令”，就可以通过--help或-h来查询命令的使用。比如arduino-cli -h打开的是arduino-cli的帮助文档，而arduino-cli lib -h打开的是lib子命令的帮助文档。
  不输入任何参数，默认也是打开帮助文档。如直接输入arduino-cli、arduino-cli lib也会打开帮助文档

• Tab补全设置
  这个是官方提供的一个Tab补全的操作，可以支持所有命令和参数的补全，这样在输入命令时更方便一点，前提貌似是安装Power Shell7，具体配置教程参考官网。如果不想折腾的可以跳过。

3.4 开发环境配置

  前面提到，arduino-cli是一个集成的工具，它基本囊括了Arduino IDE常用的功能，甚至可以视为就是Arduino IDE的核心，只是缺少编辑器而已。因此，最好是理解Arduino IDE的基本功能，这样差不多可以理解配置的每一步了。

  在配置之前，首先要知道Arduino IDE有哪些目录。

• 首先是IDE的安装目录，即%ProgramFiles(X86)%\Arduino_1.8.19目录（默认路径）下
• 然后是开发板SDK目录，每种开发板都有其对应的基础代码，内置库，编译下载工具等，这些文件放在%LocalAppdata%\Arduino15文件夹下
• 如果在使用过程中，有安装第三方库，那么库文件会放在项目文件夹下，当然，这个在IDE当中也可以自定义：
  

  理解了Arduino IDE的文件夹结构，应该对它的工作原理有了一定认识，接下来就开始使用安装好的arduino-cli来搭建Arduino开发环境。

VS Code部分在后面，这部分可能有点难理解，但不要慌，照着做，做完可能就明白了。

• 初始化配置

arduino-cli config init  --dest-dir "$env:LOCALAPPDATA\Arduino15"

之所以选择这个文件夹是因为VS Code中的Arduino插件只认这个文件夹下的配置文件，这个后面就理解了

如果要查看配置，可以：

arduino-cli config dump

这本质上是查看上面那个初始化的配置文件，文件名为arduino-cli.yaml。如果默认路径下没有配置文件，那显示的就是内置的默认配置。

• 修改配置文件(Optional)

  通过查看默认配置可知，库文件和板子SDK文件是不在同一个路径下的，个人觉得很不方便，因此修改一下配置：

arduino-cli config set directories.user "$env:LOCALAPPDATA\Arduino15"

这样配置文件、板子SDK文件和安装的第三方库文件都在一个路径下，如果需要找目标更加明确。

这里分享一下我的使用习惯。前面提到，Arduino软件（不管是1.8还是2.0）SDK和第三方包存放的位置是不一样的，一个在Local/Arduino15下，一个在文档/Arduino文件夹下。后者被官方设置为“用户目录”，即希望用户将写的项目代码也放在这个位置，但是个人更喜欢放在桌面这样更明显的位置。因此个人的习惯设置是将第三方包和板子的SDK放在一起，这样不管是查找第三方库还是默认库（一般在板子SDK包中），都只需要去一个路径下查找即可。如果使用Arduino，则是设置“首选项”中的“项目文件夹”；如果是使用Arduino-cli，则使用上述指令设置。

• 下载开发板核心

  也就是前面反复提到的SDK，不同的板子不一样，如果是只开发Arduino，那么只需要安装Arduino的开发套件即可：

# 先更新一下板子列表（core list）
arduino-cli core update-index

# 再下载arduino核心（SDK）
arduino-cli core install arduino:avr

  那如果我还要开发ESP8266和ESP32怎么办呢？还记得在Arduino IDE中是怎么设置的吗？先要添加一个板子的链接，一个json文件，然后再下载并安装，然后板子列表就多出了很多可选的开发板型号。

相信配置过的人都知道，在Arduino IDE中配置时失败概率非常高，往往要点击好几次下载。

  所以这里的重点就是那个packages的json文件，从以往的教程来看，这个链接老是会失效，因此建议还是找相对固定的GitHub链接：

• ESP8266
• ESP32

安装指令：

# 先添加额外的链接，按需选择，多个开发板用空格分隔
arduino-cli config set board_manager.additional_urls https://hub.yzuu.cf/esp8266/Arduino/releases/download/3.1.2/package_esp8266com_index.json https://hub.yzuu.cf/espressif/arduino-esp32/releases/download/2.0.7/package_esp32_index.json

# 然后再更新一下链接（实际上就是把上面两个文件下载下来）
arduino-cli core update-index

# 这个时候就可以根据需要下载对应的开发板包了
arduino-cli core install esp32:esp32
arduino-cli core install esp8266:esp8266

第三步如果下载速度太慢，这是因为每个下载包都是从GitHub下载的，这里建议修改一下packages文件，使用镜像网站下载，速度会快不少：

建议使用查找替换，将github.com全部替换成hub.yzuu.cf，然后再执行上面的命令

安装完成之后，可以使用arduino-cli清除缓存文件

# 加上-v可以看到详细输出信息
arduino-cli cache clean -v

到此为止，arduino-cli部分就配置好了，接下来再看看VS Code部分如何配置

4 VS Code配置

• 首先安装一下Arduino插件，这个毫无疑问

  我的建议是把“细节”模块仔细看一下，这样可能会对之后的操作更理解一些。这个插件有两个依赖项，即C/C++插件和一个串口的插件，安装的时候应该会自动安装。
  安装好插件之后，如果去看这个插件的安装目录，会发现目录下已默认下载了一个Arduino CLI（就是我们前面安装的Arduino CLI，可能只有版本不一样），而插件的编译下载等功能都是依赖于这个程序实现的。

  理论上来说，已经有了一个执行程序，可以不用自己再安装，但是个人觉得还是需要再安装一遍，主要有两个理由：

• ①这个文件本身也不大，<30M，下载/复制一遍感觉代价较小；
• ②为了实现在任意位置都能使用这个程序，最好是将它添加到环境变量，但是由于VS Code插件在更新时目录会更换，一般是时间上改变，这样添加到环境变量意义就不大了。

• 插件设置
  这个插件的设置非常简单，只需要把那个Use Arduino Cli勾选上即可

• 基本使用

  如果开发板的SDK已安装的话，在VS Code中新建.ino文件，然后在底下状态栏选择开发板之后，程序就会自动刷新，并且在当前项目文件夹下创建一个c_cpp_properties.json文件，它设置了对应开发板开发过程中需要使用的编译器，需要包含的库文件等，如果没有出现，可以试着Ctrl Shift P，选择重新加载窗口，多刷新几次。而且如果切换开发板，也是会自动刷新的，这就是VS Code的重要作用，即它帮助你省掉了很多工作，也不需要你自己去手打命令，非常方便。

底下的状态栏时刻需要注意：

从左至右依次是：设置编译下载工具（arduino一般是avr，esp32一般是esptool）、当前选中开发的文档、设备类型、串口显示、串口号。

• 添加库文件

  如果在程序开发过程中，想要添加第三方库并使用到程序当中怎么办呢？首先要用命令行安装第三方库：

# 查看已安装的库
arduino-cli lib list #需要注意，这里只会列出lib_path设置路径下的包，即libraries文件夹下

# 搜索某个库
arduino-cli lib search <name>

# 安装某个库
arduino-cli lib install <name>

# 升级
arduino-cli lib upgrade

  安装好第三方库之后，可以直接在程序中引用，但是一般会画波浪线，这是因为c_cpp_properties.json文件没刷新的缘故，试试重新加载窗口，差不多就好了，因为每次重新加载窗口，插件都会对打开的ino文件进行验证（Verify）

• 使用注意事项

  • 要时刻注意右下角的状态栏，即此时的板子型号，串口号，目标文件（不一定是打开的文件）等
  • arduino-cli还是沿用了Arduino IDE的项目文件的概念，因此每次新建一个文件，记得要在外面套一层同名文件夹

  总结来说，其实Arduino插件就是依赖于安装目录下的cli程序，并将它的一些常用功能集成到VS Code界面上的一些按钮，这样大大方便了开发者使用，而前面我们下载安装arduino-cli，更多的是为了不时之需，比如安装第三方库的时候，但实际执行操作的还是VS Code自带的arduino-cli程序。相当于是两个相同的程序读写同一堆文件。

5 参考链接

• Arduino cli
• VScode+ArduinoCLI环境搭建
• Arduino-CLI和VSCode——打造属于自己的Arduino IDE

6 遇到的问题汇总

6.1 output窗口出现乱码

  解决这个问题需要修改Arduino插件的源码。先找到插件的源码：C:\Users\xxxxx\.vscode\extensions\vsciot-vscode.vscode-arduino-0.2.29\out\src\common\util.js，然后在这个位置将这段代码注释掉：

修改后的效果如下所示：

6.2 如何在VS Code环境下使用编程器上传

  在上篇关于Arduino的进阶应用的博客中（没看过的可以点>这个<），介绍了如何使用USBasp这种编程器上传，然后在VS Code环境下，也可以在底部工具栏设置编程器：

点击那个编程器，可以弹出一个界面：

这里其实就和Arduino IDE中是一样的。

  但是有一个问题，界面上没有一个使用编程器上传的按钮，右上角只有编译和使用串口下载的按钮，但是既然Arduino Cli这个命令行工具集能实现硬件的开发，没道理这个功能没有，所以花了一点时间，大概搞懂了指令使用：

## 指令结构
arduino-cli upload <sketch_path> -P <Programmer> -b <board name>

## 举个例子
arduino-cli upload .\KeyBorad_test\KeyBorad_test.ino -P usbasp -b arduino:avr:leonardo

但是执行这个指令可能会报错：

Compiled sketch not found in xxxxxxx

即，没有在指定的路径找到编译后的脚本，其实就是指二进制文件，因为上传只能是上传二进制文件。所以在上传之前需要先编译一下：

arduino-cli compile .\KeyBorad_test\KeyBorad_test.ino -b arduino:avr:leonardo

然后再执行上面的上传指令，如果执行完成没有报错（warning不影响），表明脚本上传到设备成功。

  那每次使用编程器上传都需要敲指令？装逼可以，实用性太差，而且我觉得这种功能插件肯定会有才对，于是调出命名面板（快捷键Ctrl + P），搜索programmer，如下：

果然还是有的，点击试试，结果发现这个报错了？！

显然，问题是出在红框部分，因为我试了一下，确实没有这个参数，关于这个问题，我翻阅了GitHub和Arduino论坛，确实找到类似的问题，但是很奇怪的是好像这个bug修复了才对，而且我电脑上的cli版本不低，所以没道理还报这个错，有点搞不明白。

  但好在，还是找到问题的解决办法，那就是使用Arduino的编程器上传指令，还是唤起命令面板，搜索programmer：

但是使用的是Arduino的指令，亲测确实可以上传成功，ok，问题解决，搞不明白的以后再说。