28 releases (18 stable)
3.2.0 | Oct 18, 2024 |
---|---|
3.1.0 | May 27, 2024 |
3.0.0 | Mar 13, 2024 |
2.1.0 | Oct 3, 2023 |
0.1.2 | Oct 2, 2020 |
#17 in Embedded development
6,723 downloads per month
Used in 14 crates
(3 directly)
5.5MB
6.5K
SLoC
Contains (ELF exe/lib, 4MB) resources/apps/esp32c6, (ELF exe/lib, 3MB) resources/apps/esp32c2, (ELF exe/lib, 3.5MB) resources/apps/esp32c3, (ELF exe/lib, 3.5MB) resources/apps/esp32h2, (ELF exe/lib, 1.5MB) resources/apps/esp32, (ELF exe/lib, 1.5MB) resources/apps/esp32s2 and 2 more.
espflash
A library and command-line tool for flashing Espressif devices.
Supports the ESP32, ESP32-C2/C3/C6, ESP32-H2, ESP32-P4, and ESP32-S2/S3.
Table of Contents
Installation
If you are installing espflash
from source (ie. using cargo install
) then you must have rustc>=1.76.0
installed on your system.
If you are running Linux then libudev must also be installed; this is available via most popular package managers. If you are running Windows or macOS you can ignore this step.
# Debian/Ubuntu/etc.
apt-get install libudev-dev
# Fedora
dnf install systemd-devel
To install:
cargo install espflash
Alternatively, you can use cargo-binstall to download pre-compiled artifacts from the releases and use them instead:
cargo binstall espflash
Usage
A command-line tool for flashing Espressif devices
Usage: 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 connected 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
write-bin Write a binary file to a specific address in a target device's flash
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
Permissions on Linux
In Linux, when using any of the commands that requires using a serial port, the current user may not have access to serial ports and a "Permission Denied" or "Port doesn’t exist" errors may appear.
On most Linux distributions, the solution is to add the user to the dialout
group (check e.g. ls -l /dev/ttyUSB0
to find the group) with a command like sudo usermod -a -G dialout $USER
. You can call su - $USER
to enable read and write permissions for the serial port without having to log out and back in again.
Check your Linux distribution’s documentation for more information.
Windows Subsystem for Linux
It is not currently possible to use espflash
from within WSL1. There are no plans to add support for WSL1 at this time.
It is also not possible to flash chips using the built-in USB_SERIAL_JTAG
peripheral when using WSL2, because resetting also resets USB_SERIAL_JTAG
peripheral, which then disconnects the chip from WSL2. Chips can be flashed via UART using WSL2, however.
Cargo Runner
You can also use espflash
as a Cargo runner by adding the following to your project's .cargo/config.toml
file, for example:
[target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))']
runner = "espflash flash --baud=921600 --monitor /dev/ttyUSB0"
With this configuration you can flash and monitor you application using cargo run
.
Using espflash
as a Library
espflash
can be used as a library in other applications:
espflash = { version = "2.1", default-features = false }
or cargo add espflash --no-default-features
Warning Note that the
cli
module does not provide SemVer guarantees.
We disable the default-features
to opt-out the cli
feature, which is enabled by default; you likely will not need any of these types or functions in your application so there’s no use pulling in the extra dependencies.
Configuration File
The configuration file allows you to define various parameters for your application:
- Serial port:
- By name:
[connection] serial = "/dev/ttyUSB0"
- By USB VID/PID values:
[[usb_device]] vid = "303a" pid = "1001"
- By name:
- Baudrate:
baudrate = 460800
- Bootloader:
bootloader = "path/to/custom/bootloader.bin"
- Partition table
partition_table = "path/to/custom/partition-table.bin"
- Flash settings
[flash] mode = "qio" size = "8MB" frequency = "80MHz"
You can have a local and/or a global configuration file:
- For local configurations, store the file under the current working directory or in the parent directory (to support Cargo workspaces) with the name
espflash.toml
- Global file location differs based on your operating system:
- Linux:
$HOME/.config/espflash/espflash.toml
- macOS:
$HOME/Library/Application Support/rs.esp.espflash/espflash.toml
- Windows:
%APPDATA%\esp\espflash\espflash.toml
- Linux:
Configuration precedence
- Environment variables: If
ESPFLASH_PORT
orESPFLASH_BAUD
are set, the will be used instead of the config file value. - Local configuration file
- Global configuration file
Logging Format
espflash
flash
and monitor
subcommands support several logging formats using the -L/--log-format
argument:
serial
: Default logging formatdefmt
: Usesdefmt
logging framework. With logging format, logging strings have framing bytes to indicate that they aredefmt
messages.- See
defmt
section ofesp-println
readme. - For a detailed guide on how to use
defmt
in theno_std
ecosystem, seedefmt
project of Embedded Rust (no_std) on Espressif book.
- See
License
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
~3–16MB
~220K SLoC