micro:bit: chapter 04; 05

src/03-setup/README.md

@@ -29,7 +29,7 @@ should work but we have listed the version we have tested.
 
 [`cargo-binutils`]: https://github.com/rust-embedded/cargo-binutils
 
-- [`cargo-embed`]. Version 0.9.0 or newer.
+- [`cargo-embed`]. Version 0.9.1 or newer.
 
 [`cargo-embed`]: https://github.com/probe-rs/cargo-embed
 

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

@@ -2,40 +2,40 @@
 
 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")
+If you happen to be interested in a more in detail description of the board you
+can checkout the [micro:bit website](https://tech.microbit.org/hardware/).
+
+## 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 +44,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 contains chapter 10 "Ordering Information"
+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,13 @@
 [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"
+rtt-target = { version = "0.2.2", features = ["cortex-m"] }
+panic-rtt-target = { version = "0.1.1", features = ["cortex-m"] }

src/05-led-roulette/Embed.toml

@@ -0,0 +1,11 @@
+[default.general]
+chip = "nrf51822_xxAA"
+
+[default.reset]
+halt_afterwards = true
+
+[default.rtt]
+enabled = false
+
+[default.gdb]
+enabled = true

src/05-led-roulette/README.md

@@ -3,22 +3,17 @@
 Alright, let's start by building the following application:
 
 <p align="center">
-<img src="https://i.imgur.com/0k1r2Lc.gif">
+<video src="../assets/roulette_fast.mp4" loop autoplay>
 </p>
 
 I'm going to give you a high level API to implement this app but don't worry we'll do low level
 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 +41,18 @@ 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 halt the chip after we flashed it so our program does not instantly jump to the loop
+* 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.