mirror of
https://github.com/ferrous-systems/embedded-trainings-2020.git
synced 2024-05-06 18:49:10 +00:00
Merge pull request #160 from ferrous-systems/nrfdfu
start purging nrfutil from the training material
This commit is contained in:
Lotte Steenbrink
GitHub
commit
dc08868055
105
embedded-workshop-book/src/DEPRECATED-nrfutil-setup.md
Normal file
105
embedded-workshop-book/src/DEPRECATED-nrfutil-setup.md
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
## Python
|
||||
|
||||
**Windows**: Go to [https://www.python.org/downloads/](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
|
||||
$ # If you're using Arch Linux
|
||||
$ sudo pacman -S python-pip
|
||||
|
||||
$ # If you're using Ubuntu
|
||||
$ sudo apt-get install python3-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)
|
||||
```
|
||||
|
||||
## nrf tools
|
||||
|
||||
### nrfutil
|
||||
|
||||
**All**: Open a terminal and install [nrfutil](https://github.com/NordicSemiconductor/pc-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
|
||||
```
|
||||
|
||||
**NOTE** as of version 6.1.0 nrfutil indicates that it does "not" support Python 3.9 in its pip manifest. Due to this, the above `pip install` command will fail if you have a Python 3.9 interpreter installed. Here's how to work around the issue:
|
||||
|
||||
*start of nrfutil python 3.9 workaround*
|
||||
|
||||
``` console
|
||||
$ # these steps can also be done via a graphical interface
|
||||
|
||||
$ # fetch the source code of version 6.1.0
|
||||
$ # or instead of curl you can enter the URL into your web browser
|
||||
$ curl -LO https://github.com/NordicSemiconductor/pc-nrfutil/archive/v6.1.zip
|
||||
|
||||
$ # unzip the code
|
||||
$ unzip v6.1.zip
|
||||
|
||||
$ # go into the new folder
|
||||
$ cd pc-nrfutil-6.1
|
||||
```
|
||||
|
||||
Apply the following 2 patches (can also be done manually by editing these 2 files: `requirements.txt` and `setup.py`)
|
||||
|
||||
``` diff
|
||||
--- a/requirements.txt 2021-01-05 10:50:12.611556607 +0100
|
||||
+++ b/requirements.txt 2021-01-05 10:50:09.718226891 +0100
|
||||
@@ -4,7 +4,7 @@
|
||||
ecdsa
|
||||
intelhex
|
||||
libusb1
|
||||
-pc_ble_driver_py >= 0.14.2
|
||||
+pc_ble_driver_py
|
||||
piccata
|
||||
protobuf
|
||||
pyserial
|
||||
```
|
||||
|
||||
``` diff
|
||||
--- a/setup.py 2021-01-05 10:49:56.014910707 +0100
|
||||
+++ b/setup.py 2021-01-05 10:50:26.004873175 +0100
|
||||
@@ -148,7 +148,7 @@
|
||||
'../libusb/x86/libusb-1.0.dll', '../libusb/x64/libusb-1.0.dll',
|
||||
'../libusb/x64/libusb-1.0.dylib', '../libusb/LICENSE']
|
||||
},
|
||||
- python_requires='>=3.6, <3.9',
|
||||
+ python_requires='>=3.6, <3.10',
|
||||
install_requires=reqs,
|
||||
zipfile=None,
|
||||
tests_require=[
|
||||
```
|
||||
|
||||
``` console
|
||||
$ patch -p1 < requirements.patch
|
||||
$ patch -p1 < setup.patch
|
||||
```
|
||||
|
||||
Then install the patched `nrfutil`
|
||||
|
||||
``` console
|
||||
$ pip install .
|
||||
|
||||
$ # verify installation
|
||||
$ nrfutil version
|
||||
nrfutil version 6.1.0
|
||||
```
|
||||
|
||||
*end of nrfutil python 3.9 workaround*
|
||||
|
|
@ -68,5 +68,6 @@
|
|||
- [`dongle-flash` is not working](./troubleshoot-dongle-flash.md)
|
||||
- [Dongle USB functionality is not working](./troubleshoot-usb-dongle.md)
|
||||
- [`cargo run` errors](./troubleshoot-cargo-run-error.md)
|
||||
- [DEPRECATED - `nrfutil` setup](DEPRECATED-nrfutil-setup.md)
|
||||
- [Appendix](./appendix.md)
|
||||
- [Using GDB](./gdb.md)
|
||||
|
|
|
|||
|
|
@ -10,11 +10,11 @@ From this section on, we'll use the nRF52840 Dongle in addition to the nRF52840
|
|||
|
||||
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 `nrfdfu` tool to communicate with the bootloader-mode Dongle and flash new images into it.
|
||||
|
||||
✅ 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 pulsate. The Dongle will also appear as a USB CDC ACM device with vendor ID `0x1915` and product ID `0x521f`.
|
||||
|
||||
You can also use our `cargo xtask usb-list` tool, a minimal cross-platform version of the `lsusb` tool, to check out the status of the Dongle.
|
||||
|
||||
|
|
@ -29,26 +29,27 @@ Bus 001 Device 016: ID 1915:521f <- nRF52840 Dongle (in bootloader mode)
|
|||
|
||||
🔎 [`cargo xtask`](https://github.com/matklad/cargo-xtask) lets us extend `cargo` with custom commands which are installed as you run them for the first time. We've used it to add some helper tools to our workshop materials while keeping the preparation installations as minimal as possible.
|
||||
|
||||
Now that the device is in bootloader mode browse to the `boards/dongle` directory. You'll find some `*.hex` files there. These are pre-compiled Rust programs that have been converted into the Intel Hex format that the `nrfutil` tool expects.
|
||||
Now that the device is in bootloader mode browse to the `boards/dongle` directory. You'll find some `ELF` files (without a file ending) there. These are pre-compiled Rust programs to be flashed onto your dongle.
|
||||
|
||||
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 `cargo xtask dongle-flash` tool, which will invoke `nrfutil` for you. The `dongle-flash` way is shown below:
|
||||
For the next section you'll need to flash the `loopback` file onto the Dongle.
|
||||
|
||||
✅ Run the following command:
|
||||
|
||||
``` console
|
||||
$ cargo xtask dongle-flash boards/dongle/loopback.hex
|
||||
$ nrfdfu boards/dongle/loopback
|
||||
```
|
||||
|
||||
Expected output:
|
||||
``` console
|
||||
packaging iHex using nrfutil ...
|
||||
DONE
|
||||
[####################################] 100%
|
||||
Device programmed.
|
||||
[INFO nrfdfu] Sending init packet...
|
||||
[INFO nrfdfu] Sending firmware image of size 37328...
|
||||
[INFO nrfdfu] Done.
|
||||
```
|
||||
|
||||
After the device has been programmed it will automatically reset and start running the new application.
|
||||
|
||||
🔎 Alternatively, you can also use nordic's own [`nrfutil`](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fug_nrfutil%2FUG%2Fnrfutil%2Fnrfutil_intro.html) tool to convert a .hex file and flash it for you, among many other things `nrfutil` is a very powerful tool, but also unstable at times, which is why we replaced the parts we needed from it with `nrfdfu`.
|
||||
|
||||
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 `cargo xtask usb-list` tool to see the newly enumerated Dongle in the output:
|
||||
|
|
|
|||
|
|
@ -104,7 +104,7 @@ If the debugger is not supported by `probe-rs` then you'll need to use [OpenOCD]
|
|||
|
||||
[OpenOCD]: http://openocd.org/
|
||||
|
||||
If the board does not expose a JTAG, SWD or similar interface then the microcontroller probably comes with a bootloader as part of its stock firmware. In that case you'll need to use `dfu-util` or a vendor specific tool like `nrfutil` to flash programs onto the chip. This is the case of the nRF52840 Dongle.
|
||||
If the board does not expose a JTAG, SWD or similar interface then the microcontroller probably comes with a bootloader as part of its stock firmware. In that case you'll need to use `dfu-util` or a vendor specific tool like [`nrfdfu`](https://crates.io/crates/nrfdfu) or [`nrfutil`](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fug_nrfutil%2FUG%2Fnrfutil%2Fnrfutil_intro.html) to flash programs onto the chip. This is the case of the nRF52840 Dongle.
|
||||
|
||||
## Getting output
|
||||
|
||||
|
|
|
|||
|
|
@ -152,110 +152,8 @@ Installed package `probe-run v0.1.8` (..)
|
|||
$ cargo install flip-link
|
||||
(..)
|
||||
Installed package `flip-link v0.1.2` (..)
|
||||
```
|
||||
|
||||
## Python
|
||||
|
||||
**Windows**: Go to [https://www.python.org/downloads/](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
|
||||
$ # If you're using Arch Linux
|
||||
$ sudo pacman -S python-pip
|
||||
|
||||
$ # If you're using Ubuntu
|
||||
$ sudo apt-get install python3-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)
|
||||
```
|
||||
|
||||
## nrf tools
|
||||
|
||||
### nrfutil
|
||||
|
||||
**All**: Open a terminal and install [nrfutil](https://github.com/NordicSemiconductor/pc-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
|
||||
$ cargo install nrfdfu
|
||||
(..)
|
||||
|
||||
$ nrfutil version
|
||||
nrfutil version 6.1.0
|
||||
Installed package `nrfdfu v0.1.0` (..)
|
||||
```
|
||||
|
||||
**NOTE** as of version 6.1.0 nrfutil indicates that it does "not" support Python 3.9 in its pip manifest. Due to this, the above `pip install` command will fail if you have a Python 3.9 interpreter installed. Here's how to work around the issue:
|
||||
|
||||
*start of nrfutil python 3.9 workaround*
|
||||
|
||||
``` console
|
||||
$ # these steps can also be done via a graphical interface
|
||||
|
||||
$ # fetch the source code of version 6.1.0
|
||||
$ # or instead of curl you can enter the URL into your web browser
|
||||
$ curl -LO https://github.com/NordicSemiconductor/pc-nrfutil/archive/v6.1.zip
|
||||
|
||||
$ # unzip the code
|
||||
$ unzip v6.1.zip
|
||||
|
||||
$ # go into the new folder
|
||||
$ cd pc-nrfutil-6.1
|
||||
```
|
||||
|
||||
Apply the following 2 patches (can also be done manually by editing these 2 files: `requirements.txt` and `setup.py`)
|
||||
|
||||
``` diff
|
||||
--- a/requirements.txt 2021-01-05 10:50:12.611556607 +0100
|
||||
+++ b/requirements.txt 2021-01-05 10:50:09.718226891 +0100
|
||||
@@ -4,7 +4,7 @@
|
||||
ecdsa
|
||||
intelhex
|
||||
libusb1
|
||||
-pc_ble_driver_py >= 0.14.2
|
||||
+pc_ble_driver_py
|
||||
piccata
|
||||
protobuf
|
||||
pyserial
|
||||
```
|
||||
|
||||
``` diff
|
||||
--- a/setup.py 2021-01-05 10:49:56.014910707 +0100
|
||||
+++ b/setup.py 2021-01-05 10:50:26.004873175 +0100
|
||||
@@ -148,7 +148,7 @@
|
||||
'../libusb/x86/libusb-1.0.dll', '../libusb/x64/libusb-1.0.dll',
|
||||
'../libusb/x64/libusb-1.0.dylib', '../libusb/LICENSE']
|
||||
},
|
||||
- python_requires='>=3.6, <3.9',
|
||||
+ python_requires='>=3.6, <3.10',
|
||||
install_requires=reqs,
|
||||
zipfile=None,
|
||||
tests_require=[
|
||||
```
|
||||
|
||||
``` console
|
||||
$ patch -p1 < requirements.patch
|
||||
$ patch -p1 < setup.patch
|
||||
```
|
||||
|
||||
Then install the patched `nrfutil`
|
||||
|
||||
``` console
|
||||
$ pip install .
|
||||
|
||||
$ # verify installation
|
||||
$ nrfutil version
|
||||
nrfutil version 6.1.0
|
||||
```
|
||||
|
||||
*end of nrfutil python 3.9 workaround*
|
||||
|
|
|
|||
|
|
@ -7,7 +7,4 @@
|
|||
``` console
|
||||
$ cargo size --version
|
||||
cargo-size 0.3.3
|
||||
|
||||
$ nrfutil version
|
||||
nrfutil version 6.1.0
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,13 +0,0 @@
|
|||
# `dongle-flash` not working
|
||||
|
||||
``` console
|
||||
$ dongle-flash loopback.hex
|
||||
packaging iHex using nrfutil ...
|
||||
Error: No such file or directory (os error 2)
|
||||
```
|
||||
|
||||
this indicates that `nrfutil`, the Python tool, is not installed or not available in your PATH. Instructions on how to install `nrfutil` can be found in the [`nrfutil` section of the Installation Instructions].
|
||||
|
||||
❗️ If you install `nrfutil` in a virtual environment you'll need to activate the environment; the `nrfutil` binary must be available in your PATH.
|
||||
|
||||
[`nrfutil` section of the Installation Instructions]: ./installation.md#nrfutil
|
||||
Loading…
Reference in a new issue