The Built-in Network Server of the WisGate Edge gateways provides MQTT and HTTP integrations. Integrations help the user post-process the data and implement solutions based on their needs. In this article, you will learn how to create an MQTT or HTTP Integration to ThingsBoard using the Built-in Network Server.
MQTT Integration
MQTT is a publish/subscribe protocol that allows data transfer to the desired MQTT broker. In this article, two examples will be shown:
- Connecting to the local MQTT broker on the gateway
- Connecting to an external broker
In the MQTT Integration, the ThingsBoard acts as an MQTT client.
Configure ThingsBoard
Login to your ThingsBoard account. If you do not have an account yet, then create one first.
After a successful login, you will see the ThingsBoard Overview page.
The first thing you need is a data converter for the uplinks. To create one, head to the Data converters menu.
To add a data converter, click the Add Data Converter icon (➕) and choose Create a new converter.
In the Name field, type a name for the decoder (e.g. Uplink decoder). Leave the Type as Uplink. You can use the default decoder code provided by ThingsBoard.
Click Add to add the uplink decoder.
Now, that the uplink data converter is ready, you can proceed to add the MQTT integration. Click Integrations tab from the menu on the left.
Click Add Integration (➕) button to add one.
In the Name field, give a name of the integration (e.g. MQTT Integration). On the Type field, select MQTT from the drop-down menu.
| 📝 NOTE: Note that after you select the type of integration, the additional settings for the specified type will appear. |
For the Uplink data converter, choose the created decoder earlier. The Host is the address of the MQTT broker which will be used for the messages.
External MQTT Broker
The first example will be with an external MQTT broker. If you want to use the local broker, proceed to the Local MQTT broker section.
The external broker used in this example is broker.hivemq.com. It is a free public MQTT broker, ideal for testing. You can use other ones or your own broker, then click Topic filters to set the subscription topics to which the ThingsBoard client must subscribe.
For WisGate Edge gateways, the topics are:
application/{{application_ID}}/device/{{device_EUI}}/joinapplication/{{application_ID}}/device/{{device_EUI}}/rxapplication/{{application_ID}}/device/{{device_EUI}}/txapplication/{{application_ID}}/device/{{device_EUI}}/ackapplication/{{application_ID}}/device/{{device_EUI}}/statusmcast_group/{{mcast_ID}}/tx
The application_ID, device_EUI, and mcast_ID are the ID of the application, the EUI of the device, and the ID of the multicast group, respectively.
📝 NOTE: You need to change the values on the topics in the ThingsBoard. For example, application/1/device/0123456789ABCDEF/join. |
Click Add to create the integration.
Configure the Gateway
Now, that the ThingsBoard is configured, you need to configure the gateway. Start by accessing the gateway. To access the gateway check the WisGateOS user manual.
Once logged in, head to the LoRa Network menu.
By default, the gateway works as a built-in network server. If that is not the case, check the Network Server section of the WisGateOS User manual to switch the mode to the Built-in Network Server. Once the gateway is in Built-In Network Server mode, head to the Applications tab.
Type the name of the application on the Please input application name field and click Add to add an application.
On the Application Configuration tab, choose the Device Authentication Mode. Leave it as it is by default.
- The Auto Add LoRa Device feature can be enabled. When the feature is enabled, the LoRa Device will be added automatically after Application EUI and Application Key pass verification.
- Type your Application Key (Application EUI if Auto Add LoRa Device is enabled) or generate a random one with the Generate Key option.
- The description field is optional.
In the Payload format tab, you can convert the data payload format into JSON by selecting CayenneLPP.
Once set, click Save & Apply to add the application.
Add a Device to the Application
Now that your application is created, you need to add devices to that application. click Edit of the application.
Type the device EUI in the Please input device EUI field and click Add to add a device.
In the Edit Device page, you must name your device in the Device name field.
Change the other settings to match your needs.
When done, click Save & Apply to add the device to the application.
Set the MQTT Integration
After your device joins, head to the Global Integration menu on the left. By default, the Integration Mode is Generic MQTT. If that is not the case, select it.
The default MQTT Broker is the built-in one (127.0.0.1). To point the MQTT client to the hivemq broker, you need to type broker.hivemq.com in the MQTT Broker Address field and then click Save & Apply.
After your device joins and sends uplink data, you can see it in ThingsBoard -> Integrations -> Your Integration -> Events.
The MQTT integration is successful. You can now proceed with processing the data.
Local MQTT Broker
The gateway comes with a built-in broker. You can connect the ThingsBoard client to the local broker.
📝 NOTE: For the connection to be successful, you need to put the gateway on DMZ. The DMZ exposes the gateway to the public network, so make sure you set a secured password to protect your device.
To connect to the broker, find your public IP and paste it into the Host field.
Click Topic filters to set the subscription topics to which the ThingsBoard client must subscribe. For WisGate Edge gateways, the topics are:
application/{{application_ID}}/device/{{device_EUI}}/joinapplication/{{application_ID}}/device/{{device_EUI}}/rxapplication/{{application_ID}}/device/{{device_EUI}}/txapplication/{{application_ID}}/device/{{device_EUI}}/ackapplication/{{application_ID}}/device/{{device_EUI}}/statusmcast_group/{{mcast_ID}}/tx
Where application_ID, device_EUI, and mcast_ID are the ID of the application, EUI of the device, and the ID of the multicast group, respectively.
Click Add to add the integration.
Configure the Gateway (Local MQTT)
To configure the gateway, follow the steps on the Configure the Gateway section.
Set the MQTT Integration (Local MQTT)
After your device joins, head to the Global Integration menu on the left. By default, the Integration Mode is Generic MQTT. If that is not the case, select it.
The default MQTT Broker is the built-in one (127.0.0.1). Check if the device’s default broker is selected. Leave everything else to default. Click Save & Apply.
After your device joins and sends uplink data, you can see it in ThingsBoard -> Integrations -> Your Integration -> Events.
The MQTT integration is successful. You can now proceed with processing the data.
HTTP Integration
The built-in Network Server provides HTTP integration. The HTTP integration converts existing protocols and payload formats to the ThingsBoard message format.
Configure ThingsBoard (HTTP Integration)
Login to your ThingsBoard account. If you do not have an account yet, then create one first.
After a successful login, you will see the ThingsBoard Overview page.
The first thing you need is a data converter for the uplinks. To create one, head to the Data converters menu.
To add a data converter, click Add Data Converter icon (➕) and choose to Create a new converter.
In the Name field, type a name for the decoder (e.g. Uplink decoder). Leave the Type as Uplink. You can use the default decoder code provided by ThingsBoard.
Click Add to add the uplink decoder.
Now, that the uplink data converter is ready, you can proceed to add the HTTP integration. click Integrations menu on the left (below Data converters).
Click the Add Integration (➕) button to add one.
In the Name field, give a name of the integration (e.g., HTTP Integration). In the Type field, select HTTP from the drop-down menu.
| 📝 NOTE: After selecting the type of integration, the additional settings for the specified type will appear. |
Enable Debug mode. Debug mode is useful for development and troubleshooting.
For the Uplink data converter, choose the created decoder earlier.
While creating the integration you can copy the HTTP endpoint URL, as it will be needed later.
Click Add to create the integration.
Configure the Gateway (HTTP Integration)
To configure the gateway, follow the steps on the Configure the Gateway section.
Set the HTTP Integration
After your device joins, head to LoRa Network -> Application -> Edit -> Integrations tab.
Turn on the integration by clicking Enable HTTP/HTTPS Integration switch.
In the Uplink data, Join notification, Ack notification, and Device-status notification fields, paste the endpoint URL copied above.
📝 NOTE:
|
Click Save & Apply to save the changes. You should see the uplink messages in the Event log.
Data Visualization from the End-Device
In this example, the RAK7204 WisNode Sense is the device used. The method to visualize the data for other devices is the same.
After creating the data converter, integration and getting some data in the Events tab, this automatically creates a device in the default device group based on the decoder. Head to the Device group menu.
By default, in the Device groups menu, you will find only one group named All. Click the Open icon.
You can find the created device. Just click on the device and head to the Attributes tab, and you will see the data from the node.
To visualize the data, simply select the desired value you want to visualize and then click the Show on widget button. In this example, choose temperature.
On the next page, from Current bundle drop-down menu, choose a desired widget for the data. For this example, choose Analogue gauges as the analog gauges have a widget for the temperature.
After you choose the widget, click Add to dashboard.
By default, the profile does not have a dashboard. You will need to create a new one. Choose Create new dashboard and type a name for the dashboard in the New dashboard title field. For example, RAK7204.
In that dashboard, you can add more widgets for the device. When you set the name for the dashboard, click Add button to add the widget. Optionally, you can check the Open dashboard option. This will automatically open the created dashboard after the widget is added.
You can do the steps above for the other data of the device. The only difference is when adding a widget. Click Select existing dashboard and select the already created dashboard (in this case, RAK7204).
Updated