MQTT::Abstract JSON

The “MQTT :: Abstract JSON” device adapter allows data to be submitted by any MQTT enabled device or platform. The values supplied by the device are sent using standard MQTT publish requests using JSON data encoding.

MQTT Topic and Sub-Topics

The MQTT topic and sub-topic namespace is used to uniquely identify each device’s set of messages from another device’s set of messages. It is strongly recommended to use a unique identifier for your MQTT topic name so that messages for any other MQTT data source will not intermix with your device’s MQTT messages.

The MQTT Abstract JSON device adapter will subscribe to receive values supplied as the device’s “Device Code” value. The JSON message’s “code” field value is used to identify a specific message definition within the device profile that is associated with a specific “Device” instance in the application. This allows the “code” value to act like a sub-topic since it uniquely identifies the message type.

The “Device Code” value is the value used by the device adapter to subscribe to messages for this device. When you create your application “Device” instance for the actual device, please define a value that is appropriate as a MQTT topic value (i.e. “topic/subtopic1/subtopic2” – without the double quotes).

You should use a value that is globally unique to each device that will publish data via MQTT and use that as the main topic value or in combination with a string value that might identify the project. Values such as the Ethernet MAC address or Bluetooth MAC address can be used for this purpose since these values are globally unique values.

Messages published by the device can provide a “target” field value, but it is an optional field in a MQTT device message. The MQTT topic is the primary identifier used by the device adapter and it will subscribe to receive messages using the “Device Code” value from the device record. The MQTT device adapter will use the “topic” value as the default message “target” field value, so the “target” field does not need to be supplied in the JSON message. You may supply the “target” field value in the JSON message and it will use that value instead of the “topic” value. Supplying the “target” field value for each message can be helpful in situations where the device that is sending the JSON message publishes the JSON data on a topic known to the application, but the JSON message is actually from another device.

Directive Requests

This device adapter does support sending outbound JSON messages to a device. It will publish an outbound (Directive) message using the same base “topic” value but it will append the sub-topic of “/directive”.

A “Device Code” value of /topic/subtopic/UID998783 will have any directive messages published on topic /topic/subtopic/UID998783/directive

Directive JSON Data

target

• Status:
  • Always provided.
• Definition:
  • Unique ID value for this device (e.g., router serial number value).
• Example:
  • /topic/subtopic/UID998783

code

• Status:
  • Always provided.
• Definition:
  • Unique message ‘code’ value that is used by device to identify the correct directive message definition to be used to process this message
• Example:
  • dm10 This value will be defined when you create a “Device Profile” directive (outbound) message in your application. The dm10 is only an example of what it could be. This not the device profile’s code value, but the directive (outbound) message within the device profile.

time

• Status:
  • Always provided.
• Definition:
  • Time the directive message was generated on the server (always a UTC value).
• Time Zone:
  • GMT (UTC)
• Format:
  • XML 8601 format
  • YYYY-MM-DDThh:mm:ss.sTZD
  • http://www.w3.org/TR/NOTE-datetime
• Example:
  • 2014-07-24T19:20:37Z

location

• Status:
  • Optional-if defined in directive message contents.
• Definition:
  • The “latitude” and “longitude” contained in the directive message
• Fields within this block:
  • latitude
  • longitude
• Example:
  • {"latitude":37.795227, "longitude":-122.398828} Note: This field can only be set if the device profile directive (outbound) message has a Location type field with a field code of “location_” (trailing underscore character). This is how this device adapter looks at a “Location” value when processing the message field values. Any other Location field in the directive message is provided within the “values” object (defined later in this section).

values

• Status:
  • Always provided.
• Definition:
  • Block that contains field values supplied by the directive message
• Examples:
  • Sending a temperature and humidity value: "values": {"temp": 98.6, "humidity": 68.2}
  • Sending text values: "values": {"tank_level": "low", "pump_psi": 42.53}

Example Directive JSON Data

Here is an example directive (outbound) message definition. The “Location” field has a code value “location_” to have the geo location value provided via the top level “location” field.

Here’s an example of this directive (outbound) JSON message contents:

{
"time":"2015-12-11T22:36:38Z",
"target":"ABC123",
"code":"cmd1",
"location":{"latitude":37.399489,"longitude":-122.055252},
"count":1,
"success":true,
"values":{
"date_1":"2015-12-11T22:36:10Z",
"number_1":2.34,
"text_1":"Test 1",
"integer_1":1,
"boolean_1":true}
}

MQTT Server

The MQTT server used for demo / trial applications is:

Hostname: mqtt2.fusionconnect.io

Port: 1883

Please check with your application support representative for any application specific connectivity info for your application.

JSON Encoded Data

See JSON Encoded Data for information on JSON encoding and field name requirements.