rfidrig/ChameleonUltra
0
0
Fork 0
mirror of https://github.com/RfidResearchGroup/ChameleonUltra.git synced 2026-05-12 11:22:59 -07:00
Code Issues Packages Projects Releases Wiki Activity

Update How_to_use_Firmware.md

Browse Source
This commit is contained in:
Philippe Teuwen
2023-07-27 01:13:02 +02:00
parent bbb35576a4
commit f5111ee068
2 changed files with 234 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
How_to_use_Firmware.md
+234 -63
View File
@@ -1,16 +1,73 @@
# How to use the Firmware
In this file you can look up how to [edit](#Editing-the-code), [compile](#Compiling-the-code)
and [debug](#Debugging-the-code) the code!
In this file you can look up how to [install requirements](#Prerequisites-for-compiling), [edit](#Editing-the-code), [compile](#Compiling-the-code) and [debug](#Debugging-the-code) the code!
## Prerequisites for compiling
### install a cross-compiler
So far, the following compilers have been reported to work fine.
Download one of them and decompress it. Remember the path where you installed it.
- [gcc-arm-none-eabi-10.3-2021.10](https://developer.arm.com/downloads/-/gnu-rm)
- [arm-gnu-toolchain-12.2.rel1-XXX-arm-none-eabi](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads), e.g. [arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi.tar.xz](https://developer.arm.com/-/media/Files/downloads/gnu/12.2.rel1/binrel/arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi.tar.xz) for a x86_64 Linux host
Always use the official versions from ARM, *DO NOT* install `gcc-arm-none-eabi` from Debian/Ubuntu.
For some unknown reasons, same gcc version from Debian creates a bootloader too large to fit in the allocated flash space.
Moreover it does not contain the `gdb` debugger.
### install make
* **Debian/Ubuntu alike**
* Open a terminal.
* Run the following command to install Make: `sudo apt-get install build-essential`
* **Windows using Chocolatey:**
* Open a PowerShell terminal with administrator privileges.
* If not yet installed, run the following command to install Chocolatey:
``` Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) ```
* In the same PowerShell terminal, run the following command to install Make using Chocolatey: `choco install make`
* **macOS:**
* Open a terminal.
* If not yet installed, install Homebrew package manager by running the following command: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
* Once Homebrew is installed, run the following command to install Make: `brew install make`
### install nRF tools
- Install nRF Util tool [nrfutil](https://www.nordicsemi.com/Products/Development-tools/nrf-util)
- Move it to a known path like `C:\nrfutil\` or `/usr/local/bin/`
- Add this path to the `PATH` Environment Variable if not yet there.
- Install nRF Util packages:
- `nrfutil install completion device nrf5sdk-tools trace`
- Install [nRF Command Line Tools](https://www.nordicsemi.com/Products/Development-tools/nrf-command-line-tools/download) to get `nrfjprog`, `mergehex` etc.
### install programmer tools
Depending on the hardware programmer you want to use, additional tools are needed.
- If you are using a J-Link:
- Install [Segger J-Link Software](https://www.segger.com/downloads/jlink)
- alternatively, you can use openocd as described below
- Note: a JLink OB (or a STLink reflashed as a JLink OB) will not work on a nRF.
- If you are using a ST-Link V2:
- Install [openocd](https://openocd.org/pages/getting-openocd.html)
- If under Windows, install [ST-Link drivers](https://www.st.com/en/development-tools/stsw-link009.html), extract the zip and run `dpinst_amd64.exe`
### configure the project
- Edit `Makefile.defs`:
- Change `GNU_INSTALL_ROOT` (path of previously installed Compiler `bin` folder)
- Change `GNU_VERSION` (Version of the installed Compiler) (FIXME: is it really used?)
- Change the other paths to match your system if needed
- Don't forget to remove the `#` in front of the changed lines
- Alternatively, if you are committing often code, it may be easier to leave `Makefile.defs` intact and to invoke `make` with the desired variables from a script, e.g. `make GNU_INSTALL_ROOT=../../../arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi/bin/`
## Editing the code
We are using [Visual Studio Code](https://code.visualstudio.com/download) to edit this project! Simply download and
You can use [Visual Studio Code](https://code.visualstudio.com/download) to edit this project! Simply download and
install it!
- Install the [ARM-GCC](https://mynewt.apache.org/latest/get_started/native_install/cross_tools.html)
version [10.3.1 Compiler Tested](https://developer.arm.com/downloads/-/gnu-rm) and remember the path where you
installed it.
- Install the [C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) in VS-Code.
- Install
the [C++ Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack) in
@@ -24,67 +81,76 @@ install it!
## Compiling the code
- Install the compiler (for instructions have a look at [Editing the code](#Editing-the-code))
- Edit Makefile.defs:
- Change `GNU_INSTALL_ROOT`(path of previously installed Compiler `bin` folder)
- Change `GNU_VERSION` (Version of the installed Compiler)
- Change the other paths to match your system
- Don't forget to remove the `#` in front of the changed lines
- Install make
- **Ubuntu:**
- Open a terminal.
- Run the following command to install Make: `sudo apt-get install build-essential`
- **Windows using Chocolatey:**
- Install Chocolatey:
- Open a PowerShell terminal with administrator privileges.
- Run the following command to install Chocolatey:
``` Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) ```
- Install Make:
- In the same PowerShell terminal, run the following command to install Make using
Chocolatey: `choco install make`
- **macOS:**
- Open a terminal.
- Install Homebrew package manager by running the following
command: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
- Once Homebrew is installed, run the following command to install Make: `brew install make`
- go into folder and run `make`
- if make fails try to add a folder named `objects` in the `firmware` folder
- do this for `application` and `bootloader` folder
- Install prerequisites (for instructions have a look at [Prerequisites for compiling](#Prerequisites-for-compiling))
- Run `build.sh` or try to execute its steps manually if your platform is not yet properly supported. Feedback is always welcome.
## Merging the code
The script produces several images in `objects`.
* `fullimage.hex` to be used with a programmer over the SWD pins
* `dfu-app.zip` and `dfu-full.zip` to be used with DFU mode
- Install [nRF Util](https://www.nordicsemi.com/Products/Development-tools/nrf-util)
- Move it to a known path like `C:/nrfutil/`
- Add this path to `PATH` Environment Variable
- Install [nRF Command Line Tools](https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools)
- Install nRF Util packages:
- `nrfutil install completion device nrf5sdk-tools trace`
- go into `objects` folder
- generate settings
by `nrfutil settings generate --family NRF52840 --application application.hex --application-version 1 --bootloader-version 1 --bl-settings-version 2 settings.hex` (
only has to be done once)
- merge bootloader and settings by `mergehex --merge bootloader.hex settings.hex --output bootloader_settings.hex`
- copy the `s140_nrf52_7.2.0_softdevice.hex` file from `nrf52_sdk/components/softdevice/s140/hex/` to `objects`
- rename `s140_nrf52_7.2.0_softdevice.hex` to `softdevice.hex`
- merge bootloader_settings and app
by `mergehex --merge bootloader_settings.hex application.hex softdevice.hex --output project.hex`
## Uploading the code in DFU mode
## Uploading the code
If the bootloader and the SoftDevice are already properly installed on the Chameleon, you can reflash it directly over DFU.
- If you are using J-Link:
- Install [Segger J-Link](https://www.segger.com/downloads/jlink)
- [Merge](#Merging-the-code) the code
- Upload softdevice with `make flash_softdevice`
- Upload bootloader in bootloader folder with `make flash`
- Upload application in application folder with `make flash`
- If you are using ST-Link:
- Install [openocd](https://mynewt.apache.org/latest/get_started/native_install/cross_tools.html)
- Install [ST-Link drivers](https://www.st.com/en/development-tools/stsw-link009.html)
- Extract downloaded zip
- run `dpinst_amd64.exe`
- Upload full image with `make flash_stlink` in application or bootloader folder
To set the device in DFU mode:
* you can use the Python client and issue the command `hw dfu`
* you can use the script `resource/tools/enter_dfu.py` that does exactly the same but may be easier to call from your scripts
* you can unplug the device, wait for it to sleep, then press the button B and plug it. If the application is bogus, this is the only way.
## Debugging the code
The LEDs 4 & 5 should blink green when in DFU mode.
To flash only the application (safer):
`nrfutil device program --firmware objects/dfu-app.zip --traits nordicDfu`
To flash everything (be sure to also have a JLink or ST-Link V2 programmer if something goes wrong):
`nrfutil device program --firmware objects/dfu-full.zip --traits nordicDfu`
Under Linux you can use the scripts `flash-dfu-app.sh` and `flash-dfu-full.sh`, they will put the device in DFU mode and flash it.
## Uploading the code with a programmer
Connect pins GND, SWC (swclk) and SWD (swdio) to your programmer.
With a JLink and `nrfjprog`
```
# application only:
nrfjprog -f nrf52 --program objects/application.hex --sectorerase --verify --reset
# full:
nrfjprog -f nrf52 --program objects/fullimage.hex --sectorerase --verify --reset
```
With a JLink and `openocd`
```
# application only:
openocd -f interface/jlink.cfg -f target/nrf52.cfg -c "program objects/application.hex verify reset ; shutdown"
# full:
openocd -f interface/jlink.cfg -f target/nrf52.cfg -c "program objects/fullimage.hex verify reset ; shutdown"
```
With a ST-Link V2 and `openocd`
```
# application only:
openocd -f interface/stlink.cfg -f target/nrf52.cfg -c "program objects/application.hex verify reset ; shutdown"
# full:
openocd -f interface/stlink.cfg -f target/nrf52.cfg -c "program objects/fullimage.hex verify reset ; shutdown"
```
## Uploading the code over BLE
If you are adventurous it is possible to flash the device over BLE (DFU mode).
To put the device in DFU mode
* you can use the Python client and issue the command `hw dfu` **TODO:** this will be possible only when the client will be able to work over BLE...
* you can use the script `resource/tools/enter_dfu_over_ble.py`
Once in DFU mode, the device will announce itself over BLE as `CU-xxxx` where xxxx are the last 2 bytes of the Device Serial Number.
Then use the official [nRF Device Firmware Update](https://www.nordicsemi.com/Products/Development-tools/nRF-Device-Firmware-Update) mobile application to flash one of the DFU images.
## Debugging the code from VSCode
- Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) VS-Code Extension
- Open `app_main.c`
@@ -136,4 +202,109 @@ install it!
```
- To change `executable` target in `launch.json` to `application` or `bootloader`
- In the debug menu you can select `Debug with JLink` or `Debug with STLink`
- In the debug menu you can select `Debug with JLink` or `Debug with STLink`
## Debugging the code with gdb and openocd
See first if you can execute `arm-none-eabi-gdb` from the installed tools.
* gcc-arm-none-eabi-10.3-2021.10 gdb requires `libncurses5`
* arm-gnu-toolchain-12.2.rel1 gdb requires Python 3.8
In case Python 3.8 is not available anymore on your distro, to install a local copy you can do
```
wget https://www.python.org/ftp/python/3.8.17/Python-3.8.17.tgz
tar zxvf Python-3.8.17.tgz
cd Python-3.8.17
./configure --prefix=$HOME/opt/python-3.8.17 --enable-shared
make
rm -rf ~/opt/python-3.8.17
make install
```
Connect openocd to the device with a JLink or a ST-Link V2
```
openocd -f interface/jlink.cfg -f target/nrf52.cfg
```
```
openocd -f interface/stlink.cfg -f target/nrf52.cfg
```
Then run gdb as follows
```
PYTHONHOME=~/opt/python-3.8.17/ arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi/bin/arm-none-eabi-gdb
```
and tell gdb to connect to openocd
```
target extended-remote localhost:3333
```
## BlackMagicProbe with RTT support, out of a ST-Link V2
You can reflash a ST-Link V2 to use it as a BlackMagicProbe, to get support for RTT and see NRF_LOG messages.
Some clones have only 64kb, this is too short.
Even 128kb is too small when enabling RTT, but we can comment parts of the BMP source code.
```
git clone --recursive git@github.com:blackmagic-debug/stlink-tool.git
( cd stlink-tool && make )
```
Then put the `stlink-tool` binary in your path.
Get [BMP full sources](https://github.com/blackmagic-debug/blackmagic/releases)
Comment out all probes except Nordic nrf51 in `src/target/cortexm.c` big switch for probes. It should remain
```c
switch (t->designer_code) {
case JEP106_MANUFACTURER_NORDIC:
PROBE(nrf51_probe);
break;
}
```
```
make -j PROBE_HOST=stlink ST_BOOTLOADER=1 ENABLE_RTT=1
```
Then flash the ST_Link V2
```
stlink-tool src/blackmagic.bin
```
See `src/platforms/stlink/README.md` for more details.
Unplug/plug.
Every time you plug the ST-Link, you have to run `stlink-tool` to enable BMP.
Under linux, it is convenient to install [udev rules](https://github.com/blackmagic-debug/blackmagic/blob/main/driver/README.md#99-blackmagic-plugdevrules) to get aliases `/dev/ttyBmpGdb` and `/dev/ttyBmpTarg`.
Note that using a native ST-Link V2 with BlackMagicProbe "hosted" will not allow to see NRF_LOG messages.
## Debugging the code with gdb and BMP with RTT to monitor NRF_LOG
Assuming you have a BlackMagicProbe with RTT support made out of a ST-Link V2.
RTT usage: https://black-magic.org/usage/rtt.html
```
stlink-tool
sleep 1
screen /dev/ttyBmpTarg
```
In another terminal
```
$ arm-none-eabi-gdb
(gdb) target extended-remote /dev/ttyBmpGdb
(gdb) monitor swdp_scan
1 Nordic nRF52 M4
2 Nordic nRF52 Access Port.
(gdb) attach 1
(gdb) monitor rtt
```
We are now able to use gdb and see the NRF_LOG messages on the other terminal.
## Using JLink with RTT to monitor NRF_LOG
cf https://embeddedexplorer.com/nrf52-nrf-log-tutorial/
```
JLinkExe -if SWD -device nrf52 -speed 4000 -autoconnect 1
```
in a second terminal:
```
JLinkRTTClient
```
firmware/build.sh
-2
View File
@@ -1,7 +1,5 @@
#!/bin/env bash
# Partially based on informations from https://github.com/RfidResearchGroup/ChameleonUltra/issues/16
if [[ $BASH_SOURCE = */* ]]; then
cd -- "${BASH_SOURCE%/*}/" || exit
fi