LoRa Basics™ Modems: Walk-through

Application Server: Node-RED¶

This section deals with the installation and configuration of a Node-RED based Application Server example.

It also gives details of usage for the specific example provided with the node-red-contrib-loracloud-utils package.

Introduction¶

The application server handles application data and device management frames. As there is no background connection between the LoRaWAN® network server and the LoRa Cloud™ Modem & Geolocation Services, all uplinks related to modem traffic must be forwarded by the application server to the Lora Cloud Modem & Geolocation Services.

This demonstration uses Node-RED as the application server. Node-RED is a browser-based visual programming tool that allows for fast prototyping. Built on Node.js, Node-RED can be used to wire flows together using a wide array of nodes. These nodes can then be deployed to the Node-RED runtime with a single click.

Setup¶

Installation¶

To set up Node-RED, follow the instructions in the official installation guide, available here: https://nodered.org/docs/getting-started/. You can use a local computer, a Raspberry Pi, or any remote computer/server.

Accessing the Node-RED Editor¶

By default, Node-RED starts on port 1880. If you have installed Node-RED locally, browse to http://127.0.0.1:1880; otherwise navigate to http://IP_OF_INSTALLATION:1880.

Once Node-RED is set up correctly, the following page displays:

The user interface has three key areas:

Palette: This is where you can select nodes; these are functional blocks that can be dragged-and-dropped, and then can be linked together to create a flow.
Flow: This is the source code of the program. In this pane, you can link nodes together to create an application.
Sidebar: The Sidebar displays any Help or debugging information available for the selected node.

Installing Additional Nodes¶

To set up the demonstration, three additional libraries must be installed in Node-RED:

node-red-contrib-loracloud-utils: Handles calls to LoRa Cloud™ servers
node-red-dashboard: Provides tools to create dashboards, such as a temperature graph
node-red-contrib-web-worldmap: Creates a map for geolocation features

To set up Node-RED, use the Node-RED editor menu, as shown in the following video:

Video: Installing Additional Nodes

To set up Node-RED:

Click the hamburger menu in the top right corner of the screen.
Select Manage palette.
Select Install.
Search for node-red-contrib-loracloud-utils.
Click Install for the @semtech-wsp-apps/node-red-contrib-loracloud-utils package.
In the dialog box that pops-up, click Install.
Wait for the installation to complete. This might take several minutes.
Repeat these steps to install the node-red-dashboard and the node-red-contrib-web-worldmap libraries.

Importing a Flow¶

Note

The node-red-contrib-loracloud-utils package includes useful samples to walk you through this example project.

However, depending on the example you plan to run, other flows can be used. Particularly the SDKs SWSD001 and SWSD004 provide their own flows compatible with the embedded example codes they provide. Refer to the SWSD001 Application Server readme or to the SWSD004 Application Server readme for the corresponding flows.

This section illustrates the import and usage of flows based on the sample ones provided in node-red-contrib-loracloud-utils. For other flows, the process remains similar.

Watch this video to learn how to import flows:

Video: Import Samples for Demo

To import the example flow:

Click the hamburger menu in the top right corner of the screen.
1. Click Import.
2. Click Examples.
3. Select node-red-contrib-loracloud-utils and then modem.
4. Select New flow then click Import.
Place the nodes and then left-click to save their positions.
Deploy the flow by pressing the Deploy button on the device.
Dismiss the error by clicking Confirm deploy.

Note

The Deploy step reports an error because the MQTT nodes are not yet configured.

Configure the Flow¶

The example flow must be configured with the device information and the selected LoRaWAN network server.

Configuring the LoRaWAN Network Server (MQTT)¶

All network server connectors are activated by default; however, the MQTT connection must be set up separately.

Before you begin, get the required data:

MQTT server address
MQTT port
MQTT username
MQTT password

This data can be obtained when setting up the network server. For more information, see Network Server Setup.

Next, set up the desired network server:

Video: Setting up a Network Server

Delete the MQTT connectors to any unused LoRaWAN network servers.
Double-click an MQTT node to edit it.
Click the pencil icon to edit the MQTT broker configuration.
Enter values in the Server, Port, and TLS fields, if required.
On the Security tab, fill in the Username and Password fields.
Click Add and then click Done.
Click Add new mqtt-broker in the other nodes to select the server.
Click Deploy.

Note

Several LoRaWAN network servers can be used at a time.

LoRa Cloud Configuration¶

To configure the server, the MGS URL and MGS TOKEN values from the LoRa Cloud Modem & Geolocation Services setup step, are required, as is the device’s DevEUI.

Video: Configuration of MGS server connection

To configure the LoRa Cloud services for your use:

Double-click the MGS server token node to open it for editing.
Enter the token and then click Done.
Open the MGS URL node for editing.
Enter the URL and then click Done.
Open the DevEUIs URL node for editing.
Enter the DevEUIs and then click Done.
Click Deploy.

Note

Several DevEUIs can be configured at once
The characters for each DevEUI should be separated into groups of two, with a dash between each pair: XX-XX-XX-XX-XX-XX-XX-XX

Configuring Node-RED User Interface Elements¶

Node-RED user interface (UI) elements must be associated with a UI group. The following steps create an association with the default Node-RED UI group.

Video: Associating Node-RED UI elements with a UI group

To associate a Node-RED UI element with a UI group:

Select Temperature widget.
1. Click the pencil icon to edit the widget.
2. Click Update.
3. Click Done.
Repeat these steps for the Upload text widget and the Image widget.

Import the LoRa Basics Modem-E Flow Add-on¶

Once the LoRa Basics for end nodes flow has been set up, you need to import an add-on to see the geolocation features of the LoRa Edge™ Platform in action.

Video: Importing LoRa Edge™ Platform geolocation example

To import the add-on:

Click the hamburger menu in the top right corner of the screen.
1. Click Import.
2. Click Examples.
3. Select node-red-contrib-loracloud-utils then select Modem-E.
4. Select New flow and then click Import.
Place the nodes and then left-click to save their positions.
Double-click the blue node, Assistance coordinates for GNSS autonomous scans, to open it for editing.
Set the assistance coordinates [latitude, longitude] and then click Done.
Double-click the grey input link to edit it.
Check the Stream from DAS box and then click Done. This flow then connects to all streams from the LoRa Cloud™ Modem & Geolocation Services.
Double-click the grey output link to edit it.
Check the To the Lora Cloud Modem & Geolocation Services parser box and then click Done. The LoRa Cloud Modem & Geolocation Services output connects to the LoRa Cloud Modem & Geolocation Services parser block.
Press the Deploy button on the device to deploy the flow.

Note

Rough assistance coordinates are required by the solver for autonomous GNSS scans, and must have an accuracy of ± 150km. See the reference manual for a complete description.

Usage¶

Temperature¶

Temperature is sent automatically from the Murata modem when in Demo mode.

Note

If using a Nucleo board, you must press the blue button on the board itself to send the temperature data.

To display the dashboard

Add /ui to the URL in your web browser. (For example, if Node-RED is installed locally, use the URL http://127.0.0.1:1880/ui.)

The temperature graph displays:

Application server temperature graph — *Figure 2: Temperature Graph Available Via The Application Server*¶

Uploading a File¶

LoRa Basics Modem sends images through the File Upload service. The images are then reconstructed by the LoRa Cloud Modem & Geolocation Services. Once it has been fully received, the image displays in the Node-RED user interface, as shown here:

Image in the application server for file upload — *Figure 3: Image Uploaded With File Upload Service*¶

Note

The LoRa Basics Modem serial output displays INFO : File upload is complete, program a new alarm when a file transfer is complete.

Data Returned by the LoRa Cloud Modem & Geolocation Services¶

The Node-RED sidebar shows all data returned by the LoRa Cloud Modem & Geolocation Services. To view this data, click Debug, which is represented with an insect icon):

