Merge #905

905: Rewrite documentation using correct module names r=Dirbaio a=lulf

* Remove traits section now that we have embedded-hal-async and refer to
  it.
* Explanation that embassy is multiple things.
* Bootloader description image

Co-authored-by: Ulf Lilleengen <lulf@redhat.com>

docs/modules/ROOT/nav.adoc

@@ -1,10 +1,10 @@
-* xref:runtime.adoc[Runtime]
-* xref:traits.adoc[APIs]
-* xref:hal.adoc[Hardware Abstraction Layer]
-** xref:nrf.adoc[nRF]
-** xref:stm32.adoc[STM32]
-* xref:bootloader.adoc[Bootloader]
 * xref:getting_started.adoc[Getting started]
 ** xref:basic_application.adoc[Basic application]
 ** xref:layer_by_layer.adoc[Layer by Layer]
+* xref:runtime.adoc[Executor]
+* xref:hal.adoc[HAL]
+** xref:nrf.adoc[nRF]
+** xref:stm32.adoc[STM32]
+* xref:bootloader.adoc[Bootloader]
+
 * xref:examples.adoc[Examples]

docs/modules/ROOT/pages/basic_application.adoc

@@ -21,7 +21,7 @@ Then, what follows are some declarations on how to deal with panics and faults.
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="5..6"]
+include::example$basic/src/main.rs[lines="11..12"]
 ----
 
 === Task declaration
@@ -30,7 +30,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="18..27"]
+include::example$basic/src/main.rs[lines="13..22"]
 ----
 
 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.
@@ -39,32 +39,32 @@ NOTE: Notice that there is no busy waiting going on in this task. It is using th
 
 === Main
 
-The main entry point of an Embassy application is defined using the `#[embassy::main]` macro. The entry point is also required to take a `Spawner` and a `Peripherals` argument.
+The main entry point of an Embassy application is defined using the `#[embassy_executor::main]` macro. The entry point is also required to take a `Spawner` and a `Peripherals` argument.
 
-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:
+The `Spawner` is the way the main application spawns other tasks. The `Peripherals` type comes from the HAL and 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]
 ----
-include::example$basic/src/main.rs[lines="28..-1"]
+include::example$basic/src/main.rs[lines="23..-1"]
 ----
 
-`#[embassy::main]` takes an optional `config` paramter specifying a function that returns an instance of HAL's `Config` struct. For example:
+`#[embassy_executor::main]` takes an optional `config` parameter specifying a function that returns an instance of HAL's `Config` struct. For example:
 
 ```rust
 fn embassy_config() -> embassy_nrf::config::Config {
     embassy_nrf::config::Config::default()
 }
 
-#[embassy::main(config = "embassy_config()")]
-async fn main(_spawner: embassy::executor::Spawner, p: embassy_nrf::Peripherals) {
+#[embassy_executor::main(config = "embassy_config()")]
+async fn main(_spawner: Spawner, p: embassy_nrf::Peripherals) {
     // ...
 }
 ```
 
 What happens when the `blinker` task have 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::main]` macro. The macro does the following:
 
-. Creates an Embassy Executor instance
-. Initializes the microcontroller to get the `Peripherals`
+. Creates an Embassy Executor
+. Initializes the microcontroller HAL to get the `Peripherals`
 . Defines a main task for the entry point
 . Runs the executor spawning the main task
 

docs/modules/ROOT/pages/bootloader.adoc

@@ -20,7 +20,10 @@ In general, the bootloader works on any platform that implements the `embedded-s
 
 == Design
 
-The bootloader divides the storage into 4 main partitions, configured by a linker script:
+image::bootloader_flash.png[Bootloader flash layout]
+
+The bootloader divides the storage into 4 main partitions, configurable when creating the bootloader
+instance or via linker scripts:
 
 * BOOTLOADER - Where the bootloader is placed. The bootloader itself consumes about 8kB of flash.
 * ACTIVE - Where the main application is placed. The bootloader will attempt to load the application at the start of this partition. This partition is only written to by the bootloader.

docs/modules/ROOT/pages/getting_started.adoc

@@ -46,15 +46,13 @@ You can run an example by opening a terminal and entering the following commands
 [source, bash]
 ----
 cd examples/nrf
-DEFMT_LOG=info cargo run --bin blinky --release
+cargo run --bin blinky --release
 ----
 
-IMPORTANT: The DEFMT_LOG environment variable controls the example log verbosity. If you do not specify it, you will not see anything logged to the console.
-
 == Whats next?
 
 Congratulations, you have your first Embassy application running! Here are some alternatives on where to go from here:
 
-* Read more about the xref:runtime.adoc[runtime].
+* Read more about the xref:runtime.adoc[executor].
 * Read more about the xref:hal.adoc[HAL].
 * Start xref:basic_application.adoc[writing your application].

docs/modules/ROOT/pages/hal.adoc

