Merge #271

271: micro:bit: chapter 04; 05 r=eldruin a=hargoniX

A rewrite of chapter 04 and partially chapter 05.

I'm already uploading this now since the cargo-embed GDB stub is blowing up on my machine when trying to debug this chip so I'll probably have to spend some time debugging, however during that time my current work can already be reviewed so feel free to take a look at it!

Co-authored-by: Henrik Böving <hargonix@gmail.com>

Author: bors[bot]

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.