This tutorial is for people who have purchased a RAK WisGate Edge gateway and want to use the Built-in Network Server functionality to its fullest.
Here the user will learn how to subscribe to a topic to obtain data from your end-devices through MQTT. For convenience, the Built-in Network Server will be used in the examples.
This article is suitable for all RAK WisGate Edge series gateways (opens new window).
As for the examples, we will introduce how to use the built-in MQTT as well as an external one.
#A Brief Introduction to LoRaWAN and MQTT
If you are familiar with the two, you can skip this part.
As shown in Figure 1, LoRaWAN network roles are divided into:
- End nodes - The end-devices responsible for data collection. the data is then encrypted and transmitted to de gateway in the form of a wireless signal.
- Concentrator/Gateway - They collect the data from multiple nodes and send it to the Network server (NS).
- Network Server - The NS decrypts and processes the data forwarded by the gateway according to the data identification information and key.
RAK simplifies the actual deployment of a LoRaWAN network by integrating an NS in all our commercial gateways.
MQTT stands for Message Queuing Telemetry Transport, which is a publish/subscribe, extremely simple and lightweight, messaging protocol, intended for use on constrained devices and low-bandwidth, high-latency, or unreliable networks.
For more information, check out our article about MQTT (opens new window).
#The Role of MQTT in the LoRaWAN Networks
- Practical application 1: Use the built-in MQTT Broker of RAK commercial gateway
The WisGate Edge gateway obtains data from the nodes and sends it to the built-in NS, it then publishes the data to the built-in MQTT Broker. In this case, the gateway is both the publisher and the broker at the same time. The user then subscribes to the topic through third-party programs, like MQTT.fx, to be able to manage that data.
- Practical application 2: Use the built-in NS to publish data to an external MQTT Broker
The RAK commercial gateway obtains the data and sends it to the built-in NS, and it then publishes the data to a third-party MQTT Broker. Users subscribe through third-party programs. In this case, the gateway is only a publisher.
#Configuring the Built-in Network Server
This tutorial is for the WisGate Edge series of devices, all of which come pre configured in Network Server operation mode, so there is no need to adjust this setting unless you have changed it.
For details on configuring the settings mentioned above visit the WisGate Edge Documentation(opens new window)
However, there might be some adjustments needed for a particular setup like this one. Depending on your location, you have to make sure you have set the channel plan to one corresponding to your regional frequency band. Depending on the gateway variant, the default channel plan might not be the one you need.
#Use the Built-in MQTT Broker
This chapter will show you how to subscribe to topics, receive and send data reported by nodes through MQTT.fx, using the build-in MQTT Broker. You will need the MQTT.fx tool (MQTT clients) that can be downloaded here (opens new window).
#Create an Uplink Topic
- The data is transmitted by using an Uplink Topic. To see the MQTT topic templates for your gateway, in the Web UI, navigate to LoRa Network > Global Integration > Uplink Topic.
- To generate a correct Uplink Topic you will need the template and the following information:
- application_ID – This is the ID of your application. To see it, navigate to LoRa Network > Application.
- device_EUI – This is the EUI of your device. To see it, navigate to LoRa Network > Application > Edit.
With this information, the topic template
application//device//rxwill change to something like
If you want to subscribe to all nodes in an application, use the following topic (replace with the ID of your application):
- If you want to subscribe to data from all applications, use the topic:
#Subscribe to the Topic via MQTT.fx
- Open the MQTT.fx tool and click on the New button ().
- Type the IP address of the gateway and click Connect. The black indicator on the far right should turn green, indicating that the connection is successful.
- To connect to the topic, navigate to the Subscribe tab, type in the Uplink Topic you created, and click the Subscribe button.
- You can send a message from the node to test the connection. Via the RAK Serial Port Tool (opens new window), you can send a “Hello RAKwireless” message. The data must be in HEX, so if you want to send the message, use the following command:
- In the MQTT.fx interface, you can see the message you just sent. The message is encoded in base64 format.
#Send Data to the Node via MQTT.fx
- To send data to the nodes (downlink) requires publishing the data to the Downlink Topic. To see the topics templates, go to the Create an Uplink Topic part for reference. Find the Downlink Topic template and replace the application_ID with the ID of your application and device_EUI with the EUI of your device.
An example of Downlink Topic would look something like
- In the MQTT.fx navigate to Publish tab and type the name of your topic.
- To send a message to the node, in the field under the topic’s name type the command for it and click the Publish button. To send a "Hello" message, use the command:
- Confirmed can be true or false.
- The content of the data is the information you want to send. The information must be base64 encoded. This can be done with a converter (opens new window).
- fPort is the port number where you send the data. The number can be 1-255.
- The message you just sent can be seen in the RAK Serial Port tool and it is encoded in HEX format.
#Use an external MQTT Broker
This section will explain how to configure the gateway to use an external MQTT Broker and how to connect MQTT.fx to it.
#Configuring the Gateway and MQTT.fx
- To configure the gateway to point to an external MQTT server, in the Web UI, navigate to LoRa Network > Global Integration and type the MQTT Broker Address of the server you are going to use. Switch the Enable User Authentication, fill in the Username and Password to access the MQTT server, and click Save & Apply.
- Open the MQTT.fx and click on the Setting icon
- In the Edit Connection Profiles click on the plus icon ( ) in the lower-left corner to create a new Profile. Type in Profile name of your choice and the IP of the Broker Address. Click on User Credentials to enter the User Name and Password to access the MQTT server and then click OK.
- From the drop-down menu (left of the Connect button) at the main window of the MQTT.fx choose the Profile you just created and click Connect to connect to the external MQTT server. The black dot on the far right should turn green, indicating that the connection is successful.
- To subscribe, or to publish data, refer to the corresponding sections from the previous use case: Subscribe to the Topic via MQTT.fx and Send Data to the Node via MQTT.fx.
#Format Definition of the Obtained Through MQTT Data
In the previous sections, you were shown how to subscribe to Uplink data and how to send a Downlink to the node. But there are three more types of data:
- Join – This is the information received when the node is connected to the network.
- Ack – This is the confirmation message that the node sends as a reply after receiving a Downlink.
- Status – This is information about the node’s battery level.
In this section, a python code will be shown, that calls the MQTT subscription node's uploaded data and prints the corresponding content. When receiving Uplink data, the program will send a “Hello RAKwireless” message to the node. Make sure you read the code comments carefully before coding.
- For this tutorial, we will use an external MQTT Broker that is installed on a Raspberry Pi. If you want to build an MQTT server on a Raspberry Pi, run the following commands:
- You can check the status of the MQTT Broker by using the command:
- Python dependencies need to be installed. This is done with the commands:
- Create a new file where you will put the code, using the command:
- The content of the file is this code (make sure you read the explanations and make the needed changes for your particular case):
- Run the code by typing in the SSH terminal: