10 files changed, 101 insertions, 47 deletions

diff --git a/docs/modules/ROOT/examples/basic/src/main.rs b/docs/modules/ROOT/examples/basic/src/main.rs
index 2a4ee5968..4412712c8 100644
--- a/docs/modules/ROOT/examples/basic/src/main.rs
+++ b/docs/modules/ROOT/examples/basic/src/main.rs
@@ -4,12 +4,11 @@
 use defmt::*;
 use embassy_executor::Spawner;
 use embassy_nrf::gpio::{Level, Output, OutputDrive};
-use embassy_nrf::peripherals::P0_13;
 use embassy_time::{Duration, Timer};
 use {defmt_rtt as _, panic_probe as _}; // global logger
 
 #[embassy_executor::task]
-async fn blinker(mut led: Output<'static, P0_13>, interval: Duration) {
+async fn blinker(mut led: Output<'static>, interval: Duration) {
     loop {
         led.set_high();
         Timer::after(interval).await;
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs b/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
index e6753be28..004602816 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
+++ b/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
@@ -3,14 +3,14 @@
 
 use embassy_executor::Spawner;
 use embassy_stm32::exti::ExtiInput;
-use embassy_stm32::gpio::{Input, Level, Output, Pull, Speed};
+use embassy_stm32::gpio::{Level, Output, Pull, Speed};
 use {defmt_rtt as _, panic_probe as _};
 
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     let p = embassy_stm32::init(Default::default());
     let mut led = Output::new(p.PB14, Level::Low, Speed::VeryHigh);
-    let mut button = ExtiInput::new(Input::new(p.PC13, Pull::Up), p.EXTI13);
+    let mut button = ExtiInput::new(p.PC13, p.EXTI13, Pull::Up);
 
     loop {
         button.wait_for_any_edge().await;
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs b/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs
index aecba0755..743c9d99b 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs
+++ b/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs
@@ -6,13 +6,12 @@ use core::cell::RefCell;
 use cortex_m::interrupt::Mutex;
 use cortex_m::peripheral::NVIC;
 use cortex_m_rt::entry;
-use embassy_stm32::gpio::{Input, Level, Output, Pin, Pull, Speed};
-use embassy_stm32::peripherals::{PB14, PC13};
+use embassy_stm32::gpio::{Input, Level, Output, Pull, Speed};
 use embassy_stm32::{interrupt, pac};
 use {defmt_rtt as _, panic_probe as _};
 
-static BUTTON: Mutex<RefCell<Option<Input<'static, PC13>>>> = Mutex::new(RefCell::new(None));
-static LED: Mutex<RefCell<Option<Output<'static, PB14>>>> = Mutex::new(RefCell::new(None));
+static BUTTON: Mutex<RefCell<Option<Input<'static>>>> = Mutex::new(RefCell::new(None));
+static LED: Mutex<RefCell<Option<Output<'static>>>> = Mutex::new(RefCell::new(None));
 
 #[entry]
 fn main() -> ! {
@@ -62,14 +61,14 @@ fn EXTI15_10() {
 
 const PORT: u8 = 2;
 const PIN: usize = 13;
-fn check_interrupt<P: Pin>(_pin: &mut Input<'static, P>) -> bool {
+fn check_interrupt(_pin: &mut Input<'static>) -> bool {
     let exti = pac::EXTI;
     let pin = PIN;
     let lines = exti.pr(0).read();
     lines.line(pin)
 }
 
-fn clear_interrupt<P: Pin>(_pin: &mut Input<'static, P>) {
+fn clear_interrupt(_pin: &mut Input<'static>) {
     let exti = pac::EXTI;
     let pin = PIN;
     let mut lines = exti.pr(0).read();
@@ -77,7 +76,7 @@ fn clear_interrupt<P: Pin>(_pin: &mut Input<'static, P>) {
     exti.pr(0).write_value(lines);
 }
 
-fn enable_interrupt<P: Pin>(_pin: &mut Input<'static, P>) {
+fn enable_interrupt(_pin: &mut Input<'static>) {
     cortex_m::interrupt::free(|_| {
         let rcc = pac::RCC;
         rcc.apb2enr().modify(|w| w.set_syscfgen(true));
diff --git a/docs/modules/ROOT/pages/basic_application.adoc b/docs/modules/ROOT/pages/basic_application.adoc
index 95792d5a0..d5aad806d 100644
--- a/docs/modules/ROOT/pages/basic_application.adoc
+++ b/docs/modules/ROOT/pages/basic_application.adoc
@@ -17,22 +17,13 @@ The first thing you’ll notice are two attributes at the top of the file. These
 include::example$basic/src/main.rs[lines="1..2"]
 ----
 
-=== Rust Nightly
-
-The next declaration is a Rust Unstable feature, which means that Embassy requires Rust Nightly:
-
-[source,rust]
-----
-include::example$basic/src/main.rs[lines="3"]
-----
-
 === Dealing with errors
 
 Then, what follows are some declarations on how to deal with panics and faults. During development, a good practice is to rely on `defmt-rtt` and `panic-probe` to print diagnostics to the terminal:
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="10"]
+include::example$basic/src/main.rs[lines="8"]
 ----
 
 === Task declaration
@@ -41,7 +32,7 @@ After a bit of import declaration, the tasks run by the application should be de
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="12..20"]
+include::example$basic/src/main.rs[lines="10..18"]
 ----
 
 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.
@@ -56,7 +47,7 @@ We then initialize the HAL with a default config, which gives us a `Peripherals`
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="22..-1"]
+include::example$basic/src/main.rs[lines="20..-1"]
 ----
 
 What happens when the `blinker` task has been spawned and main returns? Well, the main entry point is actually just like any other task, except that you can only have one and it takes some specific type arguments. The magic lies within the `#[embassy_executor::main]` macro. The macro does the following:
diff --git a/docs/modules/ROOT/pages/best_practices.adoc b/docs/modules/ROOT/pages/best_practices.adoc
index 1e02f9ba9..bfcedec06 100644
--- a/docs/modules/ROOT/pages/best_practices.adoc
+++ b/docs/modules/ROOT/pages/best_practices.adoc
@@ -3,8 +3,10 @@
 Over time, a couple of best practices have emerged. The following list should serve as a guideline for developers writing embedded software in _Rust_, especially in the context of the _Embassy_ framework.
 
 == Passing Buffers by Reference
-It may be tempting to pass arrays or wrappers, like link:https://docs.rs/heapless/latest/heapless/[`heapless::Vec`], to a function or return one just like you would with a `std::Vec`. However, in most embedded applications you don't want to spend ressources on an allocator and end up placing buffers on the stack.
-This, however, can easily blow up your stack if you are not careful.
+It may be tempting to pass arrays or wrappers, like link:https://docs.rs/heapless/latest/heapless/[`heapless::Vec`],
+to a function or return one just like you would with a `std::Vec`. However, in most embedded applications you don't
+want to spend resources on an allocator and end up placing buffers on the stack. This, however, can easily blow up
+your stack if you are not careful.
 
 Consider the following example:
 [,rust]
diff --git a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc
index a1c31bfc7..85ad7f4a2 100644
--- a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc
+++ b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc
@@ -7,3 +7,5 @@ Here are known examples of real-world projects which make use of Embassy. Feel f
 * link:https://github.com/card-io-ecg/card-io-fw[Card/IO firmware] - firmware for an open source ECG device
 ** Targets the ESP32-S3 or ESP32-C6 MCU
 * The link:https://github.com/lora-rs/lora-rs[lora-rs] project includes link:https://github.com/lora-rs/lora-rs/tree/main/examples/stm32l0/src/bin[various standalone examples] for NRF52840, RP2040, STM32L0 and STM32WL
+** link:https://github.com/matoushybl/air-force-one[Air force one: A simple air quality monitoring system]
+*** Targets nRF52 and uses nrf-softdevice
diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc
index 147f119b0..6b5e6d009 100644
--- a/docs/modules/ROOT/pages/faq.adoc
+++ b/docs/modules/ROOT/pages/faq.adoc
@@ -29,11 +29,10 @@ If you see an error like this:
 
 You are likely missing some features of the `embassy-executor` crate.
 
-For Cortex-M targets, consider making sure that ALL of the following features are active in your `Cargo.toml` for the `embassy-executor` crate:
+For Cortex-M targets, check whether ALL of the following features are enabled in your `Cargo.toml` for the `embassy-executor` crate:
 
 * `arch-cortex-m`
 * `executor-thread`
-* `nightly`
 
 For ESP32, consider using the executors and `#[main]` macro provided by your appropriate link:https://crates.io/crates/esp-hal-common[HAL crate].
 
@@ -44,11 +43,12 @@ The first step to managing your binary size is to set up your link:https://doc.r
 [source,toml]
 ----
 [profile.release]
-debug = false
 lto = true
 opt-level = "s"
 incremental = false
 codegen-units = 1
+# note: debug = true is okay - debuginfo isn't flashed to the device!
+debug = true
 ----
 
 All of these flags are elaborated on in the Rust Book page linked above.
@@ -118,21 +118,31 @@ features = [
 ]
 ----
 
+If you are in the early project setup phase and not using anything from the HAL, make sure the HAL is explicitly used to prevent the linker removing it as dead code by adding this line to your source:
+
+[source,rust]
+----
+use embassy_stm32 as _;
+----
+
 == Error: `Only one package in the dependency graph may specify the same links value.`
 
 You have multiple versions of the same crate in your dependency tree. This means that some of your
 embassy crates are coming from crates.io, and some from git, each of them pulling in a different set
 of dependencies.
 
-To resolve this issue, make sure to only use a single source for all your embassy crates! To do this,
-you should patch your dependencies to use git sources using `[patch.crates.io]` and maybe `[patch.'https://github.com/embassy-rs/embassy.git']`.
+To resolve this issue, make sure to only use a single source for all your embassy crates!
+To do this, you should patch your dependencies to use git sources using `[patch.crates.io]`
+and maybe `[patch.'https://github.com/embassy-rs/embassy.git']`.
 
 Example:
 
 [source,toml]
 ----
 [patch.crates-io]
-embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
+embassy-time-queue-driver = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
+embassy-time-driver = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
+# embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
 ----
 
 Note that the git revision should match any other embassy patches or git dependencies that you are using!
@@ -180,3 +190,21 @@ Check out link:https://docs.embassy.dev/embassy-executor/git/cortex-m/index.html
 == Can I use manual ISRs alongside Embassy?
 
 Yes! This can be useful if you need to respond to an event as fast as possible, and the latency caused by the usual “ISR, wake, return from ISR, context switch to woken task” flow is too much for your application. Simply define a `#[interrupt] fn INTERRUPT_NAME() {}` handler as you would link:https://docs.rust-embedded.org/book/start/interrupts.html[in any other embedded rust project].
+
+== How can I measure resource usage (CPU, RAM, etc.)?
+
+=== For CPU Usage:
+
+There are a couple techniques that have been documented, generally you want to measure how long you are spending in the idle or low priority loop.
+
+We need to document specifically how to do this in embassy, but link:https://blog.japaric.io/cpu-monitor/[this older post] describes the general process.
+
+If you end up doing this, please update this section with more specific examples!
+
+=== For Static Memory Usage
+
+Tools like `cargo size` and `cargo nm` can tell you the size of any globals or other static usage. Specifically you will want to see the size of the `.data` and `.bss` sections, which together make up the total global/static memory usage.
+
+=== For Max Stack Usage
+
+Check out link:https://github.com/Dirbaio/cargo-call-stack/[`cargo-call-stack`] for statically calculating worst-case stack usage. There are some caveats and inaccuracies possible with this, but this is a good way to get the general idea. See link:https://github.com/dirbaio/cargo-call-stack#known-limitations[the README] for more details.
diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc
index ab819ac2a..73cb5530d 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/modules/ROOT/pages/getting_started.adoc
@@ -3,7 +3,7 @@
 So you want to try Embassy, great! To get started, there are a few tools you need to install:
 
 * link:https://rustup.rs/[rustup] - the Rust toolchain is needed to compile Rust code.
-* link:https://crates.io/crates/probe-rs[probe-rs] - to flash the firmware on your device. If you already have other tools like `OpenOCD` setup, you can use that as well.
+* link:https://probe.rs/[probe-rs] - to flash the firmware on your device. If you already have other tools like `OpenOCD` setup, you can use that as well.
 
 If you don't have any supported board, don't worry: you can also run embassy on your PC using the `std` examples.
 
@@ -82,19 +82,19 @@ If everything worked correctly, you should see a blinking LED on your board, and
 └─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:27
 ----
 
-NOTE: How does the `cargo run` command know how to connect to our board and program it? In each `examples` folder, there’s a `.cargo/config.toml` file which tells cargo to use link:https://probe.rs/[probe-rs] as the runner for ARM binaries in that folder. probe-rs handles communication with the debug probe and MCU. In order for this to work, probe-rs needs to know which chip it’s programming, so you’ll have to edit this file if you want to run examples on other chips.
+NOTE: How does the `+cargo run+` command know how to connect to our board and program it? In each `examples` folder, there’s a `.cargo/config.toml` file which tells cargo to use link:https://probe.rs/[probe-rs] as the runner for ARM binaries in that folder. probe-rs handles communication with the debug probe and MCU. In order for this to work, probe-rs needs to know which chip it’s programming, so you’ll have to edit this file if you want to run examples on other chips.
 
 === It didn’t work!
 
-If you hare having issues when running `cargo run --release`, please check the following:
+If you hare having issues when running `+cargo run --release+`, please check the following:
 
-* You are specifying the correct `--chip on the command line``, OR
-* You have set `.cargo/config.toml`'s run line to the correct chip, AND
-* You have changed `examples/Cargo.toml`'s HAL (e.g. embassy-stm32) dependency's feature to use the correct chip (replace the existing stm32xxxx feature)
+* You are specifying the correct `+--chip+` on the command line, OR
+* You have set `+.cargo/config.toml+`’s run line to the correct chip, AND
+* You have changed `+examples/Cargo.toml+`’s HAL (e.g. embassy-stm32) dependency's feature to use the correct chip (replace the existing stm32xxxx feature)
 
 At this point the project should run. If you do not see a blinky LED for blinky, for example, be sure to check the code is toggling your board's LED pin.
 
-If you are trying to run an example with `cargo run --release` and you see the following output:
+If you are trying to run an example with `+cargo run --release+` and you see the following output:
 [source]
 ----
 0.000000 INFO Hello World!
@@ -115,6 +115,22 @@ To get rid of the frame-index error add the following to your `Cargo.toml`:
 debug = 2
 ----
 
+If you’re getting an extremely long error message containing something like the following:
+
+[source]
+----
+error[E0463]: can't find crate for `std`
+  |
+  = note: the `thumbv6m-none-eabi` target may not support the standard library
+  = note: `std` is required by `stable_deref_trait` because it does not declare `#![no_std]`
+----
+
+Make sure that you didn’t accidentally run `+cargo add probe-rs+` (which adds it as a dependency) instead of link:https://probe.rs/docs/getting-started/installation/[correctly installing probe-rs].
+
+If you’re using a raspberry pi pico-w, make sure you’re running `+cargo run --bin wifi_blinky --release+` rather than the regular blinky. The pico-w’s on-board LED is connected to the WiFi chip, which needs to be initialized before the LED can be blinked.
+
+If you’re using an rp2040 debug probe (e.g. the pico probe) and are having issues after running `probe-rs info`, unplug and reconnect the probe, letting it power cycle. Running `probe-rs info` is link:https://github.com/probe-rs/probe-rs/issues/1849[known to put the pico probe into an unusable state].
+
 If you’re still having problems, check the link:https://embassy.dev/book/dev/faq.html[FAQ], or ask for help in the link:https://matrix.to/#/#embassy-rs:matrix.org[Embassy Chat Room].
 
 == What's next?
@@ -124,3 +140,4 @@ Congratulations, you have your first Embassy application running! Here are some
 * Read more about the xref:runtime.adoc[executor].
 * Read more about the xref:hal.adoc[HAL].
 * Start xref:basic_application.adoc[writing your application].
+* Learn how to xref:new_project.adoc[start a new embassy project by adapting an example].
diff --git a/docs/modules/ROOT/pages/new_project.adoc b/docs/modules/ROOT/pages/new_project.adoc
index ce139ed8d..320966bb6 100644
--- a/docs/modules/ROOT/pages/new_project.adoc
+++ b/docs/modules/ROOT/pages/new_project.adoc
@@ -1,6 +1,17 @@
 = Starting a new Embassy project
 
-Once you’ve successfully xref:getting_started.adoc[run some example projects], the next step is to make a standalone Embassy project. The easiest way to do this is to adapt an example for a similar chip to the one you’re targeting.
+Once you’ve successfully xref:getting_started.adoc[run some example projects], the next step is to make a standalone Embassy project.
+
+There are some tools for generating Embassy projects: (WIP)
+
+==== CLI
+- link:https://github.com/adinack/cargo-embassy[cargo-embassy] (STM32 and NRF)
+
+==== cargo-generate
+- link:https://github.com/lulf/embassy-template[embassy-template] (STM32, NRF, and RP)
+- link:https://github.com/bentwire/embassy-rp2040-template[embassy-rp2040-template] (RP)
+
+But if you want to start from scratch:
 
 As an example, let’s create a new embassy project from scratch for a STM32G474. The same instructions are applicable for any supported chip with some minor changes.
 
@@ -166,13 +177,13 @@ should result in a blinking LED (if there’s one attached to the pin in `src/ma
      Erasing sectors ✔ [00:00:00] [#########################################################] 18.00 KiB/18.00 KiB @ 54.09 KiB/s (eta 0s )
  Programming pages   ✔ [00:00:00] [#########################################################] 17.00 KiB/17.00 KiB @ 35.91 KiB/s (eta 0s )    Finished in 0.817s
 0.000000 TRACE BDCR configured: 00008200
-└─ embassy_stm32::rcc::bd::{impl#3}::init::{closure#4} @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:117 
+└─ embassy_stm32::rcc::bd::{impl#3}::init::{closure#4} @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:117
 0.000000 DEBUG rcc: Clocks { sys: Hertz(16000000), pclk1: Hertz(16000000), pclk1_tim: Hertz(16000000), pclk2: Hertz(16000000), pclk2_tim: Hertz(16000000), hclk1: Hertz(16000000), hclk2: Hertz(16000000), pll1_p: None, adc: None, adc34: None, rtc: Some(Hertz(32000)) }
-└─ embassy_stm32::rcc::set_freqs @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:130 
+└─ embassy_stm32::rcc::set_freqs @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:130
 0.000000 INFO  Hello World!
-└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:14  
+└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:14
 0.000091 INFO  high
-└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:19  
+└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:19
 0.300201 INFO  low
-└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:23  
-----
\ No newline at end of file
+└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:23
+----
diff --git a/docs/modules/ROOT/pages/project_structure.adoc b/docs/modules/ROOT/pages/project_structure.adoc
index 61ffd05a6..2adfcc1df 100644
--- a/docs/modules/ROOT/pages/project_structure.adoc
+++ b/docs/modules/ROOT/pages/project_structure.adoc
@@ -38,13 +38,18 @@ DEFMT_LOG = "trace" # <- can change to info, warn, or error
 
 == build.rs
 
-This is the build script for your project. It links defmt (what is defmt?) and the `memory.x` file if needed. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example].
+This is the build script for your project. It links defmt (what is link:https://defmt.ferrous-systems.com[defmt]?) and the `memory.x` file if needed. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example].
 
 == Cargo.toml
 
 This is your manifest file, where you can configure all of the embassy components to use the features you need.
 
-TODO: someone should exhaustively describe every feature for every component!
+==== Features
+===== Time
+- tick-hz-x: Configures the tick rate of `embassy-time`. Higher tick rate means higher precision, and higher CPU wakes.
+- defmt-timestamp-uptime: defmt log entries will display the uptime in seconds.
+
+...more to come
 
 == memory.x