Connecting the Portenta Max Carrier to The Things Network

This tutorial explains how to connect your Portenta Max Carrier to the Things Network(TTN) using its onboard LoRaWAN® module.

Overview

This tutorial explains how to connect your Arduino® Max Carrier, with an Arduino® Portena H7 to The Things Network (TTN) using its onboard LoRaWAN® module. The article will focus on achieving communication between the Max Carrier and an application on TTN.

Goals

  • Enable LoRaWAN® connectivity on the Portenta Max Carrier.
  • Establish a connection between the Portenta Max Carrier and TTN.

Required Hardware and Software

The Arduino® Portenta Max Carrier LoRaWAN® Module

The Portenta Max Carrier provides you with an unlimited range of applications, from robotics and medical devices to industrial or automotive applications; the Max Carrier possibilities are endless. One feature that boosts Portenta's Max Carrier possibilities is its onboard LoRaWAN® module, the CMWX1ZZABZ-078 from Murata®. LoRaWAN® is a Low Power Wide Area Network (LPWAN) designed to connect low power devices to the Internet. It was developed to meet and fulfill Internet of Things (IoT) devices' requirements, such as low-power consumption and low data throughput.

CMWX1ZZABZ-078 LoRaWAN® module in the Portenta Max Carrier.
CMWX1ZZABZ-078 LoRaWAN® module in the Portenta Max Carrier.

For more in-depth information about LoRa® and LoRaWAN®, please read The Arduino Guide to LoRa® and LoRaWAN®.

Connecting to TTN

Let's start sending data to TTN using the Portenta Max Carrier LoRaWAN® module. To do this, you will need a TTN account and to be in the range of a public TTN gateway. You can check the world map of public gateways connected to TTN and see if your region already has a gateway installed. If not, consider installing one!

Check out this article from TTN, where you can find how to buy or build your gateway to extend TTN coverage in your region.

To connect your Portenta Max Carrier to TTN, we must follow these steps:

  1. Hardware setup.
  2. Software setup.
  3. Portenta Max Carrier provisioning.
  4. Create an application in TTN.
  5. Send a message to a TTN application.

Let's start!

1. Setting up the Hardware

Begin by attaching the Arduino® Portenta H7 board to the high-density connectors of the Portenta Max Carrier, as shown in the image below:

CMWX1ZZABZ-078 LoRaWAN® module in the Portenta Max Carrier.
CMWX1ZZABZ-078 LoRaWAN® module in the Portenta Max Carrier.

To power the CMWX1ZZABZ-078 LoRaWAN® module of the Portenta Max Carrier, you can use the DC power jack (with a 4.5V to 36V external DC power supply) of the Portenta Max Carrier or a 18650 3.7V Li-Ion battery, connected to the Portenta Max Carrier battery clips; you can power the module also directly from the USB-C connector of the Portenta H7 board. Also, do not forget to attach an 868-915 MHz antenna to the SMA connector (J9) on the Max Carrier.

Power sources and LoRa® antenna connector in the Portenta Max Carrier.
Power sources and LoRa® antenna connector in the Portenta Max Carrier.

Using the LoRaWAN® module of the Portenta Max Carrier without an antenna may damage it. Please, do not forget to connect a suitable antenna to the dedicated SMA connector (J9) on the Portenta Max Carrier.

Now you can connect the Portenta H7 board to your computer using a USB-C cable. Don't forget to change the position of the BOOT DIP switch (SW1) to OFF ; otherwise, you will not be able to program your Portenta H7 board when attached to the Portenta Max Carrier.

Power sources and LoRa® antenna connector in the Portenta Max Carrier.
Power sources and LoRa® antenna connector in the Portenta Max Carrier.

2. Setting up the Software

You can use several Arduino libraries with the CMWX1ZZABZ-078 LoRaWAN® module from Murata®; we recommend the MKRWAN library, developed by the Arduino Team. The MKRWAN library provides you with the APIs to communicate with LoRa® and LoRaWAN® networks using the CMWX1ZZABZ-078 module. You can use this library in the Arduino IDE, both online and offline.

If you are using the online IDE, you don't need to do anything; the library is already installed and ready to be used. If you are using the offline IDE, you must install the library manually. Installing the library can be done quickly by navigating to Tools > Manage Libraries... and then in the Library Manager search for MKRWAN library by Arduino; remember to install the latest version of the libraries. You can also access the Library Manager using the left toolbar of the IDE, as shown in the image below:

