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.

Telit deviceWISE Cloud was updated to require a minimum version of TLS/DTLS v1.2. Additionally, access via CoAP (coap://api.devicewise.com), HTTP (http://api.devicewise.com/api), and MQTT (mqtt://api.devicewise.com:1883) has been deprecated.

Key facts about the MQTT interface

Protocol specification available from IBM: here
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.
The mqtt.receive event event cannot be used to listen to reserved topics api and apiz, and if the topic starts with 'thing', it will only listen to topics that have "custom" as the third element.
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 support

Secure MQTT connections support the following TLS versions:

Minimum of TLS 1.2

The TLS ciphers supported are:

tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

Disable support for a TLS version except 1.2 by specifying the property ssl.method=TLSv1_2_method in the properties file. This configuration is related to the deviceWISE Edge Gateway ability to disable support for TLS versions below 1.2. 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".