【单片机】基于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开发环境。

• 初始化配置

arduino-cli config init  --dest-dir "$env:localappdata\arduino15"

如果要查看配置，可以：

arduino-cli config dump

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

• 修改配置文件(optional)

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

arduino-cli config set directories.user "$env:localappdata\arduino15"

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

• 下载开发板核心

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

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

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

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

  所以这里的重点就是那个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

4 vs code配置

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

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

• 插件设置
  这个插件的设置非常简单，只需要把那个use arduino cli勾选上即可

• 基本使用

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

• 添加库文件

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

# 查看已安装的库
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，问题解决，搞不明白的以后再说。