Updated tutorial for embassy

Merge Request Overview

This merge request updates the Embassy-RS Setup tutorial:

• updated command for probe-rs installation
• added new suggestions for compilation and flashing over USB
• added details on how to setup VSC debugging
• updated toolchain to use rustc 1.83
• updated dependencies so that everything compiles
• changed the example code to a program that prints defmt logs from 2 different tasks

Updated 21.02

• added instructions on using a second RPi Pico as a debugger
• added more details on configuring cargo
• added information on probe-rs installation on Windows (untested)

Updated 24.02

• added more details for setup on Windows
• edition should now be set to 2021 in cargo.toml
• fixed 2 warnings on example code

Updated 02.03

• changed tutorial to use Pico 2W/RP2350
• use specific git version for embassy

Testing Strategy

This pull request was tested by building and running the site locally. After following the tutorial step by step, I was able to run and debug the example program from VSCode on Linux. Panic messages are also printed in the terminal.

We have to test this:

• Test on Windows
• Test on Linux
• Test on MacOS

TODO or Help Wanted

Feedback on the changes, especially on introducing the use of defmt for logs and the new example program.

Build

• Ran ./build.sh.

Author

Signed-off-by: Alexandru Ungureanu alexagungureanu@gmail.com

requested review from @irina_cristina.nita, @teodor.dicu, and @george_danut.aldea

Can anyone test this please?

requested review from @layla.el and @cristiana.precup

@aungureanu1002 please rebase this, we fixed the pipeline and it should run the test website.

changed the description

added 5 commits

• 1a5b4f90...73177a95 - 4 commits from branch main
• bb1f9476 - Updated tutorial for embassy

Compare with previous version

resolved all threads

marked the checklist item Test on Windows as completed

marked the checklist item Test on Windows as incomplete

marked the checklist item Ran ./build.sh. as incomplete

Hi, so before "Flashing over USB" after "VS code extention" it mentioned "using a .cargo/config.toml file:" so i went ahead and ran

cargo new my-pico-project
cd my-pico-project

After that it took like 30 mins to get cargo build to work, first it didnt like the main that was written which is

fn main() { 
	println!("Hello, world!"); 
}

I kept modifying and only these 2 versions ended up worked:

#![no_std]
#![no_main]
use panic_halt as _;
fn main() -> ! {
    loop {}
}

#![no_std]
#![no_main]
use panic_halt as _;

then I ran:

elf2uf2-rs -d -s C:\Users\scarl\Documents\my-pico-project\target\thumbv6m-none-eabi\release\my-pico-project

I got this :

warning: unused manifest key: build Compiling my-pico-project v0.1.0 (C:\Users\scarl\Documents\my-pico-project)
Finished release profile [optimized] target(s) in 2.38s

Then I connected a pico W, the folder with RPI-RP2 appeared, i tried the 2 methods with elf2uf2 and probe rs and these were the errors i had:

Error: "entry point is not in mapped part of file"
Error: "entry point is not in mapped part of probe-rs run --chip RP2040 --protocol swd --speed 16000 
C:\Users\scarl	\Documents\my-pico-project\target\thumbv6m-none-eabi\release\my-pico-project\scarl\Documents\my-pico-project>
Error: No connected probes were found.

I probably did something wrong but this is what i have so far. I will try again.

I also have this. I think I messed up the whole installation.

added tutorial label

Hi! I attempted to follow the tutorial on both macOS (12.7.6) and Ubuntu, but encountered multiple issues:

cargo install probe-rs --features cli --locked
    Updating crates.io index
error: there is nothing to install in `probe-rs v0.27.0`, because it has no binaries
`cargo install` is only for installing programs, and can't be used with libraries.
To use a library crate, add it as a dependency to a Cargo project with `cargo add`.

2. Compilation Failure on macOS (cargo build --release --target thumbv6m-none-eabi) Error (followed by 81 additional errors):

error[E0583]: file not found for module `inner`
  --> /Users/ines_maria/.cargo/registry/src/index.crates.io-6f17d22bba15001f/embassy-rp-0.3.1/src/rom_data/mod.rs:32:1
   |
32 | mod inner;
   | ^^^^^^^^^^
   |
   = help: to create the module `inner`, create file ".../src/rom_data/inner.rs" or ".../src/rom_data/inner/mod.rs"

3. Compilation Failure on Ubuntu (cargo build --release --target thumbv6m-none-eabi) Errors:

error[E0432]: unresolved import `defmt`
 --> src/main.rs:4:5
  |
4 | use defmt::*;
  |     ^^^^^ use of undeclared crate or module `defmt`

error[E0433]: failed to resolve: could not find `task` in `embassy_executor`
  --> src/main.rs:11:21
   |
11 | #[embassy_executor::task]
   |                     ^^^^ could not find `task` in `embassy_executor`

error[E0433]: failed to resolve: could not find `main` in `embassy_executor`
  --> src/main.rs:19:21
   |
19 | #[embassy_executor::main]
   |                     ^^^^ could not find `main` in `embassy_executor`

4. Issue with cargo add embassy-executor

cargo add embassy-executor --features arch-cortex-m,executor-thread,executor-interrupt,integrated-timers,task-arena-size-32768
    Updating crates.io index
      Adding embassy-executor v0.7.0 to dependencies.
error: unrecognized feature for crate embassy-executor: integrated-timers

Hi! I think you may be following the old tutorial, since both

cargo install probe-rs --features cli --locked

and

cargo add embassy-executor --features arch-cortex-m,executor-thread,executor-interrupt,integrated-timers,task-arena-size-32768

