itsscb/espflash
1
0
Fork 0
mirror of https://github.com/esp-rs/espflash.git synced 2026-03-13 17:37:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update all READMEs, add missing information

Browse Source
This commit is contained in:
Jesse Braham 2021-11-19 08:53:46 -08:00
parent cbd8ef1d38
commit 3d3d4e220c
3 changed files with 189 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
README.md
View File

@ -1,105 +1,79 @@
# ESPFlash
# espflash
[![Actions Status](https://github.com/esp-rs/espflash/workflows/CI/badge.svg)](https://github.com/esp-rs/espflash/actions?query=workflow%3A"CI")
![Crates.io](https://img.shields.io/crates/l/espflash)
_ESP8266_ and _ESP32_ family serial flasher based on [esptool.py](https://github.com/espressif/esptool).
Serial flasher utility for Espressif SoCs and modules based on [esptool.py].
Requires `rustc 1.55.0` or greater.
Currently supports the **ESP32**, **ESP32-C3**, **ESP32-S2**, **ESP32-S3**, and **ESP8266**.
- [espflash library & binary](https://github.com/esp-rs/espflash/tree/master/espflash)
- [espflash cargo subcommand](https://github.com/esp-rs/espflash/tree/master/cargo-espflash)
This repository contains two applications:
| Application | Description |
| :--------------- | :---------------------------------------------------------- |
| [cargo-espflash] | Cargo subcommand for espflash |
| [espflash] | Library and `espflash` binary (_without_ Cargo integration) |
> **NOTE:** requires `rustc >= 1.55.0` in order to build either application
## Installation
```shell
cargo install cargo-espflash
$ cargo install cargo-espflash
$ cargo install espflash
```
## Usage
## cargo-espflash
Note: the documentation below is for the `cargo espflash` sub-command, which is probably what you are looking for.
For the standalone espflash binary, follow the link above
[cargo-espflash] is a subcommand for Cargo which utilizes the [espflash] library. This tool integrates with your Cargo projects and handles compilation, flashing, and monitoring for target devices.
```text
cargo-espflash 1.1.0
Cargo subcommand for flashing Espressif devices over serial
USAGE:
cargo espflash [FLAGS] [OPTIONS] [SERIAL] [SUBCOMMAND]
FLAGS:
--board-info Display the connected board's information (deprecated, use the `board-info` subcommand instead)
-h, --help Prints help information
--monitor Open a serial monitor after flashing
--ram Load the application to RAM instead of Flash
--release Build the application using the release profile
-V, --version Prints version information
OPTIONS:
--bootloader <PATH> Path to a binary (.bin) bootloader file
--example <EXAMPLE> Example to build and flash
--features <FEATURES> Comma delimited list of build features
--format <image format> Image format to flash
--partition-table <PATH> Path to a CSV file containing partition table
--speed <SPEED> Baud rate at which to flash target device
ARGS:
<SERIAL> Serial port connected to target device
SUBCOMMANDS:
board-info Display the connected board's information
help Prints this message or the help of the given subcommand(s)
save-image Save the image to disk instead of flashing to device
```
When the `--ram` option is specified, the provided ELF image will be loaded into ram and executed without touching the flash.
### Config
You can also specify the serial port by setting it in the config file located at `~/.config/espflash/espflash.toml` or Linux
or `%APPDATA%/esp/espflash/espflash.toml` on Windows.
```toml
[connection]
serial = "/dev/ttyUSB0"
```
### Package metadata
You can also specify the bootloader, partition table or image format for a project in the package metadata in `Cargo.toml`
```toml
[package.metadata.espflash]
partition_table = "partitions.csv"
bootloader = "bootloader.bin"
format = "direct-boot"
```
Please see the [cargo-espflash README] for more information.
### Example
```bash
$ cargo espflash --release --example blinky /dev/ttyUSB0
```shell
$ cargo espflash --release --example=blinky /dev/ttyUSB0
```
## License
## espflash
Licensed under the GNU General Public License Version 2. See [LICENSE](LICENSE) for more details.
[espflash] is a standalone binary and library contained within the same crate. This tool does not integrate with Cargo, but supports all of the same features as [cargo-espflash] which are not related to compilation.
Please see the [espflash README] for more information.
### Example
```shell
$ espflash /dev/ttyUSB0 target/xtensa-esp32-none-elf/release/examples/blinky
```
## Quickstart - Docker
The docker image `esprs/espflash` contains all necessary toolchains and tooling including espflash to build and flash.
To clone, build and flash the [esp32-hal](https://github.com/esp-rs/esp32-hal) examples run the following:
The `esprs/espflash` Docker image contains all necessary toolchains and tooling (including espflash) to build an application and flash it to a target device.
```cmd
git clone https://github.com/esp-rs/esp32-hal
cd esp32-hal
docker run -v "$(pwd):/espflash" --device=/dev/ttyUSB0 -ti esprs/espflash --release --tool=cargo --example=blinky /dev/ttyUSB0
To clone, build and flash the [esp32-hal] examples run the following:
```shell
$ git clone https://github.com/esp-rs/esp32-hal
$ cd esp32-hal
$ docker run -v "$(pwd):/espflash" --device=/dev/ttyUSB0 -ti esprs/espflash --release --example=blinky /dev/ttyUSB0
```
### Custom Docker Build
```cmd
git clone --depth 1 https://github.com/esp-rs/espflash.git
cd espflash
docker build -t esprs/espflash .
```shell
$ git clone --depth 1 https://github.com/esp-rs/espflash.git
$ cd espflash
$ docker build -t esprs/espflash .
```
## License
Licensed under the GNU General Public License Version 2. See [LICENSE](./espflash/LICENSE) for more details.
[esptool.py]: https://github.com/espressif/esptool
[cargo-espflash]: https://github.com/esp-rs/espflash/tree/master/cargo-espflash
[espflash]: https://github.com/esp-rs/espflash/tree/master/espflash
[cargo-espflash readme]: https://github.com/esp-rs/espflash/blob/master/cargo-espflash/README.md
[espflash readme]: https://github.com/esp-rs/espflash/blob/master/espflash/README.md
[esp32-hal]: https://github.com/esp-rs/esp32-hal

119
cargo-espflash/README.md
View File

@ -1,78 +1,107 @@
# `cargo-espflash`
# cargo-espflash
Cross-compiler and serial flasher cargo subcommand for Espressif devices. Supports __ESP32__, __ESP32-C3__, __ESP32-S2__, __ESP32-S3__, and __ESP8266__.
Cross-compiler and serial flasher cargo subcommand for Espressif SoCs and modules.
Prior to flashing, the project is built using the `build-std` unstable cargo feature. Please refer to the [cargo documentation](https://doc.rust-lang.org/cargo/reference/unstable.html#build-std) for more information.
Currently supports the **ESP32**, **ESP32-C3**, **ESP32-S2**, **ESP32-S3**, and **ESP8266**.
Prior to flashing, the project is built using the `build-std` unstable Cargo feature. Please refer to the [cargo documentation](https://doc.rust-lang.org/cargo/reference/unstable.html#build-std) for more information.
## Installation
```shell
cargo install cargo-espflash
$ cargo install cargo-espflash
```
## Usage
```text
cargo-espflash 1.1.0
Cargo subcommand for flashing Espressif devices over serial
USAGE:
cargo espflash [FLAGS] [OPTIONS] [SERIAL] [SUBCOMMAND]
FLAGS:
--board-info Display the connected board's information (deprecated, use the `board-info` subcommand instead)
-h, --help Prints help information
--monitor Open a serial monitor after flashing
--ram Load the application to RAM instead of Flash
--release Build the application using the release profile
-V, --version Prints version information
OPTIONS:
--bootloader <PATH> Path to a binary (.bin) bootloader file
--example <EXAMPLE> Example to build and flash
--features <FEATURES> Comma delimited list of build features
--format <image format> Image format to flash
--partition-table <PATH> Path to a CSV file containing partition table
--speed <SPEED> Baud rate at which to flash target device
ARGS:
<SERIAL> Serial port connected to target device
SUBCOMMANDS:
board-info Display the connected board's information
help Prints this message or the help of the given subcommand(s)
cargo-espflash 1.1.0
USAGE:
cargo espflash [OPTIONS] [SERIAL] [SUBCOMMAND]
ARGS:
<SERIAL> Serial port connected to target device
OPTIONS:
--board-info
Display the connected board's information (deprecated, use the `board-info` subcommand
instead)
--bootloader <BOOTLOADER>
Path to a binary (.bin) bootloader file
--example <EXAMPLE>
Example to build and flash
--features <FEATURES>...
Comma delimited list of build features
--format <FORMAT>
Image format to flash (bootloader/direct-boot)
-h, --help
Print help information
--monitor
Open a serial monitor after flashing
--partition-table <PARTITION_TABLE>
Path to a CSV file containing partition table
--ram
Load the application to RAM instead of Flash
--release
Build the application using the release profile
--speed <SPEED>
Baud rate at which to flash target device
--target <TARGET>
Target to build for
-V, --version
Print version information
SUBCOMMANDS:
board-info Display the connected board's information
help Print this message or the help of the given subcommand(s)
save-image Save the image to disk instead of flashing to device
```
When the `--ram` option is specified, the provided ELF image will be loaded into ram and executed without touching the flash.
## Configuration
### Config
You can also specify the serial port and/or expected VID/PID values by setting them in the configuration file. This file is in different locations depending on your operating system:
You can also specify the serial port by setting it in the config file located at `~/.config/espflash/espflash.toml` or Linux
or `%APPDATA%/esp/espflash/espflash.toml` on Windows.
| Operating System | Configuration Path |
| :--------------- | :----------------------------------------------------------------------- |
| **Linux:** | `/home/alice/.config/espflash/espflash.toml` |
| **Windows:** | `C:\Users\Alice\AppData\Roaming\esp\espflash\espflash.toml` |
| **macOS:** | `/Users/Alice/Library/Application Support/rs.esp.espflash/espflash.toml` |
An example configuration file may look as follows (note that TOML does _not_ support hexadecimal literals):
```toml
[connection]
serial = "/dev/ttyUSB0"
[usb_device]
vid = 12346 # 0x303A
pid = 32768 # 0x8000
```
### Package metadata
## Package Metadata
You can also specify the bootloader, partition table or image format for a project in the package metadata in `Cargo.toml`
You can specify the bootloader, partition table, or image format for a project in the package metadata in `Cargo.toml`:
```toml
[package.metadata.espflash]
[package.metadata.espflash]
partition_table = "partitions.csv"
bootloader = "bootloader.bin"
format = "direct-boot"
```
### Example
```bash
$ cargo espflash --release --example blinky /dev/ttyUSB0
```
## License
Licensed under the GNU General Public License Version 2. See [LICENSE](LICENSE) for more details.

79
espflash/README.md
View File

@ -1,46 +1,95 @@
# `espflash`
# espflash
__ESP32__, __ESP32-C3__, __ESP32-S2__, __ESP32-S3__, and __ESP8266__ serial flasher library and CLI application.
Serial flasher utility for Espressif SoCs and modules.
[![asciicast](https://asciinema.org/a/367205.svg)](https://asciinema.org/a/367205)
Currently supports the **ESP32**, **ESP32-C3**, **ESP32-S2**, **ESP32-S3**, and **ESP8266**.
[![asciicast](https://asciinema.org/a/UxRaCy4pretvGkghrRO0Qvypm.svg)](https://asciinema.org/a/UxRaCy4pretvGkghrRO0Qvypm)
## Installation
```shell
cargo install espflash
$ cargo install espflash
```
## Usage
```bash
$ espflash [--board-info] [--ram] <path to serial> <path to elf image>
```text
espflash 1.1.0
USAGE:
espflash [OPTIONS] [ARGS] [SUBCOMMAND]
ARGS:
<SERIAL> Serial port connected to target device
<IMAGE> ELF image to flash
OPTIONS:
--board-info
Display the connected board's information (deprecated, use the `board-info` subcommand
instead)
--bootloader <BOOTLOADER>
Path to a binary (.bin) bootloader file
--format <FORMAT>
Image format to flash
-h, --help
Print help information
--monitor
Open a serial monitor after flashing
--partition-table <PARTITION_TABLE>
Path to a CSV file containing partition table
--ram
Load the application to RAM instead of Flash
--speed <SPEED>
Baud rate at which to flash target device
-V, --version
Print version information
SUBCOMMANDS:
board-info Display the connected board's information
help Print this message or the help of the given subcommand(s)
save-image Save the image to disk instead of flashing to device
```
When the `--ram` option is specified, the provided ELF image will be loaded into ram and executed without touching the flash.
## Configuration
When the `--board-info` is specified, instead of flashing anything, the chip type and flash size will be printed.
You can also specify the serial port and/or expected VID/PID values by setting them in the configuration file. This file is in different locations depending on your operating system:
### Config
| Operating System | Configuration Path |
| :--------------- | :----------------------------------------------------------------------- |
| **Linux:** | `/home/alice/.config/espflash/espflash.toml` |
| **Windows:** | `C:\Users\Alice\AppData\Roaming\esp\espflash\espflash.toml` |
| **macOS:** | `/Users/Alice/Library/Application Support/rs.esp.espflash/espflash.toml` |
You can also specify the serial port by setting it in the config file located at `~/.config/espflash/espflash.toml` or linux
or `%APPDATA%/esp/espflash/espflash.toml` on Windows.
An example configuration file may look as follows (note that TOML does _not_ support hexadecimal literals):
```toml
[connection]
serial = "/dev/ttyUSB0"
[usb_device]
vid = 12346 # 0x303A
pid = 32768 # 0x8000
```
## Use as a Cargo Runner
### As cargo runner
You can also use `espflash` as a cargo runner by setting
You can also use `espflash` as a Cargo runner by adding the followin to your project's `.cargo/config` file:
```
[target.'cfg(all(target_arch = "xtensa", target_os = "none"))']
runner = "espflash --ram /dev/ttyUSB0"
```
in your `.cargo/config`, which then allows you to run your project using `xargo run`.
This then allows you to run your project using `cargo run`.
## License