Merge pull request #51 from ferrous-systems/add-buttons

Add buttons exercise.

build.sh

@@ -23,6 +23,10 @@ pushd boards/dk
 cargo build --target=thumbv7em-none-eabihf
 cargo fmt --check
 popd
+pushd boards/dk-solution
+cargo build --target=thumbv7em-none-eabihf
+cargo fmt --check
+popd
 pushd radio-app
 cargo build --target=thumbv7em-none-eabihf --release
 cargo fmt --check

exercise-book/src/SUMMARY.md

@@ -47,6 +47,8 @@
     - [Collision avoidance](./nrf52-radio-collision-avoidance.md)
     - [Interrupt handling](./nrf52-radio-interrupt-handling.md)
     - [Starting a Project from Scratch](./nrf52-radio-from-scratch.md)
+- [nRF52 HAL Workbook](./nrf52-hal-workbook.md)
+  - [Adding Buttons](./nrf52-hal-buttons.md)
 - [nRF52 USB Workbook](./nrf52-usb-workbook.md)
   - [Listing USB Devices](./nrf52-usb-listing-usb-devices.md)
   - [Hello, world!](./nrf52-usb-hello-world.md)

exercise-book/src/nrf52-hal-buttons.md

@@ -0,0 +1,61 @@
+# Adding Buttons
+
+To practice using a HAL to provide functionality through a Board Support Package, you will now modify the `dk` crate to add support for Buttons.
+
+## Change the demo app
+
+✅ Change the `hal-app/src/bin/buttons.rs` file as described within, so it looks for button presses.
+
+It should now fail to compile, because the `dk` crate doesn't have support for buttons. You will now fix that!
+
+## Define a Button
+
+✅ Open up the `dk` crate in VS Code (`nrf52-code/board/dk`) and open `src/lib.rs`.
+
+✅ Add a `struct Button` which represents a single button.
+
+It should be similar to `struct Led`, except the inner type must be `Pin<Input<PullUp>>`. You will need to import those types - look where `Output` and `PushPull` types were imported from for clues! Think about where it makes sense to add this new type. At the top? At the buttom? Maybe just after to the LED related types?
+
+🔎 The pins must be set as pull-ups is because each button connects a GPIO pin to ground, but the pins float when the button is not pressed. Enabling the pull-ups inside the SoC ensure that the GPIO pin is weakly connected to 3.3V through a resistor, giving it a 'default' value of 'high'. Pressing the button then makes the pin go 'low.
+
+## Define all the Buttons
+
+✅ Add a `struct Buttons` which contains four buttons.
+
+Use `struct Leds` for guidance. Add a `buttons` field to `struct Board` which is of type `Buttons`. Again, think about where it makes sense to insert this new field.
+
+## Set up the buttons
+
+Now the `Board` struct initaliser is complaining you didn't initialise the new `buttons` field.
+
+✅ Take pins from the HAL, configure them as inputs with pull-ups, and install them into the Buttons structure.
+
+The mapping is:
+
+* Button 1: P0.11
+* Button 2: P0.12
+* Button 3: P0.24
+* Button 4: P0.25
+
+You can verify this in the [User Guide](https://infocenter.nordicsemi.com/pdf/nRF52840_DK_User_Guide_v1.3.pdf).
+
+## Run your program
+
+✅ Run the `buttons` demo:
+
+```console
+cd nrf52-code/hal-app
+cargo run --bin buttons
+```
+
+Now when you press the button, the LED should illuminate. If it does the opposite, check your working!
+
+## Write a more interesting demo program for the BSP
+
+✅ You've got four buttons and four LEDs. Make up a demo!
+
+If you're stuck for ideas, you could have the LEDs do some kind of animation. The buttons might then stop or start the animation, or make it go faster or slower. Try setting up a loop with a 20ms delay inside it, to give yourself a basic 50 Hz "game tick". You can look at the `blinky` demo for help with the timer.
+
+## Troubleshooting
+
+🔎 If you get totally stuck, ask for help! If all else fails, you could peek in `board/dk-solution`, which has a complete set of the required BSP changes.

exercise-book/src/nrf52-hal-workbook.md

@@ -0,0 +1,20 @@
+# nRF52 HAL Workbook
+
+In this workshop you'll learn to:
+
+- use a HAL to provide features in a BSP
+- configure GPIO pins using the nRF52 HAL
+
+To test your BSP changes, you will modify a small example: `hal-app/src/bin/blinky.rs`
+
+You will need an nRF52840 Development Kit for this exercise, but not the nRF USB dongle.
+
+If you haven't completed the Radio Workbook, you should start there, and go at least as far as completing the "Timers and Time" section.
+
+## The nRF52840 Development Kit
+
+This is the larger development board.
+
+The board has two USB ports: J2 and J3 and an on-board J-Link programmer / debugger -- [there are instructions to identify the ports in a previous section][id-ports]. USB port J2 is the J-Link's USB port. USB port J3 is the nRF52840's USB port. Connect the Development Kit to your computer using the **J2** port.
+
+[id-ports]: ./nrf52-hardware.md#nrf52840-development-kit-dk

nrf52-code/boards/dk-solution/.gitignore

@@ -0,0 +1 @@
+target

nrf52-code/boards/dk-solution/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+authors = ["Ferrous Systems"]
+edition = "2018"
+license = "MIT OR Apache-2.0"
+name = "dk"
+version = "0.0.0"
+
+[dependencies]
+cortex-m = {version = "0.7.6", features = ["critical-section-single-core"]}
+cortex-m-rt = "0.7.2"
+embedded-hal = "0.2.7"
+hal = { package = "nrf52840-hal", version = "0.14.0" }
+panic-probe = { version = "0.3.0", features = ["print-defmt"] }
+defmt = "0.3.5"
+defmt-rtt = "0.3.2"
+
+[features]
+advanced = []
+radio = []
+
+default = [
+  "other-feature"
+]
+other-feature = []
+
+# do NOT modify these features
+defmt-default = []
+defmt-trace = []
+defmt-debug = []
+defmt-info = []
+defmt-warn = []
+defmt-error = []

nrf52-code/boards/dk-solution/README.md

@@ -0,0 +1,7 @@
+# `dk`
+
+Board Support Package (BSP) for the nRF52840 Development Kit (DK)
+
+See <https://www.nordicsemi.com/Products/Development-hardware/nrf52840-dk>
+
+This copy contains support for Buttons 1 to 4.

nrf52-code/boards/dk-solution/build.rs

@@ -0,0 +1,12 @@
+use std::{env, error::Error, fs, path::PathBuf};
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let out_dir = PathBuf::from(env::var("OUT_DIR")?);
+
+    // put memory layout (linker script) in the linker search path
+    fs::copy("memory.x", out_dir.join("memory.x"))?;
+
+    println!("cargo:rustc-link-search={}", out_dir.display());
+
+    Ok(())
+}

nrf52-code/boards/dk-solution/memory.x

@@ -0,0 +1,5 @@
+MEMORY
+{
+  FLASH : ORIGIN = 0x00000000, LENGTH = 1024K
+  RAM   : ORIGIN = 0x20000000, LENGTH = 256K
+}

nrf52-code/boards/dk-solution/src/errata.rs

@@ -0,0 +1,13 @@
+/// USBD cannot be enabled
+pub unsafe fn e187a() {
+    (0x4006_EC00 as *mut u32).write_volatile(0x9375);
+    (0x4006_ED14 as *mut u32).write_volatile(3);
+    (0x4006_EC00 as *mut u32).write_volatile(0x9375);
+}
+
+/// USBD cannot be enabled
+pub unsafe fn e187b() {
+    (0x4006_EC00 as *mut u32).write_volatile(0x9375);
+    (0x4006_ED14 as *mut u32).write_volatile(0);
+    (0x4006_EC00 as *mut u32).write_volatile(0x9375);
+}