From d28f6a97f885428f080d007f34358a96d91ab01c Mon Sep 17 00:00:00 2001 From: Mirabellensaft Date: Tue, 14 Jul 2020 13:50:19 +0200 Subject: [PATCH] turned intro into preparations chapter --- embedded-workshop-book/src/SUMMARY.md | 5 +- embedded-workshop-book/src/hardware.md | 117 +++++++++++-- embedded-workshop-book/src/installation.md | 194 +++++++++++++++++++++ embedded-workshop-book/src/intro.md | 12 -- embedded-workshop-book/src/preparations.md | 31 ++++ 5 files changed, 333 insertions(+), 26 deletions(-) create mode 100644 embedded-workshop-book/src/installation.md delete mode 100644 embedded-workshop-book/src/intro.md create mode 100644 embedded-workshop-book/src/preparations.md diff --git a/embedded-workshop-book/src/SUMMARY.md b/embedded-workshop-book/src/SUMMARY.md index be45db6..cd8f9c3 100644 --- a/embedded-workshop-book/src/SUMMARY.md +++ b/embedded-workshop-book/src/SUMMARY.md @@ -1,7 +1,8 @@ # Summary -- [Intro](./intro.md) -- [Hardware](./hardware.md) +- [Preparations](./preparations.md) + - [Checking the Hardware](./hardware.md) + - [Installation Instructions](./installation.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/hardware.md b/embedded-workshop-book/src/hardware.md index 0e99036..b90859c 100644 --- a/embedded-workshop-book/src/hardware.md +++ b/embedded-workshop-book/src/hardware.md @@ -1,19 +1,112 @@ -# Hardware +# Checking the Hardware -In this workshop we'll 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 Dongle -For the span of this workshop 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. +Connect the Dongle to your PC/laptop. Its red LED should start oscillating in intensity. The device will also show up as: -[❗️link or crosspost J2 instructions, for less clicking] +**Windows**: a USB Serial Device (COM port) in the Device Manager under the Ports section -## The nRF52840 +**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`: -Some details about the nRF52840 microcontroller that are relevant to this workshop. +``` console +$ lsusb +(..) +Bus 001 Device 023: ID 1915:521f Nordic Semiconductor ASA 4-Port USB 2.0 Hub +``` -- single core ARM Cortex-M4 processor clocked at 64 MHz -- 1 MB of Flash (at address `0x0000_0000`) -- 256 KB of RAM (at address `0x2000_0000`) -- IEEE 802.15.4 and BLE (Bluetooth Low Energy) compatible radio -- USB controller (device function) +The device will also show up in the `/dev` directory as a `ttyACM` device: -[❗️Info about Dongle] \ No newline at end of file +``` console +$ 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`: + +``` console +$ ioreg -p IOUSB -b -n "Open DFU Bootloader" +(...) +| +-o Open DFU Bootloader@14300000 `: + +``` console +$ ls /dev/tty.usbmodem* +/dev/tty.usbmodemCA1781C8A1EE1 +``` + +## nRF52840 Development Kit (DK) + +Connect one end of a 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 concave 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. + + + + + +After connecting the DK to your PC/laptop it will show up as: + +**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 `0x1015` -- the `0x` prefix will be omitted in the output of `lsusb`: + +``` console +$ lsusb +(..) +Bus 001 Device 014: ID 1366:1015 SEGGER 4-Port USB 2.0 Hub +``` + +The device will also show up in the `/dev` directory as a `ttyACM` device: + +``` console +$ 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"`. + +``` console +$ ioreg -p IOUSB -b -n "J-Link" +(...) + | +-o J-Link@14300000 `: + +``` console +$ ls /dev/tty.usbmodem* +/dev/tty.usbmodem0006834208031 +``` + +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 on-board switches: + +- Switch SW8, located on the bottom edge left corner, is set to the ON position; this is the left position of the two possible positions. +- Switch SW9, located on the surface of the board, to the right of USB connector (J2), is set to the VDD position; this is the center position of the three possible positions. \ No newline at end of file diff --git a/embedded-workshop-book/src/installation.md b/embedded-workshop-book/src/installation.md new file mode 100644 index 0000000..54939e8 --- /dev/null +++ b/embedded-workshop-book/src/installation.md @@ -0,0 +1,194 @@ +# Installation Instructions + +## Base Rust installation + +Go to https://rustup.rs and follow the instructions. + +**Windows**: *Do* install the optional components of the C++ build tools package. The installation size may take up to 2 GB of disk space. + +## VS Code + +**Windows**: Go to https://code.visualstudio.com and run the installer + +**Linux**: Check your Linux distribution package manager (example below). If it's not there follow the instructions on https://code.visualstudio.com/docs/setup/linux + +``` console +$ # Arch Linux +$ sudo pacman -S code +``` + +**macOS**: Go to https://code.visualstudio.com and click on "Download for Mac" + +## Rust Analyzer + +**All**: Open VS Code and look for 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 + +## Rust Cross compilation support + +**All**: Run this command in a terminal: + +``` console +$ rustup +stable target add thumbv7em-none-eabi +``` + +## ELF analysis tools + +**All**: Run these commands in a terminal: + +``` console +$ rustup +stable component add llvm-tools-preview + +$ cargo install cargo-binutils +``` + +## Python + +**Windows**: Go to https://www.python.org/downloads/ and run the Python *3* installer + +- in the installer check the "add Python 3.x to PATH" box +- also run the "Disable path length limit" action at the end, if you are on Windows 10 and the option is displayed to you + +**Linux**: Install `pip` using the package manager; this will also install Python. + +``` console +$ # Arch Linux +$ sudo pacman -S python-pip +``` + +**macOS**: +Ensure that you have python 3 and pip installed. Refer to the following link for [Instructions on how to install python 3 and pip](https://docs.python-guide.org/starting/install3/osx/) + +```console +$ python --version +Python 3.7.7 +$ pip --version +pip 20.0.2 from /usr/local/lib/python3.7/site-packages/pip (python 3.7) +``` + +## nrfutil + +**All**: Open a terminal and install nrfutil as follows. *If you are familiar with python, it is advised to do this in a [virtual environment](https://docs.python.org/3/library/venv.html).* + +``` console +$ pip install nrfutil +(..) + +$ nrfutil version +nrfutil version 6.1.0 +``` + +## USB (Linux only) + +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: + +1. (Optional) 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 +$ # ^ ^^ + +$ # 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. + +2. Create the following file with the displayed contents. You'll need root permissions to create the file. + +``` console +$ cat /etc/udev/rules.d/50-oxidize-global.rules +# udev rules to allow access to USB devices as a non-root user + +# nRF52840 Dongle in bootloader mode +ATTRS{idVendor}=="1915", ATTRS{idProduct}=="521f", TAG+="uaccess" + +# nRF52840 Dongle applications +ATTRS{idVendor}=="2020", TAG+="uaccess" + +# nRF52840 Development Kit +ATTRS{idVendor}=="1366", ATTRS{idProduct}=="1015", TAG+="uaccess" +``` + +3. Run the following command to make the new udev rules effective + +``` console +$ sudo udevadm control --reload-rules +``` + +4. (Optional) Disconnect and reconnect the dongle. Then check its permissions again. + +``` 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 +``` + +The `+` part in `crw-rw-r--+` indicates the device can be accessed without `root` permissions. + +## JLink driver (Windows only) + +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. + +[Zadig]: https://zadig.akeo.ie/ + +In Zadig's graphical user interface, + +1. Select the 'List all devices' option from the Options menu at the top. + +2. From the device (top) drop down menu select "BULK interface (Interface 2)" + +3. Once that device is selected, `1366 1015` should be displayed in the USB ID field. That's the Vendor ID - Product ID pair. + +4. Select 'WinUSB' as the target driver (right side) + +5. Click "Install WinUSB driver". The process may take a few minutes to complete. + +## `nrf-recover` + +Some nRF52840 devices, specially older revisions, may have parts of their Flash memory locked. To unlock the memory use the `nrf-recover` tool. + +This is only relevant to the nRF52840 Development Kit. First connect the nRF52840 DK to your PC using micro-USB J2 (as done before) then run the following commands: + +``` console +$ cargo install nrf-recover + +$ nrf-recover -y +Starting mass erase... +Mass erase completed, chip unlocked +``` + +## Cargo subcommands + +Install version v0.8.0 of the `cargo-flash` and `cargo-embed` subcommands, as well as the `cargo-binutils` set of subcommands and the `cargo-bloat` subcommand using the following Cargo commands: + +``` console +$ cargo install cargo-flash --version 0.8.0 -f +(..) +Installed package `cargo-flash v0.8.0` (..) + +$ cargo install cargo-embed --version 0.8.0 -f +(..) +Installed package `cargo-embed v0.8.0` (..) + +$ cargo install cargo-binutils +(..) +Installed package `cargo-binutils v0.3.0` (..) + +$ cargo install cargo-bloat +(..) +Installed package `cargo-bloat v0.9.3` (..) +``` \ No newline at end of file diff --git a/embedded-workshop-book/src/intro.md b/embedded-workshop-book/src/intro.md deleted file mode 100644 index e65c5f5..0000000 --- a/embedded-workshop-book/src/intro.md +++ /dev/null @@ -1,12 +0,0 @@ -# Intro - -## Icons used - -### in development -❗️ To do - - -### in Production - - -## About the Course \ No newline at end of file diff --git a/embedded-workshop-book/src/preparations.md b/embedded-workshop-book/src/preparations.md new file mode 100644 index 0000000..ef998aa --- /dev/null +++ b/embedded-workshop-book/src/preparations.md @@ -0,0 +1,31 @@ +# Preparations + +This chapter contains informations about the course material, the required hardware and an installation guide. + + +## Required Hardware + +- [nRF52840 Development Kit (DK)](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) +- [nRF52840 Dongle](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-Dongle) +- 2 micro-USB cables +- 2 available USB-A ports on your laptop / PC (you can use a USB hub if you don't have enough ports) + +In this workshop we'll 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 this workshop 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. + + +## Required Software +Please install the required software before the course starts. + +## Course Material +This book contains the material for the beginner and the advanced workshop in embedded Rust. It aims to be as inclusive as possible. This means, that some information is available in several forms, for example pictures and text description. We also use icons so that different kinds of information are visually distiguishable on the first glance. If you have accessibility needs that are not covered, please let us know. + +# Icons and Formatting we use +We use Icons to mark different kinds of information in the book: +* ✅ Call for action +* ❗️ Warnings, Details that require special attention +* 🔎 Knowledge, that gets you deeper into the subject, but you do not have to understand it completely to proceed. +* 💬 Descriptions for Accessibility + +> Note: Notes like this one contain helpful information \ No newline at end of file