DOCSEARCHbyAlgolia
Submit Docs

espflash

repository·main·Indexed 20 days ago

https://github.com/esp-rs/espflash

A set of serial flasher utilities for Espressif devices, including a standalone CLI, a Rust library, and the cargo-espflash Cargo subcommand. It supports ESP32, ESP32-C, ESP32-H, ESP32-P, and ESP32-S series microcontrollers. Key features include flashing ELF files, serial monitoring with serial or defmt logging, erasing flash, and reading SPI flash content. Configuration is managed via espflash.toml and espflash_ports.toml files or environment variables.

Tokens
20.2K
Snippets
84
Records
105
Agent score
72%

What's inside espflash

  1. Overview of espflash

    main

    espflash provides serial flasher utilities for Espressif devices, inspired by esptool.py. It is available as both a standalone command-line tool/library and a Cargo extension.

    Supported Devices:

    • ESP32
    • ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61
    • ESP32-H2
    • ESP32-P4
    • ESP32-S2, ESP32-S3

  2. Understand configuration precedence and locations

    main

    The configuration for cargo-espflash follows a specific hierarchy. Environment variables always take precedence over file-based configurations.

    Precedence Order:

    1. Environment Variables: ESPFLASH_PORT, MONITOR_BAUD, or ESPFLASH_BAUD.
    2. Local Configuration: espflash.toml or espflash_ports.toml in the current or parent directory (supports Cargo workspaces).
    3. Global Configuration: Located in OS-specific directories.

    Global Configuration Locations:

    • Linux: $HOME/.config/espflash/espflash.toml or espflash_ports.toml
    • macOS: $HOME/Library/Application Support/rs.esp.espflash/espflash.toml or espflash_ports.toml
    • Windows: %APPDATA%\esp\espflash\espflash.toml or espflash_ports.toml

  3. Manage ESP-IDF tools path

    main

    By default, ESP-IDF tools are installed and exported to target/esp-idf-tools. This allows them to be cleaned up along with the rest of the target directory.

    To use a different location for these tools, set the IDF_TOOLS_PATH environment variable explicitly.

    • Unix: Uses install.sh and export.sh for setup.
    • Windows: Uses install.bat and export.bat for setup.

  4. Use cargo-espflash as a Cargo extension

    main
    If you want to flash Espressif devices directly through Cargo, use the cargo-espflash extension. For specific installation instructions, refer to the cargo-espflash package documentation.

  5. Use espflash as a CLI tool or library

    main
    The espflash package provides a standalone command-line tool and a library for flashing Espressif devices. For installation and detailed usage, refer to the espflash package documentation.

  6. Enable the pre-commit Git hook

    main

    To ensure package formatting is verified before commits, you can enable the provided pre-commit hook by copying it to your local .git/hooks/ directory.

    If the hook fails, you can bypass it for a specific commit using the --no-verify flag, but ensure all packages are correctly formatted before submitting a pull request.

    $ cp pre-commit .git/hooks/pre-commit

  7. Configure espflash as a Cargo Runner

    main

    You can integrate espflash into your Rust workflow by setting it as the runner in your .cargo/config.toml. This allows you to flash and monitor your application automatically when running cargo run.

    [target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))']
runner = "espflash flash --baud=921600 --monitor /dev/ttyUSB0"

  8. Configure WSL2 for flashing via UART

    main

    Flashing via USB_SERIAL_JTAG is not supported in WSL2 because resetting the chip disconnects the peripheral from WSL2. However, flashing via UART is possible if systemd is enabled in WSL2.

    Steps to enable systemd in WSL2:

    1. Edit (or create) /etc/wsl.conf with sudo:
      [boot]
systemd=true
    2. Close the WSL distribution in Windows via PowerShell:
      wsl.exe --shutdown
    [boot]
systemd=true

  9. Install cargo-espflash

    main

    You can install cargo-espflash from source using cargo install. Note that you must have rustc>=1.95.0 installed. Alternatively, you can use cargo-binstall to download pre-compiled artifacts from the official releases.

    Requirements:

    • rustc >= 1.95.0 (if installing from source)
    • cargo-binstall (optional, for pre-compiled binaries)
    # Install from source
cargo install cargo-espflash --locked

# Install via pre-compiled binaries
cargo binstall cargo-espflash

  10. Rebuild the bootloaders

    main

    If you need to rebuild the bootloaders listed in the repository, use the build-bootloaders xtask command. This command uses the sdkconfig fragments defined in bootloaders/manifest.yaml and generates bootloaders from ESP-IDF release/v6.1.

    To rebuild them and ensure all necessary tools are installed, run:

    cargo build-bootloaders --install-tools
# or
cargo run -p xtask -- build-bootloaders --install-tools
    cargo build-bootloaders --install-tools

  11. Install espflash

    main

    You can install espflash from source using cargo install. Note that you must have rustc>=1.95.0 installed. Alternatively, use cargo-binstall to download pre-compiled artifacts.

    # Install from source
cargo install espflash --locked

# Install via pre-compiled binaries
cargo binstall espflash
    cargo install espflash --locked

  12. Use cargo-espflash to flash and monitor ESP32 devices

    main

    The cargo-espflash tool is a Cargo subcommand that automates the process of building, flashing, and monitoring ESP32-based applications. It handles converting ELF files into the appropriate binary formats (like ESP-IDF), managing bootloaders and partition tables, and providing a serial monitor.

    To use it, ensure you have espflash installed and that your project is configured for the target chip. You can run commands via cargo espflash <COMMAND>.

    cargo espflash flash
cargo espflash monitor