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.

Connecting to the Default MQTT Broker

First, connect to the default MQTT broker. Connect to one of the MQTT brokers below depending on the server location where you created your application.

  • Hostname: mqtt-us.kii.com, mqtt-jp.kii.com, mqtt-cn3.kii.com, or mqtt-sg.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.

Connection Parameter Value
Username type=oauth2&client_id={APP_ID}
Password client_secret={APP_KEY}
Client ID anonymous

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.

Connection Parameter Value
Hostname "host" included in the onboarding response
Port number "portTCP" (for TCP) or "portSSL" (for SSL/TLS) included in the onboarding response
Port number for WebSocket "portWS" (for TCP) or "portWSS" (for SSL/TLS) included in the onboarding response
Keep alive timer for the CONNECT command Specify this according to your app implementation (See Keep alive timer)
Client identifier for the CONNECT command "mqttTopic" included in the onboarding response
Username for the CONNECT command "username" included in the onboarding response
Password for the CONNECT command "password" included in the onboarding response

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.