This is an example application based on Mbed-OS LoRaWAN protocol APIs. The Mbed-OS LoRaWAN stack implementation is compliant with LoRaWAN v1.0.2 specification.

Dependents:   Projet_de_bachelor_code Projet_de_bachelor_code

Example LoRaWAN application for Mbed-OS

This is an example application based on Mbed-OS LoRaWAN protocol APIs. The Mbed-OS LoRaWAN stack implementation is compliant with LoRaWAN v1.0.2 specification. See this link for information on support for other LoRaWAN spec versions. This application can work with any Network Server if you have correct credentials for the said Network Server.

Getting Started

Supported Hardware

Mbed Enabled board with an Arduino form factor and one of the following:

OR

Mbed Enabled LoRa Module

Import the example application

For Mbed Online Compiler users:

  • Select "Import", then search for "mbed-os-example-lorawan" from "Team mbed-os-examples". Or simply, import this repo by URL.
  • NOTE: Do NOT select "Update all libraries to latest revision" as this may cause breakage with a new lib version we have not tested.

For mbed-cli users:

$ mbed import mbed-os-example-lorawan
$ cd mbed-os-example-lorawan

#OR

$ git clone git@github.com:ARMmbed/mbed-os-example-lorawan.git
$ cd mbed-os-example-lorawan
$ mbed deploy

Example configuration and radio selection

Because of the pin differences between the SX126x and SX127x radios, example application configuration files are provided with the correct pin sets in the config/ dir of this project.

Please start by selecting the correct example configuration for your radio:

  • For Mbed Online Compiler users, this can be done by simply replacing the contents of the mbed_app.json at the root of the project with the content of the correct example configuration in config/ dir.
  • For mbed-cli users, the config file can be specifed on the command line with the --app-config option (ie --app-config config/SX12xx_example_config.json)

With the correct config file selected, the user can then provide a pin set for their target board in the NC fields at the top if it is different from the default targets listed. If your device is one of the LoRa modules supported by Mbed-OS, the pin set is already provided for the modules in the target-overrides field of the config file. For more information on supported modules, please refer to the module support section

Add network credentials

Open the file mbed_app.json in the root directory of your application. This file contains all the user specific configurations your application and the Mbed OS LoRaWAN stack need. Network credentials are typically provided by LoRa network provider.

For OTAA

Please add Device EUI, Application EUI and Application Key needed for Over-the-air-activation(OTAA). For example:

"lora.device-eui": "{ YOUR_DEVICE_EUI }",
"lora.application-eui": "{ YOUR_APPLICATION_EUI }",
"lora.application-key": "{ YOUR_APPLICATION_KEY }"

For ABP

For Activation-By-Personalization (ABP) connection method, modify the mbed_app.json to enable ABP. You can do it by simply turning off OTAA. For example:

"lora.over-the-air-activation": false,

In addition to that, you need to provide Application Session Key, Network Session Key and Device Address. For example:

"lora.appskey": "{ YOUR_APPLICATION_SESSION_KEY }",
"lora.nwkskey": "{ YOUR_NETWORK_SESSION_KEY }",
"lora.device-address": " YOUR_DEVICE_ADDRESS_IN_HEX  " 

Configuring the application

The Mbed OS LoRaWAN stack provides a lot of configuration controls to the application through the Mbed OS configuration system. The previous section discusses some of these controls. This section highlights some useful features that you can configure.

Selecting a PHY

The LoRaWAN protocol is subject to various country specific regulations concerning radio emissions. That's why the Mbed OS LoRaWAN stack provides a LoRaPHY class that you can use to implement any region specific PHY layer. Currently, the Mbed OS LoRaWAN stack provides 10 different country specific implementations of LoRaPHY class. Selection of a specific PHY layer happens at compile time. By default, the Mbed OS LoRaWAN stack uses EU 868 MHz PHY. An example of selecting a PHY can be:

        "phy": {
            "help": "LoRa PHY region. 0 = EU868 (default), 1 = AS923, 2 = AU915, 3 = CN470, 4 = CN779, 5 = EU433, 6 = IN865, 7 = KR920, 8 = US915, 9 = US915_HYBRID",
            "value": "0"
        },

