mirrors/embedded-trainings-2020
1
0
Fork 0
mirror of https://github.com/ferrous-systems/embedded-trainings-2020.git synced 2024-05-19 08:48:17 +00:00
Code Issues Projects Releases Wiki Activity

didactic changes

Browse source
This commit is contained in:
Mirabellensaft 2020-07-14 13:51:11 +02:00
parent d28f6a97f8
commit 6839418768
6 changed files with 63 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
embedded-workshop-book/src/dongle.md
View file

@ -1,8 +1,14 @@
# nRF52840 Dongle
Next, we'll look into the radio API exposed by the `dk` HAL. But before that we'll need to set up the nRF52840 Dongle.
From this section on, we'll use the nRF52840 Dongle in addition to the nRF52840 DK. We'll run some pre-compiled programs on the Dongle and write programs for the DK that will interact with the Dongle over a radio link.
Install the `dongle-flash` tool by running the following command from the `tools/dongle-flash` directory.
**💬 How to find the buttons on the Dongle:**
Put the Dongle in front of you, so that the side with the parts moundted on faces up. Rotate it, so that the narrower part of the board, the surface USB connector, faces away from you.
The Dongle has two buttons. They are next to each other in the lower left corner of the Dongle. The reset button (RESET) is mounted sideways, it's square shaped button faces you. Further away from you is the round-ish user button (SW1), which faces up.
✅ Install the `dongle-flash` tool by running the following command from the `tools/dongle-flash` directory.
``` console
$ cargo install --path . -f
@ -12,13 +18,15 @@ The Dongle does not contain an on-board debugger, like the DK, so we cannot use
When put in bootloader mode the Dongle will run a bootloader program instead of the last application that was flashed into it. This bootloader program will make the Dongle show up as a USB CDC ACM device (AKA Serial over USB device) that accepts new application images over this interface. We'll use the `nrfutil` tool to communicate with the bootloader-mode Dongle and flash new images into it.
To put the Dongle in bootloader mode connect it to your laptop / PC / mac and then press its *reset* button. The Dongle has two buttons: a round-ish user button (SW1) and a square-ish reset button (RESET); the latter is mounted "sideways". The buttons are next to each other. The RESET button is mounted closer to the edge of the board that has the Nordic logo on silkscreen and the actual button is facing towards that edge. The opposite edge of the board is narrower and has the surface USB connector; this is the end that goes into your PC USB port.
✅ Connect the Dongle to your computer. Put the Dongle in bootloader mode by pressing its *reset* button.
When the Dongle is in bootloader mode its red LED will oscillate in intensity. The Dongle will also appear as a USB CDC ACM device with vendor ID `0x1915` and product ID `0x521f`.
When the Dongle is in bootloader mode its red LED will oscillate in intensity. Alternatively, the status can be checked using the `usb-list` tool introduced below. The Dongle will also appear as a USB CDC ACM device with vendor ID `0x1915` and product ID `0x521f`.
In the `tools` folder you'll find `usb-list`: a minimal cross-platform version of the `lsusb` tool. Run it (`cargo run` from `tools/usb-list`) to list all USB devices; the Dongle will be highlighted in the output, along with a note if in bootloader mode.
You can also use the tool `usb-list`, a minimal cross-platform version of the `lsusb` tool, to check out the status of the Dongle.
✅ Run `cargo run` from `tools/usb-list` to list all USB devices; the Dongle will be highlighted in the output, along with a note if in bootloader mode.
Output should look like this:
``` console
$ cargo run
(..)
@ -29,8 +37,14 @@ Now that the device is in bootloader mode browse to the `boards/dongle` director
For the next section you'll need to flash the `loopback.hex` file into the Dongle. There are two ways to do this. You can make 2 long `nrfutil` invocations or you can use our `dongle-flash` tool, which will invoke `nrfutil` for you. The `dongle-flash` way is shown below:
✅ Run the following command:
``` console
$ dongle-flash loopback.hex
```
Expected output:
``` console
packaging iHex using nrfutil ...
DONE
[####################################] 100%
@ -39,20 +53,24 @@ Device programmed.
After the device has been programmed it will automatically reset and start running the new application.
The `loopback` application will *blink* the red LED in a heartbeat fashion: two fast blinks (LED on then off) followed by two periods of silence (LED off). The application will also make the Dongle enumerate itself as a CDC ACM device. If you run `usb-list` tool (from the `tools/usb-list` directory) you should see the newly enumerated Dongle in the output:
The `loopback` application will *blink* the red LED in a heartbeat fashion: two fast blinks (LED on then off) followed by two periods of silence (LED off). The application will also make the Dongle enumerate itself as a CDC ACM device.
✅ Run `usb-list` tool from the `tools/usb-list` directory to see the newly enumerated Dongle in the output:
``` console
$ cargo run
Bus 001 Device 020: ID 2020:0309 <- nRF52840 Dongle (loopback.hex)
```
The `loopback` app will log messages over the USB interface. To display these messages on the host we have provided a cross-platform tool: `serial-term`. Install it by running the following command from the `tools/serial-term` directory.
The `loopback` app will log messages over the USB interface. To display these messages on the host we have provided a cross-platform tool: `serial-term`.
✅ Install it by running the following command from the `tools/serial-term` directory.
``` console
$ cargo install --path . -f
```
If you run the `serial-term` application you should see the following output:
✅ Run the `serial-term` application. You should see the following output:
``` console
$ serial-term

