7 files changed, 180 insertions, 9 deletions

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index dbf9b0bae..98c4ee77f 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -1,4 +1,8 @@
-* xref:runtime.adoc[Executor]
-* xref:traits.adoc[Async traits]
-* xref:hal.adoc[Hardware Interface]
+* xref:runtime.adoc[Runtime]
+* xref:traits.adoc[APIs]
+* xref:hal.adoc[Hardware Abstraction Layer]
+** xref:nrf.adoc[nRF]
+** xref:stm32.adoc[STM32]
+* xref:getting_started.adoc[Getting started]
+** xref:basic_application.adoc[Basic application]
 * xref:examples.adoc[Examples]
diff --git a/docs/modules/ROOT/pages/basic_application.adoc b/docs/modules/ROOT/pages/basic_application.adoc
new file mode 100644
index 000000000..d56cb5e1d
--- /dev/null
+++ b/docs/modules/ROOT/pages/basic_application.adoc
@@ -0,0 +1,75 @@
+= A basic Embassy application
+
+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.
+
+
+== The Cargo.toml
+
+== The main
+
+=== Rust Nightly
+
+The first thing you'll notice is a few declarations stating that Embassy requires some nightly features:
+
+[source,rust]
+----
+#![no_std]
+#![no_main]
+#![feature(type_alias_impl_trait)]
+----
+
+=== 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]
+----
+use defmt_rtt as _;
+use panic_probe as _;
+----
+
+=== Task declaration
+
+After a bit of import declaration, the tasks run by the application should be declared:
+
+[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;
+    }
+}
+----
+
+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.
+
+NOTE: Notice that there is not busy waiting going on in this task. It is using the Embassy timer to yield execution, allowing the microcontroller to sleep in between the blinking.
+
+=== 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 `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]
+----
+#[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)));
+}
+----
+
+
+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`
+. Defines a main task for the entry point
+. Runs the executor spawning the main task
+
+There is also a way to run the executor without using the macro, in which case you have to create the `Executor` instance yourself.
diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc
new file mode 100644
index 000000000..760fe8601
--- /dev/null
+++ b/docs/modules/ROOT/pages/getting_started.adoc
@@ -0,0 +1,59 @@
+= Getting started
+
+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-run[probe-run] - 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.
+
+== Getting a board with examples
+
+Embassy supports many microcontroller families, but the easiest ways to get started is if you have one of the more common development kits.
+
+=== nRF kits
+
+* link:https://www.nordicsemi.com/Products/Development-hardware/nrf52-dk[nRF52 DK]
+* link:https://www.nordicsemi.com/Products/Development-hardware/nRF9160-DK[nRF9160 DK]
+
+=== STM32 kits
+
+* link:https://www.st.com/en/evaluation-tools/nucleo-h743zi.html[STM32 Nucleo-144 development board with STM32H743ZI MCU]
+* link:https://www.st.com/en/evaluation-tools/nucleo-f429zi.html[STM32 Nucleo-144 development board with STM32F429ZI MCU]
+* link:https://www.st.com/en/evaluation-tools/b-l4s5i-iot01a.html[STM32L4+ Discovery kit IoT node, low-power wireless, BLE, NFC, WiFi]
+* link:https://www.st.com/en/evaluation-tools/b-l072z-lrwan1.html[STM32L0 Discovery kit LoRa, Sigfox, low-power wireless]
+* link:https://www.st.com/en/evaluation-tools/nucleo-wl55jc.html[STM32 Nucleo-64 development board with STM32WL55JCI MCU]
+* link:https://www.st.com/en/evaluation-tools/b-u585i-iot02a.html[Discovery kit for IoT node with STM32U5 series]
+
+
+=== RP2040 kits
+
+* link:https://www.raspberrypi.com/products/raspberry-pi-pico/[Raspberry Pi Pico]
+
+== Running an example
+
+First you need to clone the [github repository];
+
+[source, bash]
+----
+git clone https://github.com/embassy-rs/embassy.git
+cd embassy
+----
+
+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
+----
+
+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:hal.adoc[HAL].
+* Start xref:basic_application.adoc[writing your application].
diff --git a/docs/modules/ROOT/pages/hal.adoc b/docs/modules/ROOT/pages/hal.adoc
index 75dd496c9..8e7fb8dba 100644
--- a/docs/modules/ROOT/pages/hal.adoc
+++ b/docs/modules/ROOT/pages/hal.adoc
@@ -2,8 +2,8 @@
 
 Embassy provides HAL's for several microcontroller families:
 
