In this tutorial, we will learn how to set up specific LoRaWAN® regional parameters for the LoRa® module (Murata CMWX1ZZABZ-078) of the Arduino® MKR WAN 1310 and Arduino® MKR WAN 1300 boards. For doing this, we are going to use the Arduino MKRWAN library functionalities.
LoRaWAN® is a "Low Power Wide Area (LPWA) end-to-end system architecture designed to wirelessly connect battery operated "things" to the internet in regional, national or global networks. The architecture includes protocol standards and features that support low-cost, mobile, and secure bi-directional communication for Internet of Things (IoT), machine-to-machine (M2M), smart city & industrial applications". LoRaWAN® is optimized for low-power consumption and it is designed to scale from a simple gateway up to a large global network of billions of connected devices.
LoRaWAN® fundamental characteristics are the following:
The LoRa Alliance® specifies the LoRaWAN® networking protocol in the LoRaWAN® specification documents. These documents are developed and maintained by the LoRa® Alliance, an open association of collaborating members. As stated before, though LoRaWAN® operates on license-free and cost-free ISM bands, manufacturers and operators of LoRaWAN® devices still have to fulfill various country-specific regulations.
The LoRaWAN® Regional Parameters specification is a companion to the LoRaWAN® Link Layer specification. While the LoRaWAN® Link Layer specification defines the air interface between a compliant end-device (sensor, actuator, tracker, etc.) and a compliant network core, the LoRaWAN® Regional Parameters specification defines the adaptation of the LoRaWAN® Link Layer specification to comply with the various regulations enforced throughout the world on the use of various frequency bands of the unlicensed spectrum which are available.
Also, the LoRaWAN® Regional Parameters specification documents the physical layer configurations required for the compliant operation of LoRaWAN® Link Layer radios using various radio frequency modulation techniques.
The idea behind the LoRaWAN® Regional Parameters specification is to create the smallest number of regional channel plans covering the largest possible number of regulatory regions. With this, complexity is decreased to implementers as well as the certification cost (end-device certification is enumerated by Link Layer, Regional Parameters and channel plan revision).
LoRaWAN® Regional Parameters specifications do not specify everything. They only cover a region by specifying the common denominator. For example, the LoRaWAN® Regional Parameters for Asia only specify a common subset of channels, but there are variations between regulations in Asian countries. Furthermore, each network server operator, for example The Things Network (TTN), is free to select additional parameters, such as additional emission channels.
For more information, you can read the RP002-1.0.2 LoRaWAN® Regional Parameters document here.
Let's use Australia (AU915-928) as an example of how we can set up, or configure, it's specific LoRaWAN® regional parameters in the LoRa® module of our MKR WAN 1310 board and connect it to TTN. TTN also have specific LoRaWAN® protocol characteristics for every region, including Australia, that must be configured. You can read more about The Things Network and the LoRaWAN® Regional Parameters here.
As stated in section 2.8 of the LoRaWAN® Regional Parameters specification, in Australia the LoRaWAN® frequency spectrum has 64 uplink channels available, channels 0 to 63 (125 kHz each), starting at 915.2 MHz which increment every 200 kHz up to 927.8 MHz. There are also 8 additional uplink channels, channels 64 to 71 (500 kHz each), starting at 915.9 MHz which increment every 1.6 MHz up to 927.1 MHz. The frequency spectrum for those is overlapping with the basic 64 channels. For gateway to end-node device communication there are 8 downlink channels, channels 0 to 7 (500 KHz each), starting at 923.3 MHz which increment every 600 KHz up to 927.5 MHz. This information is shown in the table below:
Frequency Bands | Frequency Range (MHz) | Channels |
---|---|---|
Australia | 915.2 - 927.8 | 0 - 63 |
Uplink Sub-Bands | Frequency Range (MHz) | Channels |
Sub-Band 1 | 915.2 - 916.6 | 0 - 7 |
Sub-Band 2 | 916.8 - 918.2 | 8 - 15 |
Sub-Band 3 | 918.4 - 919.8 | 16 - 23 |
Sub-Band 4 | 920.0 - 921.4 | 24 - 31 |
Sub-Band 5 | 921.6 - 923.0 | 32 - 39 |
Sub-Band 6 | 923.2 - 924.6 | 40 - 47 |
Sub-Band 7 | 924.8 - 926.2 | 48 - 55 |
Sub-Band 8 | 926.4 - 927.8 | 56 - 63 |
Additional Sub Band | 915.9 - 927.1 | 64 - 71 |
Downlink Sub-Bands | Frequency Range (MHz) | Channels |
Downlink Sub-Band | 923.3 - 927.5 | 0 - 7 |
For 8 channel gateways, TTN in Australia uses sub-band 2 plus channel 65 only (uplink). This means that we need to program those specific channels (channel masking) in our MKR WAN 1310 board in order to make it work with a gateway connected to TTN. This can be easily done for our MKR WAN 1310 board using the Arduino MKRWAN library. Note that the downlink channels don't need to be configured.
First, let's make sure our board drivers are installed. If we are using the online IDE, we do not need to install anything. If we are using the offline IDE, we need to go to Tools > Board > Board Manager.... Here we need to look for Arduino SAMD boards (32-bits ARM Cortex M0+) and install the latest version. After installing the drivers remember to select the board and the port, to which it is connected, in the Tools menu.
After installing our board drivers, we need to install also the MKRWAN library. If we are using the online IDE, there is no need to install anything. If we are using the offline IDE, we need to go to Tools > Manage Libraries.... Here we need to search for MKRWAN and install the latest version.
Before we can use the MKRWAN library a firmware update of the LoRa® module of our MKR 1310 board is recommended. Updating the module's firmware can be done easily with the MKRWANFWUpdate_standalone sketch. We can find this sketch in File > Examples > MKRWAN > MKRWANFWUpdate_standalone. After uploading the sketch, we should see the following output in the Arduino IDE Serial Monitor when the firmware update is done:
For enabling or disabling, or masking, specific LoRaWAN® frequency spectrum channels in our MKR WAN 1310 board we can use the
enableChannel()
and disableChannel()
functions from the MKRWAN library. Channel masking should be made in the initialization function like in the example code shown below:1#include <MKRWAN.h>2
3LoRaModem modem;4
5void setup() {6 int status;7
8 // Initialize serial port at 9600 bauds9 Serial.begin(9600);10 while (!Serial);11
12 loraSetup();13 14 Serial.println("--------------------------------");15 Serial.println("- MKR WAN 1310 Channel Masking -");16 Serial.println("--------------------------------");17
18 // Print default channels configuration19 Serial.print("- Default mask: ");20 Serial.println(modem.getChannelMask());21
22 // Disable all channels23 Serial.println("- Disabling all channels..."); 24 for (unsigned int i = 0; i < 72; i++) {25 modem.disableChannel(i);26 }27 28 // Print current channels configuration29 Serial.print("- Current mask: ");30 Serial.println(modem.getChannelMask());31 32 // Enable AU915-928 channels33 // LoRaWAN® Regional Parameters and TTN specification: channels 8 to 15 plus 65 34 Serial.println("- Enabling channels 8 to 15 plus 65..."); 35 for (unsigned int i = 8; i <= 15; i++) {36 modem.enableChannel(i);37 }38
39 modem.enableChannel(65);40
41 // Print current channels configuration42 Serial.print("- Current mask: ");43 Serial.println(modem.getChannelMask());44}45
46void loraSetup() {47 // Initialize LoRa module with the AU915-928 region parameters48 if (!modem.begin(AU915)) {49 Serial.println("- Failed to start LoRa module!");50 while (1);51 };52
53 delay(5000); 54}55
56void loop() {}
After uploading the sketch, we should see the following output in the Arduino IDE Serial Monitor:
ff000000f000ffff00020000
is the channel mask we get if we block all channels except those from sub-band 2 plus channel 65. Now, with this mask and the sendMask()
function from the MKRWAN library, we can try a common Over-The-Air-Activation (OTAA) join to TTN like in the example code shown below:1#include <MKRWAN.h>2#include "arduino_secrets.h"3
4LoRaModem modem;5
6// Enter your sensitive data in the secret tab or arduino_secrets.h7String appEui = SECRET_APP_EUI;8String appKey = SECRET_APP_KEY;9
10void setup() {11 // Initialize serial port at 9600 bauds12 Serial.begin(9600);13 while (!Serial);14 15 // Initialize LoRa module with the AU915-928 region parameters16 if (!modem.begin(AU915)) {17 Serial.println("Failed to start module");18 while (1) {}19 };20
21 // Device module version and EUI22 delay(5000);23 Serial.print("Your module version is: ");24 Serial.println(modem.version());25 Serial.print("Your device EUI is: ");26 Serial.println(modem.deviceEUI());27
28 // Enable AU915-928 channels29 // LoRaWAN® Regional Parameters and TTN specification: channels 8 to 15 plus 65 30 modem.sendMask("ff000001f000ffff00020000");31 Serial.println(modem.getChannelMask());32 modem.setADR(true);33 join();34}35
36void join() {37 // Try to connect38 int connected = modem.joinOTAA(appEui, appKey);39 if (!connected) {40 Serial.println("Something went wrong, retrying...");41 join();42 }43}44
45void loop(){}
That's it! Now you should be able to configure your own LoRaWAN® Regional Parameters using the
enableChannel()
, disableChannel()
and sendMask()
functions.In this tutorial we learned how to set up specific LoRaWAN® Regional Parameters for the LoRa® module (Murata CMWX1ZZABZ-078) of the Arduino® MKR WAN 1310 board using the
enableChannel()
, disableChannel()
and sendMask()
functions from the MKRWAN library.