Skip to content

Commit

Permalink
Replaced "Usage" by "Getting Started chapter".
Browse files Browse the repository at this point in the history
  • Loading branch information
@mluis1
mluis1 committed Apr 17, 2020
1 parent 64a4716 commit d3791e2
Show file tree
Hide file tree
Showing 4 changed files with 329 additions and 18 deletions.
2 changes: 1 addition & 1 deletion .vscode/settings.json
View file
Expand Up @@ -52,7 +52,7 @@
// SX1272MB2DAS, SX1276MB1LAS, SX1276MB1MAS, SX1261MBXBAS(Default), SX1262MBXCAS, SX1262MBXDAS, LR1110MB1XXS.
"MBED_RADIO_SHIELD":"SX1261MBXBAS",

// Secure element type selection the follwing are supported
// Secure element type selection the following are supported
// SOFT_SE(Default), LR1110_SE, ATECC608A_TNGLORA_SE
"SECURE_ELEMENT":"SOFT_SE",

Expand Down
Binary file added Doc/images/vscode-cmake-build.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Doc/images/vscode-cmake-configure.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
345 changes: 328 additions & 17 deletions readme.md
View file
@@ -1,12 +1,12 @@
# LoRaWAN endpoint stack implementation and example projects
# LoRaWAN end-device stack implementation and example projects

______ _
/ _____) _ | |
( (____ _____ ____ _| |_ _____ ____| |__
\____ \| ___ | (_ _) ___ |/ ___) _ \
_____) ) ____| | | || |_| ____( (___| | | |
(______/|_____)_|_|_| \__)_____)\____)_| |_|
(C)2013-2019 Semtech
(C)2013-2020 Semtech

___ _____ _ ___ _ _____ ___ ___ ___ ___
/ __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __|
Expand All @@ -16,20 +16,17 @@

## Introduction

The aim of this project is to show an example of the endpoint LoRaWAN stack implementation.
The aim of this project is to show an example of an end-device LoRaWAN stack implementation.

