Tobias Jansen / Mbed OS Lorawan_Version_0_1

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.

Dependencies:   Lorawan_Version_0_1

Dependents:   Lorawan_Version_0_1

README.md@55:6f2e16ebde99, 2019-08-20 (annotated)

Committer:
mbed_official
Date:
Tue Aug 20 15:01:49 2019 +0100
Revision:
55:6f2e16ebde99
Parent:
52:1bd775571014
Child:
57:36e87c44c920
Merge pull request #154 from itziardelatorre/update_IM880B



Add iM880B to readme

.

Commit copied from https://github.com/ARMmbed/mbed-os-example-lorawan

Who changed what in which revision?

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