Skip to content

Latest commit

 

History

History
260 lines (212 loc) · 11.3 KB

development-environment.md

File metadata and controls

260 lines (212 loc) · 11.3 KB
Raw

Introduction

This project uses CMake and the GNU ARM-Toolchain as build system and GDB/OpenOCD are used for debugging purposes.

By using these tools the development environment is platform agnostic and independent of chip manufacturer specific Integrated Development Environments.
It allows to build the project either by using a command line terminal or by using IDE's like VSCode or KDevelop.

Prerequisites

  • CMake >= 3.6
    • GNU/Linux:
      • Ubuntu 16.04/ Linux Mint 18: Since the official repository version is too old, one can use e.g. PPA
      • Linux Arch: pacman -S cmake
    • Windows:
      • CMake Download
        Note: Please use the latest full release and ensure that CMake path is added to the system path variable. (On Windows 10 search for Environment Variables at start menu and add your CMake installation path e.g. C:\Program Files\CMake\bin to Path variable )
    • OSX:
      • Homebrew: brew install cmake
  • GNU ARM-Toolchain

    • GNU/Linux:

      • Ubuntu 16.04/ Linux Mint 18: Since the official repository version is too old, one can use e.g. PPA
      • Linux Arch: pacman -S arm-none-eabi-gcc arm-none-eabi-newlib

    • Windows:

      • GNU Arm Embedded Toolchain
      • The Make utility is also required, one can use e.g. MSYS2 or MinGW
        • With MSYS2:
          • Follow the installation instructions provided by them.
          • Install MinGW Make with pacman -S mingw-w64-x86_64-make.

      Note: Please ensure that both paths are added to the system PATH variable. Add for example: C:\msys64\mingw64\bin and C:\Program Files (x86)\GNU Tools ARM Embedded\6 2017-q2-update\bin to Path variable.

    • OSX:

      • Homebrew: brew tap ARMmbed/homebrew-formulae && brew install arm-none-eabi-gcc
  • OpenOCD
    • GNU/Linux:
      • Ubuntu 16.04/ Linux Mint 18: apt-get install openocd
      • Linux Arch: pacman -S openocd
    • Windows:
      • Unofficial binary packages are available here for download
        Note: The debug configuration for VSCode will assume that OpenOCD is installed under C:/openocd. If it is not the case one must change the OPENOCD_BIN variable according to right location.
    • OSX:
      • Homebrew: brew install openocd

Commandline build instructions

  1. Go to root directory of the project

    cd path/to/project/directory

  2. Create a directory named 'build'

    mkdir build

  3. Go to the created build directory

    cd build

  4. run

    cmake -DCMAKE_TOOLCHAIN_FILE="cmake/toolchain-arm-none-eabi.cmake" ..

Note: If the GNU ARM-Toolchain is not installed under the default path (GNU Linux:/usr, Mac OS /usr/local) a prefix has to be provided:
cmake -DCMAKE_TOOLCHAIN_FILE="cmake/toolchain-arm-none-eabi.cmake" -DTOOLCHAIN_PREFIX="/path/to/the/toolchain" ..
For Windows platforms the prefix has to be provided anyway and additionally the CMake Generator for MinGW Makefiles has to be chosen:
cmake -DCMAKE_TOOLCHAIN_FILE="cmake/toolchain-arm-none-eabi.cmake" -DTOOLCHAIN_PREFIX="/path/to/the/toolchain" -G "MinGW Makefiles" ..

Available configuration options for CMake

The possibility to choose the application, target board and more options can be done using the provided configuration options.

These configuration options can be set through additional commandline parameters, for example:
cmake -DCMAKE_TOOLCHAIN_FILE="cmake/toolchain-arm-none-eabi.cmake" -DAPPLICATION="LoRaMac" -DCLASS="classC" ..

Alternatively one can use a graphical interface to configure CMake, drop down menus and check boxes will provide to the user the possible options.

  • CMake QT GUI with cmake-gui ..
  • CMake curses interface with ccmake ..

Options that can be choose by the user

  • APPLICATION - Application example choice.
    The possible choices are:
    • LoRaMac (Default)
    • ping-pong
    • rx-sensi
    • tx-cw
  • CLASS - Class specific application example choice.
    Note: Only applicable to LoRaMac APPLICATION choice.
    The possible choices are:
    • classA
    • classB
    • classC
  • ACTIVE_REGION - Active region for which the stack will be initialized.
    Note: Only applicable to LoRaMac APPLICATION choice.
    The possible choices are:
    • LORAMAC_REGION_EU868
    • LORAMAC_REGION_US915
    • LORAMAC_REGION_CN779
    • LORAMAC_REGION_EU433
    • LORAMAC_REGION_AU915
    • LORAMAC_REGION_AS923
    • LORAMAC_REGION_CN470
    • LORAMAC_REGION_KR920
    • LORAMAC_REGION_IN865
    • LORAMAC_REGION_RU864
  • MODULATION - Type of modulation choice.
    Note: Only applicable to ping-pong or rx-sensi APPLICATION choice.
    The possible choices are:
    • LORA
    • FSK
  • USE_DEBUGGER- Enables debugger support. (Default ON)
  • BOARD - Target board choice.
    The possible choices are:
    • NAMote72
    • NucleoL073 (default)
    • NucleoL152
    • NucleoL476
    • SAML21
    • SKiM880B
    • SKiM980A
    • SKiM881AXL
  • REGION_EU868 - Enables support for the Region EU868 (Default ON)
  • REGION_US915 - Enables support for the Region US915 (Default OFF)
  • REGION_CN779 - Enables support for the Region CN779 (Default OFF)
  • REGION_EU433 - Enables support for the Region EU433 (Default OFF)
  • REGION_AU915 - Enables support for the Region AU915 (Default OFF)
  • REGION_AS923 - Enables support for the Region AS923 (Default OFF)
  • REGION_CN470 - Enables support for the Region CN470 (Default OFF)
  • REGION_KR920 - Enables support for the Region IN865 (Default OFF)
  • REGION_IN865 - Enables support for the Region AS923 (Default OFF)
  • REGION_RU864 - Enables support for the Region RU864 (Default OFF)

