Merge #246

bors[bot] · ninjasource · web-flow · commit 4bc4bfaf85b0 · 2021-05-19T09:02:51.000Z
246: Add readme documentation for demos r=thejpster a=ninjasource

Hi, I've recently worked through all the demos and took notes as I was going. I thought it may be useful to add those notes to this repo if appropriate. I'm not sure if this is the correct place to put them but adding a `README.md` file to the examples folder confuses cargo builds for some reason. I hope that this will be useful as I was not familiar with all the acronyms in the project and I think that newcomers will find this quick reference useful too.

Co-authored-by: David Haig &lt;david@ninjametal.com&gt;
Co-authored-by: David Haig &lt;davidhydep@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -51,3 +51,49 @@ at your option.
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.
+
+## Summary of the Examples
+
+Here follows a brief description of each demo for quick reference. For a more in-depth explanation on how the peripherals work please refer to the device reference manuals linked above, the readme for each demo and the comments in the demo code itself.
+
+| Demo                                                  | Category          | Description                                                           |
+|-------------------------------------------------------|-------------------|-----------------------------------------------------------------------|
+| [blinky-button-demo](./examples/blinky-button-demo/README.md)  | Hello World       | Blinky button demo                                                    |
+| [ccm-demo](./examples/ccm-demo/README.md)                      | Encryption        | Cipher block chaining - message authentication code (CCM) mode demo   |
+| [comp-demo](./examples/comp-demo/README.md)                    | Analog Pins       | Voltage comparator peripheral demo                                    |
+| [ecb-demo](./examples/ecb-demo/README.md)                      | Encryption        | AES electronic codebook mode encryption demo                          |
+| [gpiote-demo](./examples/gpiote-demo/README.md)                | Digital Pins      | General-Purpose Input Output Tasks and Events module demo             |
+| [i2s-controller-demo](./examples/i2s-controller-demo/README.md)| Audio             | Inter-IC Sound interface "controller mode (aka master mode)" demo     |
+| [i2s-peripheral-demo](./examples/i2s-peripheral-demo/README.md)| Audio             | Inter-IC Sound interface "peripheral mode (aka slave mode)" demo      |
+| [lpcomp-demo](./examples/lpcomp-demo/README.md)                | Analog Pins       | Low power voltage comparator demo                                     |
+| [ppi-demo](./examples/ppi-demo/README.md)                      | Channels          | Programmable peripheral interconnect (PPI) demo                       |
+| [pwm-demo](./examples/pwm-demo/README.md)                      | Digital Pins      | Pulse width modulation demo                                           |
+| [qdec-demo](./examples/qdec-demo/README.md)                    | Sensor Decoding   | Quadrature sensor decoder (QDEC) demo                                 |
+| [rtic-demo](./examples/rtic-demo/README.md)                    | Framework         | The Real-Time Interrupt-driven Concurrency framework demo             |
+| [spi-demo](./examples/spi-demo/README.md)                      | Digital Pins      | Serial peripheral interface master (SPIM) with EasyDMA demo           |
+| [spis-demo](./examples/spis-demo/README.md)                    | Digital Pins      | Serial peripheral interface slave (SPIS) demo                         |
+| [twi-ssd1306](./examples/twi-ssd1306/README.md)                | Digital Pins      | I2C compatible Two-Wire Interface with the SSD1306 OLED Display demo  |
+| [twim-demo](./examples/twim-demo/README.md)                    | Digital Pins      | I2C compatible Two-Wire Interface Master mode demo                    |
+| [twis-demo](./examples/twis-demo/README.md)                    | Digital Pins      | I2C compatible Two-Wire Interface Slave mode demo                     |
+| [wdt-demo](./examples/wdt-demo/README.md)                      | Timer             | Watchdog timer demo                                                   |
+
+
+## Running the Examples
+
+Each demo readme should contain instructions on how to run it. However, the information below describes the technologies used and can be used to troubleshoot your system setup. Run the demos from within their respective project directories. E.g. to run `ccm-demo`, you must be in the `nrf-hal/examples/ccm-demo/` directory.
+> Since the demos are stand-alone projects you would **NOT** typically run them with `cargo run --example xyz-demo` like some cargo projects are configured to do.
+
+### Once Off System Setup
+
+Install the cross compilation toolchain to target your device. You would typically pass the target as a parameter to cargo or explicitly set it in your cargo config file. If you get compilation errors about `eh_personality` then you have not set the target correctly. Here is an example of the target for a nRF52840 chip:
+```console
+$ rustup target add thumbv7em-none-eabihf
+```
+Install the tools to flash the device. 
+```console
+$ cargo install cargo-embed
+```
+
+### For Every Project (optional)
+
+Setup the `Cargo.toml` file to use the correct features. Features allow for conditional compilation which is essential for a library like this that supports multiple different devices. Under the `[features]` section add the following line `default = ["52840"]` for the nRF52840-DK device or whatever other feature is applicable for your device. This is optional but it will allow you to simply call `cargo run` and `cargo build` instead of `cargo run --features 52840` and `cargo build --features 52840` respectively. Note that some demo projects do not have features so this step may not be necessary. If you get a whole bunch of compilation errors or plugins like rust-analyzer are not working then check that you have set the chip features correctly. 
diff --git a/examples/blinky-button-demo/README.md b/examples/blinky-button-demo/README.md
@@ -1,6 +1,7 @@
 # Blinky button demo
 
