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

NuMaker mbed OS v6.x LoRaWAN

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

Committer:
cyliang
Date:
Tue Sep 01 20:28:04 2020 +0800
Revision:
0:a160d512fe55
Mbed OS v6.x LoRaWAN example for NuMaker platforms

Who changed what in which revision?

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