Future Electronics / Mbed OS mbed-os-example-lorawan-sequana

Fork of the official LoRaWAN example adapted for Future Electronic's Sequana board with SX1272MB2DAS LoRa shield.

README.md@57:36e87c44c920, 2019-09-03 (annotated)

Committer:
mbed_official
Date:
Tue Sep 03 14:01:54 2019 +0100
Revision:
57:36e87c44c920
Parent:
55:6f2e16ebde99 
Merge pull request #140 from bentcooke/add_sx126x



add SX126X radio option and update driver lib

.

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