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.
- 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
toPath
variable )
- CMake Download
- OSX:
- Homebrew:
brew install cmake
- Homebrew:
- GNU/Linux:
- 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
- Ubuntu 18.04: the toolchain has been updated but there is a bug with
libnewlib
causing the linker to fail.sudo apt install gcc-arm-none-eabi
- 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
.
- With MSYS2:
Note: Please ensure that both paths are added to the system PATH variable. Add for example:
C:\msys64\mingw64\bin
andC:\Program Files (x86)\GNU Tools ARM Embedded\6 2017-q2-update\bin
toPath
variable. -
OSX:
- Homebrew:
brew tap ARMmbed/homebrew-formulae && brew install arm-none-eabi-gcc
- Homebrew:
-
- OpenOCD
- GNU/Linux:
- Ubuntu 16.04/ Linux Mint 18:
apt-get install openocd
- Linux Arch:
pacman -S openocd
- Ubuntu 16.04/ Linux Mint 18:
- Windows:
- OSX:
- Homebrew:
brew install openocd
- Homebrew:
- GNU/Linux:
-
Go to root directory of the project
cd path/to/project/directory
-
Create a directory named 'build'
mkdir build
-
Go to the created
build
directorycd build
-
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" ..
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" -DSUB_PROJECT="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 ..
APPLICATION
- Application example choice.
The possible choices are:- LoRaMac (Default)
- ping-pong
- rx-sensi
- tx-cw
SUB_PROJECT
- LoRaMac sub project example choice.
Note: Only applicable to LoRaMacAPPLICATION
choice.
The possible choices are:- classA
- classB
- classC
- periodic-uplink-lpp
- fuota-test-01
ACTIVE_REGION
- Active region for which the stack will be initialized.
Note: Only applicable to LoRaMacAPPLICATION
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-sensiAPPLICATION
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
- SAMR34
- 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)
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.
-
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
-
SAMR34 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
-
-
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
- Run ARM-GNU GDB with:
- Visual Studio Code:
- GNU/Linux, Windows and OSX:
- Extensions: Open
VSCode ->EXTENSION (Crtl+Shift+x)
and search for:- C/C++
- CMake
- CMake Tools
- Native Debug
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"
- Open the directory of the cloned repository.
The CMake Tools extension will automatically generate a.cmaketools.json
file based on the CMakeLists. - 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. - Click on the blue status bar of CMake Tools to choose a build type (
Debug
orRelease
).
A CMake configuration process will be performed. - A
Build
button will now be available.
Click this button to build the target. - The CMake build system will automatically generate a
launch.json
file which setups the debugging process for the given board. - Press the
F5
key to start a debug session.
This will automatically start the GDB and OpenOCD processes.
- 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:
- GNU/Linux:
- Ubuntu 16.04/ Linux Mint 18:
apt-get install kdevelop
- Linux Arch:
pacman -S kdevelop
- Ubuntu 16.04/ Linux Mint 18:
- Windows:
- KDevelop Download
Note: Currently there is no GDB support but it is planned for future releases.
- KDevelop Download
- OSX:
- KDevelop Download.
No official binaries are available. Must be built from source code.
- KDevelop Download.
- GNU/Linux:
- To open the project click on
Project->Open /Import Project...
and choose the top levelCMakeLists.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 theExtra Arguments
. - 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. - Click on
Build
to build the project. - Create a launch configuration for debugging:
- Click on
Run->Configure Launches...
and add a newCompiled 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.
- Click on
- Start OpenOCD in a command line terminal as described on chapter Debugging.
- Click on "Debug" to launch a debug session.