From 3d3d4e220c497729fa6719eecb0a1f63d271eb08 Mon Sep 17 00:00:00 2001 From: Jesse Braham Date: Fri, 19 Nov 2021 08:53:46 -0800 Subject: [PATCH] Update all READMEs, add missing information --- README.md | 128 ++++++++++++++++----------------------- cargo-espflash/README.md | 119 ++++++++++++++++++++++-------------- espflash/README.md | 79 +++++++++++++++++++----- 3 files changed, 189 insertions(+), 137 deletions(-) diff --git a/README.md b/README.md index 11ac32e..37769c0 100644 --- a/README.md +++ b/README.md @@ -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 to a binary (.bin) bootloader file - --example Example to build and flash - --features Comma delimited list of build features - --format Image format to flash - --partition-table Path to a CSV file containing partition table - --speed Baud rate at which to flash target device - -ARGS: - 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 diff --git a/cargo-espflash/README.md b/cargo-espflash/README.md index 4883cf1..4457565 100644 --- a/cargo-espflash/README.md +++ b/cargo-espflash/README.md @@ -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 to a binary (.bin) bootloader file - --example Example to build and flash - --features Comma delimited list of build features - --format Image format to flash - --partition-table Path to a CSV file containing partition table - --speed Baud rate at which to flash target device - -ARGS: - 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 port connected to target device + +OPTIONS: + --board-info + Display the connected board's information (deprecated, use the `board-info` subcommand + instead) + + --bootloader + Path to a binary (.bin) bootloader file + + --example + Example to build and flash + + --features ... + Comma delimited list of build features + + --format + Image format to flash (bootloader/direct-boot) + + -h, --help + Print help information + + --monitor + Open a serial monitor after flashing + + --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 + Baud rate at which to flash target device + + --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. diff --git a/espflash/README.md b/espflash/README.md index f02efce..b9bf006 100644 --- a/espflash/README.md +++ b/espflash/README.md @@ -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] +```text +espflash 1.1.0 + +USAGE: + espflash [OPTIONS] [ARGS] [SUBCOMMAND] + +ARGS: + Serial port connected to target device + ELF image to flash + +OPTIONS: + --board-info + Display the connected board's information (deprecated, use the `board-info` subcommand + instead) + + --bootloader + Path to a binary (.bin) bootloader file + + --format + Image format to flash + + -h, --help + Print help information + + --monitor + Open a serial monitor after flashing + + --partition-table + Path to a CSV file containing partition table + + --ram + Load the application to RAM instead of Flash + + --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