This tutorial explains how to connect your Portenta H7 to The Things Network (TTN) using the Vision Shield's LoRa® Connectivity feature. A data communication channel will be enabled between the H7 and a TTN application that will be configured on your TTN console.
In order to connect your Portenta to the TTN, make sure you are within the range (max. 10 Km) from an available LoRa® Gateway. Indoor gateways will have a much shorter range. It is recommended that you check LoRa® Gateway availability on The Things Network map before you try this tutorial.
The Portenta Vision Shield - LoRa® can be connected to TTN and can transmit data to other devices connected to this network through a secure channel. This channel is nothing but an application on the TTN network dedicated for your board. In this tutorial, you will be guided through a step-by-step process of setting up your Portenta board and the Vision Shield - LoRa® to communicate with a TTN application using OpenMV and MicroPython. As stated before, to be able to follow this guide, you need to be under coverage of one of the TTN gateways. You can check for the coverage now, if you have not done so yet.
Start by going here. First choose your region. Next, sign in with your The Things Network account or create a new one on the login page.
Once you have created an account with TTN, you need to create a TTN application. An application provides a way to aggregate data from different devices and then use these data with other 3rd party integrations. After signing in, click on Create an application or Go to applications if you already have created one.
Here you will have a list of all your applications. Now create your first app by pressing the Create an application button.
You have now to fill only the first two fields:
After completing these two fields, press the "Create application" button located at the bottom left corner of the page. The dashboard will then show you an overview of the newly created app.
Let's take a closer look at these sections:
To be able to use the LoRa® functionality, you need to first update the modems firmware through the Arduino IDE. Connect the Portenta H7 and Vision Shield to your computer and open the Arduino IDE. The LoRa® module on the Vision Shield can be accessed by using the MKRWAN library(if you cannot find it in your examples list, you can go to Tools > Library Manager and type "MKRWAN library" to install it). This library provides all the APIS to communicate with LoRa® and LoRaWAN® networks and can be installed from the library manager. Select the Portenta H7 (M7 core) board in the Arduino IDE, like shown below.
The code you need to upload and run is from the MKRWAN library and its name is MKRWANFWUpdate_standalone. With the Portenta M7 selected, upload the MKRWANFWUpdate_standalone sketch.
After uploading the sketch, open the Serial Monitor to confirm that the firmware has been updated. If the upload is successful, it will print the progress in the Serial Monitor.
If it all went correctly, you should see the same text in your Serial Monitor as on the image above.
It is now time to connect your Portenta H7 and Vision Shield - LoRa® to TTN. You will need to upload code to the board using OpenMV
Plug the Portenta Vision Shield - LoRa® to the Portenta H7 and them to your PC through the USB port. If the Portenta board does not show up on OpenMV, try double-pressing the reset button on the Portenta. Now update to the latest firmware in OpenMV.
The only line you may need to change before uploading the code is the one that sets the frequency. Set the frequency code according to your country if needed. You can find more information about frequency by country at this TTN link.
Consider that in Australia the boards connect correctly to TTN gateways on AS923 frequencies; AU915 frequencies requires the selection of sub band 2 which is not yet implemented in the firmware.
1// change this to your regional band (eg. US915, AS923, ...)2lora = Lora(band=BAND_EU868, poll_ms=60000, debug=False)
The
lora.join_OTAA()
or lora.join_ABP()
functions connect your Portenta Vision Shield to The Things Network (TTN), using either Over-The-Air-Activation (OTAA) or Activating-By-Personalization (ABP) protocols. You just need to enter our appEui
and appKey
. The timeout decides how long the board will try and connect before stopping.1try:2 lora.join_OTAA(appEui, appKey, timeout=20000)3 # Or ABP:4 #lora.join_ABP(devAddr, nwkSKey, appSKey, timeout=5000)
You can then send data to your TTN application with
lora.send_data()
, in here you can decide what data you want to send to your TTN application.1try:2 if lora.send_data("HeLoRA world!", True):3 print("Message confirmed.")4 else:5 print("Message wasn't confirmed")
Now you need to read the downlink message. Using the
lora.available()
function, you can check if data are received on the board. If there are data on the board that has been received, you can use the lora.receive_data()
function to take that data and put them into a local variable, making it easier to print in the OpenMV IDE serial terminal. Using lora.poll()
, you can make sure that the LoRa® module is ready before you run the loop again.1# Read downlink messages2while (True):3 if (lora.available()):4 data = lora.receive_data()5 if data:6 print("Port: " + data["port"])7 print("Data: " + data["data"])8 lora.poll()9 sleep_ms(1000)
Hint: The Complete Sketch can be found in the Conclusions
Then, once the upload is completed, open the Serial Terminal where you can now see firmware info, device EUI, data rate and join status.
In order to select the way in which the board is going to connect with TTN (OTAA or ABP) we need to configure it on the TTN portal. You will see which option you should select in the following steps.
Before your Portenta H7 can start communicating with the TTN, you need to register the board with an application. Go back to the TTN portal and scroll to End devices section on your Application dashboard, then click Add end device.
On the registration page, first you have to fill in information about your board. Select brand Arduino SA and Portenta Vision Shield - LoRa® as the model. Hardware and firmware versions will automatically be set to the newest ones. Then set your preferred region.
In the second step of registering the device, fill in End device ID and EUI. You can click the generate button next to the AppKey field to generate an app key for this device. Similarly, you can press the button next to the AppEUI field to make it all zeros or enter your own AppEUI.
Note: The Device ID must be lowercase and without spaces. The DevEUI can be copied from the terminal in OpenMV. You can run the following script to obtain it.
1from lora import *2print("Device EUI:", Lora().get_device_eui())
After pressing the Register button, your board will show up on the Device Overview page. You can now see all the information needed to complete the Arduino setup.
Once your board has been registered, you can send information to TTN. Let's go back to the sketch to fill in the appEui and appKey. The sketch you use here will leverage OTA connection.
You can read more into OTA vs ABP activation mode at this link
Once your board has been registered, you can send information to TTN. Let's proceed in OpenMV. In the sketch the application EUI and the app key needs to be filled in. Find the EUI and the App key from TTN Device Overview page.
If this process is done successfully, you will see this message:
1Message confirmed.
If you receive this message, you have managed to configure the Portenta H7 and the Portenta Vision Shield - LoRa® to TTN. You have retrieved the device EUI, used it to register the device in the TTN console and programmed the board using the data provided by TTN. Now, you can send data over LoRa® network, which can be viewed from anywhere in the world (as long as you have an Internet connection and your device is in range from a TTN gateway).
1from lora import *2
3lora = Lora(band=BAND_EU868, poll_ms=60000, debug=False)4
5print("Firmware:", lora.get_fw_version())6print("Device EUI:", lora.get_device_eui())7print("Data Rate:", lora.get_datarate())8print("Join Status:", lora.get_join_status())9
10appEui = "" # Add your App EUI here11appKey = "" # Add your App Key here12
13try:14 lora.join_OTAA(appEui, appKey, timeout=20000)15 # Or ABP:16 #lora.join_ABP(devAddr, nwkSKey, appSKey, timeout=5000)17# You can catch individual errors like timeout, rx etc...18except LoraErrorTimeout as e:19 print("Something went wrong; are you indoor? Move near a window and retry")20 print("ErrorTimeout:", e)21except LoraErrorParam as e:22 print("ErrorParam:", e)23
24print("Connected.")25lora.set_port(3)26
27try:28 if lora.send_data("HeLoRA world!", True):29 print("Message confirmed.")30 else:31 print("Message wasn't confirmed")32
33except LoraErrorTimeout as e:34 print("ErrorTimeout:", e)35
36# Read downlink messages37while (True):38 if (lora.available()):39 data = lora.receive_data()40 if data:41 print("Port: " + data["port"])42 print("Data: " + data["data"])43 lora.poll()44 sleep_ms(1000)
The most common issue is that the device cannot connect to a TTN gateway. Again, it is a good idea to check if you have coverage in the area you are conducting this tutorial, by checking out this map.
If you are within a good range from a gateway, you should also try to move your device and antenna to a window and even hold it out the window and move it around. This has proven successful on numerous accounts, as the signal can travel less obstructed.