1# Introduction
2
3This project uses CMake and the GNU ARM-Toolchain as build system and GDB/OpenOCD are used for debugging purposes.
4
5By using these tools the development environment is platform agnostic and independent of chip manufacturer specific Integrated Development Environments.
6It allows to build the project either by using a command line terminal or by using IDE's like [VSCode](#vscode) or [KDevelop](#kdevelop).
7
8# Prerequisites
9
10* CMake >= 3.6
11  * GNU/Linux:
12    * Ubuntu 16.04/ Linux Mint 18: Since the official repository version is too old, one can use e.g. [PPA](https://launchpad.net/~adrozdoff/+archive/ubuntu/cmake)
13    * Linux Arch: `pacman -S cmake`
14  * Windows:
15    * [CMake Download](https://cmake.org/download/)
16     **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 )
17  * OSX:
18    * Homebrew: `brew install cmake`
19* GNU ARM-Toolchain
20  * GNU/Linux:
21    * Ubuntu 16.04/ Linux Mint 18: Since the official repository version is too old, one can use e.g. [PPA](https://launchpad.net/~team-gcc-arm-embedded/+archive/ubuntu/ppa)
22    * Ubuntu 18.04: the toolchain has been updated but there is a bug with [`libnewlib`](https://github.com/bbcmicrobit/micropython/issues/514#issuecomment-404759614) causing the linker to fail. `sudo apt install gcc-arm-none-eabi`
23    * Linux Arch: `pacman -S arm-none-eabi-gcc arm-none-eabi-newlib`
24  * Windows:
25    * [GNU Arm Embedded Toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm)
26    * The Make utility is also required, one can use e.g. [MSYS2](http://www.msys2.org) or [MinGW](http://mingw.org/)
27        * With MSYS2:
28            * Follow the installation instructions provided by them.
29            * Install MinGW Make with `pacman -S mingw-w64-x86_64-make`.
30
31     **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.
32  * OSX:
33    * Homebrew: `brew tap ARMmbed/homebrew-formulae && brew install arm-none-eabi-gcc`
34* OpenOCD
35  * GNU/Linux:
36    * Ubuntu 16.04/ Linux Mint 18: `apt-get install openocd`
37    * Linux Arch: `pacman -S openocd`
38  * Windows:
39    * Unofficial binary packages are available [here](http://openocd.org/getting-openocd/) for download
40    **Note**: The debug configuration for [VSCode](#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.
41  * OSX:
42    * Homebrew: `brew install openocd`
43
44# Commandline build instructions
45
461. Go to root directory of the project
47
48    `cd path/to/project/directory`
49
502. Create a directory named 'build'
51
52    `mkdir build`
53
543. Go to the created `build` directory
55
56    `cd build`
57
584. run
59
60    `cmake -DCMAKE_TOOLCHAIN_FILE="cmake/toolchain-arm-none-eabi.cmake" ..`
61
62**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:
63    `cmake -DCMAKE_TOOLCHAIN_FILE="cmake/toolchain-arm-none-eabi.cmake" -DTOOLCHAIN_PREFIX="/path/to/the/toolchain" ..`
64For Windows platforms the prefix has to be provided anyway and additionally the CMake Generator for MinGW Makefiles has to be chosen:
65    `cmake -DCMAKE_TOOLCHAIN_FILE="cmake/toolchain-arm-none-eabi.cmake" -DTOOLCHAIN_PREFIX="/path/to/the/toolchain" -G "MinGW Makefiles" ..`
66
67## Available configuration options for CMake
68
69The possibility to choose the application, target board and more options can be done using the provided configuration options.
70
71These configuration options can be set through additional commandline parameters, for example:
72    `cmake -DCMAKE_TOOLCHAIN_FILE="cmake/toolchain-arm-none-eabi.cmake" -DAPPLICATION="LoRaMac" -DSUB_PROJECT="periodic-uplink-lpp" ..`
73
74Alternatively one can use a graphical interface to configure CMake, drop down menus and check boxes will provide to the user the possible options.
75
76* CMake QT GUI with `cmake-gui ..`
77* CMake curses interface with `ccmake ..`
78
79### Options that can be choose by the user
80
81* `APPLICATION` - Application example choice.
82   The possible choices are:
83     * LoRaMac (Default)
84     * ping-pong
85     * rx-sensi
86     * tx-cw
87* `SUB_PROJECT` - LoRaMac sub project example choice.
88   **Note**: Only applicable to LoRaMac `APPLICATION` choice.
89   The possible choices are:
90     * periodic-uplink-lpp
91     * fuota-test-01
92* `ACTIVE_REGION` - Active region for which the stack will be initialized.
93   **Note**: Only applicable to LoRaMac `APPLICATION` choice.
94   The possible choices are:
95     * LORAMAC_REGION_EU868
96     * LORAMAC_REGION_US915
97     * LORAMAC_REGION_CN779
98     * LORAMAC_REGION_EU433
99     * LORAMAC_REGION_AU915
100     * LORAMAC_REGION_AS923
101     * LORAMAC_REGION_CN470
102     * LORAMAC_REGION_KR920
103     * LORAMAC_REGION_IN865
104     * LORAMAC_REGION_RU864
105* `MODULATION` - Type of modulation choice.
106   **Note**: Only applicable to ping-pong or rx-sensi `APPLICATION` choice.
107   The possible choices are:
108     * LORA
109     * FSK
110* `USE_DEBUGGER`- Enables debugger support. (Default ON)
111* `BOARD` - Target board choice.
112   The possible choices are:
113     * NAMote72
114     * NucleoL073 (default)
115     * NucleoL152
116     * NucleoL476
117     * SAMR34
118     * SKiM880B
119     * SKiM980A
120     * SKiM881AXL
121* `REGION_EU868` - Enables support for the Region EU868 (Default ON)
122* `REGION_US915` - Enables support for the Region US915 (Default OFF)
123* `REGION_CN779` - Enables support for the Region CN779 (Default OFF)
124* `REGION_EU433` - Enables support for the Region EU433 (Default OFF)
125* `REGION_AU915` - Enables support for the Region AU915 (Default OFF)
126* `REGION_AS923` - Enables support for the Region AS923 (Default OFF)
127* `REGION_CN470` - Enables support for the Region CN470 (Default OFF)
128* `REGION_KR920` - Enables support for the Region IN865 (Default OFF)
129* `REGION_IN865` - Enables support for the Region AS923 (Default OFF)
130* `REGION_RU864` - Enables support for the Region RU864 (Default OFF)
131
132### Options that are automatically set
133
134* `RADIO` - Defines the radio to be used.
135   The possible choices are:
136     * sx1272
137     * sx1276
138* `LINKER_SCRIPT` - Defines the target specific linker script path.
139* `OPENOCD_BIN` - Defines the OpenOCD path.
140* `OPENOCD_INTERFACE` - Defines the interface configuration file to be used by OpenOCD.
141* `OPENOCD_TARGET` - Defines the target configuration file to be used by OpenOCD.
142
143# Debugging
144
1451. OpenOCD
146    OpenOCD has to be started with parameters that depend on the used debugger device and target board.
147    Some examples are shown below:
148    * NucleoL073 + STLinkV2-1 (On board debugger):
149    `openocd -f interface/stlink-v2-1.cfg  -f target/stm32l0.cfg`
150
151    * SAMR34 Xplained Pro (On board debugger, tested with openocd 0.10, did not work with 0.9):
152    `openocd -f interface/cmsis-dap.cfg -f target/at91samdXX.cfg`
153
1542. GDB
155    The below GDB usage example shows how to start a debug session, writing the program to the flash and run.
156   * Run ARM-GNU GDB with:
157   `arm-none-eabi-gdb`
158   * Choose the program you want to debug:
159   `file src/apps/LoRaMac/LoRaMac-classA`
160   * Connect GDB to OpenOCD:
161   `target extended-remote localhost:3333`
162   * Execute a reset and halt of the target:
163   `monitor reset halt`
164   * Flash the program to the target Flash memory:
165   `load`
166   * Add a one-time break point at main:
167   `thbreak main`
168   * Run the program until the break point:
169   `continue`
170   * Finally run the program:
171   `continue`
172
173
174# IDE Support
175
176## VSCode
177
178### Additional Prerequisites
179
180* Visual Studio Code:
181  * GNU/Linux, Windows and OSX:
182    * [Download](https://code.visualstudio.com/Download)
183* Extensions: Open `VSCode ->EXTENSION (Crtl+Shift+x)` and search for:
184  * C/C++
185  * CMake
186  * CMake Tools
187  * Native Debug
188
189### Configuration
190
191For Windows platforms it is necessary to make some additional configurations. Open your settings under *File->Preferences->Settings* and add the following lines:
192
193Add MinGW Makefiles as preferred Generator:
194
195```json
196"cmake.preferredGenerators": [
197        "MinGW Makefiles",
198        "Ninja",
199        "Unix Makefiles"
200    ]
201```
202
203Set the CMake path:
204```json
205    "cmake.cmakePath": "path/to/cmake.exe"
206```
207
208### Usage
209
2101. Open the directory of the cloned repository.
211   The *CMake Tools* extension will automatically generate a *`.cmaketools.json`* file based on the CMakeLists.
2122. The *`settings.json`* file under `.vscode` directory is the place where one can change the build options.
213   These are the build options that will be provided to CMake.
214   Please see chapter [Commandline Build Instructions](#commandline-build-instructions) for information about build options.
2153. Click on the blue status bar of *CMake Tools* to choose a build type (`Debug` or `Release`).
216   A CMake configuration process will be performed.
2174. A `Build` button will now be available.
218   Click this button to build the target.
2195. The CMake build system will automatically generate a *`launch.json`* file which setups the debugging process for the given board.
2206. Press the `F5` key to start a debug session.
221   This will automatically start the GDB and OpenOCD processes.
222
223### Useful Hints
224
225* Change CMake options:  Open the Command palette (Crtl+Shift+P) and type `CMake: Edit the CMake Cache`
226* Execute a clean rebuild: Open the Command palette (Crtl+Shift+P) and type `CMake: Clean rebuild`
227
228For detailed information about CMake Tools extension please see their [github repository](https://github.com/vector-of-bool/vscode-cmake-tools).
229
230## KDevelop
231
232### Additional Prerequisites
233
234* KDevelop:
235  * GNU/Linux:
236    * Ubuntu 16.04/ Linux Mint 18: `apt-get install kdevelop`
237    * Linux Arch: `pacman -S kdevelop`
238  * Windows:
239    * [KDevelop Download](https://www.kdevelop.org/download)
240    **Note**: Currently there is no GDB support but it is planned for future releases.
241  * OSX:
242    * [KDevelop Download](https://www.kdevelop.org/download).
243    No official binaries are available. Must be built from source code.
244
245### Usage
246
2471. To open the project click on *`Project->Open /Import Project...`* and choose the top level `CMakeLists.txt` directory of the cloned repository.
248   Follow the indications to setup the project and add `-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm-none-eabi.cmake` to the *`Extra Arguments`*.
2492. The CMake options and variables can be changed by right-clicking on project and selecting *`Open configuration...`*.
250   A graphical interface will pop-up.
251   Please see chapter [Commandline Build Instructions](#commandline-build-instructions) for information about build options.
2523. Click on `Build` to build the project.
2534. Create a launch configuration for debugging:
254   * Click on *`Run->Configure Launches...`* and add a new *`Compiled Binary Launcher`*.
255   * Set the field *`Debugger executable`* according to your system. For example `/usr/bin/arm-none-eabi-gdb` .
256   * Choose the `Run gdb script` according to the application you want to debug.
257     For example: `loramac-node/build/src/apps/LoRaMac/openocd-run.gdb`.
258     **Note**: The CMake build system will automatically generate the GDB run script.
2595. Start OpenOCD in a command line terminal as described on chapter [Debugging](#debugging).
2606. Click on "Debug" to launch a debug session.
261