From a3028ec75cbaaab18713b5503eb4077ab18d3ee7 Mon Sep 17 00:00:00 2001 From: Sergio Gasquez Arcos Date: Tue, 9 Jan 2024 16:32:01 +0100 Subject: [PATCH] Add defmt documentation (#540) * docs: Document differnt logging formats * docs: Add Logging format section and format ToC --- cargo-espflash/README.md | 16 +++++++++++++++- espflash/README.md | 36 ++++++++++++++++++++++++------------ 2 files changed, 39 insertions(+), 13 deletions(-) diff --git a/cargo-espflash/README.md b/cargo-espflash/README.md index 60b24fea..c94d6379 100644 --- a/cargo-espflash/README.md +++ b/cargo-espflash/README.md @@ -1,3 +1,4 @@ + # cargo-espflash [![Crates.io](https://img.shields.io/crates/v/cargo-espflash?labelColor=1C2C2E&color=C96329&logo=Rust&style=flat-square)](https://crates.io/crates/cargo-espflash) @@ -8,6 +9,7 @@ Cross-compiler and Cargo extension for flashing Espressif devices. Supports the **ESP32**, **ESP32-C2/C3/C6**, **ESP32-H2**, **ESP32-S2/S3**, and **ESP8266**. + ## Table of Contents - [Installation](#installation) @@ -17,7 +19,8 @@ Supports the **ESP32**, **ESP32-C2/C3/C6**, **ESP32-H2**, **ESP32-S2/S3**, and * - [Bootloader and Partition Table](#bootloader-and-partition-table) - [Package Metadata](#package-metadata) - [Configuration File](#configuration-file) - - [Configuration examples](#configuration-examples) + - [Configuration Examples](#configuration-examples) +- [Logging Format](#logging-format) - [License](#license) - [Contribution](#contribution) @@ -148,6 +151,17 @@ vid = "303a" pid = "1001" ``` +## Logging Format + +`cargo-espflash` `flash` and `monitor` subcommands support several logging formats using the `-L/--log-format` argument: +- `serial`: Default logging format +- `defmt`: Uses [`defmt`] logging framework. With logging format, logging strings have framing bytes to indicate that they are `defmt` messages. + - See [`defmt` section] of `esp-println` readme. + - For a detailed guide on how to use `defmt` in the `no_std` ecosystem, see [`defmt` project] of Embedded Rust (no_std) on Espressif book. + +[`defmt` section]: https://github.com/esp-rs/esp-println?tab=readme-ov-file#defmt +[`defmt` project]: https://esp-rs.github.io/no_std-training/03_6_defmt.html + ## License Licensed under either of: diff --git a/espflash/README.md b/espflash/README.md index cdeb30d3..45a43093 100644 --- a/espflash/README.md +++ b/espflash/README.md @@ -1,3 +1,4 @@ + # espflash [![Crates.io](https://img.shields.io/crates/v/espflash?labelColor=1C2C2E&color=C96329&logo=Rust&style=flat-square)](https://crates.io/crates/espflash) @@ -9,20 +10,20 @@ A library and command-line tool for flashing Espressif devices. Supports the **ESP32**, **ESP32-C2/C3/C6**, **ESP32-H2**, **ESP32-S2/S3**, and **ESP8266**. + ## Table of Contents -- [espflash](#espflash) - - [Table of Contents](#table-of-contents) - - [Installation](#installation) - - [Usage](#usage) - - [Permissions on Linux](#permissions-on-linux) - - [Windows Subsystem for Linux](#windows-subsystem-for-linux) - - [Cargo Runner](#cargo-runner) - - [Using `espflash` as a Library](#using-espflash-as-a-library) - - [Configuration File](#configuration-file) - - [Configuration Examples](#configuration-examples) - - [License](#license) - - [Contribution](#contribution) +- [Installation](#installation) +- [Usage](#usage) + - [Permissions on Linux](#permissions-on-linux) + - [Windows Subsystem for Linux](#windows-subsystem-for-linux) + - [Cargo Runner](#cargo-runner) +- [Using `espflash` as a Library](#using-espflash-as-a-library) +- [Configuration File](#configuration-file) + - [Configuration Examples](#configuration-examples) +- [Logging Format](#logging-format) +- [License](#license) + - [Contribution](#contribution) ## Installation @@ -157,6 +158,17 @@ vid = "303a" pid = "1001" ``` +## Logging Format + +`espflash` `flash` and `monitor` subcommands support several logging formats using the `-L/--log-format` argument: +- `serial`: Default logging format +- `defmt`: Uses [`defmt`] logging framework. With logging format, logging strings have framing bytes to indicate that they are `defmt` messages. + - See [`defmt` section] of `esp-println` readme. + - For a detailed guide on how to use `defmt` in the `no_std` ecosystem, see [`defmt` project] of Embedded Rust (no_std) on Espressif book. + +[`defmt` section]: https://github.com/esp-rs/esp-println?tab=readme-ov-file#defmt +[`defmt` project]: https://esp-rs.github.io/no_std-training/03_6_defmt.html + ## License Licensed under either of: