ChameleonUltra/How_to_use_Firmware.md

How to use the Firmware

In this file you can look up how to edit, compile and debug the code!

Editing the code

We are using Visual Studio Code to edit this project! Simply download and install it!

• Install the ARM-GCC version 10.3.1 Compiler Tested and remember the path where you installed it.
• Install the C++ Extension in VS-Code.
• Install the C++ Extension Pack in VS-Code.
• Create a new IntelliSense Configuration:
  • press F1 in VS-Code and enter C/C++: Edit Configurations (UI)
  • Add a new Configuration and name it
  • Specify your Compiler path (path of previously installed Compiler bin folder)
  • Change IntelliSense mode to gcc-arm (legacy)
  • Add include path ${workspaceFolder}/**

Compiling the code

• Install the compiler (for instructions have a look at 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

Merging the code

• Install nRF Util
  • Move it to a known path like C:/nrfutil/
  • Add this path to PATH Environment Variable
• Install 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

• If you are using J-Link:
  • Install Segger J-Link
  • Merge 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
  • Install ST-Link drivers
  • Extract downloaded zip
  • run dpinst_amd64.exe
  • Upload full image with make flash_stlink in application or bootloader folder

Debugging the code

• Install Cortex-Debug VS-Code Extension
• Open app_main.c
• Open the extension with CTRL-SHIFT-D
• Klick on create a launch.json file
• Select Cortex-Debug
• Add this in the configuration bracket:

{
    "cwd": "${workspaceFolder}",
    "executable": "${workspaceRoot}/firmware/objects/bootloader.out",
    "name": "Debug with JLink",
    "request": "launch",
    "type": "cortex-debug",
    "runToEntryPoint": "main",
    "showDevDebugOutput": "none",
    "servertype": "jlink",
    "device": "nrf52",
    "interface": "swd",
    "svdFile": "${workspaceRoot}/firmware/nrf52_sdk/modules/nrfx/mdk/nrf52.svd",
}, 
{
    "cwd": "${workspaceFolder}",
    "executable": "${workspaceRoot}/firmware/objects/bootloader.out",
    "name": "Debug with STLink",
    "request": "launch",
    "type": "cortex-debug",
    "runToEntryPoint": "main",
    "showDevDebugOutput": "none",
    "servertype": "openocd",
    "device": "nrf52",
    "svdFile": "${workspaceRoot}/firmware/nrf52_sdk/modules/nrfx/mdk/nrf52.svd",
    "gdbPath": "C:/Program Files (x86)/GNU Arm Embedded Toolchain/10 2021.10/bin/arm-none-eabi-gdb.exe",
    "configFiles": [
        "interface/stlink.cfg",
        "target/nrf52.cfg"
    ]
}

• If you are jlink probe, create settings.json in {projectRoot}/.vscode directory.

{
    "cortex-debug.armToolchainPath": "C:\\UserProgram\\arm_gcc\\none\\bin",
    "cortex-debug.JLinkGDBServerPath": "C:\\Program Files\\SEGGER\\JLink\\JLinkGDBServerCL.exe",
}

• 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