completed hello-world chapter

Author: BartMassey

mdbook/src/05-hello-world/Cargo.toml

@@ -7,6 +7,7 @@ version = "0.1.0"
 [dependencies]
 cortex-m-rt = "0.7.3"
 embedded-hal = "1.0.0"
+microbit-v2 = "0.15.0"
 nrf52833-hal = "0.18.0"
 panic-halt = "0.2.0"
 

mdbook/src/05-hello-world/README.md

@@ -39,19 +39,19 @@ But what do we do in software to cause this to occur? We will work at the level
 particular microcontroller easier to work with. As can be seen from the name, we have one for the
 microcontroller on the MB2. It happens to contain everything needed to turn our target LED on.
 
-Take a look at `src/bin/light-up.rs` in this chapter's directory, and then try running it.
+Take a look at `examples/light-up.rs` in this chapter's directory, and then try running it.
 You could use something fancy like before, but we have it set up so that
 
 ```
-cargo run --bin light-up
+cargo run --example light-up
 ```
 
 will load and run your program. That one LED should now be brightly lit!
 
 ``` rust
-{{#include src/bin/light-up.rs}}
+{{#include examples/light-up.rs}}
 ```
 
 Note that we access the Peripheral Access Crate (PAC) for this chip through our HAL crate. There's a
 complicated dance needed to get access to our pins. Finally, since we can just initialize the pins
-to the right levels, we don't need to set them. That's a topic for the next section.
+to the right levels, we don't need to set them. Wiggling the pins is a topic for the next section.

mdbook/src/05-hello-world/board-support-crate.md

@@ -0,0 +1,28 @@
+# Board support crate
+
+Working directly with the PAC and HAL is pretty neat. Most ARM MCUs and many other MCUs that Rust
+can compile for have a PAC crate. If you are working with one that does not, writing a PAC crate can
+be tedious but is pretty straightforward. Many MCUs that have a PAC crate also have a HAL crate —
+again, it's mostly just tedious work to build one if it is absent. Code written at the PAC and HAL
+level gives access to the fine details of the MCU.
+
+As we have seen, though, it becomes pretty annoying to keep track of just what is going on at the
+interface between our nRF52833 and the rest of our MB2. We have had to read schematics and whatnot
+to see how to use our off-board hardware.
+
+A "board support crate" — known in the non-Rust embedded community as a Board Support Package (BSP)
+— is a crate built on top of the HAL and PAC for a board to abstract away the details and provide
+conveniences. The board support crate we have been working with is the `microbit-v2` crate.
+
+Let's use `microbit-v2` to get a final, cleaned up blinky (`src/main.rs`).
+
+```rust
+{{#include src/main.rs}}
+```
+
+In this case, we haven't changed much. Our board support crate has hidden the PAC (for now). More
+importantly, it has done so by letting us just use reasonable names for the row and column GPIO pins
+for the LED.
+
+The `microbit-v2` crate provides even fancier support for those "display" LEDs. We will see this
+support used soon to do things more fun than blinky.

mdbook/src/05-hello-world/src/bin/fast-blink.rs renamed to mdbook/src/05-hello-world/examples/fast-blink.rs

@@ -0,0 +1,25 @@
+#![no_main]
+#![no_std]
+
+use cortex_m_rt::entry;
+use embedded_hal::{delay::DelayNs, digital::OutputPin};
+use nrf52833_hal::{gpio, pac, timer};
+use panic_halt as _;
+
+#[entry]
+fn main() -> ! {
+    let peripherals = pac::Peripherals::take().unwrap();
+
+    let p0 = gpio::p0::Parts::new(peripherals.P0);
+    let mut row1 = p0.p0_21.into_push_pull_output(gpio::Level::High);
+    let _col1 = p0.p0_28.into_push_pull_output(gpio::Level::Low);
+
+    let mut timer0 = timer::Timer::new(peripherals.TIMER0);
+
+    loop {
+        timer0.delay_ms(500);
+        row1.set_high().unwrap();
+        timer0.delay_ms(500);
+        row1.set_low().unwrap();
+    }
+}

