MQTT Interface

MQTT is a lightweight publish/subscribe messaging protocol designed for M2M (machine to machine) telemetry and IoT applications in low bandwidth environments. The deviceWISE Cloud provides a rich MQTT interface to enable you to create applications that use the lightweight MQTT protocol to interact with any of the available services in the platform. MQTT is a binary based protocol were the control elements are binary bytes and not text strings. MQTT uses a command and command acknowledgment format.

Key facts about the MQTT interface

Protocol specification available from IBM: here
Available on port 1883 for MQTT, and 8883 for MQTT with TLS/SSL encryption.
Supports all TR50 commands.
Supports additional Server Topics for most common APIs.
Commands are sent on topic api, and replies are received on topic reply.
Do not use mqtt.receive event to listen to reserved topics api and apiz
When you connect, you are automatically subscribed to the following topics:
- reply/#
- replyz/#
- notify/#
QoS 0 and 1 are supported.
QoS levels refer to the connection between a broker and a client. The QoS1 level guarantees that the message will be delivered at least once. In QoS1, the initiator of the request is the one generating the messageId. For example, when a client publishes a message on a topic it should generate a msgid that gets acked by the broker.

MQTT Authentication

Authentication with MQTT uses the standard MQTT v3.1.1 authentication capabilities of the Client_ID, Username, and Password.

User Authentication
- Client_ID - Must be a unique string for different connections established by the same user.
- Username - The email address for the user account.
- Password - The password for the user account.
Application Authentication
- Client_ID - The application ID for the device that is connecting.
- Username - The thing key for the application connecting. Must be globally unique for the organization.
- Password - The application token for the device that is connecting.
JWT Authentication
- Client_ID - Must be a unique string for different connections established by the same token.
- Username - Must be specified as "jwt"
- Password - Token previously generated by the session.jwt.create API call.

While doing an MQTT connection, if it fails with error 4, then resend the request with username and the MFA token as the password, other errors are considered terminal.

TLS/SSL support

Secure MQTT connections support the following TLS/SSL versions:

SSL 3.0
TLS 1.0, 1.1 & 1.2

The TLS/SSL ciphers supported are:

TLS_RSA_WITH_RC4_128_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Disable support for a TLS version except 1.2 by specifying the property ssl.method=TLSv1_2_method in the properties file. For more information on updating the property file, see Properties file management.

TR50 Interface

Using MQTT as the transport for TR50 messages is easy. This interface gives you a reliable transport for asynchronously sending TR50 commands within a single TCP session enabling significantly faster performance than using the HTTP transport.

Basic use

the TR50 JSON does not require an "auth" section as the authentication is handled by the underlying MQTT connection.

Send commands on topic "api" in the following format:

Request

{
  "1" : {
    "command" : "<insert command here>",
    "params" : {
      <command specific parameters here>
    }
  },
  "2" : {
    "command" : "<insert command here>",
    "params" : {
      <command specific parameters here>
    }
  }
}

Receive replies on topic "reply" in the following format:

Reply

{
  "1" : {
    "success" : true
  },
  "2" : {
    "success" : false,
    "errorCodes" : [-22],
    "errorMessages" : ["Device not found"]
  }
}

Sending compressed JSON
- To reduce data usage, you can send commands on special topics that expect a compressed payload. Compression is performed using the standard zlib algorithm.
- Send commands on topic "apiz".
- Receive replies on topic "replyz".
Using topic correlation Ids
- Depending on your implementation, it may be easier to handle correlation Ids using the topic name for message routing rather than in the TR50 command. To enable this functionality, the API allows a correlation Id to be specified after the "api" or "apiz" topics, and the Id will be returned appended to the reply topic when the command completes.
- Send commands on a topic such as "api/123" and the reply will be returned on "reply/123".