Message Queuing Telemetry Transport (MQTT) APIs

Operations Hub MQTT Message Broker

Operations Hub includes an MQTT client. In the Operations Hub administrative console, the MQTT client can be pointed at any MQTT broker that is accessible from the network where the Operations Hub platform is installed. If there is no existing MQTT broker, a local broker can optionally be installed on the Operations Hub server during the Operations Hub installation. Refer to the Deployment section of the document.

Operations Hub MQTT implementation

Operations Hub receives status messages from devices and stores the information in the M2M_Data entity. Operations Hub defines a standard for the MQTT topic structure and how the payload is formatted in order to allow the server to identify the device source and correctly store the M2M data.

The messages contain the following information:
  • Cloud ID: When a Operations Hub tenant account is created, it is assigned a unique cloud ID on the server. The cloud ID allows Operations Hub to control how the data from the device is collected and stored.
  • Device ID: A device or asset could be a single machine with one or more sensors communicating directly with Operations Hub. Alternatively, a device could be a gateway device on a production line, acting like a router to forward data from multiple machines along the line to Operations Hub. All devices have unique IDs that often represent network card numbers, IMEI numbers, or MAC addresses. The device ID is the minimum requirement for Operations Hub to identify the data source.
  • Instance: If you have multiple assets connected to Operations Hub through a single gateway device, the instance name provides the ability to identify which asset from which the data has been sent. The instance name is usually a logical name uniquely identifying the asset or sensor.
  • Metric: The metric is a term used by Operations Hub to define the nature of the data send from a device (for example, temperature, speed, air pressure, fuel level). Metrics in the M2M_Data entity allow the application developer to define queries and events for retrieving data and triggering responses to specific conditions.

Operations Hub MQTT Topic Structure

When Operations Hub receives a message, it needs to identify the message source. The MQTT message format is defined as: <topic> <payload>

Operations Hub defines a standard topic format so that the server knows the source of the message.

The Operations Hub topic structure contains the following three components in the given order:
  • Cloud_ID: This value must be the cloud_id defined in the entity cloud_users.
  • Device_ID: This value can be anything. Normally, it identifies a specific device or gateway.
  • Instance_Name: This value can be anything. Normally, it identifies a specific asset. It is optional.

A topic with an instance name appears as follows: <Cloud_ID>/<Device_ID>/<Instance_Name>

A topic without an instance name appears as follows: <Cloud_ID>/<Device_ID>

Operations Hub MQTT Payload Structure

For each message, Operations Hub needs to identify the metric. (For example, identify whether 32 is the reading for temperature or light.)

Operations Hub supports the following basic formats for the payload:
  • Basic Payload format: The basic Operations Hub payload is usually used for simple sensors. The Operations Hub payload is formatted using keyname value pairs: keyname=<value>. The keyname value pairs are separated by a Tilde character (~). The basic Operations Hub Payload message uses two keyname value pairs to indicate the metric and the data. met=<value>~data=<value>

    Example: met=Temperature~data=32

  • Multi Sensor Device/Gateway Payload format: For devices or gateways with multi sensor capability the Operations Hub payload supports extra keyname value pairs to allow them to send extra data.
Supported keynames: The following table provides the keynames that are supported.
Keyname M2M_data Field Storage Format
Met metric String Developer-defined string
Data data String Developer-defined string
Lat latitude String WGS84-recommended for online map compatibility
Long longitude String WGS84-recommended for online map compatibility
Time timestamp DateTime ISO 8601 “YYYY-MM-DDThh:mm:ss.sss±TZ”
Alt altitude String Developer-defined value
Desc description String Developer-defined string
Type data_type String Data type of the data field String or Number
gen1 generic_1 String Developer-defined string or value
gen2 generic_2 String Developer-defined string or value
Note:
  • All Operations Hub payload messages must contain the metric and data keyname value pairs. All other fields are optional.
  • The order of the keyname value pairs in the payload is not compulsory.
  • If included, Timestamps must be formatted according to the ISO 8601 format specified above.
  • Data Type can be specified in cases where Operations Hub does not automatically identify the data type correctly. For example if you are sending a numeric ID, it should be treated as a String.
The keynames in the keyname value pairs define the field in the Operations Hub M2M_data entity where the value will be stored.
Note: The latitude and longitude values are also combined and added to the M2M_data LatLong field.

Payloads with location and timestamp information

Some devices also have a built-in GPS (for example, a car). These devices can also send GPS latitude and longitude co-ordinates indicating the location of the reading. Many modern devices can also include the timestamp for the date and time the data was recorded. In this case, the payload is formatted as a set of keyname value pairs such as met=Speed~data=120~ lat=35.678~long=135.678~time=2014-12-23T07:14:30.546+09:00

Payloads with multiple metrics

In order to reduce the number of calls required to send data from the device, a device that collects several metrics can send multiple metrics in a single payload. For example, a car device may send speed, odometer reading, and fuel level as one payload. This can be achieved by concatenating multiple metrics together in the payload using a semi-colon (;) as the delimiter.

A payload with three metrics appears as follows: met=Temperature~data=32;met=Pressure~data=12;met=Wind Speed~data=5.

A payload for two metrics with GPS co-ordinates appears as follows: met=Speed~data=120~lat=35.678~long=135.678;met=Fuel~data=12~ lat=35.678~long=135.678.

A payload including GPS and time details from a multi-sensor weather device appears as follows: 
met=Temperature~data=36~lat=35.388628~long=139.673573~time=2014-12-23T07:14:30.546+09:00;
                met=Humidity~data=70~lat=35.388628~long=139.673573~time=2014-12-23T07:14:30.546+09:00;
                met=Pressure~data=1.2~lat=35.388628~long=139.673573~time=2014-12-23T07:14:30.546+09:00