The Built-in Network server of the WisGate Edge V2 gateways provides MQTT and HTTP integrations. Integration helps the user to post-process the data and implement solutions based on their needs. This article will show you 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 to Create new converter.
In the Name field, type a name for the decoder (e.g. Uplink decoder). Leave the Type as Uplink. You can also use the default decoder code provided by ThingsBoard.
/** Decoder **/
// decode payload to string
var payloadStr = decodeToString(payload);
var data = JSON.parse(payloadStr);
var deviceName = 'RAK7204';
var result = {
deviceName: deviceName,
attributes: {
integrationName: metadata['integrationName'],
temperature: data.temperature,
humidity: data.humidity,
barometer: data.barometer,
gas_resistance: data.analogInput,
},
};
/** Helper functions **/
function decodeToString(payload) {
return String.fromCharCode.apply(String, payload);
}
function decodeToJson(payload) {
// convert payload to string.
var str = decodeToString(payload);
// parse string to JSON
var data = JSON.parse(str);
return data;
}
return result;
Click Add to add the uplink decoder.
Now that the uplink data converter is ready, you can proceed to add the MQTT integration. Click the Integrations menu on the left tab.
Click the Add Integration button to add one.
In the Name field, give a name of the integration (e.g. MQTT Integration). In the Type field, select MQTT from the drop-down menu.
| 📝 NOTE: Selecting the type of integration pops up settings for the specified type. |
For the Uplink data converter, choose the decoder created earlier. The Host is the address of the MQTT broker which will be used for the messages.
| 📝 NOTE: Check the Debug mode to track events while configuring the integration. |
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 the Topic filters to set the subscription topics to which the ThingsBoard client must subscribe.
For WisGate Edge gateways, the topics are as follows:
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, the EUI of the device, and the ID of the multicast group, respectively.
📝 NOTE: You need to change the values in the topics in the ThingsBoard. For example, application/1/device/0123456789ABCDEF/join. |
Configure the Gateway
Now that the ThingsBoard is configured, you need to configure the gateway. Start by accessing the gateway. You can see how to do it in the WisGateOS V2 user manual.
Once you log in, head to the LoRa menu.
By default, the gateway works as a built-in network server. If that is not the case, check the Built-in Network Server Mode Settings in the WisGateOS V2 User manual to switch the mode to Built-in network server.
Once the gateway is in Built-in network server mode, head to the Applications tab.
Click the Add application button or add one now link to add a new application. On the new page, fill in the following information:
- Application name – type a name for the application.
- Application description – optionally, you can write a description of the application.
-
Application Type – from the drop-down menu select the type of application.
- Unified Application key – all devices will use the same application key. Selecting this option pops up an Application Key field. You can type your application key there or use the Autogenerate button to generate one.
| 📝 NOTE: The Auto Add Device switch pops up an Application EUI field. The device will be automatically added to the application after application EUI and key verification. |
-
- Separate Application keys – each device will have its own application key. The key is added when registering the device.
- Payload type – from the drop-down select CayenneLPP payload type and turn on the Only forward data object feature.
Once done setting up, click Save Application to add the application.
After the application is added, head to the End devices tab. If you are using the Auto Add Device feature, the devices should automatically register upon join request.
If that’s not the case, click the Add end device button. On the End device information page, fill in the following information:
- Activation Mode – choose the activation mode of your device – OTAA or ABP. ABP mode pops up two additional fields for the Application Session Key and Network Session Key.
- End device (group) name – name of the device.
- End device description (optional) – optionally, you can add description for the device.
- Class – the class of the device.
- Frame Counter width – the width of the frame counter. Leave as default.
- LoRaWAN MAC Version – the LoRaWAN MAC version. V1.0.2 pops up a LoRaWAN Regional Parameters reversion field where you need to select the reversion of the device.
Once everything is set, click Add end devices to go the page to add the device.
In the Adding end devices page, type the device EUI at the End Device EUI (main) and click Add to “End Devices list”.
📝 NOTE:
|
You will be redirected to the End devices page, where the device is added.
Set the MQTT Integration
After your device joins, head to LoRa -> Integration Interface Parameters section.
Turn on the integration by clicking Enable Integration Interface switch. By default, the Integration mode is Generic MQTT. If that is not the case, select the Generic MQTT as the integration mode.
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 changes.
After your device joins and sends uplink data, you can see it in ThingsBoard -> Integrations -> Your Integration -> Events.
The MQTT integration is ready. 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:
|
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 as follows:
-
application/{{application_ID}}/device/{{device_EUI}}/join application/{{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.
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 LoRa -> Integration Interface Parameters section.
Turn on the integration by clicking Enable Integration Interface switch. By default, the Integration mode is Generic MQTT. If that is not the case, select it manually.
The default MQTT Broker is the built-in one (127.0.0.1). Check if the device default broker is selected. Leave everything else to default, then click Save changes.
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 the Add Data Converter icon () and choose to Create new converter.
| 📝 NOTE: Check the Debug mode to track events while configuring the integration. |
In the Name field, type a name for the decoder (e.g. Uplink decoder). Leave the Type as Uplink. You can also use the default decoder code provided by ThingsBoard.
/** Decoder **/
// decode payload to string
var payloadStr = decodeToString(payload);
var data = JSON.parse(payloadStr);
var deviceName = 'RAK7204';
var result = {
deviceName: deviceName,
attributes: {
integrationName: metadata['integrationName'],
temperature: data.temperature,
humidity: data.humidity,
barometer: data.barometer,
gas_resistance: data.analogInput,
},
};
/** Helper functions **/
function decodeToString(payload) {
return String.fromCharCode.apply(String, payload);
}
function decodeToJson(payload) {
// convert payload to string.
var str = decodeToString(payload);
// parse string to JSON
var data = JSON.parse(str);
return data;
}
return result;
Click Add to add the uplink decoder.
Now that the uplink data converter is ready, you can proceed to add the HTTP integration. Click the Integrations menu on the left tab.
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: Selecting the type of integration pops up settings for the specified type. |
Enable the Debug mode. The debug mode is useful for development and troubleshooting.
For 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 -> Applications -> Select your application -> Configuration -> Integration Parameters.
Turn on the integration by clicking Enable HTTP/HTTPS Integration switch. This will pop up the HTTP/S integration field settings.
In the Uplink data, Join notification, Ack notification, and Device-status notification URLs fields, paste the end point URL copied above.
📝 NOTE:
|
If you want to see only the uplink messages, you can place the endpoint URL only in the Uplink data field.
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 choosing a 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.
📝 NOTE: If you have not checked the Open dashboard option, you can easily navigate to Dashboard groups menu -> All -> <Name_of_your_group> to see the added widget. |
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