esp-rs/no_std-training

Getting-started guide on using the Rust with Espressif SoCs using no_std.

no_std training

This repository contains Training Material for learning to use Embedded Rust with no_std with the Espressif ESP32-C3.

We suggest you start by reading the book.

Contents

• Some introductory level examples:
  • A basic hello-world (Source)
  • A panic example(Source)
  • A blinky example(Source)
  • A button example(Source)
  • A button with interrupt example(Source)
  • An HTTP client example(Source)

no_std-training's Issues

No link to crate documentation in intro/http-client/src/main.rs

Context: I have a reasonable Rust experience, but zero experience with ESP32. I got the ESP32-C3-RUST dev board and followed the https://esp-rs.github.io/no_std-training/ up until the http client example.

The example requires you to configure the clocks, but that's a bit of an abrupt departure. There's no link to the documentation for this.

Only when using Visual Code Studio can I find the hal crate, but it doesn't really make it clear how to proceed from here. By grepping around deep inside .cargo I finally find examples-util/src/lib.rs that suggests I should use ClockControl::configure(system.clock_control, CpuClock::Clock160MHz).freeze(); but I'm at a loss at how I was supposed to have known that.

I imagine I'm not the only to be confused at this point.

ADD: this is apparently only the beginning of the trouble. Hopefully there is documentation that I'm just missing.

Example `http-client` fails to build

I've tried following https://esp-rs.github.io/no_std-training/ but had troubles compiling the http-client example.

Steps to reproduce (running on NixOS):

$ rustup toolchain install nightly-2023-06-25 --component rust-src --target riscv32imc-unknown-none-elf
$ rustup --version
rustup 1.26.0 (1980-01-01)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active `rustc` version is `rustc 1.72.0-nightly (f7ca9df69 2023-06-24)`
$ git clone https://github.com/esp-rs/no_std-training
$ cd no_std-training/intro/http-client/
$ cargo run --release --example http-client

I have attached the build output: http-client.txt.

I'm not very familiar with Rust, but it looks like dependencies embedded-io and linked_list_allocator failed to build.

I was able to build the hello world, per https://esp-rs.github.io/no_std-training/02_4_hello_world.html .

Proposed change to the format of the examples

Proposed change to the format of the examples:

Currently the repo is setup to use the example format:

cargo run --release --example http-client

to run each example.

I find this difficult for a number of reasons:

1.) Multiple apparent versions of the example source exist in the repo:

diff intro/http-client/src/main.rs intro/http-client/examples/http-client.rs

Having 2 different apparent source files for the same example in the repo could cause some unnecessary confusion.

2.) If you want to start a project based on that example, you're left with the very confusing process of trying to figure out how to integrate a new cargo generate folder with the example folder.

It would seem so much easier to just create each example as a matching set of a complete cargo generated project that can be a starting point. (Minus the git, vscode, wokwi integrations.)

The challenge:

The main challenge I see to this is that git/wokwi/vscode etc integrations that exists in the cargo generated project. I would suggest completely stripping them from the suggested examples.

Update defmt example

See esp-rs/esp-backtrace#48 and esp-rs/esp-println#80

Ideas for additional content

Here are some ideas for additional content in no particular order

• async with embassy
• advanced peripherals (e.g. I2C sensor, SPI display ...)
• writing / reading flash with esp-storage
• esp-wifi: non-async and async
  • basics for the start, later we can add a few more things here
• TLS with embedded-tls and esp-mbedtls

CI: Cover HTTP client example

Currently, http client example is not built in CI

Remove disabling watchdog from examples

Since the last esp-hal release we can get rid of the code disabling the watchdog.

Consider including parts of the solution instead of copy pasting to the markdown file

It might be better to use https://rust-lang.github.io/mdBook/format/mdbook.html#including-portions-of-a-file (especially with anchors) instead of copy-pasting code.

That way we could make sure that what is written in the book is always in sync with the actual code and we can make sure the code snippets are correct (since we check them in CI).

Only drawback I see when doing this: the ANCHOR comments in Rust source files might look a bit confusing - but we could explain that in the introduction