基于Docker+WSL+VSCODE的ESP32-C3开发环境搭建

# 前言
继红旭无线发布了[乐鑫ESP32-C3开发环境的搭键](https://www.bilibili.com/video/BV1hu411q719?spm_id_from=333.337.search-card.all.click)的视频教程后，微信群中有个网友私下跟小编聊到：**“其实还有更简单的环境搭建方式”**，然后丢下这两行命令就走了：
```c
docker pull espressif/idf
docker run -it espressif/idf	
```

剩下一脸茫然的小编，一时半会不知所措；后来，抱着试一试且装逼的心态调查了一番，发现果然是个大杀器；众所周知，嵌入式这个圈子相较于互联网，在工具方面是绝对被碾压的，因为嵌入式开发者不断地在重复造轮子，效率极低！！！这也是为什么很多人喜欢玩Linux的原因之一，可以毫无夸张地说：**“100个厂家或者不同的芯片，嵌入式开发者可能就要搭建100个不同的环境”**，尤其是国产芯片的开发环境，让开发者苦不堪言，狂吐芬芳。然而，Docker则可以完美地解决很多造轮子的问题，即：
1. 100%统一的开发环境，只要导入至电脑，所有人都是一样的
1. 无须安装任何开发芯片相关的工具，如Python、Cmake、开发工具链、SDK等等
1. 无须配置任何相关的环境变量以及工具参数
1. 开箱即用，**让开发者只需要专注于代码地编写而无视任何其他问题**

这些完美的属性，瞬间让小编的鸡血直接打到100%的状态，经过将近一星期地摸索，现已经可以跟windows开发环境媲美，在编译速度上更是完胜。简单地说，继承了windows的图形化界面操作，又遗传了Linux的编译速度，同时还免去了一系列的工具下载和配置，就算有那也是一次痛苦，受益几年甚至终身**（如果一直干嵌入式的话）**。

# 工具
搭建上述提及的开发环境，这里我们只需要下载如下几个工具即可：
1. Ubuntu 20.04 on Windows
1. [Visual Studio Code](https://code.visualstudio.com/)
1. [usbipd-win](https://github.com/dorssel/usbipd-win/releases)
1. [Docker Desktop For Windows](https://hub.docker.com/)

由上述可知，我们只需要下载上述4个工具即可，而之前小编在[基于VSCODE的ESP32C3开发环境的搭建](https://docs.wireless-tech.cn/doc/6/)中提及的各种五花八门的工具和SDK，这里再也不用去下载和配置了。

## Docker Desktop For Windows
对于什么是Docker，它有什么功能，能做哪些事情；小编这里不细述，想要了解该工具的详情，就查阅此[链接](https://docs.docker.com/get-started/)；而Docker在搭建本次环境的作用是：**加载ESP32-C3的镜像，并创建一个本地windows系统的沙盒进程，与本地windows系统的所有其他进程隔离**。可以简单地类比为：ESP32-C3的镜像就是在Windows系统上独立运行的Linux系统，而其里面所有的文件或者工具仅属于Linux系统，如果想要访问本地Windows的文件，则可以将其挂载至此Linux系统上，而Docker只是负责管理这些容器镜像，如打开，关闭，重启等。

至于Docker的安装方式，跟普通的Windows应用软件是一样的，所以此处就不细述。然而，还有一点需要提醒读者的是：**Dokcer默认是将镜像安装至C盘，所以如果空间不够的话，需要使用`mklink`命令转移至其他盘符**。

## Ubuntu 20.04 on Windows
这个是Windows10系统开始才有的Linux子系统，我们可以利用Windows10系统的`Powersehll`，键入以下命令查看可通过在线商店获得的 Linux 发行版列表：
```c
wsl -l -o
```
![](https://docdisk.wireless-tech.cn/img/2022/04/02/2022-04-02_213824_995734.png)

因此，想要安装Windows10的Linux子系统，只需键入下述命令：
```c
wsl --install --distribution　Ubuntu-20.04
```
**这里是以小编自己安装的Ubuntu-20.04为例**。

## Visual Studio Code
这个是微软推出的一款轻量级的文本编辑器，通过大量插件的加持，使其也变得无所不能，本次的开发环境搭建就是利用VSCODE加插件的方式，实现`下载`、`监控`、`调试`等功能；至于安装方式，其跟普通的Windows应用软件是一样的，所以此处就不细述了。

## usbipd-win
该工具是解决WSL访问Windows本地的USB、串口、JTAG等接口的核心所在，否则你想要在WSL中开展嵌入式开发，尤其是调试下载，那基本上是天方夜谭。但是，usbipd-win可以很好地解决WSL访问本地Windows USB设备的问题，这也是小编花费时间最多的地方，以至于差点放弃；至于安装方式，其跟普通的Windows应用软件是一样的，所以此处也就不细述了。

# 配置
在安装完上述的工具之后，我们还需要做一些简单的配置：

## Ubuntu 20.04 on Windows
默认安装完Ubuntu 20.04 LTS之后，如果是WSL1的话，还需要将其升级为WSL2，最后将其配置成默认的WSL，具体的方法如下：
1. 首先，查看当前的WSL是哪个版本：
```c
wsl -l -v
```
![](https://docdisk.wireless-tech.cn/img/2022/04/03/2022-04-03_124354_526487.png)
2. 如果不是WSL2，则需要将其升级为WSL2：
```c
wsl --set-version Ubuntu-20.04 2
```
3. 配置Ubuntu 20.04为默认的WSL，命令如下：
```c
wsl -s Ubuntu 20.04
```

最后，再键入`wsl --status`命令，检查上述的配置是否生效：

![](https://docdisk.wireless-tech.cn/img/2022/04/03/2022-04-03_125119_909576.png)

## Docker Desktop For Windows
由于我们在上面将Ubuntu 20.04配置成默认的WSL2，因此我们需要同步在Docker将WSL也设置为Ubuntu 20.04，即`Settings`->`Resources`->`WSL Integration`：

![](https://docdisk.wireless-tech.cn/img/2022/04/03/2022-04-03_142219_635278.png)

## usbipd
关于这个工具的配置，**是后续ESP32-C3能否正常下载或者调试的关键**；对于本地的Windows系统而言，其安装完成就可以了，无需任何更多的配置。然而，仍然还需要在WSL系统中安装此工具，从菜单中点击**Ubuntu 20.04 on Windows**：

![](https://docdisk.wireless-tech.cn/img/2022/04/03/2022-04-03_143342_581028.png)

然后，**分别**键入下述命令即可：
```c
apt install linux-tools-5.4.0-77-generic hwdata
update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/5.4.0-77-generic/usbip 20
```
如果出现无法安装的情况，则先对apt进行更新再安装，如下：
```c
apt-get update
```

此时，Windows和WSL均安装了此工具；那么，我们通过下述的步骤验证是否成功：
1. <span id="usbip_setting"></span>以**管理员权限**打开Powershell，并键入`usbipd wsl list`:
![](https://docdisk.wireless-tech.cn/img/2022/04/03/2022-04-03_145838_504741.png)
可以看到，WSL发现了如上图所示的几个Windows USB设备，而且均处于非attached状态
1. 为了让WSL可以访问这些Windows USB设备，将你想要访问的USB设备绑定，同样以**管理员权限**打开Powershell并键入命令`usbipd bind -b <BUSID>`，除非电脑重启了，否则此命令只需要输入一次即可：
![](https://docdisk.wireless-tech.cn/img/2022/04/03/2022-04-03_151615_979659.png)

**其中`1-1`是我想要绑定的Windows USB设备**
1. 绑定完成之后，紧接着以**普通权限**打开Powershell并键入命令键入`usbipd wsl attach --busid 1-1`命令：
![](https://docdisk.wireless-tech.cn/img/2022/04/03/2022-04-03_151938_249265.png)
	**其中`1-1`是WSL想要访问的Windows USB设备，如果热插拔了该USB设备，则需要再次键入这条命令**
1. 最后，我们回过来到WSL，键入`dmesg | tail`命令：
![](https://docdisk.wireless-tech.cn/img/2022/04/03/2022-04-03_152513_388770.png)
我们可以看到，Windows的`1-1` USB设备被附到了WSL中的**ttyACM0**上面去了，这也意味着WSL现在可以通过该接口直接访问Windows的`1-1` USB设备了。

如果上述命令均成功地运行，则说明usbipd软件在Windows和WSL上的安装已经成功了。

## Visual Studio Code
由于VSCODE是Windows上的应用软件，而ESP32-C3的Docker镜像是运行在WSL中，所以需要额外安装`Remote - Containers`、`Remote Development`以及`ESP-IDF`插件即可，无需做任何特别的配置：

![](https://docdisk.wireless-tech.cn/img/2022/04/03/2022-04-03_154413_932713.png)

![](https://docdisk.wireless-tech.cn/img/2022/04/05/2022-04-05_144918_754116.png)

![](https://docdisk.wireless-tech.cn/img/2022/04/05/2022-04-05_161121_914473.png)

通过这些插件的加持，在Windows中的VSCODE可以直接操作ESP32-C3的Docker镜像，也就是说可以像在Windows中操作其他软件一样，来操作基于WSL的ESP32-C3的Docker镜像，如编译、下载等功能，而无须在WSL中敲命令。

# 实践
通过上述的一次性并为后续连续使用几年的配置，基本上完成了此次开发环境搭建的所有工具安装和设置；同时我们可以看到，截止目前为止小编还未提及任何关于ESP32-C3的配置，那是因为ESP32-C3的Docker镜像都帮我们弄好了，只需要向其发命令即可。这里小编将以实际的工程给他们讲解如何使用：

## 配置示例工程
这里以`blink`和`hello_World`的示例工程为例，如果你们有更多相关的ESP32-C3的工程代码，则可以将它们统一放在同一个文件夹内，然后一起挂载到ESP32-C3的Docker镜像内，**最后选择你想要编辑的工程做为工作区文件夹，否则每个工程都要创建一个容器，怕你的硬盘顶不住，这也是小编在实践中改良后的一个方法**，即只需要一个容器存放多个工程项目，最后选中想要开发的那个工程项目即可。

![](https://docdisk.wireless-tech.cn/img/2022/04/05/2022-04-05_151233_739242.png)

从上图可知，小编将`blink`和`hello_World`的示例工程均放在了**example_project**文件夹中，此时只需要在此文件夹中打开VSCODE即可：

![](https://docdisk.wireless-tech.cn/img/2022/04/05/example_project_vscode_20220405151932788315.gif)

有眼尖的读者可能会看到，**example_project**文件夹中多了一个 **.devcontainer** 文件夹，默认是没有这个文件夹的；**这个是小编利用VSCODE的ESP-IDF插件生成，用于控制和配置Docker镜像**；所以读者还需要生成自己的`.devcontainer`文件夹内容，如下：
1. 通过VSCODE打开example_project文件夹之后，键入`F1`键
1. 在弹出来的对话框输入`ESP-IDF: Add docker container configuration`
1. .devcontainer文件夹就会自动生成了

![](https://docdisk.wireless-tech.cn/img/2022/04/05/dev_container_20220405161737118453.gif)

但是，自动生成的`.devcontainer`文件夹内容，它是不可以直接使用的，还需要进行适当地修改，至于每个参数的含义，小编不在这里浪费篇幅介绍，读者们只需要查看小编的下述的注释即可，分别如下：
- devcontainer.json
```json
	// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
	// https://github.com/microsoft/vscode-dev-containers/tree/v0.183.0/containers/ubuntu
	{
		/* 显示在UI上的容器名称 */
		"name": "ESP-IDF",
		/* 容器注册表中的镜像名称 */
		"image":"espressif/idf:latest",
		/* 加载本地的文件夹到镜像的/workspaces文件夹 */
		"workspaceMount": "source=${localWorkspaceFolder},target=/workspaces,type=bind",
		/* 容器内的工作空间文件夹路径，也就是说容器运行后打开的就是这个文件夹 */
		"workspaceFolder": "/workspaces/blink",
		/* 当容器创建时所下载的VSCODE插件挂载到容器target的路径下，
			 这样再rebuild容器时不用再次下载VSCODE插件
		*/
		"mounts": [
			"source=extensionCache,target=/root/.vscode-server/extensions,type=volume",
		],
		/* 根据Dockerfile的内容创建容器 */
		"build": {
			"dockerfile": "Dockerfile"
		},
		/* 将配置插件的相关参数复印到容器中去 */
		"settings": {
			"terminal.integrated.defaultProfile.linux": "bash",
			"idf.espIdfPath": "/opt/esp/idf",
			"idf.customExtraPaths": "",
			"idf.pythonBinPath": "/opt/esp/python_env/idf5.0_py3.8_env/bin/python",
			"idf.toolsPath": "/opt/esp",
			"idf.gitPath": "/usr/bin/git"
		},
		/* 选择容器在创建时，需要安装的插件 */
		"extensions": [
			"ms-vscode.cpptools",
			"espressif.esp-idf-extension"
		],
		/* 使用特权的方式启动容器，否则在镜像中将无法访问usbip绑定的USB设备 */
		"runArgs": [
			"--privileged"
		]
	}
```
- Dockerfile
```c
	# 创建容器所需要的docker镜像，这里是ESP-IDF的镜像
	FROM espressif/idf:latest
	# 执行命令时，不需要交互，直接运行
	ARG DEBIAN_FRONTEND=nointeractive

# RUN apt-get update \
	#   && apt install -y -q \
	#   cmake \
	#   git \
	#   libglib2.0-0 \
	#   libnuma1 \
	#   libpixman-1-0

# ESP-IDF的相关配置，默认即可
	RUN ./opt/esp/entrypoint.sh && pip install --no-cache-dir idf-component-manager

RUN echo $($IDF_PATH/tools/idf_tools.py export) >> $HOME/.bashrc

ENTRYPOINT [ "/opt/esp/entrypoint.sh" ]

CMD ["/bin/bash"]
```

至此，所有的工程相关配置工作就完成了，可能首次会稍微麻烦些，但是后续基本上都不用动了，这是一劳永逸的配置。

## 创建容器
当上面所有的配置都完成了之后，此时只需要创建容器就可以马上进行ESP32-C3开发了，即单击VSCODE左下方的绿色按钮，选择`Open Folder in Container`即可开始创建容器**（首次创建容器会稍微慢点，因为要下载ESP-IDF的Docker镜像，仅须下载一次）**，并最终打开`Blink`的示例工程；如果需要切换到另外的工程，只需要将`"workspaceFolder": "/workspaces/blink"`,更改为`"workspaceFolder": "/workspaces/你想要打开的示例工程名"`，然后重新选择`Open Folder in Container`，具体操作如下：

![](https://docdisk.wireless-tech.cn/img/2022/04/06/动画_20220406223827746664.gif)

我们可以看到，当容器创建完成之后就可以马上对`Blink`这个示例工程进行编译、下载、调试了。这就是容器厉害的地方，开箱即用无须对环境做任何的配置。

## 编译
当容器创建完成之后，就可以马上在工程代码上进行编译了，这里直接就可以利用`ESP-IDF插件`实现而无须做任何的配置，唯一要做的就是将设备从`esp32`切换为`esp32-c3`，如下图所示：

![](https://docdisk.wireless-tech.cn/img/2022/04/06/2022-04-06_225218_469908.png)

紧接着编译出来的就是ESP32-C3固件了，如下所示：

![](https://docdisk.wireless-tech.cn/img/2022/04/06/container_build_20220406225644432643.gif)

## 下载
当完成编译之后，接下来我们通过下述不同的方式来下载固件至ESP32-C3：
### 外置的USB-Serial
这里以[HX-DK-商](https://item.taobao.com/item.htm?spm=a1z10.1-c-s.w4004-22286946226.12.7f292c2cfSNrZb&id=654877303965)为例，将USB线插入标有UART的一侧，如下图所示：
![](https://docdisk.wireless-tech.cn/img/2021/10/15/hx_dk_shang_20211015110649848518.png)

此时，我们通过上述章节[usbipd](#usbip_setting)提及的方法，将Windows的USB设备**（这里是Silicon Labs CP210x USB to UART Bridge）**附到Docker镜像上并查到最终在WSL的哪个口，如下图所示：

![](https://docdisk.wireless-tech.cn/img/2022/04/07/2022-04-07_000834_688002.png)
我们可以看到，它附到了`ttyUSB0`了，所以我这里需要在`blink`的工程上将UART口更改为`ttyUSB0`，如下所示：

![](https://docdisk.wireless-tech.cn/img/2022/04/07/2022-04-07_001030_169512.png)

但是，**此时容器还不知此时UART口换为ttyUSB0**，如下所示：

![](https://docdisk.wireless-tech.cn/img/2022/04/07/2022-04-07_001310_998658.png)
我们可以看到，提示找不到`/dev/ttyUSB0`这个文件或文件夹，**这里我们只需要重新打开容器即`Reopen Folder Locally`，然后再次连接上容器，才会重新加载这个配置**：

![](https://docdisk.wireless-tech.cn/img/2022/04/07/container_reopen_20220407003159440649.gif)

最后，再次点击`下载`按钮即可实现下载：

![](https://docdisk.wireless-tech.cn/img/2022/04/07/container_flash_uart_20220407003331921296.gif)
### 内置的USB-Serial
内置的USB-Serial也是同样的方法，只不过是附到了`ttyACMx`上了，因为小编只有一个开发板插上电脑，所以最终为`ttyACM0`，下图是采用内置的USB-Serial下载情况：

![](https://docdisk.wireless-tech.cn/img/2022/04/07/container_flash_uart_internal_20220407004100016634.gif)

### JTAG
也是跟上述的`外置的USB-Serial`和`内置的USB-Serial`方法一样，只是需要额外配置下图所示的3个参数：

![](https://docdisk.wireless-tech.cn/img/2022/04/07/2022-04-07_004429_896933.png)

接口跟内置的USB-Serial是一样的，都是`ttyACM0`，最终的下载情况如下：

![](https://docdisk.wireless-tech.cn/img/2022/04/07/container_flash_jtag_20220407004922743692.gif)

## 调试
其实调试的配置跟上述的[JTAG](#JTAG)是一模一样的，紧接着直接按下`F5键`即可实现调试：

![](https://docdisk.wireless-tech.cn/img/2022/04/07/container_debug_20220407224947371991.gif)

# 注意事项
1. 在首次创建容器时，会提示`ESP-IDF`插件由于依赖`C++ tools`插件，而导致无法激活，这个只需要重新再次打开容器即可。
1. 如果要回到Windows上调试，则需要进行热插拔USB线，否则在Windows的设备管理器上找不到对应的USB口。
1. 在使用此方法搭建的环境，Docker Desktop For Windows是需要打开的，不可以关闭的。

至此，所有的功能均以实现，且与Windows那套环境在操作上没有任何的区别。Enjoy！！！