LoRaWAN® Regional Parameters in the Arduino® MKRWAN 1310

Learn how to set up specific LoRaWAN® regional parameters in the LoRa® module of the Arduino® MKR WAN 1310 board using the Arduino MKRWAN library.

Introduction

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.

Goals

Required Hardware and Software

LoRaWAN® Networking Protocol Overview

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:

  • Long-range: typically two to 5 km in urban areas (obstacles) and 5 to 15 km in rural areas.
  • Long battery duration: up to 10 years without a replacement (note that long battery duration will require an increased downlink latency configuration).
  • Low cost: regarding sensors and maintenance.
  • License-free spectrum: LoRaWAN® networks operates on license-free and cost-​free ISM (Industrial, Scientific, Medical) bands; however, region-specific regulations apply.
  • Limited payload: 51 to 256 bytes (depending on data rate).
  • Limited data rate: 0.3 to 27 Kbps.

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.

LoRa Alliance® Regional Parameters Overview

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.

Regional Parameters Configuration Example: Australia

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 BandsFrequency Range (MHz)Channels
Australia915.2 - 927.80 - 63
Uplink Sub-BandsFrequency Range (MHz)Channels
Sub-Band 1915.2 - 916.60 - 7
Sub-Band 2916.8 - 918.28 - 15
Sub-Band 3918.4 - 919.816 - 23
Sub-Band 4920.0 - 921.424 - 31
Sub-Band 5921.6 - 923.032 - 39
Sub-Band 6923.2 - 924.640 - 47
Sub-Band 7924.8 - 926.248 - 55
Sub-Band 8926.4 - 927.856 - 63
Additional Sub Band915.9 - 927.164 - 71
Downlink Sub-BandsFrequency Range (MHz)Channels
Downlink Sub-Band923.3 - 927.50 - 7

AU915-928 channel frequencies (source: lora-alliance.org)
AU915-928 channel frequencies (source: lora-alliance.org)

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.

Channel Masking on the MKR WAN 1310 Board

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:

Updating the firmware of the MKR WAN 1310 LoRa® module.
Updating the firmware of the MKR WAN 1310 LoRa® module.

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 bauds
9 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 configuration
19 Serial.print("- Default mask: ");
20 Serial.println(modem.getChannelMask());
21
22 // Disable all channels
23 Serial.println("- Disabling all channels...");
24 for (unsigned int i = 0; i < 72; i++) {
25 modem.disableChannel(i);
26 }
27
28 // Print current channels configuration
29 Serial.print("- Current mask: ");
30 Serial.println(modem.getChannelMask());
31
32 // Enable AU915-928 channels
33 // 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 configuration
42 Serial.print("- Current mask: ");
43 Serial.println(modem.getChannelMask());
44}
45
46void loraSetup() {
47 // Initialize LoRa module with the AU915-928 region parameters
48 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:

Channel Masking in the MKR WAN 1310 board.
Channel Masking in the MKR WAN 1310 board.

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.h
7String appEui = SECRET_APP_EUI;
8String appKey = SECRET_APP_KEY;
9
10void setup() {
11 // Initialize serial port at 9600 bauds
12 Serial.begin(9600);
13 while (!Serial);
14
15 // Initialize LoRa module with the AU915-928 region parameters
16 if (!modem.begin(AU915)) {
17 Serial.println("Failed to start module");
18 while (1) {}
19 };
20
21 // Device module version and EUI
22 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 channels
29 // 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 connect
38 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.

Conclusion

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.

Suggest changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. If you see anything wrong, you can edit this page here.

License

The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.