mdbook/src/05-hello-world/src/bin/light-up.rs renamed to mdbook/src/05-hello-world/examples/light-up.rs

@@ -0,0 +1,25 @@
+#![no_std]
+#![no_main]
+
+use panic_halt as _;
+use riscv_rt::entry;
+use gd32vf103xx_hal::{pac, prelude::*, delay::McycleDelay};
+use embedded_hal::{blocking::delay::DelayMs, digital::v2::OutputPin};
+
+#[entry]
+fn main() -> ! {
+    let dp = pac::Peripherals::take().unwrap();
+
+    let mut rcu = dp.RCU.configure().ext_hf_clock(8.mhz()).sysclk(108.mhz()).freeze();
+
+    let gpioc = dp.GPIOC.split(&mut rcu);
+    let mut led = gpioc.pc13.into_push_pull_output();
+    let mut delay = McycleDelay::new(&rcu.clocks);
+
+    loop {
+        delay.delay_ms(500);
+        led.set_high().unwrap();
+        delay.delay_ms(500);
+        led.set_low().unwrap();
+    }
+}

mdbook/src/05-hello-world/src/bin/spin-wait.rs renamed to mdbook/src/05-hello-world/examples/spin-wait.rs

@@ -4,12 +4,12 @@ You might wonder what that `nop()` call is doing in the `wait()` loop in `src/bi
 
 The answer is that it literally does nothing. The `nop()` function causes the compiler to put a
 `NOP` ARM machine instruction at that point in the program. `NOP` is a special instruction that
-causes the CPU to skip it. To ignore it. To literally do No OPeration with it, hence the name.
+causes the CPU to skip it. To ignore it. To literally do No OPeration with it (hence the name).
 
 So get rid of that line and recompile the program. Don't forget `--release` mode. Then run it.
 
 We're back to a slightly darker solid LED again. With no loop body, the compiler's optimizer decided
-that `wait()` wasn't doing anything. So it just removed it for you at compile time. Thanks
+that `wait()` function wasn't doing anything. So it just removed it for you at compile time. Thanks
 optimizer. You have made my wait loop infinitely fast.
 
 How does `nop()` do its job? Well, if you look at the implementation of `nop()` you will find
@@ -28,4 +28,4 @@ embedded programming. Sometime a CPU will have instructions the compiler doesn't
 that you still need in order to use the CPU effectively. Rust's `asm!()` directive gives you a way
 to do that.
 
-But our spin-wait is still terrible. Let's talk about doing better.
+Our spin-wait is still terrible. Let's talk about doing better.

mdbook/src/05-hello-world/examples/timer-blinky.rs

@@ -0,0 +1,32 @@
+# Portability
+
+(This section is optional. Feel free to skip to the [next section], where we clean our code up a bit
+and call it a day.)
+
+[next section]: board-support.html
+
+You may wonder whether all this fancy ecosystem is worth its weight. The setup for our blinky is
+pretty fancy, and uses a lot of Rust crates and features for such a simple job.
+
+One cool advantage, though, is that our code becomes really portable. On a different board, the
+setup may be different, but the actual blinky loop is identical!
+
+Let's take a look at a blinky for the Sipeed Longan Nano. This is a little $5 board that, like the
+MB2, is an embedded board with an MCU. Otherwise, it is completely different: different processor
+(the GD32VF103, with a RISC-V instruction set entirely unlike the ARM instruction set we're using),
+different peripherals, different board. But it has an LED attached to a GPIO pin, so we can blinky
+it.
+
+```rust
+{{#include nanoblinky.rs}}
+```
+
+The differences in setup here are partly because different hardware, and partly because this code
+uses an older HAL crate that hasn't yet been updated for `embedded-hal` 1.0. Yet the main loop is
+identical as advertised, and the rest of the code is pretty recognizable. Because of the portability
+provided by Rust's easy cross-compilation and the embedded Rust ecosystem, blinky is just blinky.
+
+You can find a complete working [nanoblinky] example on GitHub, if you want to see all the
+details or even get your own board and try it yourself.
+
+[nanoblinky]: https://github.com/pdx-cs-rust/nanoblinky