mirrors/embedded-trainings-2020
1
0
Fork 0
mirror of https://github.com/ferrous-systems/embedded-trainings-2020.git synced 2024-10-31 22:28:49 +00:00
Code Issues Projects Releases Wiki Activity

then remove the now redundant install instructions

Browse source
This commit is contained in:
Jorge Aparicio 2020-07-14 17:04:20 +02:00
parent 236c85956b
commit 845b2d4835
4 changed files with 13 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -8,12 +8,6 @@ From this section on, we'll use the nRF52840 Dongle in addition to the nRF52840
Put the Dongle in front of you, so that the side with the parts mounted on faces up. Rotate it, so that the narrower part of the board, the surface USB connector, faces away from you. Put the Dongle in front of you, so that the side with the parts mounted 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. 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
```
The Dongle does not contain an on-board debugger, like the DK, so we cannot use `probe-rs` tools to write programs into it. Instead, the Dongle's stock firmware comes with a *bootloader*. The Dongle does not contain an on-board debugger, like the DK, so we cannot use `probe-rs` tools to write programs into it. Instead, the Dongle's stock firmware comes with a *bootloader*.
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. 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.
@ -22,9 +16,9 @@ When put in bootloader mode the Dongle will run a bootloader program instead of
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. The Dongle will also appear as a USB CDC ACM device with vendor ID `0x1915` and product ID `0x521f`.
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. You can also use our `usb-list` tool, 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. ✅ Run the `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: Output should look like this:
``` console ``` console
@ -55,20 +49,17 @@ After the device has been programmed it will automatically reset and start runni
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. 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: ✅ Run the `usb-list` tool to see the newly enumerated Dongle in the output:
``` console ``` console
$ cargo run $ usb-list
(..)
Bus 001 Device 020: ID 2020:0309 <- nRF52840 Dongle (loopback.hex) 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`. 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. ❗ Do not use serial terminal emulators like `minicom` or `screen`. They use the USB TTY ACM interface in a slightly different manner and may result in data loss.
``` console
$ cargo install --path . -f
```
✅ Run the `serial-term` application. You should see the following output: ✅ Run the `serial-term` application. You should see the following output:

6
embedded-workshop-book/src/hello-world.md
View file

@ -1,8 +1,6 @@
# Hello, world! # Hello, world!
In this section, we'll set up the integration in VS Code and run the first program. In this section, we'll set up the integration in VS Code and run the first program.
✅ Open the `tools/dk-run` folder and run `cargo install --path . -f` to install the `dk-run` tool.
✅ Open the `advanced/firmware` folder in VS Code and open the `src/bin/hello.rs` file from the `advanced/apps` folder. ✅ Open the `advanced/firmware` folder in VS Code and open the `src/bin/hello.rs` file from the `advanced/apps` folder.
@ -21,4 +19,4 @@ The `firmware` workspace has been configured to cross-compile applications to th
The `dk-run` process will terminate when the microcontroller enters the "halted" state. From the embedded application, one can enter the "halted" state using the `asm::bkpt` function. For convenience, an `exit` function is provided in the `dk` Hardware Abstraction Layer (HAL). This function is divergent like `std::process::exit` (`fn() -> !`) and can be used to halt the device and terminate the `dk-run` process. The `dk-run` process will terminate when the microcontroller enters the "halted" state. From the embedded application, one can enter the "halted" state using the `asm::bkpt` function. For convenience, an `exit` function is provided in the `dk` Hardware Abstraction Layer (HAL). This function is divergent like `std::process::exit` (`fn() -> !`) and can be used to halt the device and terminate the `dk-run` process.
Note that when the `dk-run` tool sees the device enter the halted state it will proceed to *reset-halt* the device. This is particularly important when writing USB applications because simply leaving the device in a halted state will make it appear as an unresponsive USB device to the host. Some OSes (e.g. Linux) will try to make an unresponsive device respond by power cycling the entire USB bus -- this will cause all other USB devices on the bus to be re-enumerated. Reset-halting the device will cause it to be electrically disconnected from the host USB bus and avoid the "power cycle the whole USB bus" scenario. Note that when the `dk-run` tool sees the device enter the halted state it will proceed to *reset-halt* the device. This is particularly important when writing USB applications because simply leaving the device in a halted state will make it appear as an unresponsive USB device to the host. Some OSes (e.g. Linux) will try to make an unresponsive device respond by power cycling the entire USB bus -- this will cause all other USB devices on the bus to be re-enumerated. Reset-halting the device will cause it to be electrically disconnected from the host USB bus and avoid the "power cycle the whole USB bus" scenario.

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

@ -2,22 +2,13 @@
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. 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.
✅ Install the Cargo runner. ✅ Open the `src/bin/hello.rs` file and click the "Run" button that's hovering over the `main` function.
1. Run the following command from the `tools/dk-run` folder:
``` console
$ cargo install --path . -f
```
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, you can run the program out of your console. 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. 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: Expected output:
``` console ``` console

4
embedded-workshop-book/src/tooling-check.md
View file

@ -2,7 +2,7 @@
## Setup check ## Setup check
✅ First, let's check that you have installed all the required tools. ✅ First, let's check that you have installed all the tools listed in the previous section.
❗ The first two commands *must* return version `0.8.x` ❗ The first two commands *must* return version `0.8.x`
@ -20,6 +20,8 @@ $ nrfutil version
nrfutil version 6.1.0 nrfutil version 6.1.0
``` ```
Note: The first two commands *must* return version `0.8.x`
## More tools ## More tools
✅ Now let's install some tools shipped with the workshop material. ✅ Now let's install some tools shipped with the workshop material.