This project has 3 active branches in place. The **[master](https://github.com/Lora-net/LoRaMac-node/tree/master)** branch which provides the latest released source code ([v4.4.3](https://github.com/Lora-net/LoRaMac-node/releases/tag/v4.4.3)), the **[develop](https://github.com/Lora-net/LoRaMac-node/tree/develop)** branch which provides the current source code development status to be released next ([Milestone 4.4.4](https://github.com/Lora-net/LoRaMac-node/milestone/6)) and the **[feature/5.0.0](https://github.com/Lora-net/LoRaMac-node/tree/feature/5.0.0)** branch which provides a preview of the current source code development status for [LoRaWAN Specification v1.1](https://lora-alliance.org/resource-hub/lorawantm-specification-v11) specification.([Milestone 5.0.0](https://github.com/Lora-net/LoRaMac-node/milestone/3))
This project has 3 active branches in place.

* The [master](https://github.com/Lora-net/LoRaMac-node/tree/master) branch implementation is based on [LoRaWAN Specification v1.0.3](https://lora-alliance.org/resource-hub/lorawantm-specification-v103) and [LoRaWAN Regional Parameters v1.0.3revA](https://www.lora-alliance.org/resource-hub/lorawantm-regional-parameters-v103reva) specifications.
ClassA, ClassB and ClassC end-device classes are fully implemented.
| Branch | L2 spec | RP spec | Tag/Milestone | Class | Comments |
| ------------- |:-------------:|:---------:|:---------:|:---------:|:--------------|
| [master](https://github.com/Lora-net/LoRaMac-node/tree/master) | [1.0.3](https://lora-alliance.org/resource-hub/lorawantm-specification-v103) | [v1.0.3revA](https://www.lora-alliance.org/resource-hub/lorawantm-regional-parameters-v103reva) | [v4.4.3](https://github.com/Lora-net/LoRaMac-node/releases/tag/v4.4.3) | A/B/C | Released |
| [develop](https://github.com/Lora-net/LoRaMac-node/tree/develop) | [1.0.3](https://lora-alliance.org/resource-hub/lorawantm-specification-v103) | [v1.0.3revA](https://www.lora-alliance.org/resource-hub/lorawantm-regional-parameters-v103reva) | [M 4.4.4](https://github.com/Lora-net/LoRaMac-node/milestone/6) | A/B/C | Next release |
| [feature/5.0.0](https://github.com/Lora-net/LoRaMac-node/tree/feature/5.0.0) | [1.1.1](https://lora-alliance.org/resource-hub/lorawantm-specification-v11) | [v1.1.0rB](https://lora-alliance.org/resource-hub/lorawantm-regional-parameters-v11rb) | [M 5.0.0](https://github.com/Lora-net/LoRaMac-node/milestone/3) | A/B/C | LoRaWAN 1.1.1 preview |

* The [develop](https://github.com/Lora-net/LoRaMac-node/tree/develop) branch implementation is based on [LoRaWAN Specification v1.0.3](https://lora-alliance.org/resource-hub/lorawantm-specification-v103) and [LoRaWAN Regional Parameters v1.0.3revA](https://lora-alliance.org/resource-hub/lorawan-regional-parameters-v103reva) specifications.
ClassA, ClassB and ClassC end-device classes are fully implemented.

* The [feature/5.0.0](https://github.com/Lora-net/LoRaMac-node/tree/feature/5.0.0) branch implementation is based on [LoRaWAN Specification v1.1](https://lora-alliance.org/resource-hub/lorawantm-specification-v11) and [LoRaWAN Regional Parameters v1.1rB](https://lora-alliance.org/resource-hub/lorawantm-regional-parameters-v11rb) specifications.
ClassA, ClassB and ClassC end-device classes are fully implemented.

This project also provides SX1272/73, SX1276/77/78/79 and SX1261/2 radio drivers.
This 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.

For each currently supported platform example applications are provided.

Expand All @@ -49,7 +46,7 @@ For each currently supported platform example applications are provided.

* **tx-cw**: Example application to show how to generate an RF Continuous Wave transmission.

**Note**: *Each LoRaWAN application example (LoRaMac/classX) includes an implementation of the LoRa-Alliance; LoRaWAN certification protocol.*
**Note**: *Each LoRaWAN application example (LoRaMac/\*) includes an implementation of the LoRa-Alliance; LoRaWAN certification protocol.*

**Note**: *The LoRaWAN stack API documentation can be found at: http://stackforce.github.io/LoRaMac-doc/*

Expand All @@ -71,11 +68,325 @@ The [Porting Guide](http://stackforce.github.io/LoRaMac-doc/_p_o_r_t_i_n_g__g_u_
* SAMR34
* [SAMR34 platform documentation](Doc/SAMR34-platform.md)

## Usage
## Getting Started

### Prerequisites

Please follow instructions provided by [Development environment](Doc/development-environment.md) document.

### Cloning the repository

Clone the repository from GitHub

```bash
$ git clone https://github.com/lora-net/loramac-node.git loramac-node
```

LoRaMac-node project contains Git submodules that must be initialized

```bash
$ cd loramac-node
$ git submodule update --init
```

### Secure-element commissioning

This project currently supports 3 different secure-elements `soft-se`, `lr1110-se`
and `atecc608a-tnglora-se` implementations.

In order to personalize the MCU binary file with LoRaWAN EUIs or/and AES128 keys
one must follow the instructions provided by [soft-se](####soft-se),
[lr1110-se](####lr1110-se) and [atecc608a-tnglora-se](####atecc608a-tnglora-se) chapters

#### soft-se

*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.

In 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.

**Note:** In previous versions of this project this was done inside `Commissioning.h` files located under each provided example directory.

#### lr1110-se

*lr1110-se* abstraction implementation handles all the required exchanges with the LR1110 radio crypto-engine.

All 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).

In 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).

When 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`).
When 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).
The `DevEUI`, `Pin` and `JoinEUI` can be changed by editing the `se-identity.h` file located in `./src/peripherals/lr1110-se/` directory.

#### atecc608a-tnglora-se

The *atecc608a-tnglora-se* abstraction implmentation handles all the required exchanges with the ATECC608A-TNGLORA secure-element.

ATECC608A-TNGLORA secure-element is always pre-provisioned and its contents can't be changed.

### Building Process

#### Command line

**periodic-uplink-lpp** example for NucleoL476 platform with LR1110MB1DIS MBED shield and using LR1110 pre-provisioned secure-element

A CMAKE building system is used in order to generate the right set of files to compile and debug the different projects.
```bash
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Release \
-DTOOLCHAIN_PREFIX="<replace by toolchain path>" \
-DCMAKE_TOOLCHAIN_FILE="../cmake/toolchain-arm-none-eabi.cmake" \
-DAPPLICATION="LoRaMac" \
-DSUB_PROJECT="periodic-uplink-lpp" \
-DCLASSB_ENABLED="ON" \
-DACTIVE_REGION="LORAMAC_REGION_EU868" \
-DREGION_EU868="ON" \
-DREGION_US915="OFF" \
-DREGION_CN779="OFF" \
-DREGION_EU433="OFF" \
-DREGION_AU915="OFF" \
-DREGION_AS923="OFF" \
-DREGION_CN470="OFF" \
-DREGION_KR920="OFF" \
-DREGION_IN865="OFF" \
-DREGION_RU864="OFF" \
-DBOARD="NucleoL476" \
-DMBED_RADIO_SHIELD="LR1110MB1XXS" \
-DSECURE_ELEMENT="LR1110_SE" \
-DSECURE_ELEMENT_PRE_PROVISIONED="ON" \
-DUSE_RADIO_DEBUG="ON" ..
$ make
```

Further information can be found in [Development environment](Doc/development-environment.md) document.
**ping-pong** example using LoRa modulation for NucleoL476 platform with LR1110MB1DIS MBED shield

```bash
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Release \
-DTOOLCHAIN_PREFIX="<replace by toolchain path>" \
-DCMAKE_TOOLCHAIN_FILE="../cmake/toolchain-arm-none-eabi.cmake" \
-DAPPLICATION="ping-pong" \
-DMODULATION:"LORA" \
-DREGION_EU868="ON" \
-DREGION_US915="OFF" \
-DREGION_CN779="OFF" \
-DREGION_EU433="OFF" \
-DREGION_AU915="OFF" \
-DREGION_AS923="OFF" \
-DREGION_CN470="OFF" \
-DREGION_KR920="OFF" \
-DREGION_IN865="OFF" \
-DREGION_RU864="OFF" \
-DBOARD="NucleoL476" \
-DMBED_RADIO_SHIELD="LR1110MB1XXS" \
-DUSE_RADIO_DEBUG="ON" ..
$ make
```

#### VSCode

**periodic-uplink-lpp** example for NucleoL476 platform with LR1110MB1DIS MBED shield and using LR1110 pre-provisioned secure-element

* Please edit .vscode/settings.json file

<details>
<summary>Click to expand!</summary>
<p>

```json
// 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/92019-~1".
// 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.
"APPLICATION":"LoRaMac",

// Select LoRaMac sub project. You can choose between:
// classA, classB or classC, periodic-uplink-lpp, fuota-test-01.
"SUB_PROJECT":"periodic-uplink-lpp",

// Switch for Class B support of LoRaMac:
"CLASSB_ENABLED":"ON",

// 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:
// NAMote72, NucleoL073 (Default), NucleoL152, NucleoL476, SAMR34, SKiM880B, SKiM980A, SKiM881AXL, B-L072Z-LRWAN1.
"BOARD":"NucleoL476",

// MBED Radio shield selection. (Applies only to Nucleo platforms)
// The following shields are supported:
// SX1272MB2DAS, SX1276MB1LAS, SX1276MB1MAS, SX1261MBXBAS(Default), SX1262MBXCAS, SX1262MBXDAS, LR1110MB1XXS.
"MBED_RADIO_SHIELD":"LR1110MB1XXS",

// Secure element type selection the following are supported
// SOFT_SE(Default), LR1110_SE, ATECC608A_TNGLORA_SE
"SECURE_ELEMENT":"LR1110_SE",

// Secure element is pre-provisioned
"SECURE_ELEMENT_PRE_PROVISIONED":"ON",

// 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_RU864":"OFF",
"USE_RADIO_DEBUG":"ON"
}
}
```

</p>
</details>

* Click on "CMake: Debug: Ready" and select build type Debug or Release.
![cmake configure](Doc/images/vscode-cmake-configure.png)
* Wait for configuration process to finish
* Click on "Build" to build the project.
![cmake build](Doc/images/vscode-cmake-build.png)
* Wait for build process to finish
* Binary files will be available under `./build/src/apps/LoRaMac/`
* LoRaMac-periodic-uplink-lpp - elf format
* LoRaMac-periodic-uplink-lpp.bin - binary format
* LoRaMac-periodic-uplink-lpp.hex - hex format

**ping-pong** example using LoRa modulation for NucleoL476 platform with LR1110MB1DIS MBED shield

* Please edit .vscode/settings.json file

<details>
<summary>Click to expand!</summary>
<p>

```json
// 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/92019-~1".
// 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.
"APPLICATION":"ping-pong",

// Select LoRaMac sub project. You can choose between:
// classA, classB or classC, periodic-uplink-lpp, fuota-test-01.
"SUB_PROJECT":"periodic-uplink-lpp",

// Switch for Class B support of LoRaMac:
"CLASSB_ENABLED":"ON",

// 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:
// NAMote72, NucleoL073 (Default), NucleoL152, NucleoL476, SAMR34, SKiM880B, SKiM980A, SKiM881AXL, B-L072Z-LRWAN1.
"BOARD":"NucleoL476",

// MBED Radio shield selection. (Applies only to Nucleo platforms)
// The following shields are supported:
// SX1272MB2DAS, SX1276MB1LAS, SX1276MB1MAS, SX1261MBXBAS(Default), SX1262MBXCAS, SX1262MBXDAS, LR1110MB1XXS.
"MBED_RADIO_SHIELD":"SX1261MBXBAS",

// Secure element type selection the following are supported
// SOFT_SE(Default), LR1110_SE, ATECC608A_TNGLORA_SE
"SECURE_ELEMENT":"SOFT_SE",

// Secure element is pre-provisioned
"SECURE_ELEMENT_PRE_PROVISIONED":"ON",

// 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_RU864":"OFF",
"USE_RADIO_DEBUG":"ON"
}
}
```

</p>
</details>

* Click on "CMake: Debug: Ready" and select build type Debug or Release.
![cmake configure](Doc/images/vscode-cmake-configure.png)
* Wait for configuration process to finish
* Click on "Build" to build the project.
![cmake build](Doc/images/vscode-cmake-build.png)
* Wait for build process to finish
* Binary files will be available under `./build/src/apps/ping-pong/`
* ping-pong - elf format
* ping-pong.bin - binary format
* ping-pong.hex - hex format

## Acknowledgments

Expand Down

0 comments on commit d3791e2

Please sign in to comment.