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.

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.

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".

While it is possible to leverage the full capability of the platform via the TR50 interface, the vast majority of APIs can be executed in an easier way using the Server Topics. The Server Topics enable you to develop applications that use MQTT's pub/sub interface to send and receive data regarding properties, alarms, and attributes on things.
- In any topic that specifies a <thingKey>, "self" can be used to indicate to the server to use the thingKey that is associated with your MQTT session.
- Wildcards + and # are supported.
- Example: Subscribe to: "thing/+/property/temp" to receive notifications when property "temp" on any thing in the organization changes.
- See: Server Topic API Documentation for more information