Establishing MQTT Connection

You need to establish an MQTT connection in order to communicate with the server over the MQTT protocol. See the sequence diagram in Communication Overview for the process of establishing a connection.

To establish a connection, you need to connect to the default MQTT broker to get connection information and then connect to another MQTT broker using the obtained connection information. You cannot call the API through the default broker but the second broker. You can implement this process with an external library.

Take these steps in order to establish a connection.

• Connect to the default MQTT broker
• Send the PUBLISH command
• Receive the PUBLISH command
• Connect to the MQTT broker

Connecting to the Default MQTT Broker

First, connect to the default MQTT broker. Connect to the MQTT broker.

• Hostname: mqtt-jp.kii.com
• Port number: 1883 for TCP, 8883 for TCP with SSL/TLS, 12470 for WebSocket, 12473 for WebSocket with SSL/TLS

Usually, things connect to port 8883 with SSL/TLS. Web apps connect with WebSocket.

Connect to the default MQTT broker with the following parameters.

Numerous MQTT libraries automatically send the CONNECT command and receive the CONNACK command on initiating a connection.

Sending the PUBLISH Command

Once you are connected to the default MQTT broker, send a PUBLISH command to the broker to onboard the thing. A PUBLISH command with these parameters below onboards a thing to Thing Interaction Framework.

• MQTT Topic Name

  p/anonymous/thing-if/apps/{APP_ID}/onboardings

• Payload

  Specify text data as below in the payload. Replace {VENDOR_THING_ID} and {THING_PASSWORD} with the vendorThingID and password of the thing to onboard.

  POST
  Content-type: application/vnd.kii.OnboardingWithVendorThingIDByThing+json
  
  {
    "vendorThingID" : "{VENDOR_THING_ID}",
    "thingPassword" : "{THING_PASSWORD}"
  }
  

  This format is specific to Kii Cloud and designed to map data in the MQTT protocol to that in the HTTPS protocol. See Calling API for more information about the format.

Receiving the PUBLISH Command

The onboarding result is received as a PUBLISH command from the server side.

The MQTT topic name in the received PUBLISH command is the one you specified in the PUBLISH command sent to the server.

Ensure to check the MQTT topic name on receiving the PUBLISH command from the server because the PUBLISH command is used for various purposes. Also, ignore PUBLISH commands with unknown MQTT topic names for future enhancement.

• MQTT Topic Name

  p/anonymous/thing-if/apps/{APP_ID}/onboardings

• Payload

  You can obtain text data like this from the payload, which contains the onboarding result and information to connect to the MQTT broker which can accept API call.

  200
  Accept-Ranges:bytes
  Age:0
  Cache-Control:max-age=0, no-cache, no-store
  Content-Type:application/json
  Date:Fri, 27 May 2016 05:44:17 GMT
  Connection:keep-alive
  
  {
    "accessToken" : "{ACCESS_TOKEN}",
    "thingID" : "{THING_ID}",
    "mqttEndpoint" : {
      "installationID" : "{INSTALLATION_ID}",
      "username" : "{USERNAME}",
      "password" : "{PASSWORD}",
      "mqttTopic" : "{MQTT_TOPIC}",
      "host" : "{BROKER_HOST}",
      "portTCP" : {PORT_TCP},
      "portSSL" : {PORT_SSL},
      "portWS" : {PORT_WS},
      "portWSS" : {PORT_WSS},
      "ttl" : {MQTT_TTL}
    }
  }
  

Once you receive this information, you can disconnect from the default MQTT broker.

The default MQTT broker only accepts onboarding requests.

Connecting to the MQTT Broker

Next, connect to the broker which accepts requests for API call. Establish a new MQTT connection to the MQTT broker using the connection information obtained in onboarding.

Connect to the MQTT broker with the following parameters.

Usually, you also subscribe to the MQTT topic returned as "mqttTopic" in the onboarding response with the SUBSCRIBE command. This MQTT topic is used for push notification with which you can receive PUBLISH commands that contain commands from the mobile app. See Receiving Command to learn how to process the PUBLISH command which contains push notification.

Keep alive timer

MQTT defines an alive monitoring process with the keep alive timer to verify the connection is active.

The connection will be disconnected if the client does not send any message for the duration of 1.5 * the value of the keep alive timer set on the CONNECT command. If the client is not going to send any message within this duration, it needs to send the PINGREQ command. Please refer to the documentation of the MQTT library you are using for more specific information.

When you implement an MQTT client, 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, the PINGREQ command might not have been sent.