diff --git a/exercise-book/src/nrf52-hardware.md b/exercise-book/src/nrf52-hardware.md index 05bc2066..4d6d2b9c 100644 --- a/exercise-book/src/nrf52-hardware.md +++ b/exercise-book/src/nrf52-hardware.md @@ -1,17 +1,35 @@ # nRF52 Hardware -## nRF52840 Dongle +In our nRF52-focussed exercises we will use both the nRF52840 Development Kit (DK) and the nRF52840 Dongle. We'll mainly develop programs for the DK and use the Dongle to assist with some exercises. + +## nRF52840 Development Kit (DK) + +Connect one end of one of the supplied micro USB cable to the USB connector *J2* of the board and the other end to your PC. + +💬 These directions assume you are holding the board "horizontally" with components (switches, buttons and pins) facing up. In this position, rotate the board, so that its convex shaped short side faces right. You'll find one USB connector (J2) on the left edge, another USB connector (J3) on the bottom edge and 4 buttons on the bottom right corner. + +![Labeled Diagram of the nRF52840 Development Kit (DK)](img/nrf52840_dk_board.jpg) + +The board has several switches to configure its behavior. The out of the box configuration is the one we want. If the above instructions didn't work for you, check the position of the following switches: -Connect the Dongle to your PC/laptop. Its red LED should start oscillating in intensity. The device will also show up as: +- SW6 is set to the DEFAULT position (to the right - nRF = DEFAULT). +- SW7 (protected by Kapton tape) is set to the Def. position (to the right - TRACE = Def.). +- SW8 is set to the ON (to the left) position (Power = ON) +- SW9 is set to the VDD position (center - nRF power source = VDD) +- SW10 (protected by Kapton tape) is set to the OFF position (to the left - VEXT -> nRF = OFF). + +### Windows -**Windows**: a USB Serial Device (COM port) in the Device Manager under the Ports section +When the nRF52-DK is connected to your PC it shows up as a removable USB Flash Drive (named JLINK) and also as a USB Serial Device (COM port) in the Device Manager under the Ports section. -**Linux**: a USB device under `lsusb`. The device will have a VID of `0x1915` and a PID of `0x521f` -- the `0x` prefix will be omitted in the output of `lsusb`: +### Linux + +When the nRF52-DK is connected to your PC it shows up as a USB device under `lsusb`. The device will have a VID of `1366` and a PID of `10xx` or `01xx`, where `x` can vary: ```console $ lsusb (..) -Bus 001 Device 023: ID 1915:521f Nordic Semiconductor ASA 4-Port USB 2.0 Hub +Bus 001 Device 014: ID 1366:1051 SEGGER 4-Port USB 2.0 Hub ``` The device will also show up in the `/dev` directory as a `ttyACM` device: @@ -21,52 +39,52 @@ $ ls /dev/ttyACM* /dev/ttyACM0 ``` -**macOS**: a usb device when executing `ioreg -p IOUSB -b -n "Open DFU Bootloader"`. The device will have a vendor ID (`"idVendor"`) of `6421` and a product ID (`"idProduct"`) of `21023`: +### macOS + +When the nRF52-DK is connected to your Mac it shows up as a removable USB flash drive (named JLINK) on the Desktop, and also a USB device named "J-Link" when executing `ioreg -p IOUSB -b -n "J-Link"`. ```console -$ ioreg -p IOUSB -b -n "Open DFU Bootloader" +$ ioreg -p IOUSB -b -n "J-Link" (...) -| +-o Open DFU Bootloader@14300000 `: +The device will also show up in the `/dev` directory as `tty.usbmodem`: ```console $ ls /dev/tty.usbmodem* -/dev/tty.usbmodemCA1781C8A1EE1 +/dev/tty.usbmodem0006834208031 ``` -## nRF52840 Development Kit (DK) +## nRF52840 Dongle -Connect one end of a micro USB cable to the USB connector *J2* of the board and the other end to your PC. +Connect the Dongle to your PC/laptop. Its red LED should start oscillating in intensity. -💬 These directions assume you are holding the board "horizontally" with components (switches, buttons and pins) facing up. In this position, rotate the board, so that its convex shaped short side faces right. You'll find one USB connector (J2) on the left edge, another USB connector (J3) on the bottom edge and 4 buttons on the bottom right corner. +### Windows -![Labeled Diagram of the nRF52840 Development Kit (DK)](img/nrf52840_dk_board.jpg) +The device shows up as a USB Serial Device (COM port) in the Device Manager under the Ports section -After connecting the DK to your PC/laptop it will show up as: +### Linux -**Windows**: a removable USB flash drive (named JLINK) and also as a USB Serial Device (COM port) in the Device Manager under the Ports section - -**Linux**: a USB device under `lsusb`. The device will have a VID of `0x1366` and a PID of `0x10??` or `0x01??` (`?` is a hex digit) -- the `0x` prefix will be omitted in the output of `lsusb`: +The dongle shows up as a USB device under `lsusb`. The device will have a VID of `0x1915` and a PID of `0x521f` -- the `0x` prefix will be omitted in the output of `lsusb`: ```console $ lsusb (..) -Bus 001 Device 014: ID 1366:1051 SEGGER 4-Port USB 2.0 Hub +Bus 001 Device 023: ID 1915:521f Nordic Semiconductor ASA 4-Port USB 2.0 Hub ``` The device will also show up in the `/dev` directory as a `ttyACM` device: @@ -76,22 +94,24 @@ $ ls /dev/ttyACM* /dev/ttyACM0 ``` -**macOS**: a removable USB flash drive (named JLINK) in Finder and also a USB device named "J-Link" when executing `ioreg -p IOUSB -b -n "J-Link"`. +### macOS + +The device shows up as a usb device when executing `ioreg -p IOUSB -b -n "Open DFU Bootloader"`. The device will have a vendor ID (`"idVendor"`) of `6421` and a product ID (`"idProduct"`) of `21023`: ```console -$ ioreg -p IOUSB -b -n "J-Link" +$ ioreg -p IOUSB -b -n "Open DFU Bootloader" (...) - | +-o J-Link@14300000 nRF = OFF). - -For reference, here's the board picture again: - -![Labeled Diagram of the nRF52840 Development Kit (DK)](img/nrf52840_dk_board.jpg) diff --git a/exercise-book/src/nrf52-preparation.md b/exercise-book/src/nrf52-preparation.md index 7979c74f..1454a565 100644 --- a/exercise-book/src/nrf52-preparation.md +++ b/exercise-book/src/nrf52-preparation.md @@ -8,11 +8,13 @@ This chapter contains information about the nRF52-based exercises, the required - [nRF52840 Dongle](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-Dongle) - 2 micro-USB cables - ❗️ make sure you're using micro usb cables which can transmit data (some are charging-only; these are not suitable for these exercises) -- 2 available USB-A ports on your laptop / PC (you can use a USB hub if you don't have enough ports) +- 2 corresponding available USB ports on your laptop / PC (you can use a USB hub if you don't have enough ports) In our nRF52-focussed exercises we will use both the nRF52840 Development Kit (DK) and the nRF52840 Dongle. We'll mainly develop programs for the DK and use the Dongle to assist with some exercises. -For the span of these exercises keep the nRF52840 DK connected to your PC using a micro-USB cable. Connect the USB cable to the J2 port on the nRF52840 DK. Instructions to identify the USB ports on the nRF52840 board can be found in the top level README file. +For the span of these exercises keep the nRF52840 DK connected to your PC using a micro-USB cable. Connect the USB cable to the J2 port on the nRF52840 DK. + +![Labeled Diagram of the nRF52840 Development Kit (DK)](img/nrf52840_dk_board.jpg) ## Starter code diff --git a/exercise-book/src/nrf52-tools.md b/exercise-book/src/nrf52-tools.md index 3aa86ec3..82f57a7a 100644 --- a/exercise-book/src/nrf52-tools.md +++ b/exercise-book/src/nrf52-tools.md @@ -1,43 +1,48 @@ # nRF52 Tools -## VS Code +Follow the entire section for the operating system that you're using, then go to [Setup check](#setup-check). -**Windows**: Go to [https://code.visualstudio.com](https://code.visualstudio.com) and run the installer. +## Linux -**Linux**: Follow the instructions for your distribution on [https://code.visualstudio.com/docs/setup/linux](https://code.visualstudio.com/docs/setup/linux). + -**macOS**: Go to [https://code.visualstudio.com](https://code.visualstudio.com) and click on "Download for Mac" +### Install VS Code -## OS specific dependencies +Follow the instructions for your distribution on [https://code.visualstudio.com/docs/setup/linux](https://code.visualstudio.com/docs/setup/linux). -### Linux only: USB +### Install dependencies -Some of our tools depend on `pkg-config` and `libudev.pc`. Ensure you have the proper packages installed; on Debian based distributions you can use: +Some of our tools depend on `pkg-config` and `libudev.pc`. + +Ensure you have the proper packages installed. +On Debian based distributions you can use: ```console sudo apt-get install libudev-dev libusb-1.0-0-dev ``` -To access the USB devices as a non-root user, follow these steps: +### Configure USB Device access for non-root users -1. (Optional) Connect the dongle and check its permissions with these commands: +Connect the dongle and check its permissions with these commands: - ```console - $ lsusb -d 1915:521f - Bus 001 Device 016: ID 1915:521f Nordic Semiconductor ASA USB Billboard - $ # ^ ^^ +```console +$ lsusb -d 1915:521f +Bus 001 Device 016: ID 1915:521f Nordic Semiconductor ASA USB Billboard +$ # ^ ^^ - $ # take note of the bus and device numbers that appear for you when run the next command - $ ls -l /dev/bus/usb/001/016 - crw-rw-r-- 1 root root 189, 15 May 20 12:00 /dev/bus/usb/001/016 - ``` +$ # take note of the bus and device numbers that appear for you when run the next command +$ ls -l /dev/bus/usb/001/016 +crw-rw-r-- 1 root root 189, 15 May 20 12:00 /dev/bus/usb/001/016 +``` - The `root root` part in `crw-rw-r-- 1 root root` indicates the device can only be accessed by the `root` user. +The `root root` part in `crw-rw-r-- 1 root root` indicates the device can only be accessed by the `root` user. -2. Create the following file with the displayed contents. You'll need root permissions to create the file. +To access the USB devices as a non-root user, follow these steps: + +1. As root, create `/etc/udev/rules.d/50-ferrous-training.rules` with the following contents: ```console - $ cat /etc/udev/rules.d/50-ferrous-training.rules # udev rules to allow access to USB devices as a non-root user # nRF52840 Dongle in bootloader mode @@ -50,29 +55,76 @@ To access the USB devices as a non-root user, follow these steps: ATTRS{idVendor}=="1366", ENV{ID_MM_DEVICE_IGNORE}="1", TAG+="uaccess" ``` -3. Run the following command to make the new udev rules effective +2. Run the following command to put the new udev rules into effect ```console sudo udevadm control --reload-rules ``` -4. (Optional) Disconnect and reconnect the dongle. Then check its permissions again. +To check the permissions again, first disconnect and reconnect the dongle. Then run `lsusb`. - ```console - $ lsusb - Bus 001 Device 017: ID 1915:521f Nordic Semiconductor ASA 4-Port USB 2.0 Hub +```console +$ lsusb +Bus 001 Device 017: ID 1915:521f Nordic Semiconductor ASA 4-Port USB 2.0 Hub - $ ls -l /dev/bus/usb/001/017 - crw-rw-r--+ 1 root root 189, 16 May 20 12:11 /dev/bus/usb/001/017 - ``` +$ ls -l /dev/bus/usb/001/017 +crw-rw-r--+ 1 root root 189, 16 May 20 12:11 /dev/bus/usb/001/017 +``` + +The `+` part in `crw-rw-r--+` indicates the device can be accessed without `root` permissions. If you have permission to access them dongle, then the nRF52-DK should also work because both were listed in the udev rules file. + +### Install base rust tooling + +Go to [https://rustup.rs](https://rustup.rs/) and follow the instructions. + +### Install rust analyzer + +Open VS Code, find [Rust Analyzer](https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer) in the marketplace (bottom icon in the left panel), then install it. + +### Configure Rust Cross compilation support + +Run this command in a terminal: + +```console +rustup +stable target add thumbv7em-none-eabihf +``` + +### Install ELF analysis tools + +Run these commands in a terminal: + +```console +cargo install cargo-binutils +rustup +stable component add llvm-tools +``` + +### Third-party tools written in Rust + +Install the [`flip-link`](https://crates.io/crates/flip-link), [`nrf-dfu`](https://crates.io/crates/nrfdfu) and [`cyme`](https://crates.io/crates/cyme) tools from source using the following Cargo commands: + +```console +cargo install flip-link +cargo install nrfdfu +cargo install cyme +``` + +Install `probe-rs` 0.24 pre-compiled binaries on Linux with: + +```bash +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/probe-rs/probe-rs/releases/download/v0.24.0/probe-rs-tools-installer.sh | sh +``` + +## Windows - The `+` part in `crw-rw-r--+` indicates the device can be accessed without `root` permissions. +### Install VS Code -### Windows only: Zadig JLink driver +Go to [https://code.visualstudio.com](https://code.visualstudio.com) and run the installer. + +### Associate the device with the WinUSB drivers On Windows you'll need to associate the nRF52840 Development Kit's USB device to the WinUSB driver. -To do that connect the nRF52840 DK to your PC using micro-USB port J2 (as done before) then download and run the [Zadig] tool. +To do that connect the nRF52840 DK to your PC using micro-USB port J2, then download and run the [Zadig] tool. [Zadig]: https://zadig.akeo.ie/ @@ -90,31 +142,30 @@ In Zadig's graphical user interface, > You do not need to do anything for the **nRF52840 Dongle** device. -## Rust and tooling - -### Base Rust installation +### Install base rust tooling Go to [https://rustup.rs](https://rustup.rs/) and follow the instructions. -**Windows**: Be sure to select the optional "Desktop development with C++" part of the [C++ build tools package](https://visualstudio.microsoft.com/visual-cpp-build-tools/). The installation size may take up to 5.7 GB of disk space. +You will need a C compiler to use Rust on Windows. The rustup installer will suggest you install either Visual Studio, or the Build Tools for Visual Studio - either is fine. When that is installing, be sure to select the optional "Desktop development with C++" part of the [C++ build tools package](https://visualstudio.microsoft.com/visual-cpp-build-tools/). The installation may take up to 5.7 GB of disk space. Please also be aware of the license conditions attached to these products, especially in an enterprise environment. + -### Rust Analyzer +### Install rust analyzer -**All**: Open VS Code and look for [Rust Analyzer](https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer) in the marketplace (bottom icon in the left panel). Then install it. +Open VS Code, find [Rust Analyzer](https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer) in the marketplace (bottom icon in the left panel), then install it. -**Windows**: It's OK to ignore the message about `git` not being installed, if you get one! +If you get a message about `git` not being installed, ignore it! -### Rust Cross compilation support +### Configure Rust Cross compilation support -**All**: Run this command in a terminal: +Run this command in a terminal: ```console rustup +stable target add thumbv7em-none-eabihf ``` -### ELF analysis tools +### Install ELF analysis tools -**All**: Run these commands in a terminal: +Run these commands in a terminal: ```console cargo install cargo-binutils @@ -131,18 +182,61 @@ cargo install nrfdfu cargo install cyme ``` -Install `probe-rs` 0.24 pre-compiled binaries on Linux or macOS with: +Install `probe-rs` 0.24 pre-compiled binaries on Windows with: ```bash -curl --proto '=https' --tlsv1.2 -LsSf https://github.com/probe-rs/probe-rs/releases/download/v0.24.0/probe-rs-tools-installer.sh | sh +powershell -c "irm https://github.com/probe-rs/probe-rs/releases/download/v0.24.0/probe-rs-tools-installer.ps1 | iex" ``` -Install `probe-rs` 0.24 pre-compiled binaries on Windows with: +## macOS + +### Install VS Code + +Go to [https://code.visualstudio.com](https://code.visualstudio.com) and click on "Download for Mac". + +### Install base rust tooling + +Go to [https://rustup.rs](https://rustup.rs/) and follow the instructions. + +### Install rust analyzer + +Open VS Code, find [Rust Analyzer](https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer) in the marketplace (bottom icon in the left panel), then install it. + +### Configure Rust Cross compilation support + +Run this command in a terminal: + +```console +rustup +stable target add thumbv7em-none-eabihf +``` + +### Install ELF analysis tools + +Run these commands in a terminal: + +```console +cargo install cargo-binutils +rustup +stable component add llvm-tools +``` + +### Third-party tools written in Rust + +Install the [`flip-link`](https://crates.io/crates/flip-link), [`nrf-dfu`](https://crates.io/crates/nrfdfu) and [`cyme`](https://crates.io/crates/cyme) tools from source using the following Cargo commands: + +```console +cargo install flip-link +cargo install nrfdfu +cargo install cyme +``` + +Install `probe-rs` 0.24 pre-compiled binaries on macOS with: ```bash -powershell -c "irm https://github.com/probe-rs/probe-rs/releases/download/v0.24.0/probe-rs-tools-installer.ps1 | iex" +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/probe-rs/probe-rs/releases/download/v0.24.0/probe-rs-tools-installer.sh | sh ``` +--- + ## Setup check ✅ Let's check that you have installed all the tools listed in the previous section. @@ -184,7 +278,7 @@ Bus 002 Device 015: ID 1366:1051 <- J-Link on the nRF52840 Development Kit Erasing ✔ [00:00:00] [################################################] 8.00 KiB/8.00 KiB @ 31.22 KiB/s (eta 0s ) Programming ✔ [00:00:00] [################################################] 8.00 KiB/8.00 KiB @ 36.25 KiB/s (eta 0s ) Finished in 0.496s Hello, world! -└─ hello::__cortex_m_rt_main @ src/bin/hello.rs:21 +└─ hello::__cortex_m_rt_main @ src/bin/hello.rs:21 `dk::exit()` called; exiting ... -└─ dk::exit @ /home/samuel/src/ferrous/rust-exercises/nrf52-code/boards/dk/src/lib.rs:415 +└─ dk::exit @ /home/samuel/src/ferrous/rust-exercises/nrf52-code/boards/dk/src/lib.rs:415 ```