Library Manager in the Arduino IDE 2.
Library Manager in the Arduino IDE 2.

Currently, there are two versions of the MKRWAN library. We recommend using the MKRWAN_v1 library since MKRWAN_v2 library is still in beta phase.

To use the MKRWAN library with the Portenta Max Carrier, you must define

PORTENTA_CARRIER
before the library inclusion, as shown below:

1#define PORTENTA_CARRIER
2#include <MKRWAN.h>

2.1 Updating the LoRaWAN® Module Firmware

The LoRaWAN® module firmware of the Portenta Max Carrier must be updated before its first use. This can be done using the example sketch

MKRWANFWUpdate_standalone
of the MKRWAN library. You can open this example by navigating to File > Examples > MKRWAN. Before uploading the sketch to the Portenta H7 board, open the
MKRWANFWUpdate_standalone.ino
file and define
PORTENTA_CARRIER
before the library inclusion, as shown in the image below:

Library Manager in the Arduino IDE 2.
Library Manager in the Arduino IDE 2.

Upload the sketch, open the Serial Monitor and wait for the firmware update to finish. You should see a confirmation message when the process is done.

3. Provisioning the Arduino® Portenta Max Carrier

Device provisioning is a process comparable to bank card numbering. Let's think about bank cards; bank cards numbers start with a six-digit vendor ID number that indicates who allocated and controls the card's security; the remaining digits are unique numbers associated with a specific card. Devices with LoRa® and LoRaWAN® capabilities have a similar system; the Join Server Unique Identifier (usually referred to as

JoinEUI
) is a number that manages the security and authorizes the device in a network, while the Device Unique Identifier (usually referred to as
DevEUI
) is a unique number that identifies the device. The
JoinEUI
and
DevEUI
are required to send information to TTN; the
JoinEUI
number is provided by the network (in this case TTN) while the
DevEUI
is provided by the manufacturer of the device's LoRa® module.

The following sketch let's you find out what is the

DevEUI
of your Portenta Max Carrier:

1#define PORTENTA_CARRIER
2#include <MKRWAN.h>
3
4auto region = US915;
5
6LoRaModem modem(Serial1);
7
8void setup() {
9 Serial.begin(115200);
10 while(!Serial1);
11
12 if(!modem.begin(region)) {
13 Serial.println("Failed to start the module...");
14 while(1) {}
15 }
16
17 Serial.print("Your Portenta Max Carrier DevEUI is: ");
18 Serial.println(modem.deviceEUI());
19}
20
21void loop() {}

The only line you may need to change before uploading the code is the one that sets the frequency:

1auto region = US915;

Set the frequency designator according to your country. You can find more information about frequency plans definitions used in TTN here. After you upload the sketch to your Portenta H7 board, you should see the Portenta Max Carrier

DevEUI
in the Arduino IDE Serial Monitor as shown below:

1Your Portenta Max Carrier DevEUI is: a861XXXXXXXXXXXX

Now, let's use the

DevEUI
number from your Portenta Max Carrier to create an application in TTN.

3. Creating an Application in TTN

To send information to TTN, first we need to create an application and register a device with it. Navigate to TTN portal and sign in; after signing in, click on Create an application. If you already created an application, click on Go to applications.

TTN console welcome page.
TTN console welcome page.

Now click on Create an application. You will need to add the following information:

  • Owner: the person or organization that owns the application.
  • Application ID: a unique identifier for your application (must be lowercase and without spaces).

Complete both fields and click on Create application. Now you will be redirected to the application dashboard that shows information of the newly created application.

Application dashboard in TTN.
Application dashboard in TTN.

Now, scroll to End devices in the left toolbar and then click on Add end device; a registration page for end devices will open.

Registering an end device in TTN.
Registering an end device in TTN.

On the registration page, click on Manually; you will have to add the following information for your Portenta Max Carrier:

  • Frequency plan: choose a region according to your country.
  • LoRaWAN® version: 1.0.2.
  • Regional Parameters version: 1.0.2.

Click on Show advanced activation, LoRaWAN® class and cluster settings and choose:

  • Activation mode: Over the air activation (OTAA).
  • Additional LoRaWAN® class capabilities: None (class A only).
  • Network defaults: Use network's default MAC settings.

