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@2:dc95ac6d6d4e, 2018-03-09 (annotated)

Committer:
mbed_official
Date:
Fri Mar 09 13:15:17 2018 +0000
Revision:
2:dc95ac6d6d4e
Parent:
0:7037ed05f54f
Child:
12:5015dfead3f2
Refactor construction of LoRaWANInterface object



This is refactoring of commit 59b4e195c39 to get rid of unnecessary pointer assignment.



.

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 0:7037ed05f54f 28 Please select your radio type by modifying the `lora-radio` field 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 0:7037ed05f54f 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 0:7037ed05f54f 108 ## Compiling the application
mbed_official 0:7037ed05f54f 109
mbed_official 0:7037ed05f54f 110 Use Mbed CLI commands to generate a binary for the application.
mbed_official 0:7037ed05f54f 111 For example:
mbed_official 0:7037ed05f54f 112
mbed_official 0:7037ed05f54f 113 ```sh
mbed_official 0:7037ed05f54f 114 $ mbed compile -m YOUR_TARGET -t ARM
mbed_official 0:7037ed05f54f 115 ```
mbed_official 0:7037ed05f54f 116
mbed_official 0:7037ed05f54f 117 ## Running the application
mbed_official 0:7037ed05f54f 118
mbed_official 0:7037ed05f54f 119 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 120
mbed_official 0:7037ed05f54f 121 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 122
mbed_official 0:7037ed05f54f 123 You should see an output similar to this:
mbed_official 0:7037ed05f54f 124
mbed_official 0:7037ed05f54f 125 ```
mbed_official 0:7037ed05f54f 126 Mbed LoRaWANStack initialized
mbed_official 0:7037ed05f54f 127
mbed_official 0:7037ed05f54f 128 CONFIRMED message retries : 3
mbed_official 0:7037ed05f54f 129
mbed_official 0:7037ed05f54f 130 Adaptive data rate (ADR) - Enabled
mbed_official 0:7037ed05f54f 131
mbed_official 0:7037ed05f54f 132 Connection - In Progress ...
mbed_official 0:7037ed05f54f 133
mbed_official 0:7037ed05f54f 134 Connection - Successful
mbed_official 0:7037ed05f54f 135
mbed_official 0:7037ed05f54f 136 Dummy Sensor Value = 2.1
mbed_official 0:7037ed05f54f 137
mbed_official 0:7037ed05f54f 138 25 bytes scheduled for transmission
mbed_official 0:7037ed05f54f 139
mbed_official 0:7037ed05f54f 140 Message Sent to Network Server
mbed_official 0:7037ed05f54f 141
mbed_official 0:7037ed05f54f 142 ```
mbed_official 0:7037ed05f54f 143
mbed_official 0:7037ed05f54f 144 ## [Optional] Adding trace library
mbed_official 0:7037ed05f54f 145 To enable Mbed trace, add to your `mbed_app.json` the following fields:
mbed_official 0:7037ed05f54f 146
mbed_official 0:7037ed05f54f 147 ```json
mbed_official 0:7037ed05f54f 148 "target_overrides": {
mbed_official 0:7037ed05f54f 149 "*": {
mbed_official 0:7037ed05f54f 150 "target.features_add": ["COMMON_PAL"],
mbed_official 0:7037ed05f54f 151 "mbed-trace.enable": true
mbed_official 0:7037ed05f54f 152 }
mbed_official 0:7037ed05f54f 153 }
mbed_official 0:7037ed05f54f 154 ```
mbed_official 0:7037ed05f54f 155 The trace is disabled by default to save RAM.
mbed_official 0:7037ed05f54f 156
mbed_official 0:7037ed05f54f 157 ## [Optional] Memory optimization
mbed_official 0:7037ed05f54f 158
mbed_official 0:7037ed05f54f 159 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 160
mbed_official 0:7037ed05f54f 161 For example, add the following into `config` section in your `mbed_app.json`:
mbed_official 0:7037ed05f54f 162
mbed_official 0:7037ed05f54f 163 ```
mbed_official 0:7037ed05f54f 164 "main_stack_size": {
mbed_official 0:7037ed05f54f 165 "value": 2048
mbed_official 0:7037ed05f54f 166 }
mbed_official 0:7037ed05f54f 167 ```
mbed_official 0:7037ed05f54f 168
mbed_official 0:7037ed05f54f 169 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 170
mbed_official 0:7037ed05f54f 171
mbed_official 0:7037ed05f54f 172 For more information, please follow this [blog post](https://os.mbed.com/blog/entry/Reducing-memory-usage-by-tuning-RTOS-con/).