From 8b9e0f5ec089bf980d53a44f0dfbc0edf9326390 Mon Sep 17 00:00:00 2001
From: Lotte Steenbrink <lotte.steenbrink@ferrous-systems.com>
Date: Fri, 9 Oct 2020 11:32:26 +0200
Subject: [PATCH] README: add installation instructions

---
 README.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 121 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index cd557dc..e7fd70d 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,131 @@
 # `app-template`
 
-> Quickly set up a [`probe-run`] + [`defmt`] embedded project
+> Quickly set up a [`probe-run`] + [`defmt`] + [`flip-link`] embedded project
 
 [`probe-run`]: https://crates.io/crates/probe-run
 [`defmt`]: https://github.com/knurling-rs/defmt
+[`flip-link`]: https://github.com/knurling-rs/flip-link
 
-Currently setup instructions can be found [in this blog post].
+## Dependencies
 
-[in this blog post]: https://ferrous-systems.com/blog/defmt
+#### 1. `flip-link`:
+
+<!-- TODO: update this once flip-link is on crates.io -->
+```console
+$ cargo install \
+    --git https://github.com/knurling-rs/flip-link \
+    --branch main
+```
+
+#### 2. The **git** version of `probe-run`:
+
+<!-- TODO: update this once defmt is on crates.io? -->
+``` console
+$ cargo install \
+    --git https://github.com/knurling-rs/probe-run \
+    --branch main \
+    --features defmt
+```
+
+#### 3. [`cargo-generate`]:
+
+```
+$ cargo install cargo-generate
+```
+
+[`cargo-generate`]: https://crates.io/crates/cargo-generate
+
+> *Note:* You can also just clone this repository instead of using `cargo-generate`, but this involves additional manual adjustments. [This flip-link CI patch](https://github.com/knurling-rs/flip-link/blob/main/.github/workflows/0001-configure-test-flip-link-app-for-nrf52840.patch) can serve as a reference on what to do.
+
+## Setup
+
+#### 1. Initialize the project template
+
+``` console
+$ cargo generate \
+    --git https://github.com/knurling-rs/app-template \
+    --branch main \
+    --name my-app
+```
+
+If you look into your new `my-app` folder, you'll find that there are a few `TODO`s in the files marking the properties you need to set.
+
+Let's walk through them together now.
+
+#### 2. Set `probe-run` chip
+
+Pick a chip from `probe-run --list-chips` and enter it into `.cargo/config.toml`.
+
+If, for example, you have a nRF52840 Development Kit from one of [our workshops], replace `{{chip}}` with `nRF52840_xxAA`.
+
+[our workshops]: https://github.com/ferrous-systems/embedded-trainings-2020
+
+``` diff
+ # .cargo/config.toml
+ [target.'cfg(all(target_arch = "arm", target_os = "none"))']
+-runner = "probe-run --chip {{chip}} --defmt"
++runner = "probe-run --chip nRF52840_xxAA --defmt"
+```
+
+#### 3. Adjust the compilation target
+
+In `.cargo/config.toml`, pick the right compilation target for your board.
+
+``` diff
+ # .cargo/config.toml
+ [build]
+-target = "thumbv6m-none-eabi"    # Cortex-M0 and Cortex-M0+
+-# target = "thumbv7m-none-eabi"    # Cortex-M3
+-# target = "thumbv7em-none-eabi"   # Cortex-M4 and Cortex-M7 (no FPU)
+-# target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)
++target = "thumbv7em-none-eabihf" # Cortex-M4F (with FPU)
+```
+
+### 4. Add a HAL as a dependency
+
+In `Cargo.toml`, list the Hardware Abstraction Layer (HAL) for your board as a dependency.
+
+For the nRF52840 you'll want to use the [`nrf52840-hal`].
+
+[`nrf52840-hal`]: https://crates.io/crates/nrf52840-hal
+
+``` diff
+ # Cargo.toml
+ [dependencies]
+-# some-hal = "1.2.3"
++nrf52840-hal = "0.11.0"
+```
+
+#### 5. Import your HAL
+
+Now that you have selected a HAL fix the HAL import in `src/lib.rs`
+
+``` diff
+ // my-app/src/lib.rs
+-// use some_hal as _; // memory layout
++use nrf52840_hal as _; // memory layout
+```
+
+#### 6. run!
+
+You are now all set to `cargo-run` your first `defmt`-powered application!
+There are some examples in the `src/bin` directory.
+
+Start by `cargo run`-ning `my-app/src/bin/hello.rs`:
+
+``` console
+$ # `rb` is an alias for `run --bin`
+$ cargo rb hello
+    Finished dev [optimized + debuginfo] target(s) in 0.03s
+flashing program ..
+DONE
+resetting device
+0.000000 INFO Hello, world!
+(..)
+
+$ echo $?
+0
+```
 
 ## Support