The LR1110 LoRa Edge tracker is Semtech's new base design tracker technology. It is battery operated, leverages LoRa connectivity, and it doesn't require a GPS because it scans for geolocation signals such as WiFi and GNSS to compute its location in the cloud, making it very cost effective. The payload coming from the tracker needs to be decoded, which you can do by leveraging Semtech's open source library that interacts with their LoRa Cloud geolocation service.
This project takes Semtech's decoder to the next level by integrating it with Azure IoT Hub and making it easy to deploy to your Azure subscription via an Azure Resource Manager (ARM) template and leverage Azure services to implement your business applications. Because there is code that is dependent on the LoRaWAN Network Server (LNS) implementation being used, we provide support for 3 popular LNS providers as an example: Actility, Helium, and The Things Industries. Users of this code are welcome to extend it to support additional LNS providers.
Here is the general architecture for this solution:
Main components:
- LNS to Azure IoT Hub integration. This is a pre-requisite, since the LNS needs to be able to interact with Azure IoT Hub for both uplinks and downlinks.
- Router Azure Function. This function is responsible for getting the tracker payload, calling the LNS specific function to prepare the package required for using the LoRa Cloud APIs to decode the payload, and passing the resulting lat/long coordinates forward.
- LNS specific Azure Function. This project supports 3 LNS providers: Actility, Helium, and The Things Industries. Users are encourage to extend it to other LNS providers.
- Event Hub + Azure Stream Analytics. These components are used for routing the incoming data once decoded to the corresponding business application (e.g., storage, Power BI).
- Power BI dashboard using Azure Maps. We provide an example of a Power BI dashboard that's consuming data directly from an Azure SQL DB and displaying the lat/long coordinates using Azure Maps.
Here is what you need to do if you would like to take advantage of this project to connect your LoRa Edge tracker to Azure:
- Deploy ARM template to your Azure subscription.
- Setup configuration paramaters based on your specific deployment (e.g., Event Hub connection string, LNS to be used, etc.).
- Configure your LoRaWAN gateway to connect to your desired LNS provider.
- Configure your LNS via the corresponding console to listen to your gateway/tracker and to push data to the corresponding IoT Hub.
- Reset your tracker and make sure it wasn't connected to another LNS provider (and if it was, please make sure you remove it first before trying to connect it to a new one).
- LoRaWAN gateway to connect to the desired LoRaWAN network/LNS.
- LR1110 tracker.
- Azure subscription.
This is a step by step guide to setup the infrastructure and deploy the code to ingest, compute, and visualise the LoRa Edge tracker data.
For now the process is semi-automated. Certain steps need to be done manually.
The following tools and extension are necessary to build and deploy the sources and projects. Please make sure to have the pre-requisites ready before starting the setup.
- Visual Studio Code
- Visual Studio Code Azure Functions Extension
- Visual Studio Code SQL Server (mssql) Extension
- Visual Studio Code Stream Analytics Tools Extension
- Visual Studio Code Python Extension
- Visual Studio Code C# Extension
- Azure Tools Visual Studio Code
- Azure Functions Core Tools
- .NET 6.0 SDK
- .NET Core 3.1
- Python Version 3.9 or higher
Please make sure to log into your Azure Account with Visual Studio Code. A tutorial can be found in this article: Configure Visual Studio Code for Azure development
The following button deploys the core infrastructure into your chosen subscription.
For the custom deployment, the following parameters need to be defined:
- Region: Select your designated Azure Region, make sure to pick a region which supports the necessary components
- Unique Solution Prefix: Pick a unique string for your solution. Storage account names must be between 3 and 24 characters in length and use numbers and lower-case letters only
- Sql Administrator Login: pick an username for your SQL administrator
- Sql Administrator Login Password: define a strong password for your SQL administrator. It has to include small letters, capital letters, a number and a special character
- Sql Firewall Start IP: Add the public IP of your computer to this field, for testing purposes you can use
1.1.1.1
- Sql Firewall End IP: Add the public IP of your computer to this field, for testing purposes you can use
255.255.255.255
The template includes the following components
- IoT Hub
- Azure Function
- SQL DB
- Event Hub
- Stream Analytics
If you would like to deploy the ARM template manually you can find the code in the /arm
directory.
This chapter describes how to deploy the source code into the created Azure components from the step before.
Before starting with the deployment, please make sure that the Azure services have been deployed and the necessary tool pre-requisites have been installed on your local machine.
Clone this github repository to your local computer:
git clone https://github.com/Azure-Samples/semtech-lr1110-azureiot-integration
- In your file explorer navigate to the
SensorDataSQLDB
folder and open it with Visual Studio Code - Establish the connection to the previously created DB with the Visual Studio Code SQL extension. During the setup of the connection, make sure you set the database name of the previously created Azure SQL DB, do not leave this to default.
- Open the
signal_position.sql
file in the project folder - Click the execute button in the top right corner and make sure to pick the previously created connection
- The query should be successfully executed
- Use the Visual Studio Code SQL Server extension to check the existing tables in your DB, it should show
dbo.signal_position
- In your file explorer navigate to the
DataPipelineASA
folder and open it with Visual Studio Code - Please, make sure you login to your Azure account
- The Azure Stream Analytics Visual Code extension should recognize the project, you can verify this if the following options are shown in the
loraedge-ASA.asaql
file:
- Open the
decoder-input.json
file in the Inputs folder
- Use the Azure Stream Analytics extension to add the previously created Azure EventHub as input
- Open the
sqldb.json
file in the Outputs folder - Use the Azure Stream Analytics extension and the offered wizard to add the previously created Azure SQL DB as output
- Make sure to use the same User and Password as defined in the deployment
- Use the wizard to set the password in the file to store it in the secure configuration manager
- The SQL output table has the name
signal_position
- Open the file
loraedge-ASA.asaql
and use the Visual Studio Code Command Palette (Ctrl-Shift-P) to run the following command:ASA: Submit to Azure
- Follow the wizard to deploy your Job to the previously deployed ASA instance on Azure. If you do not see this instance listed in the wizard, please look in the Azure portal and create a new job using the deployed instance name:
- Once the deployment is successful, the Cloud Job View of the Azure Stream Analytics Tools extension should open and you should be able to start the job (and it does take some time until it is up and running and you can see it on your screen)
- In your file explorer navigate to the
Router
folder and open it with Visual Studio Code - The C# Visual Studio Code Extension should recognize the project
- Use the Visual Studio Code Command Palette (Ctrl-Shift-P) to run the following command:
Azure Functions: Deploy to Function App...
- An input window should open below the command bar asking for your subscription.
- Pick the subscription where you performend the automatic deployment.
- Next the dialog will ask you to create a new function app or use an existing function. Make sure you pick the existing function app ending with
-csharp
- The function should now be automatically built and deployed to Azure
- Before the functions starts working, we need to set some environment variables this will be done after we deployed the decoder function.
- Double check if the deployment was successful in the Console output of your Visual Studio Code:
The Decoder function is used to transform the LoRa Uplink messages into usable and computable sensor information. The decoding function is depended on the LoRaWAN Network Server (LNS) where your LoRa Edge tracker is connected and is integrated with your Azure IoT Hub. At the moment the following vendors are supported:
- Actility ThingPark
- The Things Network/The Things Industries
- Helium Console
Depending on the LNS of your choice, navigate to one of the following folders and open it with Visual Studio Code
ActilityLoRaEdgeDecoder
HeliumLoRaEdgeDecoder
TTNLoRaEdgeDecoder
- The Python Visual Studio Code Extension should recognize the project
- Use the Visual Studio Code Command Palette (Ctrl-Shift-P) to run the following command:
Azure Functions: Deploy to Function App...
- An input window should open below the command bar asking for your subscripton.
- Pick the subscription where you performend the automatic deployment.
- Next the dialog will ask you to create a new function or use an existing function. Make sure you pick the existing function app ending with
-python
- The function should now be automatically built and deployed to Azure
- Double check if the deployment was successful in the Console output of your Visual Studio Code:
After completing the deployment of the function code, we now need to take care of the configuration.
To set the environment variables of your Azure Function navigate to the Settings
sections of your Azure Function and open the Configuration
page.
The Router function application uses a collection of environment variables. If the following variables aren't present in the environment variables, add them to the configuration.
The connection string of the IoT Hub's Event Hub, used as trigger on the Router Function to send the messages to the appropriate decoders.
Please follow the link below for detailed instructions on how to find the connection string. Make sure to use the Event Hub-compatible endpoint
:
Read from the built-in IoT Hub endpoint
Endpoint=sb://something.servicebus.windows.net/;SharedAccessKeyName=iothubowner;SharedAccessKey=xx;EntityPath=iothubname
Connection string defining the output of the router function to the enriched and decoded message Event Hub.
Please follow the link below for detailed instructions on how to find the connection string:
Connection string for a specific event hub in a namespace
Endpoint=sb://<NamespaceName>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<KeyValue>;EntityPath=<EventHubNameSpace>
The connection string for the IoT Hub used for device syncing and reading the device registry.
Please follow the link below for detailed instructions on how to find the connection string:
Retrieve connection string iothubowner shared access policy
HostName=something.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=xx
The Router function only supports a single decoder for moment. This configuration is the Azure Function URL of the deployed decoder Function. The URL can be found in the deployed Decoder function under Code + Test
and Get function URL
https://{yourfunctionname}.azurewebsites.net/api/LoRaEdgeDecoderHelium
Please, make sure to save all your settings configuration changes before continuing to the next step.
After the deployment of the function code succeeded, we need to take care of the configuration.
To set the environment variables of your Azure Function navigate to the Settings
sections of your Azure Function and open the Configuration
page.
The Decoder function application uses a collection of environment variables. If the following variables aren't present in the environment variables, add them to the configuration.
URL of the Semtech LoRa Cloud to compute the LoRa Edge positioning fix.
https://das.loracloud.com/api/v1/device/send
Authentication Token for the Semtech LoRa Cloud. Tokens can be generated in the Semtech Portal.
AQEAxxxxxHvset0OS9ZidYRgpSlYrd12NDvqxxxxxDVIGQAi+WFF
The connection string for the IoT Hub used for sending downlinks to the LoRa devices.
Please follow the link below for detailed instructions on how to find the connection string:
Retrieve connection string iothubowner shared access policy
HostName=something.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=xx
Please, make sure to save all your settings configuration changes before continuing to the next step.
To check if the setup was successful, please verify the following Azure components:
- Make sure your LoRa Edge device is sending LoRaWAN uplink messages to your designated LoRaWAN Network Server
- Check your IoT Hub instance and see if the used message count is raising according to the LoRaWAN uplink messages received by the LNS
- Open up your
Router
Azure Function, navigate to the deployed function and open theMonitor
dashboard. It should show that your function is successfully excecuted. The logs should also show that your router function is able to call your decoder function and gets the decoded message in response. Please, do the same for the Decoder function. - Use the existing Azure SQL connection to check the entries in the table, after a while it should show rows with positioning data.
An example of how to create a Power BI report to visualize the data generated by the tracker is included here.
- LR1110 documentation.
- Dragino LPS8 gateway documentation.
- Actility and Azure IoT Hub integration documentation.
- Actlity and Azure IoT Hub integration IoT Show episode.
- Helium and Azure IoT Hub integration.
- Helium Hacks episode - Azure IoT Hub integration.
- The Things Industries and Azure IoT Hub integration.