-This example turns on LED 1 when you press Button 1 on the nrf52-dk (PCA10040).
+This hello world example turns on LED 1 when you press Button 1 on the nrf52-dk (PCA10040).
+> Note: You will have to change the pin numbers if you use a different device.
 
 ## Set up with `cargo-embed`
 
diff --git a/examples/ccm-demo/README.md b/examples/ccm-demo/README.md
@@ -1,4 +1,8 @@
-# AES-CCM demo
+# CCM encryption demo
+
+This CCM (cipher block chaining) encryption demo initialises a text message of the maximum size of 251 bytes and encrypts and decrypts it, measuring the time it takes. It then repeats the process with smaller and smaller chunks of data to demonstrate how long smaller packets take to process.
+
+## How to run
 
 Choose the microcontroller with one of the following features:
 - 52810
diff --git a/examples/comp-demo/README.md b/examples/comp-demo/README.md
@@ -0,0 +1,11 @@
+# Comp demo
+
+ This demo uses the Comparator (comp) peripheral to compare the differential voltages between two pins. If the voltage on Pin 30 is higher than Pin 31 (reference voltage) the built in LED will switch off otherwise it will switch on. The demo uses `nrf52840-hal` but this can be swapped out with an alternative if required.
+
+## How to run
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/ecb-demo/README.md b/examples/ecb-demo/README.md
@@ -1,4 +1,8 @@
-# AES electronic codebook mode encryption demo
+# ECB encryption demo
+
+The AES electronic codebook mode (ECB) demo demonstrates a blocking 128-bit AES encryption of 16 bytes of data using a 16 byte key. Encryption only, no decryption.
+
+## How to run
 
 Choose the microcontroller with one of the following features:
 - 51
diff --git a/examples/gpiote-demo/README.md b/examples/gpiote-demo/README.md
@@ -0,0 +1,11 @@
+# Gpiote demo
+
+The General-Purpose Input Output Tasks and Events (gpiote) module demo targets the nRF52840-DK in particular because of the 4 available hardware buttons on the board itself. The demo shows how you can use the `cortex-m-rtic` crate to easily debounce some buttons without blocking the CPU. GPIO pin state changes fire events which can be used to carry out tasks. This showcases the PPI (programmable peripheral interconnect) system for which there is also a dedicated demo.
+
+## How to run
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/i2s-controller-demo/README.md b/examples/i2s-controller-demo/README.md
@@ -0,0 +1,11 @@
+# I2S controller demo
+
+The Inter-IC Sound interface (I2S) controller mode (aka master mode) demo. This demo generates Morse code audio signals from text received over UART and plays them back over I2S. Tested with nRF52840-DK and a UDA1334a DAC. 
+
+## How to run 
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/i2s-peripheral-demo/README.md b/examples/i2s-peripheral-demo/README.md
@@ -0,0 +1,11 @@
+# I2S peripheral demo
+
+The Inter-IC Sound interface (I2S) peripheral mode (aka slave mode) demo. This demonstrates full duplex communication between a controller and peripheral mode I2S peripheral using the EasyDMA capabilities of the chip. This targets the nrf52840 family of devices.
+
+## How to run 
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/lpcomp-demo/README.md b/examples/lpcomp-demo/README.md
@@ -0,0 +1,11 @@
+# Lpcomp demo
+
+This low power voltage comparator (lpcomp) demo shows how you would keep the device in low power mode and power it up when an analog voltage on a pin changes with respect to a voltage on a reference pin. This targets the nrf52840 family of devices.
+
+## How to run 
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/ppi-demo/README.md b/examples/ppi-demo/README.md
@@ -1,4 +1,8 @@
-# Programmable peripheral interconnect demo
+# PPI demo
+
+The Programmable Peripheral Interconnect (PPI) allows peripherals to interact with each other without having to go through the CPU. Note that you need to choose a chip feature in order for this demo to build. See above. This demo uses the Bluetooth RADIO peripheral as an example but does nothing special with Bluetooth itself so this is not the demo to learn about that capability.
+
+## How to run 
 
 Choose the microcontroller with one of the following features:
 - 51
