wayne roberts / Mbed OS mbed-os-lorawan-gps

example using mbed loramac with GPS in application layer

Dependencies:   lib_gps

This repository can work on NAmote72.

This main.cpp generates Cayenne LPP GPS payload.

See mbed documentation for provisioning instructions.

README.md@0:2e040cc7f7b8, 2019-01-03 (annotated)

Committer:
Wayne Roberts
Date:
Thu Jan 03 16:18:09 2019 -0800
Revision:
0:2e040cc7f7b8
initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Wayne Roberts 0:2e040cc7f7b8 1 # Example LoRaWAN application for Mbed-OS
Wayne Roberts 0:2e040cc7f7b8 2
Wayne Roberts 0:2e040cc7f7b8 3 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.
Wayne Roberts 0:2e040cc7f7b8 4
Wayne Roberts 0:2e040cc7f7b8 5 ## Getting started
Wayne Roberts 0:2e040cc7f7b8 6
Wayne Roberts 0:2e040cc7f7b8 7 This application can work with any Network Server if you have correct credentials for the said Network Server.
Wayne Roberts 0:2e040cc7f7b8 8
Wayne Roberts 0:2e040cc7f7b8 9 ### Download the application
Wayne Roberts 0:2e040cc7f7b8 10
Wayne Roberts 0:2e040cc7f7b8 11 ```sh
Wayne Roberts 0:2e040cc7f7b8 12 $ mbed import mbed-os-example-lorawan
Wayne Roberts 0:2e040cc7f7b8 13 $ cd mbed-os-example-lorawan
Wayne Roberts 0:2e040cc7f7b8 14
Wayne Roberts 0:2e040cc7f7b8 15 #OR
Wayne Roberts 0:2e040cc7f7b8 16
Wayne Roberts 0:2e040cc7f7b8 17 $ git clone git@github.com:ARMmbed/mbed-os-example-lorawan.git
Wayne Roberts 0:2e040cc7f7b8 18 $ cd mbed-os-example-lorawan
Wayne Roberts 0:2e040cc7f7b8 19 $ mbed deploy
Wayne Roberts 0:2e040cc7f7b8 20 ```
Wayne Roberts 0:2e040cc7f7b8 21
Wayne Roberts 0:2e040cc7f7b8 22 ### Selecting radio
Wayne Roberts 0:2e040cc7f7b8 23
Wayne Roberts 0:2e040cc7f7b8 24 Mbed OS provides inherent support for a variety of modules. If your device is one of the those modules, you may skip this part. The correct radio type and pin set is already provided for the modules in the `target-overrides` field. For more information on supported modules, please refer to the [module support section](#module-support)
Wayne Roberts 0:2e040cc7f7b8 25
Wayne Roberts 0:2e040cc7f7b8 26 If you are using an Mbed Enabled radio shield such as [Mbed SX1276 shield LoRa](https://os.mbed.com/components/SX1276MB1xAS/) or [Mbed SX1272 LoRa shield ](https://os.mbed.com/components/SX1272MB2xAS/) with any Mbed Enabled board, this part is relevant. You can use any Mbed Enabled board that comes with an arduino form factor.
Wayne Roberts 0:2e040cc7f7b8 27
Wayne Roberts 0:2e040cc7f7b8 28 Please select your radio type by modifying the `lora-radio` field and providing a pin set if it is different from the default. For example:
Wayne Roberts 0:2e040cc7f7b8 29
Wayne Roberts 0:2e040cc7f7b8 30 ```json
Wayne Roberts 0:2e040cc7f7b8 31 "lora-radio": {
Wayne Roberts 0:2e040cc7f7b8 32 "help": "Which radio to use (options: SX1272,SX1276)",
Wayne Roberts 0:2e040cc7f7b8 33 "value": "SX1272"
Wayne Roberts 0:2e040cc7f7b8 34 },
Wayne Roberts 0:2e040cc7f7b8 35 ```
Wayne Roberts 0:2e040cc7f7b8 36
Wayne Roberts 0:2e040cc7f7b8 37 ### Add network credentials
Wayne Roberts 0:2e040cc7f7b8 38
Wayne Roberts 0:2e040cc7f7b8 39 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.
Wayne Roberts 0:2e040cc7f7b8 40
Wayne Roberts 0:2e040cc7f7b8 41 #### For OTAA
Wayne Roberts 0:2e040cc7f7b8 42
Wayne Roberts 0:2e040cc7f7b8 43 Please add `Device EUI`, `Application EUI` and `Application Key` needed for Over-the-air-activation(OTAA). For example:
Wayne Roberts 0:2e040cc7f7b8 44
Wayne Roberts 0:2e040cc7f7b8 45 ```json
Wayne Roberts 0:2e040cc7f7b8 46
Wayne Roberts 0:2e040cc7f7b8 47 "lora.device-eui": "{ YOUR_DEVICE_EUI }",
Wayne Roberts 0:2e040cc7f7b8 48 "lora.application-eui": "{ YOUR_APPLICATION_EUI }",
Wayne Roberts 0:2e040cc7f7b8 49 "lora.application-key": "{ YOUR_APPLICATION_KEY }"
Wayne Roberts 0:2e040cc7f7b8 50 ```
Wayne Roberts 0:2e040cc7f7b8 51
Wayne Roberts 0:2e040cc7f7b8 52 #### For ABP
Wayne Roberts 0:2e040cc7f7b8 53
Wayne Roberts 0:2e040cc7f7b8 54 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:
Wayne Roberts 0:2e040cc7f7b8 55
Wayne Roberts 0:2e040cc7f7b8 56 ```json
Wayne Roberts 0:2e040cc7f7b8 57 "lora.over-the-air-activation": false,
Wayne Roberts 0:2e040cc7f7b8 58 ```
Wayne Roberts 0:2e040cc7f7b8 59
Wayne Roberts 0:2e040cc7f7b8 60 In addition to that, you need to provide `Application Session Key`, `Network Session Key` and `Device Address`. For example:
Wayne Roberts 0:2e040cc7f7b8 61
Wayne Roberts 0:2e040cc7f7b8 62 ```json
Wayne Roberts 0:2e040cc7f7b8 63 "lora.appskey": "{ YOUR_APPLICATION_SESSION_KEY }",
Wayne Roberts 0:2e040cc7f7b8 64 "lora.nwkskey": "{ YOUR_NETWORK_SESSION_KEY }",
Wayne Roberts 0:2e040cc7f7b8 65 "lora.device-address": " YOUR_DEVICE_ADDRESS_IN_HEX "
Wayne Roberts 0:2e040cc7f7b8 66 ```
Wayne Roberts 0:2e040cc7f7b8 67
Wayne Roberts 0:2e040cc7f7b8 68 ## Configuring the application
Wayne Roberts 0:2e040cc7f7b8 69
Wayne Roberts 0:2e040cc7f7b8 70 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.
Wayne Roberts 0:2e040cc7f7b8 71
Wayne Roberts 0:2e040cc7f7b8 72 ### Selecting a PHY
Wayne Roberts 0:2e040cc7f7b8 73
Wayne Roberts 0:2e040cc7f7b8 74 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:
Wayne Roberts 0:2e040cc7f7b8 75
Wayne Roberts 0:2e040cc7f7b8 76 ```josn
Wayne Roberts 0:2e040cc7f7b8 77 "phy": {
Wayne Roberts 0:2e040cc7f7b8 78 "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",
Wayne Roberts 0:2e040cc7f7b8 79 "value": "0"
Wayne Roberts 0:2e040cc7f7b8 80 },
Wayne Roberts 0:2e040cc7f7b8 81 ```
Wayne Roberts 0:2e040cc7f7b8 82
Wayne Roberts 0:2e040cc7f7b8 83 ### Duty cycling
Wayne Roberts 0:2e040cc7f7b8 84
Wayne Roberts 0:2e040cc7f7b8 85 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.
Wayne Roberts 0:2e040cc7f7b8 86
Wayne Roberts 0:2e040cc7f7b8 87 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:
Wayne Roberts 0:2e040cc7f7b8 88
Wayne Roberts 0:2e040cc7f7b8 89 ```josn
Wayne Roberts 0:2e040cc7f7b8 90 "target_overrides": {
Wayne Roberts 0:2e040cc7f7b8 91 "*": {
Wayne Roberts 0:2e040cc7f7b8 92 "lora.duty-cycle-on": false
Wayne Roberts 0:2e040cc7f7b8 93 },
Wayne Roberts 0:2e040cc7f7b8 94 }
Wayne Roberts 0:2e040cc7f7b8 95 }
Wayne Roberts 0:2e040cc7f7b8 96 ```
Wayne Roberts 0:2e040cc7f7b8 97
Wayne Roberts 0:2e040cc7f7b8 98 ## Module support
Wayne Roberts 0:2e040cc7f7b8 99
Wayne Roberts 0:2e040cc7f7b8 100 Here is a nonexhaustive list of boards and modules that we have tested with the Mbed OS LoRaWAN stack.
Wayne Roberts 0:2e040cc7f7b8 101
Wayne Roberts 0:2e040cc7f7b8 102 - MultiTech mDot.
Wayne Roberts 0:2e040cc7f7b8 103 - MultiTech xDot.
Wayne Roberts 0:2e040cc7f7b8 104 - LTEK_FF1705.
Wayne Roberts 0:2e040cc7f7b8 105 - Advantech Wise 1510.
Wayne Roberts 0:2e040cc7f7b8 106 - ST B-L072Z-LRWAN1 LoRa®Discovery kit (with muRata radio chip).
Wayne Roberts 0:2e040cc7f7b8 107
Wayne Roberts 0:2e040cc7f7b8 108 ## Compiling the application
Wayne Roberts 0:2e040cc7f7b8 109
Wayne Roberts 0:2e040cc7f7b8 110 Use Mbed CLI commands to generate a binary for the application.
Wayne Roberts 0:2e040cc7f7b8 111 For example:
Wayne Roberts 0:2e040cc7f7b8 112
Wayne Roberts 0:2e040cc7f7b8 113 ```sh
Wayne Roberts 0:2e040cc7f7b8 114 $ mbed compile -m YOUR_TARGET -t ARM
Wayne Roberts 0:2e040cc7f7b8 115 ```
Wayne Roberts 0:2e040cc7f7b8 116
Wayne Roberts 0:2e040cc7f7b8 117 ## Running the application
Wayne Roberts 0:2e040cc7f7b8 118
Wayne Roberts 0:2e040cc7f7b8 119 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.
Wayne Roberts 0:2e040cc7f7b8 120
Wayne Roberts 0:2e040cc7f7b8 121 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.
Wayne Roberts 0:2e040cc7f7b8 122
Wayne Roberts 0:2e040cc7f7b8 123 You should see an output similar to this:
Wayne Roberts 0:2e040cc7f7b8 124
Wayne Roberts 0:2e040cc7f7b8 125 ```
Wayne Roberts 0:2e040cc7f7b8 126 Mbed LoRaWANStack initialized
Wayne Roberts 0:2e040cc7f7b8 127
Wayne Roberts 0:2e040cc7f7b8 128 CONFIRMED message retries : 3
Wayne Roberts 0:2e040cc7f7b8 129
Wayne Roberts 0:2e040cc7f7b8 130 Adaptive data rate (ADR) - Enabled
Wayne Roberts 0:2e040cc7f7b8 131
Wayne Roberts 0:2e040cc7f7b8 132 Connection - In Progress ...
Wayne Roberts 0:2e040cc7f7b8 133
Wayne Roberts 0:2e040cc7f7b8 134 Connection - Successful
Wayne Roberts 0:2e040cc7f7b8 135
Wayne Roberts 0:2e040cc7f7b8 136 Dummy Sensor Value = 2.1
Wayne Roberts 0:2e040cc7f7b8 137
Wayne Roberts 0:2e040cc7f7b8 138 25 bytes scheduled for transmission
Wayne Roberts 0:2e040cc7f7b8 139
Wayne Roberts 0:2e040cc7f7b8 140 Message Sent to Network Server
Wayne Roberts 0:2e040cc7f7b8 141
Wayne Roberts 0:2e040cc7f7b8 142 ```
Wayne Roberts 0:2e040cc7f7b8 143
Wayne Roberts 0:2e040cc7f7b8 144 ## [Optional] Adding trace library
Wayne Roberts 0:2e040cc7f7b8 145 To enable Mbed trace, add to your `mbed_app.json` the following fields:
Wayne Roberts 0:2e040cc7f7b8 146
Wayne Roberts 0:2e040cc7f7b8 147 ```json
Wayne Roberts 0:2e040cc7f7b8 148 "target_overrides": {
Wayne Roberts 0:2e040cc7f7b8 149 "*": {
Wayne Roberts 0:2e040cc7f7b8 150 "mbed-trace.enable": true
Wayne Roberts 0:2e040cc7f7b8 151 }
Wayne Roberts 0:2e040cc7f7b8 152 }
Wayne Roberts 0:2e040cc7f7b8 153 ```
Wayne Roberts 0:2e040cc7f7b8 154 The trace is disabled by default to save RAM and reduce main stack usage (see chapter Memory optimization).
Wayne Roberts 0:2e040cc7f7b8 155
Wayne Roberts 0:2e040cc7f7b8 156 **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`**.**
Wayne Roberts 0:2e040cc7f7b8 157
Wayne Roberts 0:2e040cc7f7b8 158 ## [Optional] Memory optimization
Wayne Roberts 0:2e040cc7f7b8 159
Wayne Roberts 0:2e040cc7f7b8 160 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.
Wayne Roberts 0:2e040cc7f7b8 161
Wayne Roberts 0:2e040cc7f7b8 162 For example, add the following into `config` section in your `mbed_app.json`:
Wayne Roberts 0:2e040cc7f7b8 163
Wayne Roberts 0:2e040cc7f7b8 164 ```
Wayne Roberts 0:2e040cc7f7b8 165 "main_stack_size": {
Wayne Roberts 0:2e040cc7f7b8 166 "value": 2048
Wayne Roberts 0:2e040cc7f7b8 167 }
Wayne Roberts 0:2e040cc7f7b8 168 ```
Wayne Roberts 0:2e040cc7f7b8 169
Wayne Roberts 0:2e040cc7f7b8 170 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](https://os.mbed.com/blog/entry/Reducing-memory-usage-with-a-custom-prin/).
Wayne Roberts 0:2e040cc7f7b8 171
Wayne Roberts 0:2e040cc7f7b8 172
Wayne Roberts 0:2e040cc7f7b8 173 For more information, please follow this [blog post](https://os.mbed.com/blog/entry/Reducing-memory-usage-by-tuning-RTOS-con/).