diff --git a/book.toml b/book.toml index ef2d8261..776f5c1f 100644 --- a/book.toml +++ b/book.toml @@ -1,15 +1,16 @@ [book] -title = "The Rust on ESP Book" -description = "A comprehensive guide on using the Rust programming language with Espressif SoCs and modules" +title = "The Rust on ESP Book" +description = "A comprehensive guide on using the Rust programming language with Espressif SoCs and modules" multilingual = false -language = "en" +language = "en" [rust] edition = "2018" [output.html] git-repository-url = "https://github.com/esp-rs/book" -additional-js = ["assets/mermaid.min.js", "assets/mermaid-init.js"] +additional-js = ["assets/mermaid.min.js", "assets/mermaid-init.js"] +edit-url-template = "https://github.com/esp-rs/book/edit/main/{path}" [preprocessor.mermaid] command = "mdbook-mermaid" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9039025e..d956de92 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -11,7 +11,6 @@ - [Tooling](./tooling/index.md) - [Text Editors and IDEs](./tooling/text-editors-and-ides.md) - [espflash](./tooling/espflash.md) - - [espmonitor](./tooling/espmonitor.md) - [Debugging](./tooling/debugging/index.md) - [probe-rs](./tooling/debugging/probe-rs.md) - [OpenOCD](./tooling/debugging/openocd.md) diff --git a/src/installation/installation.md b/src/installation/installation.md index 92bfcc02..1ca6dc3a 100644 --- a/src/installation/installation.md +++ b/src/installation/installation.md @@ -84,7 +84,7 @@ Because there is no `Xtensa` support in the mainline Rust compiler you must use [esp-rs/espup] is a tool for installing and maintaining the required ecosystem to develop applications in Rust for Espressif SoC's (both `Xtensa` and `RISC-V` targets). -`espup` takes care of installing the proper Rust compiler (our fork in case of `Xtensa` targets, and the `nightly` toolchain with the necessary target for `RISC-V` targets), `LLVM` toolchain, `GCC` toolchains, and many other things. For more details, [see Usage section of the `espup` Readme]. +`espup` takes care of installing rustup, the proper Rust compiler (our fork in case of `Xtensa` targets, and the `nightly` toolchain with the necessary target for `RISC-V` targets), `LLVM` toolchain, `GCC` toolchains, and many other things. For more details, [see Usage section of the `espup` Readme]. In order to install `espup`: ```sh diff --git a/src/tooling/espflash.md b/src/tooling/espflash.md index f92e95ed..878e0252 100644 --- a/src/tooling/espflash.md +++ b/src/tooling/espflash.md @@ -4,46 +4,52 @@ A serial flasher utility for ESP devices. Supports flashing _ESP32_, _ESP32-C2_, The [esp-rs/espflash] repository contains two crates, `cargo-espflash` and `espflash`. You can find more information on both of these in their respective sections below. +> #### A note on `espflash` and `cargo-espflash`. +> +> The `espflash` and `cargo-espflash` commands shown below, assume that version `2.0` or greater. + [esp-rs/espflash]: https://github.com/esp-rs/espflash ## cargo-espflash -Provides a subcommand for `cargo` which handles cross-compilation and flashing. Note that this requires the unstable `build-std` cargo feature; for more information on this please refer to [the cargo documentation]. - -To install: +Provides a subcommand for `cargo` that handles cross-compilation and flashing. Note that this requires the unstable `build-std` cargo feature; for more information on this please refer to [the cargo documentation]. -```bash -cargo install cargo-espflash -``` +See [Installation section of cargo-espflash README] for details on how to install it. This command must be run within a Cargo project, ie.) a directory containing a `Cargo.toml` file. For example, to build an example named 'blinky' in `release` mode, flash the resulting binary to a device, and then subsequently start a serial monitor: ```bash -cargo espflash --example=blinky --release --monitor +cargo espflash flash --example=blinky --release --monitor ``` -For more information please see to the [cargo-espflash README]. +For more information about usage, please see [Usage section of cargo-espflash README]. [the cargo documentation]: https://doc.rust-lang.org/cargo/reference/unstable.html#build-std -[cargo-espflash readme]: https://github.com/esp-rs/espflash/blob/master/cargo-espflash/README.md +[Installation section of cargo-espflash README]: https://github.com/esp-rs/espflash/tree/main/cargo-espflash#installation +[Usage section of cargo-espflash README]: https://github.com/esp-rs/espflash/tree/main/cargo-espflash#usage ## espflash -Provides a standalone command-line application which flashes an ELF file to a device. +Provides a standalone command-line application that flashes an ELF file to a device. -To install: +See [Installation section of espflash README] for details on how to install it. + +Assuming you have built an ELF binary by other means already, `espflash` can be used to download it to your device and monitor the serial port. For example, if you have built the `getting-started/blinky` example from [esp-idf] using `idf.py` you might run something like: ```bash -cargo install espflash +espflash flash build/blinky --monitor ``` +See [Usage section of espflash README] for more details and other commands. -Assuming you have built an ELF binary by other means already, `espflash` can be used to download it to your device. For example, if you have built the `getting-started/blinky` example from [esp-idf] using `idf.py` you might run something like: - -```bash -espflash build/blinky +`espflash` can be used as a Cargo runner by adding the following to your project's `.cargo/config.toml` file: +```toml +[target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))'] +runner = "espflash flash --monitor" ``` +With this configuration you can flash and monitor you application using `cargo run`. -For more information please see to the [espflash README]. +[Installation section of espflash README]: https://github.com/esp-rs/espflash/tree/main/espflash#installation [esp-idf]: https://github.com/espressif/esp-idf [espflash readme]: https://github.com/esp-rs/espflash/blob/master/espflash/README.md +[Usage section of espflash README]: https://github.com/esp-rs/espflash/tree/main/espflash#usage diff --git a/src/tooling/espmonitor.md b/src/tooling/espmonitor.md deleted file mode 100644 index c3e3e4a2..00000000 --- a/src/tooling/espmonitor.md +++ /dev/null @@ -1,17 +0,0 @@ -# espmonitor - -The [esp-rs/espmonitor] repository contains two crates, `cargo-espmonitor` and `espmonitor`. - -## cargo-espmonitor - -```bash -cargo install cargo-espmonitor -``` - -## espmonitor - -```bash -cargo install espmonitor -``` - -[esp-rs/espmonitor]: https://github.com/esp-rs/espmonitor