are outdated commands that I modified in the new version. Could you please verify that you are on the update_embassy_tutorial branch when viewing the tutorial?

I was on the wrong branch. I will soon test the correct branch. Thank you!

After switching to the correct branch, I restarted the tutorial on Linux, but cargo run still fails with the following error:

error: invalid instruction mnemonic 'sev'
  --> /home/ines/.cargo/registry/src/index.crates.io-6f17d22bba15001f/embassy-executor-0.7.0/src/arch/cortex_m.rs:13:31
   |
13 |             core::arch::asm!("sev");
   |                               ^
   |
note: instantiated into assembly here
  --> <inline asm>:2:2
   |
2  |     sev
   |     ^^^

error: could not compile `embassy-executor` (lib) due to 1 previous error
warning: build failed, waiting for other jobs to finish...

Hi i have the same error i replaced core::arch::asm!("sev"); with

#[cfg(target_arch = "arm")]
                unsafe {
                    #[cfg(not(armv6m))]
                    core::arch::asm!("sev");
                }

I don't think it is okay, that is what github copilot did, i got past build with this. Anyway, I am stuck between 2 errors so

1. If I add to main a panic handler in main, the project does not build.

error\[E0152\]: found duplicate lang item `panic_impl` --\> src/main.rs:41:1 | 41 | / fn panic(_info: &PanicInfo) -\> ! { 42 | | loop {} 43 | | } | |_^ | = note: the lang item is first defined in crate `panic_probe` (which `embassy` depends on) = note: first definition in `panic_probe` loaded from \\?\\C:\\Users\\scarl\\Documents\\testEmbassy\\embassy\\target\\thumbv6m-none-eabi\\debug\\deps\\libpanic_probe-cab8d6f40ab49dd8.rlib\
= note: second definition in the local crate (`embassy`)


Some errors have detailed explanations: E0152, E0659. For more information about an error, try `rustc --explain E0152`. warning: `embassy` (bin "embassy") generated 1 warning\
error: could not compile `embassy` (bin "embassy") due to 2 previous errors; 1 warning emitted

2. If I do not add a panic handler it builds, BUT does not run and says this:

   warning: unused import: `self`\
   --\> src/main.rs:6:24 | 6 | use embassy_rp::gpio::{self}; | ^^^^ | = note: `#[warn(unused_imports)]` on by default

   error: `#[panic_handler]` function required, but not found

   error: unwinding panics are not supported without std | = help: using nightly cargo, use -Zbuild-std with panic="abort" to avoid unwinding = note: since the core library is usually precompiled with panic="unwind", rebuilding your crate with panic="abort" may not be enough to fix the problem

   warning: `embassy` (bin "embassy") generated 1 warning\
   error: could not compile `embassy` (bin "embassy") due to 2 previous errors; 1 warning emitted

Also!

Linux:
sudo apt-get install pkg-config libudev-dev cmake git


Windows:

choco install cmake -y
choco install git

I found these commands for windows, but they need to install chocolatey

(this part can be ignored but this is the order i followed: )

1. Install rust 
1.2 Install Visual Studio C++ Build Tools (if not installed)
2. verify installation with rustup --versio
3. cargo install elf2uf2-rs
4. cargo install elf2uf2-rs
5.choco install cmake -y choco install git
6. cargo install probe-rs-tools --locked
!!!7. in case you did 6 before 5 run : cargo install --force probe-rs-tools --locked 
8. Install vs probe‑rs extension
9. cargo new --vcs none embassy
10. cd embassy
11. create rust-toolchain.toml
12. add code in tutorial
13.main
14. rustup target add thumbv6m-none-eabi
15. create memory.x + add code from tutorial
16.make build.rs + add code
17. cargo add embassy-executor --features arch-cortex-m,executor-	thread,executor-interrupt,task-arena-size-32768,defmt
18. cargo add cortex-m
cargo add cortex-m-rt
19. cargo add embassy-time
20. cargo add embassy-rp --features time-driver,critical-section-	impl,rp2040,defmt
21. cargo add log
cargo add embassy-usb-logger
22. cargo add panic-probe
23.cargo add rp-pac --features cortex-m-rt,defmt,rp2040,rt
24. cargo add defmt
cargo add defmt-rtt
// I realised i forgot to put [build] in cargo.build, i ran cargo clean and build 
25. add main
26. cargo run // doesn't work :((

Im gonna try again without forgetting the build

@ines_maria.moraru it seems that you are trying to build the code for your local architecture (x86) and this is why it errors that the sev instruction does not exist. That is am instruction for Cortex-M processors.

@aungureanu1002 do we have cargo run here?

@alexandru.radovici yes, we can use cargo run to compile the code and flash the board, but a .cargo/config.toml file is required.

yay, so the original main works!

so i guess

#[cfg(target_arch = "arm")]
                unsafe {
                    #[cfg(not(armv6m))]
                    core::arch::asm!("sev");
                }

works;

now the main provided does this:

It requires a panic handler.

marked this merge request as draft

added 1 commit

• 7eadf1d6 - Debug using second Pico

Compare with previous version

changed the description

marked the checklist item Ran ./build.sh. as completed

From the get go, I see that the tutorial is written for the RP2040, but we later decided on switching to RP2350. @alexandru.radovici, @aungureanu1002, should this be adapted, considering that they will use the Pico 2 W? If it should, I will could help with the modifications.

We probably should since there are sections which specifically mention that something needs to be done because we're using the RP2040 and not the RP2350, such as installing the dependencies for the example code.