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.
Dependents: Projet_de_bachelor_code Projet_de_bachelor_code
Example LoRaWAN application for Mbed-OS
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 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.
Getting Started
Supported Hardware
Mbed Enabled board with an Arduino form factor and one of the following:
OR
Import the example application
For Mbed Online Compiler users:
- Select "Import", then search for "mbed-os-example-lorawan" from "Team mbed-os-examples". Or simply, import this repo by URL.
- NOTE: Do NOT select "Update all libraries to latest revision" as this may cause breakage with a new lib version we have not tested.
For mbed-cli users:
$ mbed import mbed-os-example-lorawan $ cd mbed-os-example-lorawan #OR $ git clone git@github.com:ARMmbed/mbed-os-example-lorawan.git $ cd mbed-os-example-lorawan $ mbed deploy
Example configuration and radio selection
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.
Please start by selecting the correct example configuration for your radio:
- For Mbed Online 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 inconfig/
dir. - For 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
)
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
Add network credentials
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.
For OTAA
Please add Device EUI
, Application EUI
and Application Key
needed for Over-the-air-activation(OTAA). For example:
"lora.device-eui": "{ YOUR_DEVICE_EUI }", "lora.application-eui": "{ YOUR_APPLICATION_EUI }", "lora.application-key": "{ YOUR_APPLICATION_KEY }"
For ABP
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:
"lora.over-the-air-activation": false,
In addition to that, you need to provide Application Session Key
, Network Session Key
and Device Address
. For example:
"lora.appskey": "{ YOUR_APPLICATION_SESSION_KEY }", "lora.nwkskey": "{ YOUR_NETWORK_SESSION_KEY }", "lora.device-address": " YOUR_DEVICE_ADDRESS_IN_HEX "
Configuring the application
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.
Selecting a PHY
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:
"phy": { "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", "value": "0" },
Duty cycling
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.
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:
"target_overrides": { "*": { "lora.duty-cycle-on": false }, } }
Module support
Here is a nonexhaustive list of boards and modules that we have tested with the Mbed OS LoRaWAN stack:
- MultiTech mDot (SX1272)
- MultiTech xDot (SX1272)
- LTEK_FF1705 (SX1272)
- Advantech Wise 1510 (SX1276)
- ST B-L072Z-LRWAN1 LoRa®Discovery kit with Murata CMWX1ZZABZ-091 module (SX1276)
Here is a list of boards and modules that have been tested by the community:
- IMST iM880B (SX1272)
- Embedded Planet Agora (SX1276)
Compiling the application
Use Mbed CLI commands to generate a binary for the application. For example:
$ mbed compile -m YOUR_TARGET -t ARM
Running the application
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.
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.
You should see an output similar to this:
Mbed LoRaWANStack initialized CONFIRMED message retries : 3 Adaptive data rate (ADR) - Enabled Connection - In Progress ... Connection - Successful Dummy Sensor Value = 2.1 25 bytes scheduled for transmission Message Sent to Network Server
Adding trace library
To enable Mbed trace, add to your mbed_app.json
the following fields:
"target_overrides": { "*": { "mbed-trace.enable": true } }
The trace is disabled by default to save RAM and reduce main stack usage (see chapter Memory optimization).
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
.
Memory optimization
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.
For example, add the following into config
section in your mbed_app.json
:
"main_stack_size": { "value": 2048 }
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.
For more information, please follow this blog post.
License and contributions
The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see contributing.md for more info.
This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide.
main.cpp
- Committer:
- mbed_official
- Date:
- 2019-11-28
- Revision:
- 59:23cc35ed9008
- Parent:
- 56:39847849d219
File content as of revision 59:23cc35ed9008:
/** * Copyright (c) 2017, Arm Limited and affiliates. * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #include <stdio.h> #include "lorawan/LoRaWANInterface.h" #include "lorawan/system/lorawan_data_structures.h" #include "events/EventQueue.h" // Application helpers #include "DummySensor.h" #include "trace_helper.h" #include "lora_radio_helper.h" using namespace events; // Max payload size can be LORAMAC_PHY_MAXPAYLOAD. // This example only communicates with much shorter messages (<30 bytes). // If longer messages are used, these buffers must be changed accordingly. uint8_t tx_buffer[30]; uint8_t rx_buffer[30]; /* * Sets up an application dependent transmission timer in ms. Used only when Duty Cycling is off for testing */ #define TX_TIMER 10000 /** * Maximum number of events for the event queue. * 10 is the safe number for the stack events, however, if application * also uses the queue for whatever purposes, this number should be increased. */ #define MAX_NUMBER_OF_EVENTS 10 /** * Maximum number of retries for CONFIRMED messages before giving up */ #define CONFIRMED_MSG_RETRY_COUNTER 3 /** * Dummy pin for dummy sensor */ #define PC_9 0 /** * Dummy sensor class object */ DS1820 ds1820(PC_9); /** * This event queue is the global event queue for both the * application and stack. To conserve memory, the stack is designed to run * in the same thread as the application and the application is responsible for * providing an event queue to the stack that will be used for ISR deferment as * well as application information event queuing. */ static EventQueue ev_queue(MAX_NUMBER_OF_EVENTS *EVENTS_EVENT_SIZE); /** * Event handler. * * This will be passed to the LoRaWAN stack to queue events for the * application which in turn drive the application. */ static void lora_event_handler(lorawan_event_t event); /** * Constructing Mbed LoRaWANInterface and passing it the radio object from lora_radio_helper. */ static LoRaWANInterface lorawan(radio); /** * Application specific callbacks */ static lorawan_app_callbacks_t callbacks; /** * Entry point for application */ int main(void) { // setup tracing setup_trace(); // stores the status of a call to LoRaWAN protocol lorawan_status_t retcode; // Initialize LoRaWAN stack if (lorawan.initialize(&ev_queue) != LORAWAN_STATUS_OK) { printf("\r\n LoRa initialization failed! \r\n"); return -1; } printf("\r\n Mbed LoRaWANStack initialized \r\n"); // prepare application callbacks callbacks.events = mbed::callback(lora_event_handler); lorawan.add_app_callbacks(&callbacks); // Set number of retries in case of CONFIRMED messages if (lorawan.set_confirmed_msg_retries(CONFIRMED_MSG_RETRY_COUNTER) != LORAWAN_STATUS_OK) { printf("\r\n set_confirmed_msg_retries failed! \r\n\r\n"); return -1; } printf("\r\n CONFIRMED message retries : %d \r\n", CONFIRMED_MSG_RETRY_COUNTER); // Enable adaptive data rate if (lorawan.enable_adaptive_datarate() != LORAWAN_STATUS_OK) { printf("\r\n enable_adaptive_datarate failed! \r\n"); return -1; } printf("\r\n Adaptive data rate (ADR) - Enabled \r\n"); retcode = lorawan.connect(); if (retcode == LORAWAN_STATUS_OK || retcode == LORAWAN_STATUS_CONNECT_IN_PROGRESS) { } else { printf("\r\n Connection error, code = %d \r\n", retcode); return -1; } printf("\r\n Connection - In Progress ...\r\n"); // make your event queue dispatching events forever ev_queue.dispatch_forever(); return 0; } /** * Sends a message to the Network Server */ static void send_message() { uint16_t packet_len; int16_t retcode; int32_t sensor_value; if (ds1820.begin()) { ds1820.startConversion(); sensor_value = ds1820.read(); printf("\r\n Dummy Sensor Value = %d \r\n", sensor_value); ds1820.startConversion(); } else { printf("\r\n No sensor found \r\n"); return; } packet_len = sprintf((char *) tx_buffer, "Dummy Sensor Value is %d", sensor_value); retcode = lorawan.send(MBED_CONF_LORA_APP_PORT, tx_buffer, packet_len, MSG_UNCONFIRMED_FLAG); if (retcode < 0) { retcode == LORAWAN_STATUS_WOULD_BLOCK ? printf("send - WOULD BLOCK\r\n") : printf("\r\n send() - Error code %d \r\n", retcode); if (retcode == LORAWAN_STATUS_WOULD_BLOCK) { //retry in 3 seconds if (MBED_CONF_LORA_DUTY_CYCLE_ON) { ev_queue.call_in(3000, send_message); } } return; } printf("\r\n %d bytes scheduled for transmission \r\n", retcode); memset(tx_buffer, 0, sizeof(tx_buffer)); } /** * Receive a message from the Network Server */ static void receive_message() { uint8_t port; int flags; int16_t retcode = lorawan.receive(rx_buffer, sizeof(rx_buffer), port, flags); if (retcode < 0) { printf("\r\n receive() - Error code %d \r\n", retcode); return; } printf(" RX Data on port %u (%d bytes): ", port, retcode); for (uint8_t i = 0; i < retcode; i++) { printf("%02x ", rx_buffer[i]); } printf("\r\n"); memset(rx_buffer, 0, sizeof(rx_buffer)); } /** * Event handler */ static void lora_event_handler(lorawan_event_t event) { switch (event) { case CONNECTED: printf("\r\n Connection - Successful \r\n"); if (MBED_CONF_LORA_DUTY_CYCLE_ON) { send_message(); } else { ev_queue.call_every(TX_TIMER, send_message); } break; case DISCONNECTED: ev_queue.break_dispatch(); printf("\r\n Disconnected Successfully \r\n"); break; case TX_DONE: printf("\r\n Message Sent to Network Server \r\n"); if (MBED_CONF_LORA_DUTY_CYCLE_ON) { send_message(); } break; case TX_TIMEOUT: case TX_ERROR: case TX_CRYPTO_ERROR: case TX_SCHEDULING_ERROR: printf("\r\n Transmission Error - EventCode = %d \r\n", event); // try again if (MBED_CONF_LORA_DUTY_CYCLE_ON) { send_message(); } break; case RX_DONE: printf("\r\n Received message from Network Server \r\n"); receive_message(); break; case RX_TIMEOUT: case RX_ERROR: printf("\r\n Error in reception - Code = %d \r\n", event); break; case JOIN_FAILURE: printf("\r\n OTAA Failed - Check Keys \r\n"); break; case UPLINK_REQUIRED: printf("\r\n Uplink required by NS \r\n"); if (MBED_CONF_LORA_DUTY_CYCLE_ON) { send_message(); } break; default: MBED_ASSERT("Unknown Event"); } } // EOF