Add a defmt project (#33)

* feat: Initial defmt chapter

* feat: Add esp-backtrace information

* feat: Remove .gitignore files

* ci: Cover defmt project

.github/workflows/ci.yml

@@ -64,6 +64,8 @@ jobs:
             path: "intro/panic"
           - name: "http-client"
             path: "intro/http-client"
+          - name: "defmt"
+            path: "intro/defmt"
           - name: "stack-overflow-detection"
             path: "advanced/stack-overflow-detection"
     steps:
@@ -79,7 +81,7 @@ jobs:
         working-directory: ${{ matrix.project.path }}
 
       - name: Wokwi CI check
-        if: matrix.project.name != 'stack-overflow-detection' && github.actor == 'esp-rs'
+        if: (matrix.project.name != 'stack-overflow-detection' || matrix.project.name != 'defmt') && github.actor == 'esp-rs'
         uses: wokwi/wokwi-ci-action@v1
         with:
           token: ${{ secrets.WOKWI_CLI_TOKEN }}

book/src/03_6_defmt.md

@@ -0,0 +1,52 @@
+# `defmt`
+In this chapter, we will cover [`defmt`][defmt], a highly efficient logging framework, and how to use it in the `no_std` environment.
+
+
+[defmt]: https://defmt.ferrous-systems.com/
+
+## `defmt` Ecosystem
+
+[`esp-println`][esp-println], [`esp-backtrace`][esp-backtrace] and [`espflash`/`cargo-espflash`][espflash] provide mechanisms to use `defmt`:
+- `espflash` has support for different [logging formats][espflash-logformat], one of them being `defmt`.
+  - `espflash` requires framming bytes as when using `defmt` it also needs to print non-`defmt` messages, like the bootloader prints.
+    - It's important to note that other `defmt`-enabled tools like `probe-rs` won't be able to parse these messages due to the extra framing bytes.
+  - Uses [rzcobs encoding](https://github.com/Dirbaio/rzcobs)
+- Both `esp-println` and `esp-backtrace` have a `defmt-espflash` feature, which adds framming bytes so `espflash` knows that is a `defmt` message.
+
+
+[esp-println]: https://github.com/esp-rs/esp-println
+[esp-backtrace]: https://github.com/esp-rs/esp-backtrace
+[espflash]: https://github.com/esp-rs/espflash
+[espflash-logformat]: https://github.com/esp-rs/espflash/blob/main/espflash/README.md#logging-format
+
+# Setup
+
+✅ Go to `intro/defmt` directory.
+
+✅ Open the prepared project skeleton in `intro/defmt`.
+
+`intro/defmt/examples/defmt.rs` contains the solution. You can run it with the following command:
+
+```shell
+cargo run --release --example defmt
+```
+
+## Exercise
+
+✅ Make sure the `defmt-espflash` feature of `esp-println` and `esp-backtrace` are enabled.
+
+✅ Update the [linking process](https://defmt.ferrous-systems.com/setup#linker-script) in the `.cargo/config.toml`.
+
+✅ Make sure, the [`defmt` crate](https://crates.io/crates/defmt) is added to the dependencies.
+
+✅ Make sure you are building `esp_println` and `esp_backtrace`
+```rust,ignore
+{{#include ../../intro/defmt/examples/defmt.rs:println_include}}
+```
+
+✅ Use the `defmt::println!` or any of the logging [`defmt` macros](https://docs.rs/defmt/latest/defmt/#macros) to print a message.
+- If you want to use any of the logging macros like `info`, `debug`
+  - Enable the `log` feature of `esp-println`
+  - When building the app, [set `DEFMT_LOG`](https://defmt.ferrous-systems.com/filtering.html?highlight=DEFMT_LOG#defmt_log) level.
+
+✅ Add a `panic!` macro to trigger a panic with a `defmt` message.

book/src/SUMMARY.md

@@ -12,5 +12,6 @@
   - [Detect a button press](./03_3_button.md)
   - [Detect a button press with interrupt](./03_4_interrupt.md)
   - [HTTP Client](./03_5_http_client.md)
+  - [Using `defmt`](./03_6_defmt.md)
 - [Advanced level examples](./04_0_intro_advanced_examples.md)
-  - [Stack overflow protection with Debug Assist](./04_1_stack_overflow_protection.md)
+  - [Stack overflow protection with Debug Assist](./04_1_stack_overflow_protection.md)

intro/defmt/.cargo/config.toml

@@ -0,0 +1,20 @@
+[target.riscv32imc-unknown-none-elf]
+runner = "espflash flash --monitor -L defmt"
+
+[build]
+rustflags = [
+  "-C", "link-arg=-Tlinkall.x",
+
+  # Add `defmt`linking options
+  "-C", "link-arg=-Tdefmt.x",
+
+  # Required to obtain backtraces (e.g. when using the "esp-backtrace" crate.)
+  # NOTE: May negatively impact performance of produced code
+  "-C", "force-frame-pointers",
+
+]
+
+target = "riscv32imc-unknown-none-elf"
+
+[unstable]
+build-std = ["core"]