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.

Changes

RevisionDateWhoCommit message
59:23cc35ed9008 15 months ago mbed_official Updated build node (#169) default tip
58:4d1114ac60aa 17 months ago mbed_official Merge pull request #166 from trowbridgec/add-ep-agora
57:36e87c44c920 18 months ago mbed_official Merge pull request #140 from bentcooke/add_sx126x
56:39847849d219 18 months ago mbed_official Merge pull request #159 from hugueskamba/master
55:6f2e16ebde99 18 months ago mbed_official Merge pull request #154 from itziardelatorre/update_IM880B
54:19d02b47e598 19 months ago mbed_official Merge pull request #153 from itziardelatorre/add_target_IM880B
53:1b6c71e938ac 21 months ago mbed_official Update lora_radio_helper.h
52:1bd775571014 22 months ago mbed_official add contributing file
51:9fe25b38ba28 23 months ago mbed_official Updating mbed-os to mbed-os-5.12.1
50:5293a23c7ba9 24 months ago mbed_official Updating mbed-os to mbed-os-5.11.5
49:699a601deb79 24 months ago mbed_official Merge pull request #127 from ARMmbed/toolchain_update
48:dfce67eca082 2019-02-13 mbed_official Updating mbed-os to mbed-os-5.11.4
47:b6d132f1079f 2019-01-27 mbed_official Updating mbed-os to mbed-os-5.11.2
46:a124538e2891 2019-01-10 mbed_official Docathon updates (#115)
45:7df71f7c950b 2019-01-03 mbed_official Merge pull request #114 from adbridge/master
44:d4ea1d610650 2018-11-19 mbed_official Merge pull request #110 from cmonr/master
43:dd5c0526343b 2018-11-06 mbed_official Merge pull request #108 from adbridge/master
42:e120f78b12d8 2018-10-24 mbed_official Updating mbed-os to mbed-os-5.10.2
41:ceea78461fbd 2018-10-12 mbed_official Updating Radio driver pointer
40:6a512236f805 2018-10-09 mbed_official Updating mbed-os to mbed-os-5.10.1
39:e4cd45fbd4f3 2018-10-09 mbed_official Removing US915_Hybrid build
38:315a26cd0165 2018-09-17 mbed_official Merge pull request #100 from ARMmbed/enable_armc6
37:5bc348e90af0 2018-09-11 mbed_official Updating mbed-os to mbed-os-5.9.7
36:08d94248181b 2018-09-10 mbed_official Disable some ciphers not needed by lora example application
35:462743fb571e 2018-09-03 mbed_official Merge pull request #97 from ARMmbed/jenkinsfile_update
34:2294e762257c 2018-08-27 mbed_official Updating mbed-os to mbed-os-5.9.6
33:3776745e4d93 2018-08-23 mbed_official Optimize mbedtls config
32:4e80b9d620ee 2018-08-16 mbed_official Update Lora driver
31:67780d4891a9 2018-08-14 mbed_official Updating mbed-os to mbed-os-5.9.5
30:955f64c04503 2018-07-31 mbed_official Updating mbed-os to mbed-os-5.9.4
29:0da9196c900a 2018-07-23 mbed_official Update latest Semtech drivers
28:950587b41ba3 2018-07-23 mbed_official Updating mbed-os to mbed-os-5.9.3
27:cea7485b914e 2018-07-03 mbed_official Updating mbed-os to mbed-os-5.9.2
26:f07f5febf97f 2018-06-28 mbed_official Using string to identify region rather than number
25:0f75546d3f3f 2018-06-19 mbed_official Updating mbed-os to mbed-os-5.9.1
24:b36f31f93938 2018-06-18 mbed_official Updating pointer to Mbed OS 5.9.0
23:2b0d9c892149 2018-06-07 mbed_official Fix correct target name for FF1705_L151CC
22:a4fc83409028 2018-06-06 mbed_official Updating mbed-os to mbed-os-5.8.6
21:41807073b52d 2018-05-25 mbed_official Update to latest radio drivers
20:2055271192d6 2018-05-22 mbed_official Region builder (#74)
19:6accf37de3ce 2018-05-22 mbed_official Updating mbed-os to mbed-os-5.8.5
18:1720bc3831ea 2018-05-15 mbed_official Remove usage of DEVICE_SPI and MBED_CONF_APP_LORAWAN_ENABLED flags
17:2fc16c1d6434 2018-05-11 mbed_official Remove unnecessary Serial object
16:8d460198a422 2018-05-10 mbed_official Updating mbed-os to mbed-os-5.8.4
15:6ae43b4082f8 2018-05-03 mbed_official Fix default application key
14:b25fefabb634 2018-05-02 mbed_official Murata crystal update (#64)
13:2f387d100e5b 2018-04-19 mbed_official Update radio drivers to latest version
12:5015dfead3f2 2018-04-18 mbed_official Reduce example application memory usage
11:7696b8844841 2018-04-11 mbed_official Merge pull request #57 from adbridge/master
10:b6d8d4e1cc57 2018-04-10 mbed_official Merge pull request #56 from ARMmbed/add_jenkinsfile
9:baf55b160f65 2018-03-29 mbed_official Update mbed lib to 5.8.1
8:7594ad70d2bf 2018-03-19 mbed_official Use Serial object for trace prints
7:2fc0e8a7b6f0 2018-03-16 mbed_official Merge pull request #48 from janjongboom/patch-1
6:d6016e907c7a 2018-03-13 mbed_official Reduced main stack size for Disco target
5:2a08c4ee1843 2018-03-13 mbed_official Update mbed-os.lib
4:df442e6af8cf 2018-03-11 mbed_official Update mbed-lora-radio-drv.lib
3:8c7198d1a2a1 2018-03-11 mbed_official Added LORAWAN_ENABLED flag to disable building in unsupported devices
2:dc95ac6d6d4e 2018-03-09 mbed_official Refactor construction of LoRaWANInterface object
1:c7fae321242f 2018-03-09 mbed_official Fixed default PIN mappings
0:7037ed05f54f 2018-03-08 mbed_official Fix construction of LoRaWANInterface object