Danaé Bueb / Mbed 2 deprecated agr_dist_v2

work1

Dependencies:   mbed MAX44009 mbed-os Si7021

README.md@2:25f27478fdf9, 2020-05-28 (annotated)

Committer:
danaeb
Date:
Thu May 28 07:31:51 2020 +0000
Revision:
2:25f27478fdf9
Parent:
0:d3e390d62607 
work

Who changed what in which revision?

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