1. Overview
2. Broker
3. Devices
4. Configuring device properties
5. Sending telemetry
   1. Example
6. Receiving data

Overview

This document will describe how to configure and setup a successful integration to the V-Raptor™ MQTT driver. We will explain how to set up the Broker, Devices, and Device Properties.

All settings for the these items need to be configured as part of the DevicesOptions.json file which is loaded into the MQTT driver service.

Broker

The MQTT driver relies on the presence of an MQTT broker. This broker needs to be deployed separately to the V-Raptor, but in the case of IoT.nxt^® cloud deployments we will deploy a broker to each V-Raptor. Brokers are typically configured to accept connections on the secure MQTT port 8883 and are hosted on the same domain as the V-Raptor. A typical broker address will therefore be

mqtt://<vraptor-url>:8443

A valid username and password is also required to access the MQTT broker. IoT.nxt support will need to be contacted to configure this on request.

While IoT.nxt provides a broker, integrators are also free to use their own broker. The configuration process will remain the same.

The broker is set up in DevicesOptions.json in the following format:

{
    "Devices": {
        "Broker": {
            "Debug": true,
            "DeviceType": "TcpBroker",
            "Host": "eclipse-mosquitto",
            "Password": "<password>",
            "Port": 8883,
            "UserName": "<username>",
            "UseTls": true,
            "ValidateCertificate": false
        }
    }
}

Devices

Devices are configured into groupings through to the IoT.nxt platform. The device configuration structure looks like the following:

{
    "Devices": {
        "Device1": {
            "Enabled": true,
            "GroupName": "Mqtt",
            "DeviceType": "MqttTcp",
            "Debug": true,
            "BrokerDeviceName": "Broker",
            "PropertiesDeviceName": "DefaultProperties",
            "SubscribeId": "Device1Sub",
            "PublishId": "Device1Pub"
        }
    }
}

The following table describes the role of each of these fields:

Configuring device properties

The device properties are used to setup the properties that belong to a device, these properties configure how the endpoint is treated and informs the driver of the topics listed based on the telemetry from the MQTT clients. They can be grouped together as endpoints to a single property or set up separately as singular values for each property. Below is an example of how to set up the device properties and an explanation of some of the fields.

{
    "Devices": {
        "DefaultProperties": {
            "DeviceType": "DefaultProperties",
            "PropertyMaps": {
                "Temperature": {
                    "SubscribeTopic": "test/{id}/environment",
                    "SubscribeFormat": "Json",
                    "SubscribePath": "temperature",
                    "PublishTopic": "test/{id}/setenvironment",
                    "PublishFormat": "Json",
                    "PublishPath": "temperature",
                    "DataType": "double"
                },
                "Heater": {
                    "SubscribeTopic": "test/{id}/environment",
                    "PublishTopic": "test/{id}/setenvironment",
                    "DataType": "bool"
                },
                "Light": {
                    "SubscribeTopic": "test/{id}/light",
                    "SubscribeFormat": "Xml",
                    "SubscribePath": "Light/State",
                    "PublishTopic": "test/{id}/light",
                    "PublishFormat": "Xml",
                    "PublishPath": "Light/Command",
                    "DataType": "bool"
                }
            }
        }
    }
}

Device properties can be setup from Raw, Json or Xml. With Raw properties, the incoming value is treated as a single value. Json and Xml require that the SubscribePath be specified. This will either be the Json path or xpath that points to the property’s value.

The following table describes the role of each field:

Sending telemetry

Now that we have have correctly configured the devices according to the the MQTT driver, we can test that they are working.

Once you have connected your device to the MQTT broker, try posting a value to the required topic that you have just configured.

Example

Post a temperature value to the temperature property using the SubscribeTopic path in the Temperature property:

test/{id}/environment

Where {id} is the SubscribeId value from the Device1 object set up in the Devices section. The topic will look like this:

test/Device1Sub/environment

The device property is set up with a json data type, so if we post the following packet to our example topic:

{
  "temperature": 34.6
}

We should see a value arrive in portal

Figure 1 - Live telemetry value

Receiving data

The V-Raptor MQTT driver can also allow values that are set in the Commander dashboards to be transmitted to the connected clients. This is done by publishing to agreed upon topics. For example, in the property configuration section above we had the following:

    "Heater": {
          "SubscribeTopic": "test/{id}/environment",
          "PublishTopic": "test/{id}/setenvironment",
          "DataType": "bool"
        },

In this case, a publish topic called setenvironment will be used by the V-Raptor to communicate any changes in values for the environment property. The MQTT client can then subscribe on /test{id}/setenvironment topic to receive changes to environment values. Changes can be sent using the Gateway Communication widget in the Commander or triggers that set the endpoint under a specific condition.