1# LoRaWAN end-device stack implementation and example projects 2 3 ______ _ 4 / _____) _ | | 5 ( (____ _____ ____ _| |_ _____ ____| |__ 6 \____ \| ___ | (_ _) ___ |/ ___) _ \ 7 _____) ) ____| | | || |_| ____( (___| | | | 8 (______/|_____)_|_|_| \__)_____)\____)_| |_| 9 (C)2013-2022 Semtech 10 11 ___ _____ _ ___ _ _____ ___ ___ ___ ___ 12 / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __| 13 \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _| 14 |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___| 15 embedded.connectivity.solutions=============== 16 17## Introduction 18 19The aim of this project is to show an example of an end-device LoRaWAN stack implementation. 20 21This project has 2 active branches in place. 22 23| Branch | L2 spec | RP spec | Tag/Milestone | Class | Comments | 24| ------------- |:-------------:|:---------:|:---------:|:---------:|:--------------| 25| | [1.0.4](https://resources.lora-alliance.org/technical-specifications/ts001-1-0-4-lorawan-l2-1-0-4-specification) / [1.1.0](https://resources.lora-alliance.org/technical-specifications/lorawan-specification-v1-1) + [FCntDwn ERRATA](https://resources.lora-alliance.org/technical-specifications/fopts-encryption-usage-of-fcntdwn-errata-on-the-lorawan-l2-1-1-specification) | [2-1.0.3](https://resources.lora-alliance.org/technical-specifications/rp2-1-0-3-lorawan-regional-parameters) | [v4.7.0](https://github.com/Lora-net/LoRaMac-node/releases/tag/v4.7.0) | A/B/C | LoRaWAN L2 1.0.4 - **_Released_** | 26| [master](https://github.com/Lora-net/LoRaMac-node/tree/master) | [1.0.4](https://resources.lora-alliance.org/technical-specifications/ts001-1-0-4-lorawan-l2-1-0-4-specification) / [1.1.0](https://resources.lora-alliance.org/technical-specifications/lorawan-specification-v1-1) + [FCntDwn ERRATA](https://resources.lora-alliance.org/technical-specifications/fopts-encryption-usage-of-fcntdwn-errata-on-the-lorawan-l2-1-1-specification) | [2-1.0.3](https://resources.lora-alliance.org/technical-specifications/rp2-1-0-3-lorawan-regional-parameters) | [v4.7.0](https://github.com/Lora-net/LoRaMac-node/milestone/10) | A/B/C | LoRaWAN L2 1.0.4 / 1.1.0 | 27| [v5.0.0-branch](https://github.com/Lora-net/LoRaMac-node/tree/v5.0.0-branch) | [1.0.4](https://resources.lora-alliance.org/technical-specifications/ts001-1-0-4-lorawan-l2-1-0-4-specification) / [1.1.0](https://resources.lora-alliance.org/technical-specifications/lorawan-specification-v1-1) + [FCntDwn ERRATA](https://resources.lora-alliance.org/technical-specifications/fopts-encryption-usage-of-fcntdwn-errata-on-the-lorawan-l2-1-1-specification) | [2-1.0.3](https://resources.lora-alliance.org/technical-specifications/rp2-1-0-3-lorawan-regional-parameters) | [M 5.0.0](https://github.com/Lora-net/LoRaMac-node/milestone/11) | A/B/C | LoRaWAN L2 1.0.4 / 1.1.0 - Adds support for LR-FHSS modulation | 28 29This project fully implements ClassA, ClassB and ClassC end-device classes and it also provides SX1272/73, SX1276/77/78/79, SX1261/2 and LR1110 radio drivers. 30 31For each currently supported platform example applications are provided. 32 33* **LoRaMac/fuota-test-01**: FUOTA test scenario 01 end-device example application. (Based on provided application common packages) 34 35* **LoRaMac/periodic-uplink-lpp**: ClassA/B/C end-device example application. Periodically uplinks a frame using the Cayenne LPP protocol. (Based on provided application common packages) 36 37* **ping-pong**: Point to point RF link example application. 38 39* **rx-sensi**: Example application useful to measure the radio sensitivity level using an RF generator. 40 41* **tx-cw**: Example application to show how to generate an RF Continuous Wave transmission. 42 43**Note**: *Each LoRaWAN application example (LoRaMac/\*) includes an implementation of the LoRa-Alliance; LoRaWAN certification protocol.* 44 45**Note**: *The LoRaWAN stack API documentation can be found at: http://stackforce.github.io/LoRaMac-doc/* 46 47## Supported platforms 48 49This project currently provides support for the below platforms. 50This project can be ported to other platforms using different MCU than the ones currently supported. 51The [Porting Guide](https://stackforce.github.io/LoRaMac-doc/LoRaMac-doc-v4.7.0/_p_o_r_t_i_n_g__g_u_i_d_e.html) document provides guide lines on how to port the project to other platforms. 52 53* NAMote72 54 * [NAMote72 platform documentation](doc/NAMote72-platform.md) 55 56* NucleoLxxx - Discovery kit 57 * [NucleoLxxx and Discovery kit platforms documentation](doc/NucleoLxxx-platform.md) 58 59* SKiM880B, SKiM980A, SKiM881AXL 60 * [SKiM88xx platforms documentation](doc/SKiM88xx-platform.md) 61 62* SAMR34 63 * [SAMR34 platform documentation](doc/SAMR34-platform.md) 64 65## Getting Started 66 67### Prerequisites 68 69Please follow instructions provided by [Development environment](doc/development-environment.md) document. 70 71### Cloning the repository 72 73Clone the repository from GitHub 74 75```bash 76$ git clone https://github.com/lora-net/loramac-node.git loramac-node 77``` 78 79LoRaMac-node project contains Git submodules that must be initialized 80 81```bash 82$ cd loramac-node 83$ git submodule update --init 84``` 85 86### Secure-element commissioning 87 88This project currently supports 3 different secure-elements `soft-se`, `lr1110-se` 89and `atecc608a-tnglora-se` implementations. 90 91In order to personalize the MCU binary file with LoRaWAN EUIs or/and AES128 keys 92one must follow the instructions provided by [soft-se](####soft-se), 93 [lr1110-se](####lr1110-se) and [atecc608a-tnglora-se](####atecc608a-tnglora-se) chapters 94 95#### soft-se 96 97*soft-se* is a pure software emulation of a secure-element. It means that everything is located on the host MCU memories. The `DevEUI`, `JoinEUI` and `AES128 keys` may be stored on a non-volatile memory through dedicated APIs. 98 99In order to update the end-device identity (`DevEUI`, `JoinEUI` and `AES128 keys`) one must update the `se-identity.h` file located under `./src/peripherals/soft-se/` directory. 100 101**Note:** In previous versions of this project this was done inside `Commissioning.h` files located under each provided example directory. 102 103#### lr1110-se 104 105*lr1110-se* abstraction implementation handles all the required exchanges with the LR1110 radio crypto-engine. 106 107All LR1110 radio chips are pre-provisioned out of factory in order to be used with [LoRa Cloud Device Join Service](https://www.loracloud.com/documentation/join_service). 108 109In case other Join Servers are to be used the `DevEUI`, `Pin`, `JoinEUI` and `AES128 keys` can be updated by following the instructions provided on chapter "13. LR1110 Provisioning" of the [LR1110 User Manual](https://semtech.my.salesforce.com/sfc/p/#E0000000JelG/a/2R000000Q2PM/KGm1YHDoHhtaicNYHCIAnh0CbG3yodEuWWJ2WrFRafM). 110 111When the compile option `SECURE_ELEMENT_PRE_PROVISIONED` is set to `ON` the *lr1110-se* will use the factory provisioned data (`DevEUI`, `JoinEUI` and `AES128 keys`). 112When the compile option `SECURE_ELEMENT_PRE_PROVISIONED` is set to `OFF` the *lr1110-se* has to be provisioned by following one of the methods described on chapter "13. LR1110 Provisioning" of the [LR1110 User Manual](https://semtech.my.salesforce.com/sfc/p/#E0000000JelG/a/2R000000Q2PM/KGm1YHDoHhtaicNYHCIAnh0CbG3yodEuWWJ2WrFRafM). 113The `DevEUI`, `Pin` and `JoinEUI` can be changed by editing the `se-identity.h` file located in `./src/peripherals/lr1110-se/` directory. 114 115#### atecc608a-tnglora-se 116 117The *atecc608a-tnglora-se* abstraction implementation handles all the required exchanges with the ATECC608A-TNGLORA and ATECC608B-TNGLORA secure-elements. 118 119This secure-element is always pre-provisioned and its contents can't be changed. 120 121### Building Process 122 123#### Command line 124 125**periodic-uplink-lpp** example for NucleoL476 platform with LR1110MB1DIS MBED shield and using LR1110 pre-provisioned secure-element 126 127```bash 128$ mkdir build 129$ cd build 130$ cmake -DCMAKE_BUILD_TYPE=Release \ 131 -DTOOLCHAIN_PREFIX="<replace by toolchain path>" \ 132 -DCMAKE_TOOLCHAIN_FILE="../cmake/toolchain-arm-none-eabi.cmake" \ 133 -DAPPLICATION="LoRaMac" \ 134 -DSUB_PROJECT="periodic-uplink-lpp" \ 135 -DCLASSB_ENABLED="ON" \ 136 -DACTIVE_REGION="LORAMAC_REGION_EU868" \ 137 -DREGION_EU868="ON" \ 138 -DREGION_US915="OFF" \ 139 -DREGION_CN779="OFF" \ 140 -DREGION_EU433="OFF" \ 141 -DREGION_AU915="OFF" \ 142 -DREGION_AS923="OFF" \ 143 -DREGION_CN470="OFF" \ 144 -DREGION_KR920="OFF" \ 145 -DREGION_IN865="OFF" \ 146 -DREGION_RU864="OFF" \ 147 -DBOARD="NucleoL476" \ 148 -DMBED_RADIO_SHIELD="LR1110MB1XXS" \ 149 -DSECURE_ELEMENT="LR1110_SE" \ 150 -DSECURE_ELEMENT_PRE_PROVISIONED="ON" \ 151 -DUSE_RADIO_DEBUG="ON" .. 152$ make 153``` 154 155**ping-pong** example using LoRa modulation for NucleoL476 platform with LR1110MB1DIS MBED shield 156 157```bash 158$ mkdir build 159$ cd build 160$ cmake -DCMAKE_BUILD_TYPE=Release \ 161 -DTOOLCHAIN_PREFIX="<replace by toolchain path>" \ 162 -DCMAKE_TOOLCHAIN_FILE="../cmake/toolchain-arm-none-eabi.cmake" \ 163 -DAPPLICATION="ping-pong" \ 164 -DMODULATION:"LORA" \ 165 -DREGION_EU868="ON" \ 166 -DREGION_US915="OFF" \ 167 -DREGION_CN779="OFF" \ 168 -DREGION_EU433="OFF" \ 169 -DREGION_AU915="OFF" \ 170 -DREGION_AS923="OFF" \ 171 -DREGION_CN470="OFF" \ 172 -DREGION_KR920="OFF" \ 173 -DREGION_IN865="OFF" \ 174 -DREGION_RU864="OFF" \ 175 -DBOARD="NucleoL476" \ 176 -DMBED_RADIO_SHIELD="LR1110MB1XXS" \ 177 -DUSE_RADIO_DEBUG="ON" .. 178$ make 179``` 180 181#### VSCode 182 183**periodic-uplink-lpp** example for NucleoL476 platform with LR1110MB1DIS MBED shield and using LR1110 pre-provisioned secure-element 184 185* Please edit .vscode/settings.json file 186 187<details> 188 <summary>Click to expand!</summary> 189<p> 190 191```json 192// Place your settings in this file to overwrite default and user settings. 193{ 194 "cmake.configureSettings": { 195 196 // In case your GNU ARM-Toolchain is not installed under the default 197 // path: 198 // Windows : No default path. Specify the path where the 199 // toolchain is installed. i.e: 200 // "C:/PROGRA~2/GNUTOO~1/92019-~1". 201 // Linux : /usr 202 // OSX : /usr/local 203 // It is required to uncomment and to fill the following line. 204 "TOOLCHAIN_PREFIX":"/path/to/toolchain", 205 206 // In case your OpenOCD is not installed under the default path: 207 // Windows : C:/openocd/bin/openocd.exe 208 // Linux : /usr/bin/openocd 209 // OSX : /usr/local/bin/openocd 210 // Please uncomment the following line and fill it accordingly. 211 //"OPENOCD_BIN":"C:/openocd/bin/openocd.exe", 212 213 // Specifies the path to the CMAKE toolchain file. 214 "CMAKE_TOOLCHAIN_FILE":"cmake/toolchain-arm-none-eabi.cmake", 215 216 // Determines the application. You can choose between: 217 // LoRaMac (Default), ping-pong, rx-sensi, tx-cw. 218 "APPLICATION":"LoRaMac", 219 220 // Select LoRaMac sub project. You can choose between: 221 // periodic-uplink-lpp, fuota-test-01. 222 "SUB_PROJECT":"periodic-uplink-lpp", 223 224 // Switch for Class B support of LoRaMac: 225 "CLASSB_ENABLED":"ON", 226 227 // Select the active region for which the stack will be initialized. 228 // You can choose between: 229 // LORAMAC_REGION_EU868, LORAMAC_REGION_US915, .. 230 "ACTIVE_REGION":"LORAMAC_REGION_EU868", 231 232 // Select the type of modulation, applicable to the ping-pong or 233 // rx-sensi applications. You can choose between: 234 // LORA or FSK 235 "MODULATION":"LORA", 236 237 // Target board, the following boards are supported: 238 // NAMote72, NucleoL073 (Default), NucleoL152, NucleoL476, SAMR34, SKiM880B, SKiM980A, SKiM881AXL, B-L072Z-LRWAN1. 239 "BOARD":"NucleoL476", 240 241 // MBED Radio shield selection. (Applies only to Nucleo platforms) 242 // The following shields are supported: 243 // SX1272MB2DAS, SX1276MB1LAS, SX1276MB1MAS, SX1261MBXBAS(Default), SX1262MBXCAS, SX1262MBXDAS, LR1110MB1XXS. 244 "MBED_RADIO_SHIELD":"LR1110MB1XXS", 245 246 // Secure element type selection the following are supported 247 // SOFT_SE(Default), LR1110_SE, ATECC608A_TNGLORA_SE 248 "SECURE_ELEMENT":"LR1110_SE", 249 250 // Secure element is pre-provisioned 251 "SECURE_ELEMENT_PRE_PROVISIONED":"ON", 252 253 // Region support activation, Select the ones you want to support. 254 // By default only REGION_EU868 support is enabled. 255 "REGION_EU868":"ON", 256 "REGION_US915":"OFF", 257 "REGION_CN779":"OFF", 258 "REGION_EU433":"OFF", 259 "REGION_AU915":"OFF", 260 "REGION_AS923":"OFF", 261 "REGION_CN470":"OFF", 262 "REGION_KR920":"OFF", 263 "REGION_IN865":"OFF", 264 "REGION_RU864":"OFF", 265 "USE_RADIO_DEBUG":"ON" 266 } 267} 268``` 269 270</p> 271</details> 272 273* Click on "CMake: Debug: Ready" and select build type Debug or Release. 274 275* Wait for configuration process to finish 276* Click on "Build" to build the project. 277 278* Wait for build process to finish 279* Binary files will be available under `./build/src/apps/LoRaMac/` 280 * LoRaMac-periodic-uplink-lpp - elf format 281 * LoRaMac-periodic-uplink-lpp.bin - binary format 282 * LoRaMac-periodic-uplink-lpp.hex - hex format 283 284**ping-pong** example using LoRa modulation for NucleoL476 platform with LR1110MB1DIS MBED shield 285 286* Please edit .vscode/settings.json file 287 288<details> 289 <summary>Click to expand!</summary> 290<p> 291 292```json 293// Place your settings in this file to overwrite default and user settings. 294{ 295 "cmake.configureSettings": { 296 297 // In case your GNU ARM-Toolchain is not installed under the default 298 // path: 299 // Windows : No default path. Specify the path where the 300 // toolchain is installed. i.e: 301 // "C:/PROGRA~2/GNUTOO~1/92019-~1". 302 // Linux : /usr 303 // OSX : /usr/local 304 // It is required to uncomment and to fill the following line. 305 "TOOLCHAIN_PREFIX":"/path/to/toolchain", 306 307 // In case your OpenOCD is not installed under the default path: 308 // Windows : C:/openocd/bin/openocd.exe 309 // Linux : /usr/bin/openocd 310 // OSX : /usr/local/bin/openocd 311 // Please uncomment the following line and fill it accordingly. 312 //"OPENOCD_BIN":"C:/openocd/bin/openocd.exe", 313 314 // Specifies the path to the CMAKE toolchain file. 315 "CMAKE_TOOLCHAIN_FILE":"cmake/toolchain-arm-none-eabi.cmake", 316 317 // Determines the application. You can choose between: 318 // LoRaMac (Default), ping-pong, rx-sensi, tx-cw. 319 "APPLICATION":"ping-pong", 320 321 // Select LoRaMac sub project. You can choose between: 322 // periodic-uplink-lpp, fuota-test-01. 323 "SUB_PROJECT":"periodic-uplink-lpp", 324 325 // Switch for Class B support of LoRaMac: 326 "CLASSB_ENABLED":"ON", 327 328 // Select the active region for which the stack will be initialized. 329 // You can choose between: 330 // LORAMAC_REGION_EU868, LORAMAC_REGION_US915, .. 331 "ACTIVE_REGION":"LORAMAC_REGION_EU868", 332 333 // Select the type of modulation, applicable to the ping-pong or 334 // rx-sensi applications. You can choose between: 335 // LORA or FSK 336 "MODULATION":"LORA", 337 338 // Target board, the following boards are supported: 339 // NAMote72, NucleoL073 (Default), NucleoL152, NucleoL476, SAMR34, SKiM880B, SKiM980A, SKiM881AXL, B-L072Z-LRWAN1. 340 "BOARD":"NucleoL476", 341 342 // MBED Radio shield selection. (Applies only to Nucleo platforms) 343 // The following shields are supported: 344 // SX1272MB2DAS, SX1276MB1LAS, SX1276MB1MAS, SX1261MBXBAS(Default), SX1262MBXCAS, SX1262MBXDAS, LR1110MB1XXS. 345 "MBED_RADIO_SHIELD":"SX1261MBXBAS", 346 347 // Secure element type selection the following are supported 348 // SOFT_SE(Default), LR1110_SE, ATECC608A_TNGLORA_SE 349 "SECURE_ELEMENT":"SOFT_SE", 350 351 // Secure element is pre-provisioned 352 "SECURE_ELEMENT_PRE_PROVISIONED":"ON", 353 354 // Region support activation, Select the ones you want to support. 355 // By default only REGION_EU868 support is enabled. 356 "REGION_EU868":"ON", 357 "REGION_US915":"OFF", 358 "REGION_CN779":"OFF", 359 "REGION_EU433":"OFF", 360 "REGION_AU915":"OFF", 361 "REGION_AS923":"OFF", 362 "REGION_CN470":"OFF", 363 "REGION_KR920":"OFF", 364 "REGION_IN865":"OFF", 365 "REGION_RU864":"OFF", 366 "USE_RADIO_DEBUG":"ON" 367 } 368} 369``` 370 371</p> 372</details> 373 374* Click on "CMake: Debug: Ready" and select build type Debug or Release. 375 376* Wait for configuration process to finish 377* Click on "Build" to build the project. 378 379* Wait for build process to finish 380* Binary files will be available under `./build/src/apps/ping-pong/` 381 * ping-pong - elf format 382 * ping-pong.bin - binary format 383 * ping-pong.hex - hex format 384 385### Serial console NVM management 386 387The `periodic-uplink-lpp` and `fuota-test-01` examples allow to reset the NVM storage through the serial interface. 388 389In order to reset the NVM contents one must hit `ESC` + `N` keyboard keys on a serial terminal. 390 391The serial terminal will show the following after `ESC` + `N` keyboard keys are hit. After reseting the end-device the clean NVM will be used. 392 393```text 394ESC + N 395 396 397NVM factory reset succeed 398 399 400PLEASE RESET THE END-DEVICE 401``` 402 403## Acknowledgments 404 405* The mbed (https://mbed.org/) project was used at the beginning as source of 406inspiration. 407* This program uses the AES algorithm implementation (http://www.gladman.me.uk/) by Brian Gladman. 408* This program uses the CMAC algorithm implementation 409(http://www.cse.chalmers.se/research/group/dcs/masters/contikisec/) by Lander Casado, Philippas Tsigas. 410* [The Things Industries](https://www.thethingsindustries.com/) for providing 411 Microchip/Atmel SAMR34 platform and ATECC608A-TNGLORA secure-element support. 412* Tencent Blade Team for security breach findings and solving propositions. 413