Node-RED debug button — *Figure 4: Node-RED Debug Button*¶

The data displayed looks like this:

Data from the LoRa Cloud Modem & Geolocation Services displayed in the debug sidebar — *Figure 5: Data From The LoRa Cloud Modem & Geolocation Services Displayed In The Debug Sidebar*¶

Warning

If some stream fragments are lost due to network issues, the subsequent streams are kept in the LoRa Cloud Modem & Geolocation Services’ memory.

These streams will be delivered to the application server as soon as they have been reconstructed. This may result in the stream being delivered out of order.

Sending a Request to the End Node Through the LoRa Cloud Modem & Geolocation Services¶

The LoRa Cloud Modem & Geolocation Services provide an easy way to send requests to the end node to get information or update configuration data. This can be tested by clicking the square buttons adjacent to the blue nodes in the Direct API calls section of the Node-RED example.

To send a request to the LoRa Cloud Modem & Geolocation Services

Click the blue button to the left of the associated box, as shown in Figure 6:

Request to LoRa Cloud Modem & Geolocation Services buttons — *Figure 6: Request to LoRa Cloud Modem & Geolocation Services Buttons*¶

Note

The full request list can be found here.

Geolocation (LoRa Basics Modem-E)¶

Geolocation results are displayed on a map and in Node-RED’s debug tab.

To display the map, add /worldmap to the URL in your web browser. For example, if Node-RED is installed locally, use the URL http://127.0.0.1:1880/worldmap).

Geolocation map — *Figure 7: Geolocation Map*¶

Note

The worldmap does not save location data. All points are lost when the page is closed.

LoRaWAN Class C (LoRa Basics Modem-E)¶

To be able to send downlink requests to the LoRaWAN network server provider, the application server must know which LoRaWAN network server the device is connected to. For Class A downlinks, the uplink information is propagated from the uplink connector to the downlink connector along with the message. However, in the case of Class C devices, the downlink is generated without an uplink event, so this information does not exist.

LoRaWAN Network Server Storage¶

The section Network Server context, which is part of the modem flow, features local data storage for devices’ LoRaWAN network server information. It behaves as follows:

On every uplink, the network server information of the device is stored in a local data structure.
When a Class C downlink is requested, the network server information for the device is extracted from this local data structure.
The message to downlink and the network server information are provided to the downlink connector.

This mechanism is implemented by the Network Server context flow, which is available as an example and illustrated here:

Network Server context flow diagram — *Figure 8: Network Server Context Flow Overview*¶

The node Update network server configuration storage receives all uplinks that are destined for the LoRa Cloud Modem & Geolocation Services and stores the network server information.

Downlink message Node Red blocks picture — *Figure 9: Generate Downlink Message Node*¶

The node Generate downlink message retrieves the network server information when a downlink is requested. This flow allows the network server to read and clean the content of the local data structure.

The content is displayed in the debug panel when Read LoRaWAN Network Server configuration is clicked.

Sending a Class C Downlink¶

There are three examples of Class C downlinks:

Example of message downlink: Sends a dummy payload.
Turn on LED: The payload corresponds to an evaluation kit command to turn on a red LED icon (a “flash” symbol) at the top left portion of the screen.
Turn off LED: The payload corresponds to an evaluation kit command to turn on a grey LED icon (again, the “flash” symbol) at the top left portion of the screen.

All downlink messages injected into the Generate downlink message node must be formatted as follows:

{
    "payload": {
        "payload": "001122",
        "port": 2,
        "deveui": "0011223344556677"
    }
}

where:

payload.payload is the hexadecimal string representing the payload to downlink
payload.port is the LoRaWAN port to use to send the downlink
payload.deveui is the hexadecimal string corresponding to the device which should receive the downlink. It must be known to the Network Server context storage data structure