What is vNode Gateway?
vNode is an industrial software platform that combines industrial connectivity with major IoT protocols to provide a plug and play solution. vNode utilizes input modules as the core of the solution, allowing it to read data from any source through different protocols.
This article will be useful to integrate vNode with Ubidots through MQTT protocol.
Requirements
An active Ubidots account.
vNode software installed. (Download vNode here)
1. Creating an MQTT Instance Module
Once vNode is running on your computer, you have to create an MQTT client module:
Open vNode and head to “Config” in the Navigation bar.
Click on “Modules” in the Explorer bar and create a new MqttClient module with the following information.
Where:
Pause links while unavailable: This option pauses data reception from other vNode while the module is offline.
Start: Controls the module’s behavior when vNode services start, including a restart option.
Enabled: Starts automatically when the vNode services start.
Start delay: Controls the delay in starting.
2. Logger and API configuration
It's necessary to configure the logger and API configuration for the module.
Note: the default setting will be sufficient.
Click on "MQTT Module" in the Explorer bar and then create a “New Connection” in the model window.
To configure the connection with Ubidots, it's necessary to modify the following information:
Authentication: Is the way by which MQTT will authenticate with the broker.
Authentication mode: Password.
Username: will be the TOKEN of your Ubidots account.
Password: TOKEN.
Connection options: Options to connect to the broker.
Broker URL: industrial.api.ubidots.com
Client ID: This field can't be empty, however, you can put in any client ID (in this case, we use a combination of random letters and numbers).
Agents: List of all agents using this connection. The agent is in charge of defining whether to send or receive data. Agents can be a Publisher, a Writer, or a Subscriber.
3. Send data from vNode
In this instance, you have to create a “New Publisher” agent, which is responsible for sending data to the MQTT broker. In this case, you can also use the default information with the following modifications:
Publisher:
Push interval: 10000 milliseconds. It's the interval between each data push to the MQTT broker.
Topic: /v1.6/devices/<deviceLabel>. The direction where you want to send the information. You need to replace <deviceLabel> with the unique identifier of the Ubidots device.
QoS: 1. Specifies the QoS of the published message.
Message format: How the incoming message will be parsed.
Serialization: Custom.
Script: <javascript>. is the format in which Ubidots receives data.
To modify the default JavaScript code, click on the "</>" symbol and paste the following code:
$.logger.debug("Parsing %d events", $.input.length);
$.logger.info("Parsing message: %j", $.input);
// Declare a variable to create the JS object wanted.
const response = {};
// Iterate over all events in $.input
for (const event of $.input) {
// Event data:
// {
// tagName: TAG_ADDRESS, // This is the path of the tag
// data: {
// value: TAG_VALUE, // This is the value used to update the tag. It can be any value.
// quality: TAG_QUALITY, // This is the quality of the tag for this event. It is a number from 0 (Bad) to 192 (Good).
// ts: EPOCH_TIMESTAMP // This values is the timestamp of the event. It is a number in epoch format with milliseconds.
// }
// }
// Convert to:
// {
// TAG_ADDRESS: {
// "value": TAG_VALUE,
// "timestamp": EPOCH_TIMESTAMP
// }
// }
let tmpList = response[event.tagName] || [];
tmpList.push({
"value": event.data.value,
"timestamp": event.data.ts,
"context": {
"quality": event.data.quality
}
});
response[event.tagName] = JSON.parse(JSON.stringify(tmpList));
}
$.logger.info("Response: %j", response);
// Send the output as string. JSON.stringify converts an JS object into a JSON string representation.
$.output = JSON.stringify(response);
Tag Filter: Used to filter which tags are affected by a specific publisher or writer. Create a tag filter for the publisher with the default information.
4. Configure the Tags for the Publisher
When using MqttClient, tags must be configured separately, in simple words, tags will be the variables that will be created in Ubidots. So you can create as many tags as variables you want to send to Ubidots. In this case, in order to have more clarity in the tags, we created a group of tags for the publisher and another for the subscriber. In the group corresponding to the publisher, we create the new tag.
To create the tags, click on "Tags":
Navigate to “Config” in the Navigation bar.
Click on “Tags” in the Explorer bar and create a new group.
Right-click on the group you have created and create new tag.
After creating the tag, enable the simulation selecting “Yes” in the box.
Note: You can modify the name of the group and the tag as you prefer.
5. Receive data from Ubidots
In this instance, you have to create a “Subscriber” agent, which is responsible for receiving data from the MQTT broker. In this case, we will select a variable that is on the same device as the publisher, to see the results on the same screen. As in the previous points, you can also use the default information with the following modifications:
Subscriber:
◦ Topic: /v1.6/devices/<deviceLabel>/<variableLabel>. The direction from which this Subscribers data originate. You need to replace <deviceLabel> and <variableLabel> with the unique identifier of the device and variable of Ubidots.
◦ QoS: 1. Specifies the QoS (Quality of service) for the subscription to the broker.
• Keep-alive: In this case we don’t activate this option. If you want to check if the device is still sending data, or, if the device has stopped, activate this option.
• Message format: How the incoming message will be parsed.
◦ Encoding: UFT8.
◦ Compression: None
◦ Serialization: JSON
◦ Script: <javascript>. is the format in which Ubidots receives data.
• Data parser:
◦ Type: Custom
• Parser options:
◦ Script: <javascript>. is the format in which Ubidots receives data.
To modify the default JavaScript code, click on the "</>" symbol and paste the following code:
$.logger.info("Topic is %s", $.topic);
$.logger.info("input is %j", $.input);
// Declare a variable to create the JS object wanted.
const response = [];
response.push({
tag: $.topic,
value: $.input.value,
quality: 192,
ts: $.input.timestamp
});
$.output = response;Note: Quality corresponds to a number, between 0 and 255. Where tag qualities between 0 and 63 are considered bad, 64 to 127 uncertain, and 192 to 255 good.
6. Configure the tags for the Subscriber
In the tag for the Subscriber, you can also use the default information with the following modifications:
• Client access: Read and Write (To receive and send data)
• Source:
◦ Enabled: Yes
◦ Module type: MqttClient
◦ Module name: MQTT
• Config:
◦ Subscriber: Selects the subscriber that will provide data to this tag. The format is: Connection/Subscriber.
◦Tag address: /v1.6/devices/vnode/pressure. Determines an alias for the tag so it can be referenced by it, instead of its full path. If provided, the tag can only be referenced using this alias.
7. Check if the module is working
Once you have saved all the configuration changes, we will check that the module is running. Follow these steps:
Go to "System" in the Navigation bar and click on “Diagnostics”.
Then click on “Modules” and check if MQTT is running.
After confirming that MQTT is running, proceed with the following steps:
Go to “Real time logs” in the Explorer bar.
Activate the checkbox of “Enabled”.
Select the DEBUG level and the MQTT module to check the communication with Ubidots. (Here you can see the information sent to Ubidots)
Now you can see the device that includes both variables of the subscriber and publisher in your Ubidots account, as the following image.
The variable that has been created on the device you selected in step 2 in your Ubidots account will be displayed as follows:
To check that the subscriber is working correctly, you will see a data like this in the real time logs, which shows the value that the subscriber receives from Ubidots:
To check that you can access and modify that value through the tag,
• Go to “Data” in the in the Navigation bar and click on “Real Time”
• Then click on “Subscriber tags”.
There, we will find the tag and the value. If we right click on the Tag and select “Write value” we would modify the current value of the variable and it will be shown in Ubidots.