micro:bit: chapter 04; 05

src/04-meet-your-hardware/README.md

@@ -2,40 +2,37 @@
 
 Let's get familiar with the hardware we'll be working with.
 
-## STM32F3DISCOVERY (the "F3")
+## micro:bit
 
 <p align="center">
-<img title="F3" src="../assets/f3.jpg">
+<img title="micro:bit" src="../assets/microbit.jpg">
 </p>
 
-We'll refer to this board as "F3" throughout this book. Here are some of the
-many components on the board:
+Here are some of the many components on the board:
 
 - A [microcontroller].
-- A number of LEDs, including the eight aligned in a "compass" formation.
-- Two buttons.
-- Two USB ports.
-- An [accelerometer].
-- A [magnetometer].
-- A [gyroscope].
+- A number of LEDs, most notably the LED matrix on the back
+- Two user buttons as well as a reset button (the one next to the USB port).
+- One USB port.
+- A sensor that is both a [magnetometer] and an [accelerometer]
 
 [microcontroller]: https://en.wikipedia.org/wiki/Microcontroller
 [accelerometer]: https://en.wikipedia.org/wiki/Accelerometer
 [magnetometer]: https://en.wikipedia.org/wiki/Magnetometer
 [gyroscope]: https://en.wikipedia.org/wiki/Gyroscope
 
 Of these components, the most important is the microcontroller (sometimes
-shortened to "MCU" for "microcontroller unit"), which is the large black square
-sitting in the center of your board. The MCU is what runs your code. You might
-sometimes read about "programming a board", when in reality what we are doing
-is programming the MCU that is installed on the board.
+shortened to "MCU" for "microcontroller unit"), which is the bigger of the two
+black squares sitting on the side of the board with the USB port. The MCU is
+what runs your code. You might sometimes read about "programming a board", when
+in reality what we are doing is programming the MCU that is installed on the board.
 
-## STM32F303VCT6 (the "STM32F3")
+## Nordic nRF51822 (the "nRF51")
 
 Since the MCU is so important, let's take a closer look at the one sitting on our board.
 
