microtile-app

A microscopic Tetris® inspired application, targeting the BBC micro:bit v2. For the underlying engine, see microtile-engine.

I was enrolled in the 2023 edition of the Making Embedded Systems course by Elecia White. This repository is part of my final project submission.

micro:tile

This project resembles a port of the Tetris® game targeting the micro:bit 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.

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. 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.

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

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 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 for suggestions on where to acquire hardware.

Software

This project is written in Rust. To build it yourself, you will need:

• Rust
  See the official installation guide.

  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.:

  $ rustup target add thumbv7em-none-eabihf --toolchain nightly

• flip-link
  With Rust installed, you can install flip-link via cargo:

  $ cargo install flip-link

• probe-rs
  With Rust installed, you can install probe-rs via cargo:

  $ cargo install probe-rs --features cli

  Make sure to install v0.2.0 or later.

• git
  This project's build script uses git (via the vergen 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, though other programs may work as well.

• vscode
  To perform "step-through-code" debugging, vscode alongside the probe-rs vscode extension is required. Please refer to the docs 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, 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

> 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

> 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, flash and run the application using

> 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 .

To flash and run the application, make sure to have probe-rs installed. With the micro:bit attached to your host, run e.g.

> 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.

> 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

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Please feel free to point out suggestions, improvements and alike anyway! Thank you! 😊

Credits

Tetris®

Tetris® is a registered trademark of Tetris Holding, LLC and The Tetris Company, Inc. is its exclusive licensee. This repository is in no way affiliated with or sponsored by neither Tetris Holding, LLC nor The Tetris Company, Inc. nor is it part of their Tetris® line of products. For the latest information about the Tetris® brand and Tetris® products, please visit www.tetris.com.

Knurling and RTIC

This application is based on a template maintained by the Knurling project adapted by the RTIC project. The template is licensed under MIT or Apache-2.0 license, please find details on the respective licenses here and here.

If you think that their work is useful, consider sponsoring them!