From 236c85956b5875a7336d60fb042fcdd886fab9fa Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Tue, 14 Jul 2020 17:02:25 +0200 Subject: [PATCH 1/5] start off with tool check --- embedded-workshop-book/src/SUMMARY.md | 1 + embedded-workshop-book/src/tooling-check.md | 46 +++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 embedded-workshop-book/src/tooling-check.md diff --git a/embedded-workshop-book/src/SUMMARY.md b/embedded-workshop-book/src/SUMMARY.md index f500aba..31911bc 100644 --- a/embedded-workshop-book/src/SUMMARY.md +++ b/embedded-workshop-book/src/SUMMARY.md @@ -3,6 +3,7 @@ - [Preparations](./preparations.md) - [Checking the Hardware](./hardware.md) - [Installation Instructions](./installation.md) +- [Tooling check](./tooling-check.md) - [Beginner Workbook](./beginner-workbook.md) - [Parts of an Embedded Program](./parts-embedded-program.md) - [Building an Embedded Program](./building-program.md) diff --git a/embedded-workshop-book/src/tooling-check.md b/embedded-workshop-book/src/tooling-check.md new file mode 100644 index 0000000..7ab2521 --- /dev/null +++ b/embedded-workshop-book/src/tooling-check.md @@ -0,0 +1,46 @@ +# Tooling check + +## Setup check + +✅ First, let's check that you have installed all the required tools. + +❗ The first two commands *must* return version `0.8.x` + +``` console +$ cargo flash --version +0.8.0 + +$ cargo embed --version +0.8.0 + +$ cargo size --version +cargo-size 0.3.0 + +$ nrfutil version +nrfutil version 6.1.0 +``` + +## More tools + +✅ Now let's install some tools shipped with the workshop material. + +### Beginner workshop + +From the `tools` folder run these commands *from different terminals so they'll run in parallel*: + +- `cargo install --path dk-run` +- `cargo install --path usb-list` +- `cargo install --path dongle-flash` +- `cargo install --path serial-term` +- `cargo install --path change-channel` + +Leave the processes running in the background. + +### Advanced workshop + +From the `tools` folder run these commands *from different terminals so they'll run in parallel*: + +- `cargo install --path dk-run` +- `cargo install --path usb-list` + +Leave the processes running in the background. From 845b2d4835e0b620a299a61473044ad2d9cbde26 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Tue, 14 Jul 2020 17:04:20 +0200 Subject: [PATCH 2/5] then remove the now redundant install instructions --- embedded-workshop-book/src/dongle.md | 21 ++++++------------- embedded-workshop-book/src/hello-world.md | 6 ++---- .../src/running-from-vsc.md | 13 ++---------- embedded-workshop-book/src/tooling-check.md | 4 +++- 4 files changed, 13 insertions(+), 31 deletions(-) diff --git a/embedded-workshop-book/src/dongle.md b/embedded-workshop-book/src/dongle.md index 7fb5df1..b97d826 100644 --- a/embedded-workshop-book/src/dongle.md +++ b/embedded-workshop-book/src/dongle.md @@ -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. 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*. 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`. -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: ``` 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. -✅ 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 -$ cargo run +$ usb-list +(..) 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. - -``` console -$ cargo install --path . -f -``` +❗ 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. ✅ Run the `serial-term` application. You should see the following output: diff --git a/embedded-workshop-book/src/hello-world.md b/embedded-workshop-book/src/hello-world.md index 1b2dd65..8fc3dc1 100644 --- a/embedded-workshop-book/src/hello-world.md +++ b/embedded-workshop-book/src/hello-world.md @@ -1,8 +1,6 @@ # Hello, world! -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. +In this section, we'll set up the integration in VS Code and run the first program. ✅ 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. -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. \ No newline at end of file +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. diff --git a/embedded-workshop-book/src/running-from-vsc.md b/embedded-workshop-book/src/running-from-vsc.md index ab53593..58d0151 100644 --- a/embedded-workshop-book/src/running-from-vsc.md +++ b/embedded-workshop-book/src/running-from-vsc.md @@ -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. -✅ 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 in VS Code and click the "Run" button that's hovering over the `main` function. +✅ Open the `src/bin/hello.rs` file 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`. -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. - Expected output: ``` console diff --git a/embedded-workshop-book/src/tooling-check.md b/embedded-workshop-book/src/tooling-check.md index 7ab2521..ce589bf 100644 --- a/embedded-workshop-book/src/tooling-check.md +++ b/embedded-workshop-book/src/tooling-check.md @@ -2,7 +2,7 @@ ## 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` @@ -20,6 +20,8 @@ $ nrfutil version nrfutil version 6.1.0 ``` +Note: The first two commands *must* return version `0.8.x` + ## More tools ✅ Now let's install some tools shipped with the workshop material. From db0b11902aa45f6040091bb67cc7728c5ff610e1 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Wed, 15 Jul 2020 12:27:02 +0200 Subject: [PATCH 3/5] replace some cargo-runs --- embedded-workshop-book/src/dongle.md | 4 ++-- embedded-workshop-book/src/listing-usb-devices.md | 15 ++++++++------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/embedded-workshop-book/src/dongle.md b/embedded-workshop-book/src/dongle.md index b97d826..1692f6b 100644 --- a/embedded-workshop-book/src/dongle.md +++ b/embedded-workshop-book/src/dongle.md @@ -18,11 +18,11 @@ When the Dongle is in bootloader mode its red LED will oscillate in intensity. T 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 the `usb-list` to list all USB devices; the Dongle will be highlighted in the output, along with a note if in bootloader mode. +✅ Run `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 +$ usb-list (..) Bus 001 Device 016: ID 1915:521f <- nRF52840 Dongle (in bootloader mode) ``` diff --git a/embedded-workshop-book/src/listing-usb-devices.md b/embedded-workshop-book/src/listing-usb-devices.md index d5241aa..49843ad 100644 --- a/embedded-workshop-book/src/listing-usb-devices.md +++ b/embedded-workshop-book/src/listing-usb-devices.md @@ -1,26 +1,27 @@ # Listing USB Devices -In the `tools` folder you'll find `usb-list`: a minimal cross-platform version of the `lsusb` tool. - -✅ To list all USB devices, run the progam using `cargo run` from `tools/usb-list`. +In the `tools` folder you'll find `usb-list`: a minimal cross-platform version of the `lsusb` tool. +✅ To list all USB devices, run `usb-list`. ``` console -$ cargo run +$ usb-list Bus 002 Device 001: ID 1d6b:0003 Bus 001 Device 002: ID 0cf3:e300 Bus 001 Device 003: ID 0c45:6713 Bus 001 Device 001: ID 1d6b:0002 +Bus 001 Device 010: ID 1366:1015 <- J-Link on the nRF52840 Development Kit ``` -The goal of this exercise is to get the nRF52840 SoC to show in this list. The embedded application will use the vendor ID (VID) and product ID (PID) defined in `advanced/common/consts`; the `usb-list` tool will highlight the USB device that matches that VID PID pair. +The goal of this workshop is to get the nRF52840 SoC to show in this list. The embedded application will use the vendor ID (VID) and product ID (PID) defined in `advanced/common/consts`; the `usb-list` tool will highlight the USB device that matches that VID PID pair. ``` console $ # expected output -$ cargo run +$ usb-list Bus 002 Device 001: ID 1d6b:0003 Bus 001 Device 002: ID 0cf3:e300 Bus 001 Device 003: ID 0c45:6713 Bus 001 Device 001: ID 1d6b:0002 +Bus 001 Device 010: ID 1366:1015 <- J-Link on the nRF52840 Development Kit Bus 001 Device 059: ID 2020:0717 <- nRF52840 on the nRF52840 Development Kit -``` \ No newline at end of file +``` From d5b561ab0f96d2ceddb6a938c8c994713190b8c4 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Wed, 15 Jul 2020 15:47:41 +0200 Subject: [PATCH 4/5] remove duplicated text --- embedded-workshop-book/src/tooling-check.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/embedded-workshop-book/src/tooling-check.md b/embedded-workshop-book/src/tooling-check.md index ce589bf..c891d29 100644 --- a/embedded-workshop-book/src/tooling-check.md +++ b/embedded-workshop-book/src/tooling-check.md @@ -20,8 +20,6 @@ $ nrfutil version nrfutil version 6.1.0 ``` -Note: The first two commands *must* return version `0.8.x` - ## More tools ✅ Now let's install some tools shipped with the workshop material. From d00e69f461861a411ed7765cc6f7de16b3884bd0 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Wed, 15 Jul 2020 17:51:23 +0200 Subject: [PATCH 5/5] do not mention tools; instead link back --- embedded-workshop-book/src/listing-usb-devices.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/embedded-workshop-book/src/listing-usb-devices.md b/embedded-workshop-book/src/listing-usb-devices.md index 49843ad..e9c56c1 100644 --- a/embedded-workshop-book/src/listing-usb-devices.md +++ b/embedded-workshop-book/src/listing-usb-devices.md @@ -1,9 +1,11 @@ # Listing USB Devices -In the `tools` folder you'll find `usb-list`: a minimal cross-platform version of the `lsusb` tool. - ✅ To list all USB devices, run `usb-list`. +❗️ If you haven't yet installed `usb-list`; [installation instructions can be found in a previous section][install]. + +[install]: ./tooling-check.md#more-tools + ``` console $ usb-list Bus 002 Device 001: ID 1d6b:0003