-Our MCU is surrounded by 100 tiny metal **pins**. These pins are connected to
-**traces**, the little "roads" that act as the wires connecting components
+Our MCU has 48 tiny metal **pins** sitting right underneath it (it's a so called [QFN48] chip).
+These pins are connected to **traces**, the little "roads" that act as the wires connecting components
 together on the board. The MCU can dynamically alter the electrical properties
 of the pins. This works similar to a light switch altering how electrical
 current flows through a circuit. By enabling or disabling electrical current to
@@ -44,68 +41,57 @@ be turned on and off.
 
 Each manufacturer uses a different part numbering scheme, but many will allow
 you to determine information about a component simply by looking at the part
-number. Looking at our MCU's part number (`STM32F303VCT6`), the `ST` at the
-front hints to us that this is a part manufactured by [ST Microelectronics].
-Searching through [ST's marketing materials] we can also learn the following:
-
-[ST Microelectronics]: https://st.com/
-[ST's marketing materials]: https://www.st.com/en/microcontrollers-microprocessors/stm32-mainstream-mcus.html
-
-- The `M32` represents that this is an Arm®-based 32-bit microcontroller.
-- The `F3` represents that the MCU is from ST's "STM32F3" series. This is a
-  series of MCUs based on the Cortex®-M4 processor design.
-- The remainder of the part number goes into more details about things like
-  extra features and RAM size, which at this point we're less concerned about.
-
-> ### Arm? Cortex-M4?
->
-> If our chip is manufactured by ST, then who is Arm? And if our chip is the
-> STM32F3, what is the Cortex-M4?
->
-> You might be surprised to hear that while "Arm-based" chips are quite
-> popular, the company behind the "Arm" trademark ([Arm Holdings][]) doesn't
-> actually manufacture chips for purchase. Instead, their primary business
-> model is to just *design* parts of chips. They will then license those designs to
-> manufacturers, who will in turn implement the designs (perhaps with some of
-> their own tweaks) in the form of physical hardware that can then be sold.
-> Arm's strategy here is different from companies like Intel, which both
-> designs *and* manufactures their chips.
->
-> Arm licenses a bunch of different designs. Their "Cortex-M" family of designs
-> are mainly used as the core in microcontrollers. For example, the Cortex-M0
-> is designed for low cost and low power usage. The Cortex-M7 is higher cost,
-> but with more features and performance. The core of our STM32F3 is based on
-> the Cortex-M4, which is in the middle: more features and performance than the
-> Cortex-M0, but less expensive than the Cortex-M7.
->
-> Luckily, you don't need to know too much about different types of processors
-> or Cortex designs for the sake of this book. However, you are hopefully now a
-> bit more knowledgeable about the terminology of your device. While you are
-> working specifically with an STM32F3, you might find yourself reading
-> documentation and using tools for Cortex-M-based chips, as the STM32F3 is
-> based on a Cortex-M design.
+number. Looking at our MCU's part number (`nRF51822-QFAA-R`, you probably cannot
+see it with your bare eye, but it is on the chip), the `n` at the
+front hints to us that this is a part manufactured by [Nordic Semiconductor].
+Looking up the part number on their website we quickly find the [product page].
+There we learn that our chip's main marketing point is that it is a
+"Bluetooth Low Energy and 2.4 GHz SoC" (SoC being short for System on a Chip),
+which explains the RF in the product name since RF is short for radio frequency.
+If we search through the documentation of the chip linked on the [product page]
+for a bit we find the [product specification] which has chapter 10 Ordering Infomration
+dedicated to explaining the weird chip naming, here we learn that:
+
+[QFN48]: https://en.wikipedia.org/wiki/Flat_no-leads_package
+[Nordic Semiconductor]: https://www.nordicsemi.com/
+[product page]: https://www.nordicsemi.com/Products/Low-power-short-range-wireless/nRF51822
+[product specification]: https://infocenter.nordicsemi.com/pdf/nRF51822_PS_v3.3.pdf
+
+- The `nRF51` is the MCU's series, indicating that there are other `nRF51` MCUs
+- The `822` is the part code
+- The `QF` is short for `QFN48`
+- The `AA` is the variant code, indicating how much RAM and flash memory the MCU has,
+  in our case 256 kilobyte flash and 16 kilobyte RAM
+- The `R` is the packaging code which is relevant for factories manufacturing boards
+  with this chip on them in larger scales
+
+The product specification does of course contain a lot more useful information about
+the chip, for example that it is based on an ARM® Cortex™-M0 32 bit processor.
+
+### Arm? Cortex-M0?
+
+If our chip is manufactured by Nordic, then who is Arm? And if our chip is the
+nRF51822, what is the Cortex-M0?
+
+You might be surprised to hear that while "Arm-based" chips are quite
+popular, the company behind the "Arm" trademark ([Arm Holdings][]) doesn't
+actually manufacture chips for purchase. Instead, their primary business
+model is to just *design* parts of chips. They will then license those designs to
+manufacturers, who will in turn implement the designs (perhaps with some of
+their own tweaks) in the form of physical hardware that can then be sold.
+Arm's strategy here is different from companies like Intel, which both
+designs *and* manufactures their chips.
+
+Arm licenses a bunch of different designs. Their "Cortex-M" family of designs
+are mainly used as the core in microcontrollers. For example, the Cortex-M0
+(the core our chip is based on) is designed for low cost and low power usage.
+The Cortex-M7 is higher cost, but with more features and performance.
+
+Luckily, you don't need to know too much about different types of processors
+or Cortex designs for the sake of this book. However, you are hopefully now a
+bit more knowledgeable about the terminology of your device. While you are
+working specifically with an nRF51822, you might find yourself reading
+documentation and using tools for Cortex-M-based chips, as the nRF51822 is
+based on a Cortex-M design.
 
 [Arm Holdings]: https://www.arm.com/
-
-## The Serial module
-
-<p align="center">
-<img title="Serial module" src="../assets/serial.jpg">
-</p>
-
-If you have an older revision of the discovery board, you can use this module to
-exchange data between the microcontroller in the F3 and your computer. This module
-will be connected to your computer using an USB cable. I won't say more at this
-point.
-
-If you have a newer release of the board then you don't need this module. The
-ST-LINK will double as a USB<->serial converter connected to the microcontroller USART1 at pins PC4 and PC5.
-
-## The Bluetooth module
-
-<p align="center">
-<img title="The HC-05 Bluetooth module" src="../assets/bluetooth.jpg">
-</p>
-
-This module has the exact same purpose as the serial module but it sends the data over Bluetooth
-instead of over USB.

src/05-led-roulette/.cargo/config

@@ -1,5 +1,7 @@
-[target.thumbv7em-none-eabihf]
-runner = "arm-none-eabi-gdb -q"
+[target.'cfg(all(target_arch = "arm", target_os = "none"))']
 rustflags = [
   "-C", "link-arg=-Tlink.x",
 ]
+
+[build]
+target = "thumbv6m-none-eabi"

src/05-led-roulette/Cargo.toml

@@ -1,8 +1,11 @@
 [package]
-authors = ["Jorge Aparicio <jorge@japaric.io>"]
-edition = "2018"
 name = "led-roulette"
 version = "0.1.0"
+authors = ["Henrik Böving <hargonix@gmail.com>"]
+edition = "2018"
 
 [dependencies]
-aux5 = { path = "auxiliary" }
+cortex-m = "0.6.0"
+cortex-m-rt = "0.6.10"
+panic-halt = "0.2.0"
+nrf51-hal = "0.11.0"

src/05-led-roulette/Embed.toml

@@ -0,0 +1,9 @@
+[default.general]
+chip = "nrf51822"
+
+[default.rtt]
+enabled = false
+
+[default.gdb]
+enabled = true
+

src/05-led-roulette/README.md

@@ -2,6 +2,7 @@
 
 Alright, let's start by building the following application:
 
+# TODO REPLACE THIS
 <p align="center">
 <img src="https://i.imgur.com/0k1r2Lc.gif">
 </p>
@@ -10,15 +11,10 @@ I'm going to give you a high level API to implement this app but don't worry we'
 stuff later on. The main goal of this chapter is to get familiar with the *flashing* and debugging
 process.
 
-Throughout this text we'll be using the starter code that's in the [discovery] repository. Make sure
-you always have the latest version of the master branch because this website tracks that branch.
-
 The starter code is in the `src` directory of that repository. Inside that directory there are more
 directories named after each chapter of this book. Most of those directories are starter Cargo
 projects.
 
-[discovery]: https://github.com/rust-embedded/discovery
-
 Now, jump into the `src/05-led-roulette` directory. Check the `src/main.rs` file:
 
 ``` rust
@@ -46,4 +42,17 @@ as well. This directory contains a Cargo configuration file (`.cargo/config`) th
 linking process to tailor the memory layout of the program to the requirements of the target device.
 This modified linking process is a requirement of the `cortex-m-rt` crate.
 
+Furthermore there is also an `Embed.toml` file
+
+```toml
+{{#include Embed.toml}}
+```
+
+This file tells `cargo-embed` that:
+
+* we are working with a nrf51822,
+* we want to disable RTT, RTT being a protocol that allows the chip to send text to a debugger.
+  You have in fact already seen RTT in action, it was the protocol that sent "Hello World" in chapter 3.
+* we want to enable GDB, this will be required for the debugging procedure
+
 Alright, let's start by building this program.

src/05-led-roulette/build-it.md

@@ -5,7 +5,7 @@ architecture than your computer we'll have to cross compile. Cross compiling in
 as passing an extra `--target` flag to `rustc`or Cargo. The complicated part is figuring out the
 argument of that flag: the *name* of the target.
 
-The microcontroller in the F3 has a Cortex-M4F processor in it. `rustc` knows how to cross compile
+The microcontroller in the micro:bit has a Cortex-M0 processor in it. `rustc` knows how to cross compile
 to the Cortex-M architecture and provides 4 different targets that cover the different processor
 families within that architecture:
 
@@ -14,12 +14,12 @@ families within that architecture:
 - `thumbv7em-none-eabi`, for the Cortex-M4 and Cortex-M7 processors
 - `thumbv7em-none-eabihf`, for the Cortex-M4**F** and Cortex-M7**F** processors
 
-For the F3, we'll use the `thumbv7em-none-eabihf` target. Before cross compiling you have to
+For the micro:bit, we'll use the `thumbv6m-none-eabi` target. Before cross compiling you have to
 download pre-compiled version of the standard library (a reduced version of it actually) for your
 target. That's done using `rustup`:
 
 ``` console
-$ rustup target add thumbv7em-none-eabihf
+$ rustup target add thumbv6m-none-eabi
 ```
 
 You only need to do the above step once; `rustup` will re-install a new standard library
@@ -30,48 +30,53 @@ With the `rust-std` component in place you can now cross compile the program usi
 ``` console
 $ # make sure you are in the `src/05-led-roulette` directory
 
-$ cargo build --target thumbv7em-none-eabihf
+$ cargo build --target thumbv6m-none-eabi
    Compiling semver-parser v0.7.0
-   Compiling aligned v0.1.1
-   Compiling libc v0.2.35
-   Compiling bare-metal v0.1.1
-   Compiling cast v0.2.2
-   Compiling cortex-m v0.4.3
-   (..)
-   Compiling stm32f30x v0.6.0
-   Compiling stm32f30x-hal v0.1.2
-   Compiling aux5 v0.1.0 (file://$PWD/aux)
-   Compiling led-roulette v0.1.0 (file://$PWD)
-    Finished dev [unoptimized + debuginfo] target(s) in 35.84 secs
+   Compiling typenum v1.12.0
+   Compiling proc-macro2 v1.0.19
+   Compiling unicode-xid v0.2.1
+   Compiling cortex-m v0.6.3
+   (...)
+   Compiling as-slice v0.1.3
+   Compiling aligned v0.3.4
+   Compiling cortex-m-rt-macros v0.1.8
+   Compiling nrf-hal-common v0.11.1
+    Finished dev [unoptimized + debuginfo] target(s) in 18.69s
 ```
 
-> **NOTE** Be sure to compile this crate *without* optimizations. The provided Cargo.toml file and build command above will ensure optimizations are off. 
+> **NOTE** Be sure to compile this crate *without* optimizations.
 
-OK, now we have produced an executable. This executable won't blink any leds, it's just a simplified version that we will build upon later in the chapter. As a sanity check, let's verify that the produced executable is actually an ARM binary:
+> **NOTE** If you have looked into `.cargo/config` you will have noticed that the target
+  is actually always set to "thumbv6m-none-eabi" so the --target flag to `cargo` can in
+  fact be omitted here.
+
+OK, now we have produced an executable. This executable won't blink any leds,
+it's just a simplified version that we will build upon later in the chapter.
+As a sanity check, let's verify that the produced executable is actually an ARM binary:
 
 ``` console
-$ # equivalent to `readelf -h target/thumbv7em-none-eabihf/debug/led-roulette`
-$ cargo readobj --target thumbv7em-none-eabihf --bin led-roulette -- -file-headers
+$ # equivalent to `readelf -h target/thumbv6m-none-eabi/debug/led-roulette`
+ cargo readobj --target thumbv6m-none-eabi --bin led-roulette -- -file-headers
 ELF Header:
   Magic:   7f 45 4c 46 01 01 01 00 00 00 00 00 00 00 00 00
   Class:                             ELF32
   Data:                              2's complement, little endian
   Version:                           1 (current)
   OS/ABI:                            UNIX - System V
-  ABI Version:                       0x0
+  ABI Version:                       0
   Type:                              EXEC (Executable file)
   Machine:                           ARM
   Version:                           0x1
-  Entry point address:               0x8000197
+  Entry point address:               0xC1
   Start of program headers:          52 (bytes into file)
-  Start of section headers:          740788 (bytes into file)
-  Flags:                             0x5000400
+  Start of section headers:          599484 (bytes into file)
+  Flags:                             0x5000200
   Size of this header:               52 (bytes)
   Size of program headers:           32 (bytes)
   Number of program headers:         2
   Size of section headers:           40 (bytes)
-  Number of section headers:         20
-  Section header string table index: 18
+  Number of section headers:         22
+  Section header string table index: 20
 ```
 
 Next, we'll flash the program into our microcontroller.

src/05-led-roulette/build.rs

@@ -0,0 +1,30 @@
+//! This build script copies the `memory.x` file from the crate root into
+//! a directory where the linker can always find it at build time.
+//! For many projects this is optional, as the linker always searches the
+//! project root directory (wherever `Cargo.toml` is). However, if you
+//! are using a workspace or have a more complicated build setup, this
+//! build script becomes required. Additionally, by requesting that
+//! Cargo re-run the build script whenever `memory.x` is changed,
+//! a rebuild of the application with new memory settings is ensured after updating `memory.x`.
+
+use std::env;
+use std::fs::File;
+use std::io::Write;
+use std::path::PathBuf;
+
+fn main() {
+    // Put `memory.x` in our output directory and ensure it's
+    // on the linker search path.
+    let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());
+    File::create(out.join("memory.x"))
+        .unwrap()
+        .write_all(include_bytes!("memory.x"))
+        .unwrap();
+    println!("cargo:rustc-link-search={}", out.display());
+
+    // By default, Cargo will re-run a build script whenever
+    // any file in the project changes. By specifying `memory.x`
+    // here, we ensure the build script is only re-run when
+    // `memory.x` is changed.
+    println!("cargo:rerun-if-changed=memory.x");
+}