Overview of MQTT Protocol

This topic outlines the MQTT protocol and its usage in Kii Cloud.

See MQ Telemetry Transport (MQTT) V3.1 Protocol Specification by IBM Corporation for the detailed specification of the protocol.

Structure

MQTT is designed as a lightweight protocol to provide publish-subscribe messaging.

The message subscriber subscribes to an MQTT topic provided by the message publisher. Then, if any change occurs in the MQTT topic, the subscriber receives a PUBLISH command to get informed of the change.

The broker relays requests to subscribe to MQTT topics and messages.

Kii Cloud provides features of the components in the yellow square in the figure. The client can establish an MQTT connection with the hostname and port number of the broker.

Commands

MQTT is a connection-oriented protocol. Once a connection is established between the server and the client, commands are bidirectionally sent over the connection.

The server and the client send the commands in the table below to achieve desired results. The usage and the direction of each command in the table are in line with the standard use case with Kii Cloud.

Command	Description	Usage in Kii Cloud	Direction
CONNECT	Client requests a connection to a server	Initiate connection
CONNACK	Acknowledge connection request	Initiate connection (response)
PUBLISH	Publish message	Request for API
		Respond to API request, push notification
PUBACK	Publish acknowledgment	Not used because the supported QoS level is 0	-
PUBREC	Assured publish received (part 1)	Not used because the supported QoS level is 0	-
PUBREL	Assured Publish Release (part 2)	Not used because the supported QoS level is 0	-
PUBCOMP	Assured publish complete (part 3)	Not used because the supported QoS level is 0	-
SUBSCRIBE	Subscribe to named topics	Initialize push notification
SUBACK	Subscription acknowledgement	Initialize push notification (response)
UNSUBSCRIBE	Unsubscribe from named topics	End push notification
UNSUBACK	Unsubscribe acknowledgment	End push notification (response)
PINGREQ	PING request	Request for PING
PINGRESP	PING response	Respond to PING request
DISCONNECT	Disconnect notification	Disconnect client

Note: Information in the Description column is quoted from MQ Telemetry Transport (MQTT) V3.1 Protocol Specification by IBM Corporation.

Note: The icons in the Direction column indicates the direction of communication. means that the command is sent to Kii Cloud and means that the command is sent to the MQTT client.

These commands are transferred over the connection according to the format defined by the MQTT protocol. Usually, the client such as web apps and things does not need to be aware of the communication format because it sends and receives commands via an MQTT library. The client mainly handles timing for sending and receiving commands, and information in the command payload.

See Using Push Notification via MQTT and Using API via MQTT to learn how to use these commands with Kii Cloud.

MQTT Topic

Messages are subscribed and published to MQTT topics in the MQTT protocol.

Multiple MQTT topics exist on the publisher and they are represented by topic names with hierarchy. The subscriber specifies MQTT topic names in order to subscribe and issues messages to those topics.

Kii Cloud uses MQTT topics for the following two purposes:

• Using Push Notification via MQTT

  For push notification, one MQTT connection uses one MQTT topic.

  Push notification is provided by subscribing to an MQTT topic with the SUBSCRIBE command. When an event occurs on the server side, the MQTT topic issues the PUBLISH command and the client receives a push message.

  You subscribe to an MQTT topic with the SUBSCRIBE command for push notification.

• Using API via MQTT

  For API call, multiple MQTT topics corresponding to URLs of APIs to call are used.

  Identify the API to call by using the hierarchy of MQTT topics. The PUBLISH command is sent to the MQTT topic, which provides desired functionality, and processed as a request to Kii Cloud. Its response is received as a PUBLISH command from the server side.

  You do not subscribe to a topic but send and receive commands with the PUBLISH command for API call

Quality of Service

The quality of service level of MQTT provided by Kii Cloud is 0. While the client receives a push notification at most once for one event, notification is not retried when the client does not receive any.

The MQTT client does not need to process PUBACK, PUBREC, PUBREL, and PUBCOMP commands which are necessary to provide service at QoS 1 or higher.

Keep alive timer

The MQTT protocol uses the keep alive timer to detect a disconnected network connection from the client. When the client does not send any message for a certain period of time, the server disconnects the connection as the server assumes the connection is lost.

The value for the keep alive timer is specified as a parameter of the CONNECT command when a connection is initiated. As seen in the below sequence, when the client does not send any message for a certain period of time, it sends the PINGREQ command so that the server does not disconnect the client.

The PINGREQ command is processed differently among various MQTT libraries. Some libraries automatically send the command while the other require the user program to call the command. See the specification of the MQTT library of your choice to understand if you need to call the command within the user program.

When you integrate an MQTT client into your web app or thing, Kii recommends you to verify that the connection is still retained after a certain period of time without the client's sending any commands. If the connection is disconnected, check the value for the keep alive timer.

MQTT Connection

A connection between the client and the server is necessary to communicate in the MQTT protocol. MQTT commands are transferred over the connection.

Select one of the four connection methods in the below table to connect to Kii Cloud.

Kii Cloud APIs for onboarding and push notification return these types of port numbers. Select one to use with the client app.

Basically, any connection should be available. However, the best method is different depending on the client type.

• Use MQTT over the TCP socket for things. This method is simple and works well with things.

• Use MQTT over WebSocket for web apps. This method works well with HTTP and some MQTT libraries do not support the connection over the TCP socket on web browsers.

Pay attention to these points about the MQTT connection:

• Neither of MQTT over the TCP socket nor MQTT over WebSocket uses port 80 or 443, which are the default port numbers for HTTP and HTTPS. Especially, be careful with network settings such as those for the firewall if the MQTT client is used in an enterprise environment. See Network Environment for the port numbers used by Kii Cloud.

• The client behavior after disconnection varies depending on the implemented library. If the specification of the client app expects continuous connection like FCM/APNs, you might need to implement a reconnection process explicitly.