Leave the Cluster settings option unchecked. Then continue with the following information:

  • DevEUI: fill it with the
    DevEUI
    number of your Portenta Max Carrier you found before.
  • AppEUI: fill it with zeros or enter your own.
  • AppKey: generate one or enter your own.
  • Device ID: A custom identifier for your board, must be lowercase and without spaces.

Click on Register end device; this will take you to a Device Overview page where you will see all the information related to the device. Now, you will use some of this information with your Portenta Max Carrier to send data to TTN.

Device overview in TTN.
Device overview in TTN.

4. Sending Data to an Application in TTN

Now, let's start sending information to TTN. The following sketch enables you to join and send data to TTN using the Over the Air (OTAA) device activation method. You will need to define your TTN application's AppEUI and AppKey numbers in the

arduino_secrets.h
file before uploading the code:

1#define PORTENTA_CARRIER
2#include <MKRWAN.h>
3#include "arduino_secrets.h"
4
5auto region = US915;
6
7LoRaModem modem(Serial1);
8
9void setup() {
10 Serial.begin(115200);
11 while (!Serial);
12 Serial.println(F("Portenta Max Carrier LoRaWAN Example (OTAA)"));
13
14 if (!modem.begin(region)) {
15 Serial.println(F("Failed to start the module..."));
16 while (1) {}
17 };
18
19 Serial.print(F("Your Portenta Max Carrier module version is: "));
20 Serial.println(modem.version());
21
22 if (modem.version() != ARDUINO_FW_VERSION) {
23 Serial.println(F("Please make sure that the modem's firmware is updated."));
24 Serial.println(F("To update the module's firmware, open and upload the 'MKRWANFWUpdate_standalone.ino' sketch."));
25 }
26
27 Serial.print(F("Your Portenta Max Carrier DevEUI is: "));
28 Serial.println(modem.deviceEUI());
29
30 appKey.trim();
31 appEui.trim();
32
33 int connected = modem.joinOTAA(appEui, appKey);
34
35 if (!connected) {
36 Serial.println("Something went wrong; are you indoor? Move near a window and retry...");
37 while (1) {}
38 }
39
40 delay(5000);
41
42 modem.setPort(3);
43 modem.beginPacket();
44 modem.print("HelLoRa World!");
45 int errorCode = modem.endPacket(true);
46 if (errorCode > 0) {
47 Serial.println("Data sent correctly!");
48 } else {
49 Serial.println("Error sending data...");
50 }
51}
52
53void loop() {
54 while (modem.available()) {
55 Serial.write(modem.read());
56 }
57 modem.poll();
58}

The

arduino_secrets.h
file which contains AppEUI and AppKey numbers for the TTN applications can be defined as following code. AppEUI and AppKey information is found on the End device page of the TTN Application.

1String appEui = "xxxxxxxxxxxxxxxx";
2String appKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

If data was sent correctly to TTN, you should see the following messages in the Arduino IDE Serial Monitor:

Data sent correctly!

In your device overview dashboard on TTN, you should see changes in data activity every time a new message is sent.

Conclusion

You have now successfully configured and used the onboard LoRaWAN® module of your Portenta Max Carrier. You also have learned how to correctly setup a TTN application and enable LoRaWAN® connectivity between a TTN application and the Portenta Max Carrier.

Next Steps

  • Scale up the usage of Portenta Max Carrier by using its additional peripherals and turning them into interesting industrial-grade projects, taking advantage of LoRaWAN® connectivity.

Troubleshooting

While working on the sketch or when tried to upload the sketch, the Arduino IDE might show some errors preventing to proceed on the development. You can try the following troubleshooting tips to solve the commonly known issues:

  • If the sketch upload process fails, check if your Portenta H7 is in bootloader mode. To put the Portenta H7 into Bootloader mode, double-press its RESET button and verify that the green LED is waving. After this, you can try re-uploading the sketch.
  • Check the position of the BOOT DIP switch of the Portenta Max Carrier. If the Portenta H7 gets into bootloader mode immediately after power-on, including when connected via USB-C, change the position of the BOOT DIP switch to OFF.
  • If the Arduino IDE fails to compile the sketch, check if you have defined
    PORTENTA_CARRIER
    before the MKRWAN library inclusion.