From e5d4d0952b78ef343f14205f5ebd3f1d7804f9e8 Mon Sep 17 00:00:00 2001 From: Ulf Lilleengen Date: Fri, 10 Dec 2021 12:46:41 +0100 Subject: [PATCH] Add doc-specific example and add it to CI --- ci.sh | 1 + .../ROOT/examples/basic/.cargo/config.toml | 6 ++++ docs/modules/ROOT/examples/basic/Cargo.toml | 18 +++++++++++ docs/modules/ROOT/examples/basic/src/main.rs | 30 +++++++++++++++++++ .../modules/ROOT/pages/basic_application.adoc | 30 +++++-------------- 5 files changed, 63 insertions(+), 22 deletions(-) create mode 100644 docs/modules/ROOT/examples/basic/.cargo/config.toml create mode 100644 docs/modules/ROOT/examples/basic/Cargo.toml create mode 100644 docs/modules/ROOT/examples/basic/src/main.rs diff --git a/ci.sh b/ci.sh index 6beea8677..ec610d7f6 100755 --- a/ci.sh +++ b/ci.sh @@ -40,6 +40,7 @@ cargo batch \ --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32l476vg,defmt \ --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv6m-none-eabi --features stm32l072cz,defmt \ --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7m-none-eabi --features stm32l151cb-a,defmt \ + --- build --release --manifest-path docs/modules/ROOT/examples/basic/Cargo.toml --target thumbv7em-none-eabi --- build --release --manifest-path examples/std/Cargo.toml --target x86_64-unknown-linux-gnu --out-dir out/examples/std \ --- build --release --manifest-path examples/nrf/Cargo.toml --target thumbv7em-none-eabi --out-dir out/examples/nrf \ --- build --release --manifest-path examples/rp/Cargo.toml --target thumbv6m-none-eabi --out-dir out/examples/rp \ diff --git a/docs/modules/ROOT/examples/basic/.cargo/config.toml b/docs/modules/ROOT/examples/basic/.cargo/config.toml new file mode 100644 index 000000000..c75b5c539 --- /dev/null +++ b/docs/modules/ROOT/examples/basic/.cargo/config.toml @@ -0,0 +1,6 @@ +[target.'cfg(all(target_arch = "arm", target_os = "none"))'] +# replace nRF82840_xxAA with your chip as listed in `probe-run --list-chips` +runner = "probe-run --chip nRF52840_xxAA" + +[build] +target = "thumbv7em-none-eabi" diff --git a/docs/modules/ROOT/examples/basic/Cargo.toml b/docs/modules/ROOT/examples/basic/Cargo.toml new file mode 100644 index 000000000..a683a28bf --- /dev/null +++ b/docs/modules/ROOT/examples/basic/Cargo.toml @@ -0,0 +1,18 @@ +[package] +authors = ["Dario Nieuwenhuis "] +edition = "2018" +name = "embassy-basic-example" +version = "0.1.0" + +[dependencies] +embassy = { version = "0.1.0", path = "../../../../embassy", features = ["defmt"] } +embassy-traits = { version = "0.1.0", path = "../../../../embassy-traits", features = ["defmt"] } +embassy-nrf = { version = "0.1.0", path = "../../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] } + +defmt = "0.3" +defmt-rtt = "0.3" + +cortex-m = "0.7.3" +cortex-m-rt = "0.7.0" +embedded-hal = "0.2.6" +panic-probe = { version = "0.3", features = ["print-defmt"] } diff --git a/docs/modules/ROOT/examples/basic/src/main.rs b/docs/modules/ROOT/examples/basic/src/main.rs new file mode 100644 index 000000000..0152b40bb --- /dev/null +++ b/docs/modules/ROOT/examples/basic/src/main.rs @@ -0,0 +1,30 @@ +#![no_std] +#![no_main] +#![feature(type_alias_impl_trait)] + +use defmt_rtt as _; // global logger +use panic_probe as _; + +use defmt::*; + +use embassy::executor::Spawner; +use embassy::time::{Duration, Timer}; +use embassy_nrf::gpio::{Level, Output, OutputDrive}; +use embassy_nrf::Peripherals; +use embedded_hal::digital::v2::OutputPin; + +#[embassy::task] +async fn blinker(mut led: Output<'static, P0_13>, interval: Duration) { + loop { + unwrap!(led.set_high()); + Timer::after(interval).await; + unwrap!(led.set_low()); + Timer::after(interval).await; + } +} + +#[embassy::main] +async fn main(spawner: Spawner, p: Peripherals) { + let led = Output::new(p.P0_13, Level::Low, OutputDrive::Standard); + unwrap!(spawner.spawn(blinker(led, Duration::from_millis(300)))); +} diff --git a/docs/modules/ROOT/pages/basic_application.adoc b/docs/modules/ROOT/pages/basic_application.adoc index 53aaa3d7d..c2849927a 100644 --- a/docs/modules/ROOT/pages/basic_application.adoc +++ b/docs/modules/ROOT/pages/basic_application.adoc @@ -2,8 +2,9 @@ So you've got one of the xref:examples.adoc[examples] running, but what now? Let's go through a simple Embassy application for the nRF52 DK to understand it better. +== Main -== The main +The full example can be found link:https://github.com/embassy-rs/embassy/tree/book-poc/docs/modules/ROOT/examples/basic[here]. === Rust Nightly @@ -11,9 +12,7 @@ The first thing you'll notice is a few declarations stating that Embassy require [source,rust] ---- -#![no_std] -#![no_main] -#![feature(type_alias_impl_trait)] +include::example$basic/src/main.rs[lines="1..3"] ---- === Dealing with errors @@ -22,8 +21,7 @@ Then, what follows are some declarations on how to deal with panics and faults. [source,rust] ---- -use defmt_rtt as _; -use panic_probe as _; +include::example$basic/src/main.rs[lines="5..6"] ---- === Task declaration @@ -32,15 +30,7 @@ After a bit of import declaration, the tasks run by the application should be de [source,rust] ---- -#[embassy::task] -async fn blinker(led: Output<'static, P0_13>, interval: Duration) { - loop { - let _ = led.set_high(); - Timer::after(interval).await; - let _ = led.set_low(); - Timer::after(interval).await; - } -} +include::example$basic/src/main.rs[lines="16..24"] ---- An embassy task must be declared `async`, and may NOT take generic arguments. In this case, we are handed the LED that should be blinked and the interval of the blinking. @@ -53,13 +43,9 @@ The main entry point of an Embassy application is defined using the `#[embassy:: The `Spawner` is the way the main application spawns other tasks. The `Peripherals` type holds all peripherals that the application may use. In this case, we want to configure one of the pins as a GPIO output driving the LED: -[source, rust] +[source,rust] ---- -#[embassy::main] -async fn main(spawner: Spawner, p: Peripherals) { - let mut led = Output::new(p.P0_13, Level::Low, OutputDrive::Standard); - let _ = spawner.spawn(blinker(led, Duration::from_millis(300))); -} +include::example$basic/src/main.rs[lines="26..30"] ---- @@ -78,7 +64,7 @@ The project definition needs to contain the embassy dependencies: [source,toml] ---- -include::example$examples/nrf/Cargo.toml[lines="9..11"] +include::example$basic/Cargo.toml[lines="8..10"] ---- Depending on your microcontroller, you may need to replace `embassy-nrf` with something else (`embassy-stm32` for STM32. Remember to update feature flags as well).