MqttUbidots | OmnIoT

------- OmnIoT SoftHub to/from Ubidots via MQTT -------

The OmnIoT SoftHub provides a great deal of functionality allowing you to easily build intelligence into your IoT edge infrastructure. But sometimes you simply need to have your data forwarded to your preferred cloud based solution provider. While the SoftHub Platform does include a fully SSL/TLS enabled Remote Packet Capture Service component, there is also built in support to publish data directly to any third party MQTT compliant solution.

In this brief tutorial we'll show you how easy it is to get your data into the Ubidots IoT ecosystem, and more specifically how to display your sensor data on a Ubidots dashboard and how to control your OmnIoT SoftHub remotely using Ubidots dashboard's control widgets. Note that in the interest of brevity, for this tutorial we're going to keep things as simple as possible. Both the OmnIoT SoftHub and the Ubidots Platforms provide far more functionality than we'll cover here, but this tutorial should give you a good starting point to begin building your own SoftHub/Ubidots IoT applications.

Before we begin, we assume the following:

You already have a Ubidots account and are familiar with Ubidots dashboards (see www.ubidots.com)
You are familiar with basic SoftHub principals and operation (see www.omniot.com)
You are familiar with general SoftHub MQTT objects/concepts (see the OmnIoT MQTT Intro videos)

------- EXAMPLE VIDEO -------

The video below illustrates a simple scenario where the SoftHub has been configured to do the following:

Connect to a Vernier Bluetooth GDX-TMP temperature probe sensor.

Connect to a Ubidots dashboard to display the real-time sensor temperature data.

Generate an alarm when the sensor transmits a temperature out of range. For our example we consider an "out of range" temperature as greater than 30C or less than 10C.

When an alarm state is detected, we'll (1) send a warning email directly from the SoftHub, (2) light an LED connected to one of the SoftHub device's output GPIOs, and (3) disable further alarms for a period or time to prevent a flood of redundant emails.

To acknowledge an alarm the user can either (1) press a button which is connected to an input GPIO on the SoftHub device, or (2) click a button remotely on the Ubidots dashboard that will send a notification to the SoftHub device to clear the alarm.

When the alarm is acknowledged by either method above, the LED connected to the SoftHub device is turned off.

------- CONFIGURATION FILES -------

All of the files used in the video can be downloaded in a zip file HERE. The zip file contains the following (1) The RuleEngine.xml configuration file used, (2) the VnrTmpToUbi.mcfg MQTT configuration file used, and (3) the VnrTmpToUbi01.jff packet format/filter file used. Below we'll go through each of the three files and identify the sections that are specific to communicating successfully with the Ubidots platform. Following that, we summarize all the additional changes you would likely need to make to get the example working on your own.

The RuleEngine.xml file:

The RuleEngine.xml file should only be modified using the SoftHub Configuration Utility included in the OmnIot SoftHub Platform download. To send the sensor data to your specific Ubidots dashboard you will need to update the "PublishData" Action object named "doPublishPacket" in the example rule file.

Changes you will need to make include the following:

The "Message Topic" in the form of "/v1.6/devices/??????", where the question marks are replaced by the "API Label" string for the device you are targeting in Ubidots account.
The "Device Control Topic" in the form of "/v1.6/devices/??????/??????", where the left most question marks are replaced by the "API Label" string for the device you are targeting in Ubidots account, and the right most question marks are replaced by the "API Label" string for the device variable you will use to send MQTT data back to your SoftHub device. Note that this field is only required if you plan to control your SoftHub device remotely from your Ubidots dashboard.
The "Server User Name" as the string from your Ubidots' account's API Credentials / Default Token.
The "Server Address" as the target Ubidots MQTT broker address. Here for simplicity we're using "tcp://industrial.api.ubidots.com:1883", which is the unsecure Ubidots MQTT broker address and port. Note that in any production environment you would almost always want to connect using the secure Ubidots broker and appropriate SSL/TLS parameters instead.
An "Extended Options File". This file is necessary, as you will see below, to enable us to specify some "on the fly" packet transformations to transform the default SoftHub JSON output packets to a format appropriate for the Ubidots MQTT broker. We used the name "VnrTmpToUbi" in our example but you may wish to rename this file to be more in line with your own environment.

