由于集成st7789屏幕驱动的固件，没有跟随MicroPython发版而进行预编译。想要使用最新版MicroPython固件并集成该屏幕驱动，只能自己构建。

1. 概述

构建过程主要是：

• 创建Docker环境
• 安装esp-idf
• 下载st7789屏幕驱动
• 下载MicroPython项目代码
• 执行编译
• ESP32C3刷入固件

参考：

• Setting up a MicroPython firmware build environment on (WSL & Debian)

2. 构建过程

2.1. 创建Docker环境

这一步不是必须，但是建议在Docker容器里进行构建，对原来系统不产生影响。

简要说明：

• 这里采用Debian 12.12和Bash。MicroPython官方没有限制所使用的Linux发行版和命令行环境，选用熟悉的即可。
• 建议使用Docker Compose管理Docker容器，比较清晰。
• 假设Docker Compose部署在/opt/docker/debian12，用于后续示例代码。

docker-compose.yaml文件的内容，参考如下：

services:
  debian12:
    image: debian:12.12
    container_name: debian12
    working_dir: /opt/esp32c3_micropython
    volumes:
      - ./esp32c3_micropython:/opt/esp32c3_micropython
    command: bash
    tty: true

2.2. 配置和构建

相关问题或处理：

• 1. 版本搭配要求。
  • 一般使用最新发布的版本。
  • esp-idf当前最新版是v5.5.2。
  • MicroPython当前最新版是v1.27.0，建议搭配esp-idf v5.5.1。
  • st7789驱动没有发布版本，采用最新代码即可。
• 2. 下载慢的问题。
  • Python的PyPi，设置使用国内镜像（详见后文）。
  • github下载，设置代理参考git config --global http.https://github.com.proxy socks5://xxx.xxx.xxx.xxx:1080。
  • git clone默认下载整个项目的历史，这里改为只下载指定版本的最新代码，即添加参数 --branch vxx.xx.xx --single-branch --depth 1。
  • esp-idf安装时，需要从github下载几百MB的文件。如果很慢，可以中断下载，采用类似axel的多线程下载工具，根据安装过程的输出信息，手动下载相关文件（需要去掉目标文件名末尾的.tmp），并放到指定目录。
• 3. 固件版本说明添加信息。
  • 暂时没有找到最佳实践。
  • 目前是修改ports/esp32/boards/ESP32_GENERIC_C3/mpconfigboard.h里MICROPY_HW_MCU_NAME的值。
• 4. GPIO 18和19不能正常使用。
  • 这两个针脚默认用作USB JTAG。
  • 如需配置为普通GPIO，在ports/esp32/boards/ESP32_GENERIC_C3/mpconfigboard.h文件添加配置#define MICROPY_HW_ESP_USB_SERIAL_JTAG (0)。
  • 注意，这里的处理针对MicroPython v1.27.0，网上有相关处理是过时的（针对旧版）。
• 5. 编译出MicroPython版本号带有-dirty结尾。
  • 编译MicroPython时，会自动检查并生成当前的版本号，详见代码py/makeversionhdr.py。
  • 生成当前版本号的命令是git describe --tags --dirty --always --match v[1-9].* --abbrev=10，其中--dirty参数会检查当前checkout的代码是否有修改，若有，则版本号添加-dirty。
  • 如果想要生成的版本号不带-dirty，一般是checkout发布（releases）的tag版本，并且不修改任何代码。
  • 如果修改代码后，不想版本号带有-dirty，可以去掉生成版本号的git命令的--dirty参数。

相关配置和构建，已整理为Bash脚本，如下。

# Config pip to download from a mirror repository
mkdir ~/.pip
cat <<EOF | tee ~/.pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = https://pypi.tuna.tsinghua.edu.cn
EOF

# Install required tools and libraries
# Refer: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html
apt update && apt -y install git wget flex bison gperf python3 python3-pip python3-venv python-is-python3 cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

# Setup work path
WORK_PATH=/opt/esp32c3_micropython
if [ ! -d ${WORK_PATH} ]; then
  mkdir ${WORK_PATH}
fi

# Install esp-idf
cd ${WORK_PATH}
git clone --branch v5.5.1 --single-branch --depth 1 https://github.com/espressif/esp-idf
cd ${WORK_PATH}/esp-idf
git submodule sync; git submodule update --init --recursive
./install.sh esp32,esp32c3
. ./export.sh

# Checkout source code of st7789 driver
cd ${WORK_PATH}
git clone https://github.com/russhughes/st7789_mpy

# Checkout source code of MicroPython
cd ${WORK_PATH}
git clone --branch v1.27.0 --single-branch --depth 1 https://github.com/micropython/micropython
cd ${WORK_PATH}/micropython
git submodule sync; git submodule update --init --recursive

# Optional, modify version information
cd ${WORK_PATH}/micropython
cp ports/esp32/boards/ESP32_GENERIC_C3/mpconfigboard.h ports/esp32/boards/ESP32_GENERIC_C3/mpconfigboard.h.bak
sed -i -r 's/(MICROPY_HW_MCU_NAME\s+)"ESP32C3"/\1"ESP32C3-st7789"/' ports/esp32/boards/ESP32_GENERIC_C3/mpconfigboard.h

# Optional, configure pin 18 & 19 as GPIO 
# Refer: [Unable to configure pin 18 & 19 as GPIO output in ESP32C3  #12479](https://github.com/micropython/micropython/issues/12479)
cat <<EOF | tee ports/esp32/boards/ESP32_GENERIC_C3/mpconfigboard.h

// Configure pin 18 & 19 as GPIO
#define MICROPY_HW_ESP_USB_SERIAL_JTAG      (0)
EOF

# Build firmware of MicroPython
cd ${WORK_PATH}/micropython/ports/esp32
make BOARD=ESP32_GENERIC_C3 submodules
make USER_C_MODULES=../../../../st7789_mpy/st7789/micropython.cmake BOARD=ESP32_GENERIC_C3

# Firmware file
#${WORK_PATH}/micropython/ports/esp32/build-ESP32_GENERIC_C3/firmware.bin

2.3. 刷固件

这个操作，建议在宿主机执行。

按上面的操作，生成的固件文件在宿主机路径/opt/docker/debian12/esp32c3_micropython/micropython/ports/esp32/build-ESP32_GENERIC_C3/firmware.bin。

刷机命令参考：

# Install esptool
sudo pip3 install esptool

# Clean
sudo esptool.py --chip esp32-c3 --port /dev/ttyACM0 erase_flash

# Flash firmware
sudo esptool.py --chip esp32-c3 --port /dev/ttyACM0 --baud 460800 write_flash -z 0x0 /opt/docker/debian12/esp32c3_micropython/micropython/ports/esp32/build-ESP32_GENERIC_C3/firmware.bin