Nuvoton / Mbed OS NuMaker-mbed-OS-5-lorawan

NuMaker mbed OS v5.x LoRaWAN

README.md@0:895bbd4e6398, 2020-09-01 (annotated)

Committer:
cyliang
Date:
Tue Sep 01 21:06:51 2020 +0800
Revision:
0:895bbd4e6398
Mbed OS v5.x LoRaWAN example for NuMaker platforms based on https://github.com/ARMmbed/mbed-os-example-lorawan.git

Who changed what in which revision?

UserRevisionLine numberNew contents of line
cyliang 0:895bbd4e6398 1 # Example LoRaWAN application for Mbed-OS
cyliang 0:895bbd4e6398 2
cyliang 0:895bbd4e6398 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. See this [link](https://os.mbed.com/blog/entry/Introducing-LoRaWAN-11-support/) 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.
cyliang 0:895bbd4e6398 4
cyliang 0:895bbd4e6398 5 ## Getting Started
cyliang 0:895bbd4e6398 6
cyliang 0:895bbd4e6398 7 ### Supported Hardware
cyliang 0:895bbd4e6398 8 [Mbed Enabled board with an Arduino form factor](https://os.mbed.com/platforms/?q=&Form+Factor=Arduino+Compatible) and one of the following:
cyliang 0:895bbd4e6398 9 - [SX126X shield](https://os.mbed.com/components/SX126xMB2xAS/)
cyliang 0:895bbd4e6398 10 - [SX1276 shield](https://os.mbed.com/components/SX1276MB1xAS/)
cyliang 0:895bbd4e6398 11 - [SX1272 shield](https://os.mbed.com/components/SX1272MB2xAS/)
cyliang 0:895bbd4e6398 12
cyliang 0:895bbd4e6398 13 OR
cyliang 0:895bbd4e6398 14
cyliang 0:895bbd4e6398 15 [Mbed Enabled LoRa Module](#module-support)
cyliang 0:895bbd4e6398 16
cyliang 0:895bbd4e6398 17 ### Import the example application
cyliang 0:895bbd4e6398 18 For [Mbed Online Compiler](https://ide.mbed.com/compiler/) users:
cyliang 0:895bbd4e6398 19 - Select "Import", then search for "mbed-os-example-lorawan" from "Team mbed-os-examples". Or simply, import this repo by URL.
cyliang 0:895bbd4e6398 20
cyliang 0:895bbd4e6398 21 - NOTE: Do NOT select "Update all libraries to latest revision" as this may cause breakage with a new lib version we have not tested.
cyliang 0:895bbd4e6398 22
cyliang 0:895bbd4e6398 23 For [mbed-cli](https://github.com/ARMmbed/mbed-cli) users:
cyliang 0:895bbd4e6398 24 ```sh
cyliang 0:895bbd4e6398 25 $ mbed import mbed-os-example-lorawan
cyliang 0:895bbd4e6398 26 $ cd mbed-os-example-lorawan
cyliang 0:895bbd4e6398 27
cyliang 0:895bbd4e6398 28 #OR
cyliang 0:895bbd4e6398 29
cyliang 0:895bbd4e6398 30 $ git clone git@github.com:ARMmbed/mbed-os-example-lorawan.git
cyliang 0:895bbd4e6398 31 $ cd mbed-os-example-lorawan
cyliang 0:895bbd4e6398 32 $ mbed deploy
cyliang 0:895bbd4e6398 33 ```
cyliang 0:895bbd4e6398 34
cyliang 0:895bbd4e6398 35 ### Example configuration and radio selection
cyliang 0:895bbd4e6398 36
cyliang 0:895bbd4e6398 37 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.
cyliang 0:895bbd4e6398 38
cyliang 0:895bbd4e6398 39 Please start by selecting the correct example configuration for your radio:
cyliang 0:895bbd4e6398 40 - For [Mbed Online Compiler](https://ide.mbed.com/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.
cyliang 0:895bbd4e6398 41 - For [mbed-cli](https://github.com/ARMmbed/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`)
cyliang 0:895bbd4e6398 42
cyliang 0:895bbd4e6398 43 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](#module-support)
cyliang 0:895bbd4e6398 44
cyliang 0:895bbd4e6398 45 ### Add network credentials
cyliang 0:895bbd4e6398 46
cyliang 0:895bbd4e6398 47 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.
cyliang 0:895bbd4e6398 48
cyliang 0:895bbd4e6398 49 #### For OTAA
cyliang 0:895bbd4e6398 50
cyliang 0:895bbd4e6398 51 Please add `Device EUI`, `Application EUI` and `Application Key` needed for Over-the-air-activation(OTAA). For example:
cyliang 0:895bbd4e6398 52
cyliang 0:895bbd4e6398 53 ```json
cyliang 0:895bbd4e6398 54 "lora.device-eui": "{ YOUR_DEVICE_EUI }",
cyliang 0:895bbd4e6398 55 "lora.application-eui": "{ YOUR_APPLICATION_EUI }",
cyliang 0:895bbd4e6398 56 "lora.application-key": "{ YOUR_APPLICATION_KEY }"
cyliang 0:895bbd4e6398 57 ```
cyliang 0:895bbd4e6398 58
cyliang 0:895bbd4e6398 59 #### For ABP
cyliang 0:895bbd4e6398 60
cyliang 0:895bbd4e6398 61 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:
cyliang 0:895bbd4e6398 62
cyliang 0:895bbd4e6398 63 ```json
cyliang 0:895bbd4e6398 64 "lora.over-the-air-activation": false,
cyliang 0:895bbd4e6398 65 ```
cyliang 0:895bbd4e6398 66
cyliang 0:895bbd4e6398 67 In addition to that, you need to provide `Application Session Key`, `Network Session Key` and `Device Address`. For example:
cyliang 0:895bbd4e6398 68
cyliang 0:895bbd4e6398 69 ```json
cyliang 0:895bbd4e6398 70 "lora.appskey": "{ YOUR_APPLICATION_SESSION_KEY }",
cyliang 0:895bbd4e6398 71 "lora.nwkskey": "{ YOUR_NETWORK_SESSION_KEY }",
cyliang 0:895bbd4e6398 72 "lora.device-address": " YOUR_DEVICE_ADDRESS_IN_HEX "
cyliang 0:895bbd4e6398 73 ```
cyliang 0:895bbd4e6398 74
cyliang 0:895bbd4e6398 75 ## Configuring the application
cyliang 0:895bbd4e6398 76
cyliang 0:895bbd4e6398 77 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.
cyliang 0:895bbd4e6398 78
cyliang 0:895bbd4e6398 79 ### Selecting a PHY
cyliang 0:895bbd4e6398 80
cyliang 0:895bbd4e6398 81 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:
cyliang 0:895bbd4e6398 82
cyliang 0:895bbd4e6398 83 ```josn
cyliang 0:895bbd4e6398 84 "phy": {
cyliang 0:895bbd4e6398 85 "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",
cyliang 0:895bbd4e6398 86 "value": "0"
cyliang 0:895bbd4e6398 87 },
cyliang 0:895bbd4e6398 88 ```
cyliang 0:895bbd4e6398 89
cyliang 0:895bbd4e6398 90 ### Duty cycling
cyliang 0:895bbd4e6398 91
cyliang 0:895bbd4e6398 92 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.
cyliang 0:895bbd4e6398 93
cyliang 0:895bbd4e6398 94 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:
cyliang 0:895bbd4e6398 95
cyliang 0:895bbd4e6398 96 ```josn
cyliang 0:895bbd4e6398 97 "target_overrides": {
cyliang 0:895bbd4e6398 98 "*": {
cyliang 0:895bbd4e6398 99 "lora.duty-cycle-on": false
cyliang 0:895bbd4e6398 100 },
cyliang 0:895bbd4e6398 101 }
cyliang 0:895bbd4e6398 102 }
cyliang 0:895bbd4e6398 103 ```
cyliang 0:895bbd4e6398 104
cyliang 0:895bbd4e6398 105 ## Module support
cyliang 0:895bbd4e6398 106
cyliang 0:895bbd4e6398 107 Here is a nonexhaustive list of boards and modules that we have tested with the Mbed OS LoRaWAN stack:
cyliang 0:895bbd4e6398 108
cyliang 0:895bbd4e6398 109 - MultiTech mDot (SX1272)
cyliang 0:895bbd4e6398 110 - MultiTech xDot (SX1272)
cyliang 0:895bbd4e6398 111 - LTEK_FF1705 (SX1272)
cyliang 0:895bbd4e6398 112 - Advantech Wise 1510 (SX1276)
cyliang 0:895bbd4e6398 113 - ST B-L072Z-LRWAN1 LoRa®Discovery kit with Murata CMWX1ZZABZ-091 module (SX1276)
cyliang 0:895bbd4e6398 114
cyliang 0:895bbd4e6398 115 Here is a list of boards and modules that have been tested by the community:
cyliang 0:895bbd4e6398 116
cyliang 0:895bbd4e6398 117 - IMST iM880B (SX1272)
cyliang 0:895bbd4e6398 118 - Embedded Planet Agora (SX1276)
cyliang 0:895bbd4e6398 119
cyliang 0:895bbd4e6398 120 ## Compiling the application
cyliang 0:895bbd4e6398 121
cyliang 0:895bbd4e6398 122 Use Mbed CLI commands to generate a binary for the application.
cyliang 0:895bbd4e6398 123 For example:
cyliang 0:895bbd4e6398 124
cyliang 0:895bbd4e6398 125 ```sh
cyliang 0:895bbd4e6398 126 $ mbed compile -m YOUR_TARGET -t ARM
cyliang 0:895bbd4e6398 127 ```
cyliang 0:895bbd4e6398 128
cyliang 0:895bbd4e6398 129 ## Running the application
cyliang 0:895bbd4e6398 130
cyliang 0:895bbd4e6398 131 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.
cyliang 0:895bbd4e6398 132
cyliang 0:895bbd4e6398 133 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.
cyliang 0:895bbd4e6398 134
cyliang 0:895bbd4e6398 135 You should see an output similar to this:
cyliang 0:895bbd4e6398 136
cyliang 0:895bbd4e6398 137 ```
cyliang 0:895bbd4e6398 138 Mbed LoRaWANStack initialized
cyliang 0:895bbd4e6398 139
cyliang 0:895bbd4e6398 140 CONFIRMED message retries : 3
cyliang 0:895bbd4e6398 141
cyliang 0:895bbd4e6398 142 Adaptive data rate (ADR) - Enabled
cyliang 0:895bbd4e6398 143
cyliang 0:895bbd4e6398 144 Connection - In Progress ...
cyliang 0:895bbd4e6398 145
cyliang 0:895bbd4e6398 146 Connection - Successful
cyliang 0:895bbd4e6398 147
cyliang 0:895bbd4e6398 148 Dummy Sensor Value = 2.1
cyliang 0:895bbd4e6398 149
cyliang 0:895bbd4e6398 150 25 bytes scheduled for transmission
cyliang 0:895bbd4e6398 151
cyliang 0:895bbd4e6398 152 Message Sent to Network Server
cyliang 0:895bbd4e6398 153
cyliang 0:895bbd4e6398 154 ```
cyliang 0:895bbd4e6398 155
cyliang 0:895bbd4e6398 156 ## [Optional] Adding trace library
cyliang 0:895bbd4e6398 157 To enable Mbed trace, add to your `mbed_app.json` the following fields:
cyliang 0:895bbd4e6398 158
cyliang 0:895bbd4e6398 159 ```json
cyliang 0:895bbd4e6398 160 "target_overrides": {
cyliang 0:895bbd4e6398 161 "*": {
cyliang 0:895bbd4e6398 162 "mbed-trace.enable": true
cyliang 0:895bbd4e6398 163 }
cyliang 0:895bbd4e6398 164 }
cyliang 0:895bbd4e6398 165 ```
cyliang 0:895bbd4e6398 166 The trace is disabled by default to save RAM and reduce main stack usage (see chapter Memory optimization).
cyliang 0:895bbd4e6398 167
cyliang 0:895bbd4e6398 168 **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`**.**
cyliang 0:895bbd4e6398 169
cyliang 0:895bbd4e6398 170 ## [Optional] Memory optimization
cyliang 0:895bbd4e6398 171
cyliang 0:895bbd4e6398 172 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.
cyliang 0:895bbd4e6398 173
cyliang 0:895bbd4e6398 174 For example, add the following into `config` section in your `mbed_app.json`:
cyliang 0:895bbd4e6398 175
cyliang 0:895bbd4e6398 176 ```
cyliang 0:895bbd4e6398 177 "main_stack_size": {
cyliang 0:895bbd4e6398 178 "value": 2048
cyliang 0:895bbd4e6398 179 }
cyliang 0:895bbd4e6398 180 ```
cyliang 0:895bbd4e6398 181
cyliang 0:895bbd4e6398 182 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/).
cyliang 0:895bbd4e6398 183
cyliang 0:895bbd4e6398 184
cyliang 0:895bbd4e6398 185 For more information, please follow this [blog post](https://os.mbed.com/blog/entry/Reducing-memory-usage-by-tuning-RTOS-con/).
cyliang 0:895bbd4e6398 186
cyliang 0:895bbd4e6398 187
cyliang 0:895bbd4e6398 188 ### License and contributions
cyliang 0:895bbd4e6398 189
cyliang 0:895bbd4e6398 190 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.
cyliang 0:895bbd4e6398 191
cyliang 0:895bbd4e6398 192 This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide.
cyliang 0:895bbd4e6398 193