The VnrTmpToUbi.mcfg file:

A template mcfg file ("template.mcfg") is shipped as part of the installation materials and during installation is copied into the default configuration directory ("/etc/omniotshd/" on Linux platforms). For our example, the template mcfg file needed to be modified and renamed as specified below.

In the General (first) section we'll need to enable flattening of JSON records. This allows the JSON Filter/Format code to parse the outgoing packets correctly for transformation. Uncomment and change the following -

>>> FlattenJson="1"

In the JSON Filter/Format section we'll disable the publishing of packets that are not successfully transformed. Additionally we'll specify a single JFF file, named "VnrTmpToUbi01.jff" which will specify a packet transformation we'll apply to change the outgoing standard JSON packet to conform to the Ubidots broker's required format. Uncomment and change the following -

>>> PublishUnformatted="0"
>>> JffFile01="VnrTmpToUbi01"

Lastly, we'll map incoming control packet strings to our user event name. By uncommenting and specifying the string below, any incoming packet containing the substring "AckRmtAlarm" will cause the SoftHub to queue the User Defined Event labeled "30-onRmtControlMsg" in the RuleEngine.xml file -

>>> InputToUEV01="*AckRmtAlarm*","30-onRmtControlMsg"

The VnrTmpToUbi01.jff file:

As specified above, we also created a JSON Filter/Format file to reformat our outgoing packets on the fly to conform to the Ubidots broker's required format. We copied the template.jff file to VnrTmpToUbi01.jff and made the following changes -

We identified two pieces of data we wanted to extract from the outgoing packets to be included in our transformed output packet. The first is the data label for the actual temperature data, and the second is the label for the temperature data read timestamp. Note also that we also specify a format transformation on the timestamp. See the jff file documentation for further information on timestamp transformations.

>>> FmtDataLabel01="OmnIotHubPacket.PacketContents.PacketDataField[0].FieldValue"
>>> FmtDataLabel02="OmnIotHubPacket.PacketGeneratedTimestamp,2"

Lastly, we specified the output format string for our outgoing packets. This format is per Ubidots documentation where "temp-probe" is the API label for the Ubidots device variable we want to map our data to on the Ubidots dashboard.

>>> OutputFormatStr="{"temp-probe": {"value": %s, "timestamp": %s}}"

------- OTHER MODIFICATIONS -------

The preceding sections detailed the configuration file changes you would need to make that are specific to sending your data to a Ubidots dashboard. In this section we cover the additional changes you would need to make to ensure your emails can be successfully sent from your SoftHub device. To send emails from your SoftHub device there are two sections in the RuleEngine.xml file that would need to be modified.

Under the System Options / Email node you will need to change the following -

SMTP Server ID: This should be replaced with the address of the SMTP server you wish to use to send your emails.
SMTP Login ID: This is the SMTP server Login ID you wish to send the email from.
SMTP Login Password: This is the password for the SMTP server Login ID you wish to send the email from.

Under the Rule Engine / Actions / doSendAlarmEmail you will need to change the following -

To Field: This is the email ID(s) of the designated alarm email recipient(s).
From Field: This is the "from email" address to use. This is typically the same as the SMTP Login ID specified in the email options above.

You will also likely want change the disable alarm timer value to a more reasonable time. It is currently set for 30 seconds.

Under the Rule Engine / Actions / doStartAlarmTimer node you will need to change the following -

Timer Duration: Set this value to a number of milliseconds for the timer to be disabled.

------- SUMMARY -------

Again, this tutorial is only meant to outline the changes you would need to make to run the example from the example video on your own SoftHub device. We assume you are familiar with both the function of the OmnIoT SoftHub and the Ubidots platforms. Installing the OmnIoT SoftHub and using the example configuration files should enable you replicate the example scenario from the video fairly quickly. If you have any questions or comments please follow up with us via our Contact Page.