6
embedded-workshop-book/src/panicking.md
View file

@ -1,6 +1,6 @@
# Panicking
Open the `src/bin/panic.rs` file and click the "Run" button.
✅ Open the `src/bin/panic.rs` file and click the "Run" button.
This program attempts to index an array beyond its length and this results in a panic.
@ -18,7 +18,9 @@ stack backtrace:
8: 0x0000199e - Reset
```
In `no_std` programs the behavior of panic is defined using the `#[panic_handler]` attribute. In the example, the *panic handler* is defined in the `panic_log` crate but we can also implement it manually: comment out the `panic_log` import and add the following function to the example:
In `no_std` programs the behavior of panic is defined using the `#[panic_handler]` attribute. In the example, the *panic handler* is defined in the `panic_log` crate but we can also implement it manually:
✅ Comment out the `panic_log` import and add the following function to the example:
``` rust
#[panic_handler]

14
embedded-workshop-book/src/running-from-vsc.md
View file

@ -2,17 +2,23 @@
Both `cargo-embed` and `cargo-flash` are tools based on the `probe-rs` library. This library exposes an API to communicate with the J-Link and perform all the operations exposed by the JTAG protocol. For this workshop we have developed a small Cargo runner that uses the `probe-rs` library to streamline the process of running a program and printing logs, like `cargo-embed`, while also having better integration into VS code.
1. Run this command from the `tools/dk-run` folder:
✅ Install the Cargo runner.
1. Run the following command from the `tools/dk-run` folder:
``` console
$ cargo install --path . -f
```
2. Open the `src/bin/hello.rs` file and click the "Run" button that's hovering over the `main` function.
2. Open the `src/bin/hello.rs` file in VS Code and click the "Run" button that's hovering over the `main` function.
Note: you will get the "Run" button if the Rust analyzer's workspace is set to the `beginner/apps` folder. This will be the case if the current folder in VS code (left side panel) is set to `beginner/apps`.
> Note: you will get the "Run" button if the Rust analyzer's workspace is set to the `beginner/apps` folder. This will be the case if the current folder in VS code (left side panel) is set to `beginner/apps`.
If you are not using VS code, run the command `cargo run --bin hello` from within the `beginer/apps` folder. Rust Analyzer's "Run" button is a short-cut for that command.
If you are not using VS code, you can run the program out of your console.
Enter the command `cargo run --bin hello` from within the `beginer/apps` folder. Rust Analyzer's "Run" button is a short-cut for that command.
Expected output:
``` console
$ cargo run --bin hello

4
embedded-workshop-book/src/time.md
View file

@ -2,7 +2,7 @@
Next we'll look into the time related APIs exposed by the `dk` HAL.
Open the `src/bin/blinky.rs` file.
✅ Open the `src/bin/blinky.rs` file.
This program will blink (turn on and off) one of the LEDs on the board. The time interval between each toggle operation is one second. This wait time between consecutive operations is generated by the blocking `timer.wait` operation. This function call will block the program execution for the specified [`Duration`] argument.
@ -10,6 +10,4 @@ This program will blink (turn on and off) one of the LEDs on the board. The time
The other time related API exposed by the `dk` HAL is the `dk::uptime` function. This function returns the time that has elapsed since the call to the `dk::init` function. This function is used in the program to log the time of each LED toggle operation.
Next, we'll look into the radio API exposed by the `dk` HAL. But before that we'll need to set up the nRF52840 Dongle.
[❗️assignment to chnge something]

