# ESP32-C3 MicroPython 固件编译环境搭建教程
**Repository Path**: resetlove/esp32-c3_micropython_firmware
## Basic Information
- **Project Name**: ESP32-C3 MicroPython 固件编译环境搭建教程
- **Description**: ESP32-C3 MicroPython 固件编译环境搭建教程
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 2
- **Created**: 2022-06-09
- **Last Updated**: 2022-06-09
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
ESP32-C3 MicroPython 固件编译环境搭建教程
### 前言
编译`MicroPython`固件的难度主要源自国内访问 [GitHub](https://github.com) 不顺畅，只要你能克服这个困难，那就不是难事
测试环境为 `Windows 10` + `WSL` + `Ubuntu 18.04.5 LTS`
> **非**保姆级教程，所以还需要你具备一定的动手能力
### 前期准备工作
#### 更新 Ubuntu 软件包
```bash
$ sudo apt update
$ sudo apt upgrade
```
> 切换国内源可以提高更新速度，切换方法 [自行必应](https://cn.bing.com/search?q=ubuntu+%E5%9B%BD%E5%86%85%E9%95%9C%E5%83%8F%E6%BA%90)
#### 安装相关软件包
```bash
$ sudo apt install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
```
#### 更新 CMake 版本至 3.12 以上
```bash
$ wget https://cmake.org/files/v3.12/cmake-3.12.2-Linux-x86_64.tar.gz
$ tar zxvf cmake-3.12.2-Linux-x86_64.tar.gz
$ mv cmake-3.12.2-Linux-x86_64 /opt/cmake-3.12.2
$ ln -sf /opt/cmake-3.12.2/bin/* /usr/bin/
```
### 项目克隆
#### 准备一个工作目录
```bash
$ cd ~
$ mkdir esp32_idf4
$ cd esp32_idf4
```
#### 克隆主项目
```bash
$ git clone https://github.com/micropython/micropython.git
```
```bash
# v4.3 并不是一个分支，所以后期无需更新
# 不选择主分支是因为第一次使用主分支进行编译的时候出错了
$ git clone -b v4.3 https://github.com/espressif/esp-idf.git
```
#### 更新子模块
```bash
$ cd micropython
$ git submodule update --init --recursive
$ cd ../esp-idf
$ git submodule update --init --recursive
```
#### ~~自动重复执行更新子模块~~
~~简单粗暴的方式，将`更新子模块`中的`git`命令行替换成如下内容即可~~
```bash
# 反正也不会一次就能完成，干脆重复执行它 100 次~
$ for i in {1..100}; do git submodule update --init --recursive; done
```
> **针对以上步骤的提示**
>
> * 上述步骤是一个漫长且痛苦的过程
> * 如果出现包含`fatal`或`failed`的提示内容，只需要重复执行上一次的命令行即可重新开始
> * 如果长时间卡住可以尝试 ctrl+c 中断命令，并重新开始
> * 可以开两个终端对两个项目同时进行克隆和更新操作，即刻享受双倍痛苦~
> * 如果出现类似如下的提示内容，那么需要手动删除`submodule path`提到的那个目录，这里需要删除的是`CMSIS_5`
>
> fatal: Needed a single revision
>
> Unable to find current revision in submodule path 'lib/pico-sdk/lib/tinyusb/lib/CMSIS_5'
### ESP-IDF 工具和设置
#### 安装 ESP-IDF 工具
```bash
# 工具只需要安装一次即可
# 当前路径：~/esp32_idf4/esp-idf
$ export IDF_GITHUB_ASSETS="dl.espressif.com/github_assets"
$ ./install.sh
```
#### 设置环境变量
```bash
$ . $HOME/esp32_idf4/esp-idf/export.sh
```
#### 为`export.sh`设置别名
每次打开终端时之前设置的环境变量都会失效，可以使用`别名`的方式进行快速设置
```bash
$ vim ~/.profile # 打开 shell 配置文件并在最后一行粘贴如下内容
alias get_idf='. $HOME/esp32_idf4/esp-idf/export.sh' # 保存并退出
$ source ~/.profile # 刷新配置文件
```
设置好之后，每次需要编译固件的时候只需要执行如下命令即可
```bash
$ get_idf
```
> **vim 快捷键**
>
> i - 进入编辑模式
>
> esc - 退出编辑模式
>
> : - 打开命令行
>
> w,q,回车 - 保存并退出
### 开始编译固件
假设到目前为止你已经完成了上述所有操作，包括：
* 更新了`Ubuntu`系统软件包和`CMake`
* 克隆了`MicroPython`主项目，并更新了子模块
* 克隆了`ESP-IDF`主项目，并更新了子模块
* 安装了`ESP-IDF`工具并设置了环境变量
那么我们重新打开一个终端，然后开始吧
#### 重新设置环境变量
```bash
$ get_idf
```
#### 更新`MicroPython`主项目
```bash
$ cd ~/esp32_idf4/micropython
$ git pull # 提示 "Already up to date." 表示更新成功
```
#### 编译固件
```bash
$ make -C mpy-cross
$ cd ports/esp32
$ make BOARD=GENERIC_C3 clean # 可选项，如果需要完全重新编译则执行这行命令
$ make submodules
$ make BOARD=GENERIC_C3
```
如果一切顺利会出现类似如下的提示内容，代表编译成功！
```bash
Project build complete. To flash, run this command:
~/.espressif/python_env/idf4.3_py3.6_env/bin/python ../../../esp-idf/components/esptool_py/esptool/esptool.py -p (PORT) -b 460800 --before default_reset --after hard_reset --chip esp32c3 write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x0 build-GENERIC_C3/bootloader/bootloader.bin 0x8000 build-GENERIC_C3/partition_table/partition-table.bin 0x10000 build-GENERIC_C3/micropython.bin
or run 'idf.py -p (PORT) flash'
bootloader @0x001000 16528 ( 12144 remaining)
partitions @0x008000 3072 ( 1024 remaining)
application @0x010000 1408400 ( 164464 remaining)
total 1473936
```
#### 烧录固件
目前`MicroPython`官方的`makeimage.py`代码有问题，所以不能直接烧录合并出来的`firmware.bin`文件
简化分解一下上边的提示内容
```bash
python esptool.py
-p (PORT)
-b 460800
--before default_reset
--after hard_reset
--chip esp32c3
write_flash
--flash_mode dio
--flash_size detect
--flash_freq 80m
0x0 build-GENERIC_C3/bootloader/bootloader.bin
0x8000 build-GENERIC_C3/partition_table/partition-table.bin
0x10000 build-GENERIC_C3/micropython.bin
```
在`Windows WSL`环境下使用如下命令可以直接烧录固件
```bash
$ make BOARD=GENERIC_C3 deploy
```
> 前提是你可以正常访问串口，如果不能，请查看`参考内容`中的相关链接自行解决
还可以使用 [Flash 下载工具](https://www.espressif.com/sites/default/files/tools/flash_download_tool_v3.8.8.zip) 分别烧录上边得到的 3 个`.bin`文件，注意偏移量和文件名要一一对应正确
| 偏移量 | 固件文件 |
| :-: | :-: |
| 0x0 | bootloader.bin |
| 0x8000 | partition-table.bin |
| 0x10000 | micropython.bin |
或者使用`Flash 下载工具`将 3 个`.bin`文件合成为 1 个文件，合并后的固件烧录偏移量为`0x0`
#### 编译固件过程中报错
如果编译过程中出现类似如下的错误提示内容
```bash
CMake Error at ~/esp32_idf4/esp-idf/tools/cmake/component.cmake:305 (message):
Include directory
'~/esp32_idf4/esp-idf/components/mbedtls/mbedtls/include' is
not a directory.
```
则手动检查一下指定目录下是不是只有一个`.git`文件
~/esp32_idf4/esp-idf/components/mbedtls/mbedtls
如果是的话就把这个目录删除，并重新运行`更新子模块`命令
### 参考内容
* [快速入门 - ESP32-C3](https://docs.espressif.com/projects/esp-idf/zh_CN/v4.3/esp32c3/get-started/index.html)
* [Espressif 物联网开发框架](https://gitee.com/EspressifSystems/esp-idf)
* [与 ESP32-C3 创建串口连接](https://docs.espressif.com/projects/esp-idf/zh_CN/v4.3/esp32c3/get-started/establish-serial-connection.html)
* [MicroPython port to the ESP32](https://github.com/micropython/micropython/tree/master/ports/esp32)
### 合作交流
* 联系邮箱：
* QQ 交流群：
* [走线物联](https://jq.qq.com/?_wv=1027&k=xtPoHgwL)：163271910
* [扇贝物联](https://jq.qq.com/?_wv=1027&k=yp4FrpWh)：31324057
