Merge branch 'release/v4.4.1'

Author: Daniel Jaeckle

.gitignore

@@ -1,6 +1,11 @@
 lst/
 obj/
 bin/
+build/
+tmp/
+*.bin
+.kdev4
+*.log
 *.dep
 *.uvgui.*
 *.uvgui_*.bak
@@ -16,4 +21,7 @@ bin/
 *.svn
 *.pbxproj
 *.cogui
-*.comarker
+*.comarker
+.directory
+launch.json
+.cmaketools.json

.vscode/settings.json

@@ -0,0 +1,65 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+    "cmake.configureSettings": {
+
+        // In case your GNU ARM-Toolchain is not installed under the default
+        // path:
+        //     Windows : No default path. Specify the path where the
+        //               toolchain is installed. i.e:
+        //               "C:/PROGRA~2/GNUTOO~1/62017-~2".
+        //     Linux   : /usr
+        //     OSX     : /usr/local
+        // It is required to uncomment and to fill the following line.
+        //"TOOLCHAIN_PREFIX":"/path/to/toolchain",
+
+        // In case your OpenOCD is not installed under the default path:
+        //     Windows : C:/openocd/bin/openocd.exe
+        //     Linux   : /usr/bin/openocd
+        //     OSX     : /usr/local/bin/openocd
+        // Please uncomment the following line and fill it accordingly.
+        //"OPENOCD_BIN":"C:/openocd/bin/openocd.exe",
+
+        // Specifies the path to the CMAKE toolchain file.
+        "CMAKE_TOOLCHAIN_FILE":"cmake/toolchain-arm-none-eabi.cmake",
+
+        // Determines the application. You can choose between:
+        // LoRaMac (Default), ping-pong, rx-sensi, tx-cw and BootLoader.
+        "APPLICATION":"LoRaMac",
+
+        // Select LoRaMac sub project. You can choose between:
+        // classA, classB or classC.
+        "CLASS":"classA",
+
+        // Select the active region for which the stack will be initialized.
+        // You can choose between:
+        // LORAMAC_REGION_EU868, LORAMAC_REGION_US915, ..
+        "ACTIVE_REGION":"LORAMAC_REGION_EU868",
+
+        // Select the type of modulation, applicable to the ping-pong or
+        // rx-sensi applications. You can choose between:
+        // LORA or FSK
+        "MODULATION":"LORA",
+
+        // Target board, the following boards are supported:
+        // LoRaMote (Default), MoteII, NAMote72, NucleoL073, NucleoL152, SAML21, SensorNode and SK-iM880A.
+        "BOARD":"LoRaMote",
+
+        // MBED Radio shield selection. (Applies only to Nucleo platforms)
+        // The following shields are supported:
+        // SX1272MB2DAS, SX1276MB1LAS, SX1276MB1MAS, SX1261DVK1BAS(Default), SX1262DVK1CAS, SX1262DVK1DAS.
+        "MBED_RADIO_SHIELD":"SX1261DVK1BAS",
+
+        // Region support activation, Select the ones you want to support.
+        // By default only REGION_EU868 support is enabled.
+        "REGION_EU868":"ON",
+        "REGION_US915":"OFF",
+        "REGION_CN779":"OFF",
+        "REGION_EU433":"OFF",
+        "REGION_AU915":"OFF",
+        "REGION_AS923":"OFF",
+        "REGION_CN470":"OFF",
+        "REGION_KR920":"OFF",
+        "REGION_IN865":"OFF",
+        "REGION_US915_HYBRID":"OFF"
+    }
+}

CMakeLists.txt

@@ -0,0 +1,21 @@
+##
+##   ______                              _
+##  / _____)             _              | |
+## ( (____  _____ ____ _| |_ _____  ____| |__
+##  \____ \| ___ |    (_   _) ___ |/ ___)  _ \
+##  _____) ) ____| | | || |_| ____( (___| | | |
+## (______/|_____)_|_|_| \__)_____)\____)_| |_|
+## (C)2013-2017 Semtech
+##  ___ _____ _   ___ _  _____ ___  ___  ___ ___
+## / __|_   _/_\ / __| |/ / __/ _ \| _ \/ __| __|
+## \__ \ | |/ _ \ (__| ' <| _| (_) |   / (__| _|
+## |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
+## embedded.connectivity.solutions.==============
+##
+## License:  Revised BSD License, see LICENSE.TXT file included in the project
+## Authors:  Johannes Bruder (STACKFORCE), Miguel Luis (Semtech)
+##
+cmake_minimum_required(VERSION 3.6)
+
+
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/src)