17
embedded-workshop-book/src/using-hal.md
View file

@ -1,23 +1,24 @@
# Using a Hardware Abstraction Layer
[❗️Idea: explain HAL, run program, open doc with an assignment to change led pattern]
In this section we'll start using the hardware features of the nRF52840 and the board.
Open the `src/bin/led.rs` file.
The `dk` crate / library is a Hardware Abstraction Layer (HAL) over the nRF52840 Development Kit. The purpose of a HAL is to abstract away the device-specific details of the hardware, for example registers, and instead expose a higher level API more suitable for application development.
The `dk::init` function we have been calling in all programs initializes a few of the nRF52840 peripherals and returns a `Board` structure that provides access to those peripherals. We'll first look at the `Leds` API. Open the documentation for the `dk` crate running the following command from the `beginner/apps` folder:
The `dk::init` function we have been calling in all programs initializes a few of the nRF52840 peripherals and returns a `Board` structure that provides access to those peripherals. We'll first look at the `Leds` API.
✅ Run the `led` program. Two of the green LEDs on the board should turn on; the other two should stay off.
> NOTE this program will not terminate itself. Within VS code you need to click "Kill terminal" (garbage bin icon) in the bottom panel to terminate it.
✅ Open the documentation for the `dk` crate by running the following command from the `beginner/apps` folder:
``` console
$ cargo doc -p dk --open
```
Check the API docs of the `Led` abstraction then run the `led` program. Two of the green LEDs on the board should turn on; the other two should stay off.
✅ Check the API docs of the `Led` abstraction then run the `led` program. Change the `led` program, so that the bottom two leds are turned on, and the top two are turned off.
> NOTE this program will not terminate itself. Within VS code you need to click "Kill terminal" (garbage bin icon) in the bottom panel to terminate it.
Now, uncomment the `log::set_max_level` line. This will make the logs more verbose; they will now include logs from the board initialization function (`dk::init`) and from the `Led` API.
✅ Uncomment the `log::set_max_level` line. This will make the logs more verbose; they will now include logs from the board initialization function (`dk::init`) and from the `Led` API.
Among the logs you'll find the line "I/O pins have been configured for digital output". At this point the electrical pins of the nRF52840 microcontroller has been configured to drive the 4 LEDs on the board.

21
embedded-workshop-book/src/viewing-logs.md
View file

@ -1,14 +1,8 @@
# Viewing Logs
# Viewing Logs with `cargo-embed`
To observe the program logs you can use the `cargo-embed` tool.
``` console
$ cargo embed --bin hello
```
This command will bring up a Text User Interface (TUI). You should see "Hello, world!" in the output. You can close the interface using Ctrl-C.
`cargo-embed` has no `--chip` flag; instead the target chip needs to be specified in a file named `Embed.toml`. This file must be placed in the root of the Cargo project / workspace, next to the `Cargo.toml` file.
Unlike `cargo flash`, `cargo-embed` has no `--chip` flag; instead the target chip needs to be specified in a file named `Embed.toml`. This file must be placed in the root of the Cargo project / workspace, next to the `Cargo.toml` file.
``` toml
# Embed.toml
@ -16,4 +10,15 @@ This command will bring up a Text User Interface (TUI). You should see "Hello, w
chip = "nRF52840_xxAA"
```
✅ Use the following command to view your logs.
``` console
$ cargo embed --bin hello
```
This command will bring up a Text User Interface (TUI). You should see "Hello, world!" in the output. You can close the interface using Ctrl-C.
**🔎 How does logging work?**
Logging is implemented using the Real Time Transfer (RTT) protocol. Under this protocol the target device writes log messages to a ring buffer stored in RAM; the PC communicates with the J-Link to read out log messages from this ring buffer. This logging approach is non-blocking in the sense that the target device does not have to wait for physical IO (USB comm, serial interface, etc.) to complete while logging messages since they are written to memory. It is possible, however, for the target device to run out of space in its logging ring buffer; this causes old log messages to be overwritten.