diff --git a/examples/pwm-demo/README.md b/examples/pwm-demo/README.md
@@ -0,0 +1,11 @@
+# PWM demo
+
+The pulse width modulation (PWM) demo allows the user to press buttons to change demo modes. This outputs PWM signals to the built in LEDs on the nRF52840-DK.
+
+## How to run 
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/qdec-demo/README.md b/examples/qdec-demo/README.md
@@ -0,0 +1,11 @@
+# QDEC demo
+
+The quadrature decoder (QDEC) is used to read sensor information. This peripheral supports buffered decoding of quadrature-encoded sensor signals (typically used for mechanical and optical sensors). The demo shows how to use a rotary encoder to trigger an interrupt and update a variable by the amount of rotation. (nRF52840 + Bourns PEC11R rotary encoder)
+
+## How to run 
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/rtic-demo/README.md b/examples/rtic-demo/README.md
@@ -0,0 +1,3 @@
+# RTIC demo
+
+The Real-Time Interrupt-driven Concurrency (RTIC) framework demo. Many of the demos in this project use RTIC and demonstrate its capabilities in more detail but this is a bare-bones default template for you to build off. RTIC is not unique to the nRF series but very useful for a program that requires concurrency. 
diff --git a/examples/spi-demo/README.md b/examples/spi-demo/README.md
@@ -1,11 +1,10 @@
-# spi-demo
-SPIM demonstation code.
-Connect a resistor between pin 22 and 23 on the demo board to feed MOSI directly back to MISO
-If all tests pass all four Led (Led1 to Led4) will light up, in case of error only at least one of the Led will remain turned off.
+# SPI master demo
 
+The Serial peripheral interface master (SPIM) with EasyDMA demo. Sends some text out on the SPI peripheral and loops it back on itself to demonstrate full duplex direct-memory-access based SPI data transfer. You'll need a resistor to connect the output to the input. Connect a resistor between pin 22 and 23 on the demo board to feed MOSI directly back to MISO. If all tests pass all four Led (Led1 to Led4) will light up, in case of error only at least one of the LEDs will remain turned off.
 
 ## HW connections
-Pin     Connecton
+
+Pin     Connection
 P0.24   SPIclk
 P0.23   MOSI
 P0.22   MISO
diff --git a/examples/spis-demo/README.md b/examples/spis-demo/README.md
@@ -0,0 +1,11 @@
+# SPI slave demo
+
+The Serial peripheral interface slave (SPIS) demo. This demonstrates the SPIS module, transmitting the current buffer contents while receiving new data. Press the button to zero the buffer.
+
+## How to run 
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/twi-ssd1306/README.md b/examples/twi-ssd1306/README.md
@@ -1,12 +1,14 @@
-# TWI-SSD1306 
+# TWI master with SSD1306 display demo
+
+The I2C compatible Two-Wire Interface Master (TWIM) communicating with an SSD1306 OLED Display demo. This demo uses the TWIM peripheral along with the embedded_graphics library to draw "Hello Rust!" to an SSD1306 OLED screen. Note that you need to set a chip feature to get this to compile.
 
 TWI write example using an SSD1306 OLED display:
 https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf
 
 After running it you should see the words "Hello Rust!" on the display.
 
 ## HW connections
-Pin     Connecton
+Pin     Connection
 P0.26   SCL
 P0.27   SDA
 
@@ -16,3 +18,11 @@ https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK
 
 The TWI device is a 128x64px SSD1306
 https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf
+
+## How to run 
+
+If using `probe-run`, see parent folder readme for setup and then just run
+
+```console
+$ cargo run
+```
diff --git a/examples/twim-demo/README.md b/examples/twim-demo/README.md
@@ -0,0 +1,11 @@
+# TWIM demo
+
+The I2C compatible Two-Wire Interface Master mode (TWIM) demo. This demo uses the TWIM peripheral to read and write 8 bytes of data to arbitrary addresses on a device that are connected to the I2C pins p0_30 and p0_31. It demonstrates error handling if the device does not respond properly (or it is not connected).
+
+## How to run 
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/twis-demo/README.md b/examples/twis-demo/README.md
@@ -0,0 +1,11 @@
+# TWIS demo
+
+I2C compatible Two-Wire Interface Slave mode (TWIS) demo. This demo uses the TWIS peripheral with RTIC (Real-Time Interrupt-driven Concurrency) to listen for I2C signals which are exposed as events. The event handler reads data from the peripheral at the address specified.
+
+## How to run 
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
diff --git a/examples/wdt-demo/README.md b/examples/wdt-demo/README.md
@@ -0,0 +1,15 @@
+# WDT demo
+
+This demo uses the watchdog timer (WDT) to show how the entire device can be set to automatically reset if certain conditions are not met within a certain period of time. In this case you have to press all 4 buttons at least once within a 5 second period to prevent a reset. 
+
+> Can you spot an opportunity to crash the program? 
+> 
+> If you mash the buttons as the time approaches zero you will encounter an 'attempt to subtract with overflow' panic at `main.rs:205` which is ultimately cleared by the watchdog timer. This demonstrates the ability to recover from a panic. Use `probe-run` to see the actual panic message.
+
+## How to run 
+
+If using `cargo-embed`, just run
+
+```console
+$ cargo embed --release --target=thumbv7em-none-eabihf
+```
