Copy over general description from project report

README.md

@@ -3,9 +3,220 @@
 A microscopic Tetris® inspired application, targeting the [BBC micro:bit v2](https://microbit.org/).
 For the underlying engine, see [`microtile-engine`](https://github.com/90degs2infty/microtile-engine).
 
-I'm enrolled in the 2023 edition of the [Making Embedded Systems course by Elecia White](https://classpert.com/classpertx/courses/making-embedded-systems/cohort).
+I was enrolled in the 2023 edition of the [Making Embedded Systems course by Elecia White](https://classpert.com/classpertx/courses/making-embedded-systems/cohort).
 This repository is part of my final project submission.
 
+## `micro:tile`
+
+This project resembles a port of the [Tetris®](https://en.wikipedia.org/wiki/Tetris) game targeting the [`micro:bit`](https://microbit.org/) board.
+In the following, you find a general functional description of the implemented game.
+To play the game right away, skip ahead to [Getting started](#getting-started).
+
+### Overarching device state loop
+
+When powering the `micro:bit`, the device starts a new game immediately.
+For details on the gameplay and mid-game interaction, see [Gameplay](#gameplay).
+When the game ends, the device discards the finished game and starts a new one directly afterwards.
+
+### Gameplay
+
+Similar to the gameplay of Tetris®, in `micro:tile` the player gets to arrange tiles on the micro:bit's 5 by 5 LED matrix.
+
+![microbit-interaction.svg](img/microbit-interaction.svg)
+
+There is one active tile at a time.
+The player moves the active tile horizontally by tilting the micro:bit.
+The player rotates the active tile by pressing button `Btn B`.
+
+The active tile gets moved downwards at a fixed rate until it reaches the bottom part of the matrix (or there is another tile blocking the way).
+To speed up the vertical movement (so called _soft drop_), the player may press and hold button `Btn A`.
+
+Figure 1 summarizes the different types of user-device-interaction.
+
+Once reaching the bottom, the active tile is freezed (its position on the board is fixed for the rest of the game).
+After freezing the tile, the board is checked for fully covered rows.
+Any fully covered row is removed.
+Rows above get moved downwards to fill in the gap.
+
+After removal of fully covered rows a new active tile gets generated.
+The tile is placed at a fixed initial location and gameplay continues.
+Three types of tiles are implemented (cf. Figure 2):
+
+- a 1 by 1 square
+- a 2 by 2 diagonal
+- a 1 by 2 line
+
+![tiles.svg](img/tiles.svg)
+
+The game ends as soon as the first newly drawn active tile cannot be validly placed at its initial position on the board.
+
+## Getting started
+
+### Prerequisites
+
+#### Hardware
+
+This project targets the [`micro:bit`](https://microbit.org/) board.
+The `micro:bit` is available in different versions, make sure to acquire version `v2`.
+More specifically, this project has been implemented and tested using version `v2.21` (other versions may work as well, but have _not_ been tested).
+
+Additionally, you will need a standard micro USB cable to connect the `micro:bit` to your host computer for
+
+- powering the `micro:bit`,
+- flashing the `micro:bit` as well as
+- accessing the implemented serial CLI.
+
+Note that once flashed, the `micro:bit` can also be powered using a compatible battery pack instead.
+When battery powered, the serial CLI cannot be accessed.
+
+Also see [the `micro:bit`'s official products](https://microbit.org/buy/) for suggestions on where to acquire hardware.
+
+#### Software
+
+This project is written in `Rust`.
+To build it yourself, you will need:
+
+- [`Rust`](https://www.rust-lang.org/)\
+  See [the official installation guide](https://www.rust-lang.org/tools/install).
+
+  Make sure to have the `thumbv7em-none-eabihf` target installed for the nightly toolchain for cross-compilation.
+  With `rustup` available, this is possible via e.g.:
+
+  ```console
+  $ rustup target add thumbv7em-none-eabihf --toolchain nightly
+  ```
+
+- [`flip-link`](https://github.com/knurling-rs/flip-link)\
+  With `Rust` installed, you can install `flip-link` via `cargo`:
+
+  ```console
+  $ cargo install flip-link
+  ```
+
+- [`probe-rs`](https://probe.rs/)\
+  With `Rust` installed, you can install `probe-rs` via `cargo`:
+
+  ``` console
+  $ cargo install probe-rs --features cli
+  ```
+
+  Make sure to install `v0.2.0` or later.
+
+- [`git`](https://git-scm.com/)\
+  This project's build script uses `git` (via the [`vergen`](https://docs.rs/crate/vergen/latest) crate) to embed version control system information (e.g. the underlying `git commit` hash) into the binary.
+  Hence, please make sure the `git` executable is available in your `$PATH`.
+
+  Note that `git` is not only used to acquire this project's sources.
+  So even if you plan to get the sources in some other way, please make sure you have `git` installed on your system.
+- a serial communication program\
+  To access the device's command-line interface, a serial communication program in needed.
+  The interface has been tested with [`minicom`](https://salsa.debian.org/minicom-team/minicom), though other programs may work as well.
+- [`vscode`](https://code.visualstudio.com/)\
+  To perform "step-through-code" debugging, `vscode` alongside the `probe-rs` `vscode` extension is required.
+  Please refer to [the docs](https://probe.rs/docs/tools/debugger/#installation) for details on how to setup the `probe-rs` extension itself inside `vscode`.
+
+### Setting things up
+
+With the prerequisites satisfied, this project is built and run as follows.
+
+### Hardware
+
+As mentioned in [Hardware](#hardware), there are two possible hardware setups:
+
+1. using a standard micro USB cable\
+   Connect the `micro:bit` to your host computer using the standard micro USB cable.
+
+   Use this setup to power, flash and serially access the `micro:bit`.
+2. using a compatible battery pack\
+   Connect the battery pack to the `micro:bit` to power the latter.
+   Note that this way, no host-target interaction is possible (i.e. be sure to flash the `micro:bit` using setup 1 before).
+
+### Software
+
+#### Building from source
+
+In the following, `$repo_root` denotes the folder to store sources and build output in.
+Replace it by a convenient path.
+
+To get the sources, issue
+
+```console
+> git clone https://github.com/90degs2infty/microtile-app.git $repo_root
+Cloning into '$repo_root'...
+remote: Enumerating objects: 323, done.
+remote: Counting objects: 100% (98/98), done.
+remote: Compressing objects: 100% (45/45), done.
+remote: Total 323 (delta 67), reused 70 (delta 52), pack-reused 225
+Receiving objects: 100% (323/323), 73.52 KiB | 2.16 MiB/s, done.
+Resolving deltas: 100% (160/160), done.
+```
+
+Build the sources using one of
+
+```console
+> cd $repo_root
+> cargo build --bin microtile # debug build, or
+# ...
+> cargo build --release --bin microtile # release build
+    Updating git repository `https://github.com/90degs2infty/microbit.git`
+    Updating crates.io index
+    Updating git repository `https://github.com/90degs2infty/microtile-engine.git`
+   Compiling proc-macro2 v1.0.72
+# ... additional output skipped for brevity's sake ...
+   Compiling microtile-app v0.2.0 ($repo_root)
+    Finished release [optimized + debuginfo] target(s) in 32.03s
+```
+
+#### Running the application
+
+With the `micro:bit` attached to your host as described in [Hardware](#hardware-1), flash and run the application using
+
+```console
+> cd $repo_root
+> cargo run --release --bin microtile
+    Finished release [optimized + debuginfo] target(s) in 0.05s
+     Running `probe-rs run --chip nRF52833_xxAA target/thumbv7em-none-eabihf/release/microtile`
+     Erasing sectors ✔ [00:00:00] [] 24.00 KiB/24.00 KiB @ 26.92 KiB/s (eta 0s )
+ Programming pages   ✔ [00:00:01] [] 24.00 KiB/24.00 KiB @ 14.46 KiB/s (eta 0s )    Finished in 2.599s
+```
+
+Above command will (re-)build the application as necessary.
+Afterwards, start playing!
+
+#### Pre-built binaries
+
+To "just play the game", there is no need to build the application from source.
+Instead, there are pre-built binaries available for download [at the `microtile-app` repository's GitHub release page](https://github.com/90degs2infty/microtile-app/releases) .
+
+To flash and run the application, make sure to have `probe-rs` installed.
+With the `micro:bit` attached to your host, run e.g.
+
+```console
+> curl -L -o microtile https://github.com/90degs2infty/microtile-app/releases/download/v0.2.0/microtile-app-v0.2.0-release
+> probe-rs run --chip nRF52833_xxAA microtile
+```
+
+Note that in the above, the call to `curl` can be replaced by whatever method of download you prefer.
+
+#### Command-line interface
+
+Run the application with the `micro:bit` attached to your host as described above.
+
+Then open a serial communication program of your choice (`putty`, `minicom`, ...).
+Make sure to use a baud rate of `115200Hz` and disable parity checking. E.g.
+
+```console
+> minicom -D /dev/ttyACM0 -b 115200
+> # inside the terminal
+> help;
+```
+
+Once connected to the target, enter your commands.
+Commands have to be specified with a trailing `;`.
+Type `;` to clear your input on typos.
+
+See the help text for details on implemented commands.
+
 ## License
 
 Licensed under either of
@@ -17,10 +228,7 @@ at your option.
 
 ## Contribution
 
-Since the aforementioned course is still running and this repository is part of the final project, I currently do not take any outside contributions.
-This will change, once the course is over.
-
-Nevertheless, please feel free to point out suggestions, improvements and alike anyway!
+Please feel free to point out suggestions, improvements and alike anyway!
 Thank you! :blush:
 
 ## Credits