Add support for micro:bit v2

This change is a major rewrite. The crate is split into a
multi-crate workspace layed out in a similar way to nrf-rs/nrf-hal.

- `microbit-common` almost all the code, feature flagged for the
  different major board versions (V1 and V2).
- `microbit` the V1 board support crate
- `microbit-v2` the V2 board support crate
- `xtask` cargo xtask crate for running CI accross the different
  versions.
- `examples/*` the examples now need to be crates as they may support
  both versions

Code changes to support micro:bit V2
------------------------------------

Add features `v1` and `v2`. Originally they were `microbit-v1` and
`microbit-v2`, however having the feature name the same as the crate
name requires the namespaced-features cargo feature which basically
restricts us to nightly.

Add microbit v2 support to display module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This was hard and I am not super happy with the solution. It is much
more bit twiddling than I am comfortable with.

The issue that made it so difficult is that on the microbit v2 the
column pins are on the P0 and P1 ports so all the row wise writes have
to be split accross the two ports.

Get microbit v2 led examples working
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Create a new v2 gpio module and conditionally use v1 or v2
- Move NUM_ROWS and NUM_COLS consts into gpio module so they can differ
  between v1 and v2
- Move degrading the LED pins into the gpio module so it can differ
  between v1 and v2

The code for the nonblocking display is a nightmare. The columns are
split between the two GPIO ports so the cols argument to
`display_row_leds` needs to be split between the two ports. This is a
bit painful but doable. The bit that is really confusing me is that
columns 2 and 3 seem to be swapped.

CI changes
----------

I have mostly copied CI from nrf-rs/nrf-hal with some minor differences.
I didn't like having to list all the examples in the CI so it derives
the features and targets required for each example from the cargo
manifest. Copying nrf-hal also meant getting the doc tests building as
well which is nice. For the docs I've favoured complexity in the source
for the sake of docs that are clearer.

Examples changes
----------------

The microbit-v2 crate does not yet support serial so I have chosen to
favour probe-run and defmt for all the examples except those that are
specifically about serial communication (those now just run on the v1
crate). I have not ported over the examples that I could not get working
(receivedcf77 and the magnetometer ones). I plan on implementing the
magnetometer for both versions in the near future so examples for that
will hopefully come back soon.

Author: robyoung

.cargo/config

@@ -0,0 +1,20 @@
+[alias]
+xtask = "run --package xtask --"
+
+[target.thumbv6m-none-eabi]
+runner = 'probe-run --chip nRF51822_xxAA'
+rustflags = [
+  "-C", "linker=flip-link",
+  "-C", "link-arg=-Tlink.x",
+  "-C", "link-arg=-Tdefmt.x",
+]
+
+[target.thumbv7em-none-eabihf]
+# Execute binary using gdb when calling cargo run
+runner = "probe-run --chip nRF52833_xxAA"
+# Tweak to the linking process required by the cortex-m-rt crate
+rustflags = [
+  "-C", "linker=flip-link",
+  "-C", "link-arg=-Tlink.x",
+  "-C", "link-arg=-Tdefmt.x",
+]

.cargo/config.toml

@@ -26,17 +26,10 @@ jobs:
           profile: minimal
           toolchain: ${{ matrix.rust }}
           override: true
-          target: thumbv6m-none-eabi
           components: rustfmt, clippy
 
       - name: rustfmt
         run: cargo fmt -- --check
 
       - name: build
-        run: cargo build --target=thumbv6m-none-eabi
-
-      - name: clippy
-        run: cargo clippy --color=always -- -D warnings
-
-      - name: build examples
-        run: cargo build --examples --target=thumbv6m-none-eabi
+        run: cargo xtask ci

.github/workflows/ci.yaml

@@ -5,3 +5,4 @@ Cargo.lock
 bloat_log*
 !.gitignore
 !.github
+!.cargo

.gitignore

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- Add support for micro:bit V2. This is a significant change that splits
+  this repository into multiple crates.
+
 ## [0.9.0] - 2021-04-29
 
 ### Added

CHANGELOG.md