Options that are automatically set

  • RADIO - Defines the radio to be used.
    The possible choices are:
    • sx1272
    • sx1276
  • LINKER_SCRIPT - Defines the target specific linker script path.
  • OPENOCD_BIN - Defines the OpenOCD path.
  • OPENOCD_INTERFACE - Defines the interface configuration file to be used by OpenOCD.
  • OPENOCD_TARGET - Defines the target configuration file to be used by OpenOCD.

Debugging

  1. OpenOCD
    OpenOCD has to be started with parameters that depend on the used debugger device and target board.
    Some examples are shown below:

    • NucleoL073 + STLinkV2-1 (On board debugger):
      openocd -f interface/stlink-v2-1.cfg -f target/stm32l0.cfg

    • SAML21 Xplained Pro (On board debugger, tested with openocd 0.10, did not work with 0.9): openocd -f interface/cmsis-dap.cfg -f target/at91samdXX.cfg

  2. GDB
    The below GDB usage example shows how to start a debug session, writing the program to the flash and run.

    • Run ARM-GNU GDB with:
      arm-none-eabi-gdb
    • Choose the program you want to debug:
      file src/apps/LoRaMac/LoRaMac-classA
    • Connect GDB to OpenOCD:
      target extended-remote localhost:3333
    • Execute a reset and halt of the target:
      monitor reset halt
    • Flash the program to the target Flash memory:
      load
    • Add a one-time break point at main:
      thbreak main
    • Run the program until the break point:
      continue
    • Finally run the program:
      continue

IDE Support

VSCode

Additional Prerequisites

  • Visual Studio Code:
  • Extensions: Open VSCode ->EXTENSION (Crtl+Shift+x) and search for:
    • C/C++
    • CMake
    • CMake Tools
    • Native Debug

Configuration

For Windows platforms it is necessary to make some additional configurations. Open your settings under File->Preferences->Settings and add the following lines:

Add MinGW Makefiles as preferred Generator:

"cmake.preferredGenerators": [
        "MinGW Makefiles",
        "Ninja",
        "Unix Makefiles"
    ]

Set the CMake path:

    "cmake.cmakePath": "path/to/cmake.exe"

Usage

  1. Open the directory of the cloned repository.
    The CMake Tools extension will automatically generate a .cmaketools.json file based on the CMakeLists.
  2. The settings.json file under .vscode directory is the place where one can change the build options.
    These are the build options that will be provided to CMake.
    Please see chapter Commandline Build Instructions for information about build options.
  3. Click on the blue status bar of CMake Tools to choose a build type (Debug or Release).
    A CMake configuration process will be performed.
  4. A Build button will now be available.
    Click this button to build the target.
  5. The CMake build system will automatically generate a launch.json file which setups the debugging process for the given board.
  6. Press the F5 key to start a debug session.
    This will automatically start the GDB and OpenOCD processes.

Useful Hints

  • Change CMake options: Open the Command palette (Crtl+Shift+P) and type CMake: Edit the CMake Cache
  • Execute a clean rebuild: Open the Command palette (Crtl+Shift+P) and type CMake: Clean rebuild

For detailed information about CMake Tools extension please see their github repository.

KDevelop

Additional Prerequisites

  • KDevelop:
    • GNU/Linux:
      • Ubuntu 16.04/ Linux Mint 18: apt-get install kdevelop
      • Linux Arch: pacman -S kdevelop
    • Windows:
      • KDevelop Download
        Note: Currently there is no GDB support but it is planned for future releases.
    • OSX:
      • KDevelop Download.
        No official binaries are available. Must be built from source code.

Usage

  1. To open the project click on Project->Open /Import Project... and choose the top level CMakeLists.txt directory of the cloned repository.
    Follow the indications to setup the project and add -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm-none-eabi.cmake to the Extra Arguments.
  2. The CMake options and variables can be changed by right-clicking on project and selecting Open configuration....
    A graphical interface will pop-up.
    Please see chapter Commandline Build Instructions for information about build options.
  3. Click on Build to build the project.
  4. Create a launch configuration for debugging:
    • Click on Run->Configure Launches... and add a new Compiled Binary Launcher.
    • Set the field Debugger executable according to your system. For example /usr/bin/arm-none-eabi-gdb .
    • Choose the Run gdb script according to the application you want to debug.
      For example: loramac-node/build/src/apps/LoRaMac/openocd-run.gdb.
      Note: The CMake build system will automatically generate the GDB run script.
  5. Start OpenOCD in a command line terminal as described on chapter Debugging.
  6. Click on "Debug" to launch a debug session.