Duty cycling

LoRaWAN v1.0.2 specifcation is exclusively duty cycle based. This application comes with duty cycle enabled by default. In other words, the Mbed OS LoRaWAN stack enforces duty cycle. The stack keeps track of transmissions on the channels in use and schedules transmissions on channels that become available in the shortest time possible. We recommend you keep duty cycle on for compliance with your country specific regulations.

However, you can define a timer value in the application, which you can use to perform a periodic uplink when the duty cycle is turned off. Such a setup should be used only for testing or with a large enough timer value. For example:

"target_overrides": {
	"*": {
		"lora.duty-cycle-on": false
		},
	}
}

Module support

Here is a nonexhaustive list of boards and modules that we have tested with the Mbed OS LoRaWAN stack:

  • MultiTech mDot (SX1272)
  • MultiTech xDot (SX1272)
  • LTEK_FF1705 (SX1272)
  • Advantech Wise 1510 (SX1276)
  • ST B-L072Z-LRWAN1 LoRa®Discovery kit with Murata CMWX1ZZABZ-091 module (SX1276)

Here is a list of boards and modules that have been tested by the community:

  • IMST iM880B (SX1272)
  • Embedded Planet Agora (SX1276)

Compiling the application

Use Mbed CLI commands to generate a binary for the application. For example:

$ mbed compile -m YOUR_TARGET -t ARM

Running the application

Drag and drop the application binary from BUILD/YOUR_TARGET/ARM/mbed-os-example-lora.bin to your Mbed enabled target hardware, which appears as a USB device on your host machine.

Attach a serial console emulator of your choice (for example, PuTTY, Minicom or screen) to your USB device. Set the baudrate to 115200 bit/s, and reset your board by pressing the reset button.

You should see an output similar to this:

Mbed LoRaWANStack initialized 

 CONFIRMED message retries : 3 

 Adaptive data  rate (ADR) - Enabled 

 Connection - In Progress ...

 Connection - Successful 

 Dummy Sensor Value = 2.1 

 25 bytes scheduled for transmission 
 
 Message Sent to Network Server

Adding trace library

To enable Mbed trace, add to your mbed_app.json the following fields:

    "target_overrides": {
        "*": {
            "mbed-trace.enable": true
            }
     }

The trace is disabled by default to save RAM and reduce main stack usage (see chapter Memory optimization).

Please note that some targets with small RAM size (e.g. DISCO_L072CZ_LRWAN1 and MTB_MURATA_ABZ) mbed traces cannot be enabled without increasing the default "main_stack_size": 1024.

Memory optimization

Using Arm CC compiler instead of GCC reduces 3K of RAM. Currently the application takes about 15K of static RAM with Arm CC, which spills over for the platforms with 20K of RAM because you need to leave space, about 5K, for dynamic allocation. So if you reduce the application stack size, you can barely fit into the 20K platforms.

For example, add the following into config section in your mbed_app.json:

"main_stack_size": {
    "value": 2048
}

Essentially you can make the whole application with Mbed LoRaWAN stack in 6K if you drop the RTOS from Mbed OS and use a smaller standard C/C++ library like new-lib-nano. Please find instructions here.

For more information, please follow this blog post.

License and contributions

The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see contributing.md for more info.

This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide.

Committer:
mbed_official
Date:
Mon Sep 03 08:45:34 2018 +0100
Revision:
35:462743fb571e
Parent:
20:2055271192d6
Child:
38:315a26cd0165
Merge pull request #97 from ARMmbed/jenkinsfile_update