@@ -1,9 +1,10 @@
 = Hardware Abstraction Layer (HAL)
 
-Embassy provides HAL's for several microcontroller families:
+Embassy provides HALs for several microcontroller families:
 
 * `embassy-nrf` for the nRF microcontrollers from Nordic Semiconductor
 * `embassy-stm32` for STM32 microcontrollers from ST Microelectronics
 * `embassy-rp` for the Raspberry Pi RP2040 microcontrollers
 
-These HALs implement async/await functionality for most peripherals while also implementing the async traits in Embassy.
+These HALs implement async/await functionality for most peripherals while also implementing the
+async traits in `embedded-hal-async`. You can also use these HALs with another executor.

docs/modules/ROOT/pages/index.adoc

@@ -15,6 +15,20 @@ In Rust, non-blocking operations can be implemented using async-await. Async-awa
 
 == What is Embassy?
 
-Embassy is an executor and a Hardware Access Layer (HAL). The executor is a scheduler that generally executes a fixed number of tasks, allocated at startup, though more can be added later. The HAL is an API that you can use to access peripherals, such as USART, UART, I2C, SPI, CAN, and USB. Embassy provides implementations of both async and blocking APIs where it makes sense. DMA (Direct Memory Access) is an example where async is a good fit, whereas GPIO states are a better fit for a blocking API.
+The Embassy project consists of several crates that you can use together or independently:
 
-Embassy may also provide a system timer that you can use for both async and blocking delays. For less than one microsecond, blocking delays should be used because the cost of context-switching is too high and the executor will be unable to provide accurate timing.
+* **Executor** - The link:https://docs.embassy.dev/embassy-executor/[embassy-executor] is an async/await executor that generally executes a fixed number of tasks, allocated at startup, though more can be added later. The HAL is an API that you can use to access peripherals, such as USART, UART, I2C, SPI, CAN, and USB. Embassy provides implementations of both async and blocking APIs where it makes sense. DMA (Direct Memory Access) is an example where async is a good fit, whereas GPIO states are a better fit for a blocking API. The executor may also provide a system timer that you can use for both async and blocking delays. For less than one microsecond, blocking delays should be used because the cost of context-switching is too high and the executor will be unable to provide accurate timing.
+
+* **Hardware Abstraction Layers** - HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed. The Embassy project maintains HALs for select hardware, but you can still use HALs from other projects with Embassy.
+** link:https://docs.embassy.dev/embassy-stm32/[embassy-stm32], for all STM32 microcontroller families.
+** link:https://docs.embassy.dev/embassy-nrf/[embassy-nrf], for the Nordic Semiconductor nRF52, nRF53, nRF91 series.
+
+* **Networking** - The link:https://docs.embassy.dev/embassy-net/[embassy-net] network stack implements extensive networking functionality, including Ethernet, IP, TCP, UDP, ICMP and DHCP. Async drastically simplifies managing timeouts and serving multiple connections concurrently.
+
+* **Bluetooth** - The link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] crate provides Bluetooth Low Energy 4.x and 5.x support for nRF52 microcontrollers.
+
+* **LoRa** - link:https://docs.embassy.dev/embassy-lora/[embassy-lora] supports LoRa networking on STM32WL wireless microcontrollers and Semtech SX127x transceivers.
+
+* **USB** - link:https://docs.embassy.dev/embassy-usb/[embassy-usb] implements a device-side USB stack. Implementations for common classes such as USB serial (CDC ACM) and USB HID are available, and a rich builder API allows building your own.
+
+* **Bootloader and DFU** - link:https://github.com/embassy-rs/embassy/tree/master/embassy-boot[embassy-boot] is a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks.

docs/modules/ROOT/pages/runtime.adoc

@@ -1,6 +1,6 @@
-= Embassy runtime
+= Embassy executor
 
-The Embassy runtime is an async/await executor designed for embedded usage along with support functionality for interrupts and timers.
+The Embassy executor is an async/await executor designed for embedded usage along with support functionality for interrupts and timers.
 
 == Features
 

docs/modules/ROOT/pages/traits.adoc

@@ -1,8 +0,0 @@
-= Embassy Traits
-
-Embassy provides a set of traits and types specifically designed for `async` usage. Many of these futures will be upstreamed to the `embedded-hal` crate at some point in the future, probably when the required GAT (Generic Associated Types) feature is stabilized in Rust.
-
-* `embassy::io`: `AsyncBufRead`, `AsyncWrite`. Traits for byte-stream IO, essentially `no_std` compatible versions of `futures::io`. The primary reason for re-defining these traits is that the `futures::io` variant requires `std::io::Error`, which does not work in the `no_std` environment.
-* `embassy::time`: Time `Driver` trait that is implemented for different platforms. Time in Embassy is represented using the `Duration` and `Instant` types.
-
-These traits are implemented by the platform-specific crates, such as `embassy-nrf` or `embassy-stm32`.