Doc/SAML21-platform.md

@@ -0,0 +1,9 @@
+# SAML21 platform support documents
+
+The supported SAML21 platform is composed of 2 elements:
+1. SAML21-XPRO-B [User Guide](http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-42405-SAML21-Xplained-Pro_User-Guide.pdf)
+2. SX1276 "Wing Board" [Schematic](SX1276-Wing-Board-(03-91016-RA).pdf)
+
+The SAM L21 family data sheet can be found at [SAM L21 Family Data Sheet](http://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en590687)
+
+Other useful resources can be found at http://www.microchip.com/ATSAML21-XPRO-B

Doc/SX1276-Wing-Board-(03-91016-RA).pdf

@@ -0,0 +1,264 @@
+# 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](#vscode) or [KDevelop](#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](https://launchpad.net/~adrozdoff/+archive/ubuntu/cmake)
+    * Linux Arch: `pacman -S cmake`
+  * Windows:
+    * [CMake Download](https://cmake.org/download/)  
+     **Note**: Please ensure that CMake path is added to the system 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](https://launchpad.net/~team-gcc-arm-embedded/+archive/ubuntu/ppa)
+    * Linux Arch: `pacman -S arm-none-eabi-gcc arm-none-eabi-newlib`
+  * Windows:
+    * [GNU Arm Embedded Toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm)
+    * The Make utility is also required, one can use e.g. [MSYS2](http://www.msys2.org)  
+    **Note**: Please ensure that both paths are added to the system 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](http://openocd.org/getting-openocd/) for download  
+    **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.
+  * 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_US915_HYBRID
+* `MODULATION` - Type of modulation choice.  
+   **Note**: Only applicable to ping-pong or rx-sensi `APPLICATION` choice.  
+   The possible choices are:
+     * LORA
+     * FSK
+* `USE_BOOTLOADER` - Enables Bootloader support. (Default OFF)  
+   **Note**: Only applicable to LoRaMote or SensorNode `BOARD` choice.
+* `USE_USB_CDC` - Enables USB-Uart support. (Default OFF)  
+   **Note**: Only applicable to LoRaMote or SensorNode `BOARD` choice.
+* `USE_DEBUGGER`- Enables debugger support. (Default ON)
+* `BOARD` - Target board choice.  
+   The possible choices are:  
+     * LoRaMote (Default)
+     * MoteII
+     * NAMote72
+     * SAML21
+     * SensorNode
+     * SK-iM880A
+* `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_US915_HYBRID` - Enables support for the Region US915 HYBRID (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:
+    * LoRaMote + STLinkV2:  
+    `openocd -f interface/stlink-v2.cfg  -f target/stm32l1.cfg`
+
+    * MoteII + STLinkV2-1 (On board debugger):  
+    `openocd -f interface/stlink-v2-1.cfg  -f target/stm32l0.cfg`
+
+    * LoRaMote + JLink:  
+    `openocd -f interface/jlink.cfg -c "transport select swd"  -f target/stm32l1.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:
+  * GNU/Linux, Windows and OSX:
+    * [Download](https://code.visualstudio.com/Download)
+* 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:
+
+```json
+"cmake.preferredGenerators": [
+        "MinGW Makefiles",
+        "Ninja",
+        "Unix Makefiles"
+    ]
+```
+
+Set the CMake path:
+```json
+    "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](#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](https://github.com/vector-of-bool/vscode-cmake-tools).
+
+## KDevelop
+
+### Additional Prerequisites
+
+* KDevelop:
+  * GNU/Linux:
+    * Ubuntu 16.04/ Linux Mint 18: `apt-get install kdevelop`
+    * Linux Arch: `pacman -S kdevelop`
+  * Windows:
+    * [KDevelop Download](https://www.kdevelop.org/download)  
+    **Note**: Currently there is no GDB support but it is planned for future releases.
+  * OSX:
+    * [KDevelop Download](https://www.kdevelop.org/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](#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](#debugging).
+6. Click on "Debug" to launch a debug session.