-* embassy-nrf for the nRF family of devices from Nordic Semiconductor
-* embassy-stm32 for STM32 family of devices from ST Microelectronics
-* embassy-rp for Raspberry Pi Pico
+* `embassy-nrf` for the nRF microcontroller sfrom Nordic Semiconductor
+* `embassy-stm32` for STM32 microcontrollers from ST Microelectronics
+* `embassy-rp` for the Raspberry Pi RP2040 microcontrollers
 
-These HALs provide async/await access to 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 Embassy.
diff --git a/docs/modules/ROOT/pages/nrf.adoc b/docs/modules/ROOT/pages/nrf.adoc
index 21c388f61..10fe54b47 100644
--- a/docs/modules/ROOT/pages/nrf.adoc
+++ b/docs/modules/ROOT/pages/nrf.adoc
@@ -1,3 +1,25 @@
 = Embassy nRF HAL
 
-TODO
+The link:https://github.com/embassy-rs/embassy/tree/master/embassy-nrf[Embassy nRF HAL] is based on the PACs (Peripheral Access Crate) from link:https://github.com/nrf-rs/[nrf-rs].
+
+== Timer driver
+
+The nRF timer driver operates at 32768 Hz by default.
+
+== Peripherals
+
+The following peripherals have a HAL implementation at present:
+
+* PWM
+* SPIM
+* QSPI
+* NVMC
+* GPIOTE
+* RNG
+* TIMER
+* WDT
+* TEMP
+* PPI
+* UARTE
+* TWIM
+* SAADC
diff --git a/docs/modules/ROOT/pages/runtime.adoc b/docs/modules/ROOT/pages/runtime.adoc
index 2970bd59e..25feb9c29 100644
--- a/docs/modules/ROOT/pages/runtime.adoc
+++ b/docs/modules/ROOT/pages/runtime.adoc
@@ -20,6 +20,8 @@ IMPORTANT: The executor relies on tasks not blocking indefinitely, as this preve
 
 image::embassy_executor.png[Executor model]
 
+If you use the `#[embassy::main]` macro in your application, it creates the `Executor` for you and spawns the main entry point as the first task. You can also create the Executor manually, and you can in fact create multiple Executors.
+
 
 == Interrupts
 
@@ -29,10 +31,16 @@ The peripheral HAL then (4) ensures that interrupt signals are routed to to the
 
 image::embassy_irq.png[Interrupt handling]
 
+NOTE: There exists a special executor named `InterruptExecutor` which can be driven by an interrupt. This can be used to drive tasks at different priority levels by creating multiple `InterruptExecutor` instances.
+
 == Time
 
 Embassy features an internal timer queue enabled by the `time` feature flag. When enabled, Embassy assumes a time `Driver` implementation existing for the platform. Embassy provides time drivers for the nRF, STM32, RPi Pico, WASM and Std platforms.
 
-The timer driver implementations for the embedded platforms support a fixed number of alarms that can be set, which is normally the number of tasks you expect wanting to use the timer at the same time.
+The timer driver implementations for the embedded platforms might support only a fixed number of alarms that can be set. Make sure the number of tasks you expect wanting to use the timer at the same time do not exceed this limit.
+
+The timer speed is configurable at compile time using the `time-tick-<frequency>`. At present, the the timer may be configured to run at 1000 Hz, 32768 Hz, or 1 MHz. Before changing the defaults, make sure the target HAL supports the particular frequency setting.
+
+
 
 NOTE: If you do not require timers in your application, not enabling the `time` feature can save some CPU cycles and reduce power usage.
diff --git a/docs/modules/ROOT/pages/stm32.adoc b/docs/modules/ROOT/pages/stm32.adoc
new file mode 100644
index 000000000..328f69e2a
--- /dev/null
+++ b/docs/modules/ROOT/pages/stm32.adoc
@@ -0,0 +1,3 @@
+= Embassy STM32 HAL
+
+TODO