cargo-espflash

Cross-compiler 和 Cargo 扩展，用于烧录 Espressif 设备。

支持 ESP32、ESP32-C2/C3/C6、ESP32-H2、ESP32-P4 和 ESP32-S2/S3。

目录

• 安装
• 用法
  • Linux 上的权限
  • Windows 子系统 for Linux
• 引导加载程序和分区表
• 配置文件
  • 配置优先级
• 日志格式
• 许可
  • 贡献

安装

如果您从源代码安装 cargo-espflash（即使用 cargo install），则必须在您的系统上安装 rustc>=1.76.0。

如果您正在运行 Linux，则还必须安装 libudev；这通常可以通过大多数流行的软件包管理器获得。如果您正在运行 Windows 或 macOS，则可以忽略此步骤。

# Debian/Ubuntu/etc.
apt-get install libudev-dev
# Fedora
dnf install systemd-devel

安装

cargo install cargo-espflash

或者，您可以使用 cargo-binstall 下载预编译的工件并使用它们代替从 发布版 中下载的

cargo binstall cargo-espflash

默认情况下，在 Unix 系统中，我们使用 vendored-openssl Cargo 功能，这可能需要额外的工具，如 perl 和 make。要禁用此功能，请使用

OPENSSL_NO_VENDOR=1 cargo install cargo-espflash

用法

Cargo subcommand for flashing Espressif devices

Usage: cargo espflash <COMMAND>

Commands:
  board-info       Print information about a connected target device
  completions      Generate completions for the given shell
  erase-flash      Erase Flash entirely
  erase-parts      Erase specified partitions
  erase-region     Erase specified region
  flash            Flash an application in ELF format to a target device
  hold-in-reset    Hold the target device in reset
  monitor          Open the serial monitor without flashing the connected target device
  partition-table  Convert partition tables between CSV and binary format
  read-flash       Read SPI flash content
  reset            Reset the target device
  save-image       Generate a binary application image and save it to a local disk
  checksum-md5     Calculate the MD5 checksum of the given region
  help             Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Linux 上的权限

在Linux中，当使用任何需要使用串行端口的命令时，当前用户可能没有访问串行端口的权限，并可能会出现“权限被拒绝”或“端口不存在”的错误。

在大多数Linux发行版中，解决方案是将用户添加到dialout组（例如，使用ls -l /dev/ttyUSB0来查找组）的命令，例如：sudo usermod -a -G dialout $USER。您可以使用su - $USER来启用串行端口的无需注销和重新登录的读写权限。

有关更多信息，请参阅您Linux发行版的文档。

Windows 子系统 for Linux

目前无法在WSL1中使用cargo-espflash。目前没有计划添加对WSL1的支持。

在WSL2中使用时，也无法使用内置的USB_SERIAL_JTAG外设来烧录芯片，因为重置也会重置USB_SERIAL_JTAG外设，从而断开芯片与WSL2的连接。不过，可以通过UART使用WSL2来烧录芯片。

引导加载程序和分区表

cargo-espflash能够检测正在构建和烧录的包是否依赖于esp-idf-sys；如果依赖，则使用esp-idf-sys构建脚本构建的引导加载程序和分区表，否则将使用捆绑的引导加载程序和分区表。

如果提供了--bootloader和/或--partition-table选项，则无论包是否依赖于esp-idf-sys，都将使用这些选项。

配置文件

配置文件允许您为您的应用程序定义各种参数

• 串行端口
  • 按名称

    [connection]
    serial = "/dev/ttyUSB0"
    

  • 按USB VID/PID值

    [[usb_device]]
    vid = "303a"
    pid = "1001"
    

• 波特率

  baudrate = 460800
  

• 引导加载程序

  bootloader = "path/to/custom/bootloader.bin"
  

• 分区表

  partition_table = "path/to/custom/partition-table.bin"
  

• 闪存设置

  [flash]
  mode = "qio"
  size = "8MB"
  frequency = "80MHz"
  

您可以有本地和/或全局配置文件

• 对于本地配置，将文件存储在当前工作目录下或在父目录中（以支持Cargo工作区）的名称为espflash.toml
• 全局文件位置因操作系统而异
  • Linux: $HOME/.config/espflash/espflash.toml
  • macOS: $HOME/Library/Application Support/rs.esp.espflash/espflash.toml
  • Windows: %APPDATA%\esp\espflash\espflash.toml

配置优先级

1. 环境变量：如果设置了ESPFLASH_PORT或ESPFLASH_BAUD，则将使用这些值而不是配置文件值。
2. 本地配置文件
3. 全局配置文件

日志格式

cargo-espflash的flash和monitor子命令支持使用-L/--log-format参数的几种日志格式