Disabled ARMC6, enabled MTB_RAK811
.
Commit copied from https://github.com/ARMmbed/mbed-os-example-lorawan

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 10:b6d8d4e1cc57 1 properties ([[$class: 'ParametersDefinitionProperty', parameterDefinitions: [
mbed_official 20:2055271192d6 2 [$class: 'StringParameterDefinition', name: 'mbed_os_revision', defaultValue: '', description: 'Revision of mbed-os to build. To access mbed-os PR use format "pull/PR number/head"'],
mbed_official 20:2055271192d6 3 [$class: 'BooleanParameterDefinition', name: 'regions_build_test', defaultValue: true, description: 'Test build all available regions']
mbed_official 10:b6d8d4e1cc57 4 ]]])
mbed_official 10:b6d8d4e1cc57 5
mbed_official 35:462743fb571e 6 library 'mbed-lib'
mbed_official 35:462743fb571e 7
mbed_official 10:b6d8d4e1cc57 8 if (env.MBED_OS_REVISION == null) {
mbed_official 10:b6d8d4e1cc57 9 echo 'First run in this branch, using default parameter values'
mbed_official 10:b6d8d4e1cc57 10 env.MBED_OS_REVISION = ''
mbed_official 10:b6d8d4e1cc57 11 }
mbed_official 10:b6d8d4e1cc57 12 if (env.MBED_OS_REVISION == '') {
mbed_official 10:b6d8d4e1cc57 13 echo 'Using mbed OS revision from mbed-os.lib'
mbed_official 10:b6d8d4e1cc57 14 } else {
mbed_official 10:b6d8d4e1cc57 15 echo "Using given mbed OS revision: ${env.MBED_OS_REVISION}"
mbed_official 10:b6d8d4e1cc57 16 if (env.MBED_OS_REVISION.matches('pull/\\d+/head')) {
mbed_official 10:b6d8d4e1cc57 17 echo "Revision is a Pull Request"
mbed_official 10:b6d8d4e1cc57 18 }
mbed_official 10:b6d8d4e1cc57 19 }
mbed_official 10:b6d8d4e1cc57 20
mbed_official 20:2055271192d6 21 // All available regions
mbed_official 20:2055271192d6 22 def regions = [
mbed_official 20:2055271192d6 23 "\"0\"", "\"1\"", "\"2\"", "\"3\"", "\"4\"", "\"5\"", "\"6\"", "\"7\"", "\"8\"", "\"9\"",
mbed_official 20:2055271192d6 24 "\"EU868\"", "\"AS923\"", "\"AU915\"", "\"CN470\"", "\"CN779\"", "\"EU433\"",
mbed_official 20:2055271192d6 25 "\"IN865\"", "\"KR920\"", "\"US915\"", "\"US915_HYBRID\""
mbed_official 20:2055271192d6 26 ]
mbed_official 20:2055271192d6 27
mbed_official 10:b6d8d4e1cc57 28 // Supported targets
mbed_official 10:b6d8d4e1cc57 29 def targets = [
mbed_official 10:b6d8d4e1cc57 30 "K64F",
mbed_official 10:b6d8d4e1cc57 31 "MTB_MTS_XDOT",
mbed_official 10:b6d8d4e1cc57 32 "MTB_MURATA_ABZ",
mbed_official 10:b6d8d4e1cc57 33 "MTS_MDOT_F411RE",
mbed_official 10:b6d8d4e1cc57 34 "DISCO_L072CZ_LRWAN1",
mbed_official 35:462743fb571e 35 "MTB_ADV_WISE_1510",
mbed_official 35:462743fb571e 36 "MTB_RAK811"
mbed_official 10:b6d8d4e1cc57 37 ]
mbed_official 10:b6d8d4e1cc57 38
mbed_official 10:b6d8d4e1cc57 39 // Map toolchains to compilers
mbed_official 10:b6d8d4e1cc57 40 def toolchains = [
mbed_official 10:b6d8d4e1cc57 41 ARM: "armcc",
mbed_official 10:b6d8d4e1cc57 42 GCC_ARM: "arm-none-eabi-gcc",
mbed_official 35:462743fb571e 43 IAR: "iar_arm"
mbed_official 35:462743fb571e 44 //ARMC6: "arm6"
mbed_official 10:b6d8d4e1cc57 45 ]
mbed_official 10:b6d8d4e1cc57 46
mbed_official 10:b6d8d4e1cc57 47 def stepsForParallel = [:]
mbed_official 10:b6d8d4e1cc57 48
mbed_official 10:b6d8d4e1cc57 49 // Jenkins pipeline does not support map.each, we need to use oldschool for loop
mbed_official 10:b6d8d4e1cc57 50 for (int i = 0; i < targets.size(); i++) {
mbed_official 10:b6d8d4e1cc57 51 for(int j = 0; j < toolchains.size(); j++) {
mbed_official 10:b6d8d4e1cc57 52 def target = targets.get(i)
mbed_official 10:b6d8d4e1cc57 53 def toolchain = toolchains.keySet().asList().get(j)
mbed_official 10:b6d8d4e1cc57 54 def compilerLabel = toolchains.get(toolchain)
mbed_official 10:b6d8d4e1cc57 55
mbed_official 10:b6d8d4e1cc57 56 // Skip unwanted combination
mbed_official 10:b6d8d4e1cc57 57 if (target == "MTB_MURATA_ABZ" && toolchain == "GCC_ARM") {
mbed_official 10:b6d8d4e1cc57 58 continue
mbed_official 10:b6d8d4e1cc57 59 }
mbed_official 10:b6d8d4e1cc57 60 if (target == "DISCO_L072CZ_LRWAN1" && toolchain == "GCC_ARM") {
mbed_official 10:b6d8d4e1cc57 61 continue
mbed_official 10:b6d8d4e1cc57 62 }
mbed_official 35:462743fb571e 63 if (target == "MTB_RAK811" && toolchain == "GCC_ARM") {
mbed_official 35:462743fb571e 64 continue
mbed_official 35:462743fb571e 65 }
mbed_official 10:b6d8d4e1cc57 66
mbed_official 10:b6d8d4e1cc57 67 def stepName = "${target} ${toolchain}"
mbed_official 10:b6d8d4e1cc57 68
mbed_official 10:b6d8d4e1cc57 69 stepsForParallel[stepName] = buildStep(target, compilerLabel, toolchain)
mbed_official 10:b6d8d4e1cc57 70 }
mbed_official 10:b6d8d4e1cc57 71 }
mbed_official 10:b6d8d4e1cc57 72
mbed_official 20:2055271192d6 73 def stepsForRegional = [:]
mbed_official 20:2055271192d6 74
mbed_official 20:2055271192d6 75 if (params.regions_build_test == true) {
mbed_official 20:2055271192d6 76 stepsForRegional["REGION BUILDER"] = build_regions(regions)
mbed_official 20:2055271192d6 77 }
mbed_official 20:2055271192d6 78
mbed_official 10:b6d8d4e1cc57 79 timestamps {
mbed_official 10:b6d8d4e1cc57 80 parallel stepsForParallel
mbed_official 20:2055271192d6 81 parallel stepsForRegional
mbed_official 10:b6d8d4e1cc57 82 }
mbed_official 10:b6d8d4e1cc57 83
mbed_official 10:b6d8d4e1cc57 84 def buildStep(target, compilerLabel, toolchain) {
mbed_official 10:b6d8d4e1cc57 85 return {
mbed_official 10:b6d8d4e1cc57 86 stage ("${target}_${compilerLabel}") {
mbed_official 10:b6d8d4e1cc57 87 node ("${compilerLabel}") {
mbed_official 10:b6d8d4e1cc57 88 deleteDir()
mbed_official 10:b6d8d4e1cc57 89 dir("mbed-os-example-lorawan") {
mbed_official 10:b6d8d4e1cc57 90 checkout scm
mbed_official 20:2055271192d6 91 execute("mbed deploy --protocol ssh")
mbed_official 10:b6d8d4e1cc57 92
mbed_official 10:b6d8d4e1cc57 93 // Set mbed-os to revision received as parameter
mbed_official 10:b6d8d4e1cc57 94 if (env.MBED_OS_REVISION != '') {
mbed_official 10:b6d8d4e1cc57 95 dir("mbed-os") {
mbed_official 10:b6d8d4e1cc57 96 if (env.MBED_OS_REVISION.matches('pull/\\d+/head')) {
mbed_official 10:b6d8d4e1cc57 97 // Use mbed-os PR and switch to branch created
mbed_official 20:2055271192d6 98 execute("git fetch origin ${env.MBED_OS_REVISION}:_PR_")
mbed_official 20:2055271192d6 99 execute("git checkout _PR_")
mbed_official 10:b6d8d4e1cc57 100 } else {
mbed_official 20:2055271192d6 101 execute("git checkout ${env.MBED_OS_REVISION}")
mbed_official 10:b6d8d4e1cc57 102 }
mbed_official 10:b6d8d4e1cc57 103 }
mbed_official 10:b6d8d4e1cc57 104 }
mbed_official 10:b6d8d4e1cc57 105
mbed_official 10:b6d8d4e1cc57 106 // Adjust stack size and crystal values
mbed_official 10:b6d8d4e1cc57 107 if ("${target}" == "DISCO_L072CZ_LRWAN1") {
mbed_official 20:2055271192d6 108 execute("sed -i 's/#define RCC_HSICALIBRATION_DEFAULT ((uint32_t)0x10)/#define RCC_HSICALIBRATION_DEFAULT ((uint32_t)0x13)/' \
mbed_official 20:2055271192d6 109 mbed-os/targets/TARGET_STM/TARGET_STM32L0/device/stm32l0xx_hal_rcc.h")
mbed_official 10:b6d8d4e1cc57 110 }
mbed_official 10:b6d8d4e1cc57 111
mbed_official 10:b6d8d4e1cc57 112 if ("${target}" == "MTB_MURATA_ABZ") {
mbed_official 20:2055271192d6 113 execute("sed -i 's/define symbol __size_heap__ = 0x800;/define symbol __size_heap__ = 0x1000;/' \
mbed_official 20:2055271192d6 114 mbed-os/targets/TARGET_STM/TARGET_STM32L0/TARGET_STM32L0x2xZ/device/TOOLCHAIN_IAR/stm32l082xZ.icf")
mbed_official 20:2055271192d6 115 execute("sed -i 's/#define RCC_HSICALIBRATION_DEFAULT ((uint32_t)0x10)/#define RCC_HSICALIBRATION_DEFAULT ((uint32_t)0x16)/' \
mbed_official 20:2055271192d6 116 mbed-os/targets/TARGET_STM/TARGET_STM32L0/device/stm32l0xx_hal_rcc.h")
mbed_official 10:b6d8d4e1cc57 117 }
mbed_official 10:b6d8d4e1cc57 118
mbed_official 10:b6d8d4e1cc57 119 if ("${target}" == "MTB_MTS_XDOT") {
mbed_official 20:2055271192d6 120 execute("sed -i 's/define symbol __size_heap__ = 0x800;/define symbol __size_heap__ = 0x1800;/' \
mbed_official 20:2055271192d6 121 mbed-os/targets/TARGET_STM/TARGET_STM32L1/TARGET_MTB_MTS_XDOT/device/TOOLCHAIN_IAR/stm32l152xc.icf")
mbed_official 10:b6d8d4e1cc57 122 }
mbed_official 35:462743fb571e 123
mbed_official 35:462743fb571e 124 if ("${target}" == "MTB_RAK811") {
mbed_official 35:462743fb571e 125 execute("sed -i 's/#define RCC_HSICALIBRATION_DEFAULT (0x10U)/#define RCC_HSICALIBRATION_DEFAULT (0x11U)/' \
mbed_official 35:462743fb571e 126 mbed-os/targets/TARGET_STM/TARGET_STM32L1/device/stm32l1xx_hal_rcc.h")
mbed_official 35:462743fb571e 127 execute("sed -i 's/define symbol __size_heap__ = 0x800;/define symbol __size_heap__ = 0x1800;/' \
mbed_official 35:462743fb571e 128 mbed-os/targets/TARGET_STM/TARGET_STM32L1/TARGET_MTB_RAK811/device/TOOLCHAIN_IAR/stm32l152xba.icf")
mbed_official 35:462743fb571e 129 }
mbed_official 35:462743fb571e 130
mbed_official 20:2055271192d6 131 execute("mbed compile --build out/${target}_${toolchain}/ -m ${target} -t ${toolchain} -c")
mbed_official 10:b6d8d4e1cc57 132 }
mbed_official 10:b6d8d4e1cc57 133 stash name: "${target}_${toolchain}", includes: '**/mbed-os-example-lorawan.bin'
mbed_official 10:b6d8d4e1cc57 134 archive '**/mbed-os-example-lorawan.bin'
mbed_official 10:b6d8d4e1cc57 135 step([$class: 'WsCleanup'])
mbed_official 10:b6d8d4e1cc57 136 }
mbed_official 10:b6d8d4e1cc57 137 }
mbed_official 10:b6d8d4e1cc57 138 }
mbed_official 10:b6d8d4e1cc57 139 }
mbed_official 20:2055271192d6 140
mbed_official 20:2055271192d6 141 def build_regions(regions) {
mbed_official 20:2055271192d6 142 return {
mbed_official 20:2055271192d6 143 stage ("region_builder_K64F_GCC_ARM") {
mbed_official 20:2055271192d6 144 node ("arm-none-eabi-gcc") {
mbed_official 20:2055271192d6 145 deleteDir()
mbed_official 20:2055271192d6 146 dir("mbed-os-example-lorawan") {
mbed_official 20:2055271192d6 147 checkout scm
mbed_official 20:2055271192d6 148 execute("mbed deploy --protocol ssh")
mbed_official 20:2055271192d6 149
mbed_official 20:2055271192d6 150 if (env.MBED_OS_REVISION != '') {
mbed_official 20:2055271192d6 151 dir("mbed-os") {
mbed_official 20:2055271192d6 152 if (env.MBED_OS_REVISION.matches('pull/\\d+/head')) {
mbed_official 20:2055271192d6 153 execute("git fetch origin ${env.MBED_OS_REVISION}:_PR_")
mbed_official 20:2055271192d6 154 execute("git checkout _PR_")
mbed_official 20:2055271192d6 155 } else {
mbed_official 20:2055271192d6 156 execute("git checkout ${env.MBED_OS_REVISION}")
mbed_official 20:2055271192d6 157 }
mbed_official 20:2055271192d6 158 }
mbed_official 20:2055271192d6 159 }
mbed_official 20:2055271192d6 160 //Initial sed to string format for find & replacing
mbed_official 20:2055271192d6 161 execute("sed -i 's/\"lora.phy\": 0,/\"lora.phy\": \"0\",/' mbed_app.json")
mbed_official 20:2055271192d6 162 //lora.phy 0 build tested above already
mbed_official 20:2055271192d6 163 for (int i = 1; i < regions.size(); i++) {
mbed_official 20:2055271192d6 164 def curr_region = regions.get(i)
mbed_official 20:2055271192d6 165 def prev_region = regions.get(i-1)
mbed_official 20:2055271192d6 166 execute("sed -i 's/\"lora.phy\": ${prev_region},/\"lora.phy\": ${curr_region},/' mbed_app.json")
mbed_official 20:2055271192d6 167 echo "Building region: ${curr_region}"
mbed_official 20:2055271192d6 168 execute("mbed compile -t GCC_ARM -m K64F")
mbed_official 20:2055271192d6 169 }
mbed_official 20:2055271192d6 170 }
mbed_official 20:2055271192d6 171 }
mbed_official 20:2055271192d6 172 }
mbed_official 20:2055271192d6 173 }
mbed_official 20:2055271192d6 174 }