@@ -1,70 +1,8 @@
-[package]
-edition = "2018"
-authors = ["Daniel Egger <[email protected]>", "Michael Droogleever <[email protected]>"]
-categories = [
-    "hardware-support",
-    "embedded",
-    "no-std",
+[workspace]
+members = [
+  "microbit-common",
+  "microbit",
+  "microbit-v2",
+  "examples/*",
+  "xtask",
 ]
-description = "Board support crate for the BBC Micro:bit"
-documentation = "https://docs.rs/microbit"
-keywords = [
-    "arm",
-    "cortex-m",
-    "nrf51",
-]
-license = "0BSD"
-name = "microbit"
-readme = "README.md"
-repository = "https://github.com/therealprof/microbit"
-version = "0.9.0"
-
-[dependencies]
-cortex-m = "0.6.1"
-cortex-m-rt = "0.6.10"
-nb = "0.1.2"
-nrf51-hal = "0.12.1"
-tiny-led-matrix = "1.0.1"
-embedded-hal = "0.2.4"
-
-defmt = "0.1.3"
-
-[dev-dependencies]
-numtoa = "0.2.3"
-dcf77 = "0.1.0"
-mag3110 = "0.1.4"
-panic-halt = "0.2.0"
-cortex-m-rtic = "0.5"
-defmt-rtt = "0.1.0"
-panic-probe = { version = "0.1.0", features = ["print-defmt"] }
-
-[features]
-# set logging levels here
-default = [
-  "defmt-default",
-  # "dependency-a/defmt-trace",
-]
-
-# do NOT modify these features
-defmt-default = []
-defmt-trace = []
-defmt-debug = []
-defmt-info = []
-defmt-warn = []
-defmt-error = []
-
-[dev-dependencies.rand]
-default-features = false
-version = "0.8.3"
-
-[dev-dependencies.rand_chacha]
-version = "0.3.0"
-default-features = false
-
-[profile.dev]
-debug = true
-
-[profile.release]
-debug = true
-lto = true
-opt-level = "s"

Cargo.toml

@@ -1,44 +1,65 @@
 # microbit
 
-[![microbit on crates.io][cratesio-image]][cratesio]
-[![microbit on docs.rs][docsrs-image]][docsrs]
+_microbit_ contains everything required to get started using Rust to create firmwares for the fabulous
+[BBC micro:bit](https://microbit.org) microcontroller board. This little board has everything and a kitchen sink built-in,
+even a capable debugging interface.
 
-[cratesio-image]: https://img.shields.io/crates/v/microbit.svg
-[cratesio]: https://crates.io/crates/microbit
-[docsrs-image]: https://docs.rs/microbit/badge.svg
-[docsrs]: https://docs.rs/microbit
+## Getting started
 
-_microbit_ contains everything required to get started with the use of Rust to create firmwares for the fabulous [BBC micro:bit][] microcontroller board. This little board has everything and a kitchen sink built-in, even a capable debugging interface, so all that one needs to get going with programming this device is:
+All you need to start programming this device is:
 
-* A BBC micro:bit board (at the moment v1 only)
+* A BBC micro:bit board
 * A computer (macOS and Linux work perfectly, [Windows tested as well](http://flames-of-code.netlify.com/blog/rust-microbit-windows/))
 * A bit of open source software
 
-Some very preliminary examples of using this crate can be found [here in this repo][examples] or [here on my blog][myblog].
+### Know your version
 
-A guide to embedded development with Rust on the _microbit_ using this crate can be found in the [MicroRust book][microrust].
+The micro:bit comes in different versions. There is a separate crate for each major board version. See the table below to identify
+which crate you need to use.
 
-The [BBC micro:bit][] and this crate is compatible with the fantastic tooling
-provided by the [knurling] project. If you haven't done so already, installing
-`probe-run` and playing around with the examples is highly recommended:
+| Crate                          | Board version | Board image | Docs | crates.io | target |
+| ------------------------------ | ----- | ---- | --------- | ------ |
+| [`microbit`](./microbit)       | V1 | [<img src="https://github.com/microbit-foundation/microbit-svg/raw/master/microbit-drawing-back-1-5.png" width="124px" height="100px">](https://github.com/microbit-foundation/microbit-svg/blob/master/microbit-drawing-back-1-5.png) | [![docs.rs](https://docs.rs/microbit/badge.svg)](https://docs.rs/microbit) | [![crates.io](https://img.shields.io/crates/d/microbit.svg)](https://crates.io/crates/microbit) | `thumbv6m-none-eabi` |
+| [`microbit-v2`](./microbit-v2) | V2 | [<img src="https://github.com/microbit-foundation/microbit-svg/raw/master/microbit-drawing-back-2.png" width="124px" height="100px">](https://github.com/microbit-foundation/microbit-svg/blob/master/microbit-drawing-back-2.png) | [![docs.rs](https://docs.rs/microbit-v2/badge.svg)](https://docs.rs/microbit-v2) | [![crates.io](https://img.shields.io/crates/d/microbit-v2.svg)](https://crates.io/crates/microbit-v2) | `thumbv7em-none-eabihf` |
+
+### Install dependencies
+
+The examples make use of some of the fantastic tooling from the [knurling](https://knurling.ferrous-systems.com/) project.
+In order to run the examples you need to install [`probe-run`](https://github.com/knurling-rs/probe-run#installation)
+and [`flip-link`](https://github.com/knurling-rs/flip-link#installation).
+
+```bash
+> cargo install probe-run flip-link
+```
+
+### Run an example
+
+The first thing to try is one of the [examples](./examples) in this repository. Plug in your micro:bit and
+run one of the commands below.
+
+*For micro:bit V1*
 ```bash
-# cargo install probe-run
-# cargo run --release --example led_blocking
-   Compiling microbit v0.8.0
-    Finished release [optimized + debuginfo] target(s) in 15.39s
-     Running `probe-run --chip nRF51822_xxAA target/thumbv6m-none-eabi/release/examples/led_blocking`
-  (HOST) INFO  flashing program (1.95 KiB)
-  (HOST) INFO  success!
-RTT logs not available; blocking until the device halts..
+> cargo run --manifest-path ./examples/led-blocking/Cargo.toml --features v1 --target thumbv6m-none-eabi
 ```
 
-[BBC micro:bit]: https://microbit.org
-[cortex-m]:(https://github.com/japaric/cortex-m)
-[cortex-m-rt]:(https://github.com/japaric/cortex-m-rt)
-[examples]: https://github.com/therealprof/microbit/tree/master/examples
-[myblog]: https://www.eggers-club.de/blog/2018/05/31/rust-on-the-microbit-101-part-1
-[microrust]: https://droogmic.github.io/microrust/
-[knurling]: https://knurling.ferrous-systems.com/
+*For micro:bit V2*
+```bash
+> cargo run --manifest-path ./examples/led-blocking/Cargo.toml --features v2 --target thumbv7em-none-eabihf
+```
+
+You should see a lot of build output, the orange LED on the back of the micro:bit should flash quickly and
+a message should appear on the LED display.
+
+Congratulations! You've flashed your first rust program onto your micro:bit!
+
+## Further reading
+
+A guide to embedded development with Rust on the _microbit_ using this crate can be found in the [MicroRust book](https://droogmic.github.io/microrust/).
+
+Other useful resources:
+- [micro:bit developer community](https://tech.microbit.org)
+- [micro:bit hardware overview](https://tech.microbit.org/hardware/)
+- [nrf-hal](https://github.com/nrf-rs/nrf-hal#readme) the hardware abstraction layer (HAL) this repository is based on
 
 ## License
 

README.md

@@ -0,0 +1,34 @@
+[package]
+name = "gpio-direct-blinky"
+version = "0.1.0"
+edition = "2018"
+
+[dependencies]
+cortex-m = "0.6.1"
+cortex-m-rt = "0.6.12"
+panic-halt = "0.2.0"
+defmt = "0.2.0"
+
+[dependencies.microbit]
+path = "../../microbit"
+optional = true
+
+[dependencies.microbit-v2]
+path = "../../microbit-v2"
+optional = true
+
+[features]
+v1 = ["microbit"]
+v2 = ["microbit-v2"]
+
+default = [
+  "defmt-default",
+]
+
+# do NOT modify these features
+defmt-default = []
+defmt-trace = []
+defmt-debug = []
+defmt-info = []
+defmt-warn = []
+defmt-error = []

examples/gpio-direct-blinky/Cargo.toml

@@ -5,6 +5,7 @@ use panic_halt as _;
 
 use cortex_m_rt::entry;
 
+#[cfg(feature = "v1")]
 #[entry]
 fn main() -> ! {
     if let Some(p) = microbit::Peripherals::take() {
@@ -33,3 +34,33 @@ fn main() -> ! {
         continue;
     }
 }
+
+#[cfg(feature = "v2")]
+#[entry]
+fn main() -> ! {
+    if let Some(p) = microbit::Peripherals::take() {
+        p.P0.pin_cnf[28].write(|w| w.dir().output());
+        p.P0.pin_cnf[21].write(|w| w.dir().output());
+
+        p.P0.out.write(|w| unsafe { w.bits(1 << 21) });
+
+        let mut count: u8 = 0;
+        loop {
+            count += 1;
+
+            if count & 1 == 1 {
+                p.P0.out.write(|w| unsafe { w.bits(1 << 21) });
+            } else {
+                p.P0.out.write(|w| unsafe { w.bits(0) });
+            }
+
+            for _ in 0..50_000 {
+                cortex_m::asm::nop();
+            }
+        }
+    };
+
+    loop {
+        continue;
+    }
+}

examples/gpio_direct_blinky.rs renamed to examples/gpio-direct-blinky/src/main.rs

@@ -0,0 +1,35 @@
+[package]
+name = "gpio-hal-blinky"
+version = "0.1.0"
+edition = "2018"
+
+[dependencies]
+embedded-hal = "0.2.4"
+cortex-m-rt = "0.6.12"
+panic-halt = "0.2.0"
+defmt-rtt = "0.2.0"
+defmt = "0.2.0"
+
+[dependencies.microbit]
+path = "../../microbit"
+optional = true
+
+[dependencies.microbit-v2]
+path = "../../microbit-v2"
+optional = true
+
+[features]
+v1 = ["microbit"]
+v2 = ["microbit-v2"]
+
+default = [
+  "defmt-default",
+]
+
+# do NOT modify these features
+defmt-default = []
+defmt-trace = []
+defmt-debug = []
+defmt-info = []
+defmt-warn = []
+defmt-error = []