README.md
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
