Filter results by

MQTT

MQTT is a lightweight messaging protocol. It is suitable for IoT, since it is bandwidth-efficient and uses little battery power. ARTIK Cloud devices can communicate to ARTIK Cloud via MQTT.

In an MQTT session, ARTIK Cloud acts as the MQTT broker and ARTIK Cloud devices act as MQTT clients. An ARTIK Cloud device can publish a data-only message to ARTIK Cloud or subscribe to receive Actions from ARTIK Cloud.

A device ID and device token are used to connect to ARTIK Cloud via MQTT. A device ID is also used in the publish and subscription paths.

ARTIK Cloud MQTT endpoint:

1
mqtts://api.artik.cloud

Key concepts

MQTT Components Required Value Notes
Security SSL ARTIK Cloud device must be SSL-capable so that it can validate server certificate.
Broker URL api.artik.cloud Needed for opening the connection to the broker.
Broker port 8883 Needed for opening the connection to the broker.
username Device ID A valid ARTIK Cloud device ID used to login to establish a session.
password Device token A valid ARTIK Cloud device token used to login to establish a session.
Publish Path (MQTT topic) /v1.1/messages/<deviceID> Publish "data" to ARTIK Cloud for the specified device.
Subscription Path (MQTT topic) /v1.1/actions/<deviceID> Subscribe to receive "action" sent to the specified device.
Error Path /v1.1/errors/<deviceID> Subscribe to receive errors for messages published by the specified device.

To establish an MQTT session, an ARTIK Cloud device must use a device token (one of the three token types normally used to transfer messages via REST or WebSockets).

A device can only maintain at most one persistent connection with ARTIK Cloud with its device token.

Specifically, the restriction is reinforced for the connection using one of the following endpoints:

WebSocket: /websocket
MQTT: /v1.1/messages/ and /v1.1/actions/
CoAP: /v1.1/actions/

Similar to the ARTIK Cloud REST/WebSocket API connection, the ARTIK Cloud MQTT connection requires an encrypted communication channel. An ARTIK Cloud device must be SSL-capable in order to connect to the ARTIK Cloud MQTT endpoints.

Establish an MQTT session

An ARTIK Cloud device connects to ARTIK Cloud using the broker URL and port specified in the above table, with ARTIK Cloud acting as the MQTT broker. The device then logs in with its username (device ID) and password (device token).

An MQTT session is now established between this device and ARTIK Cloud. The device can publish data-only messages and/or subscribe to receive Actions targeted to it within this session.

Publish data-only messages

Data-only messages have type "message". An ARTIK Cloud device uses the following publish path:

1
/v1.1/messages/<deviceID>

The content of an MQTT message differs from that of a message sent to ARTIK Cloud via REST or WebSockets. Normally an ARTIK Cloud message is a JSON object with multiple fields indicating values such as source device ID, message type, and timestamp:

1
2
3
4
5
6
{
  "sdid": "cff2127dc",
  "ts": 1388179812427,
  "type": "message",
  "data": {"onFire":false,"temperature":50}
}           

An MQTT message contains only the value of the data field. The above message's corresponding MQTT message would be:

1
{"onFire":false,"temperature":50}

Once an MQTT message is successfully published to ARTIK Cloud, it will be stored as a normal ARTIK Cloud message with fields such as sdid (source device ID), type (message type), and ts (timestamp). You can view this message using the Data Logs or Charts features of My ARTIK Cloud.

Should the publish run into any error, the developer of the corresponding device can see the error in the Developer Dashboard. Publishing errors can also be seen by subscribing to this path.

MQTT errors are described in the API specification.

For publishing messages, the ARTIK Cloud MQTT broker supports Qualities of Service 0, 1, or 2 specified by a client.

Only messages with type message can be published via MQTT.

Any message sent to ARTIK Cloud may not be bigger than 1 KB.

Subscribe to receive actions

An ARTIK Cloud device can subscribe to the ARTIK Cloud MQTT broker to receive Actions targeted to it using the following subscription path:

1
/v1.1/actions/<deviceID>

When another device or an application sends an Action to the subscribed device via REST or WebSocket, this device receives the Action as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[
  {
     "name": "setOn",
     "parameters": {}
  },
  {
     "name": "setColorRGB",
     "parameters": {
        "colorRGB": {
          "r": 192,
          "g": 180,
           "b": 45
         },
         "intensity": 55
    }
  }
]

This received MQTT message contains two Actions: setOn and setColorRGB. As you can see, the received message only contains the value of the actions field in the data JSON object of a typical ARTIK Cloud message.

When sending Actions back to the client, ARTIK Cloud uses QoS 0, which is also called "fire and forget". The Actions are sent once, regardless of whether or not the client receives them.

A device should send its latest state to ARTIK Cloud after acting on an Action. The device can achieve this by publishing its state in the same MQTT session it uses to subscribe and receive Actions.

Example

The section describes how to publish and subscribe to the ARTIK Cloud MQTT broker using MQTT.fx, one of the many open source MQTT clients. The goal is to show you how to interact with the ARTIK Cloud MQTT broker using the above concepts.

After understanding the basics, you will need to develop your own MQTT client for your devices. There are open source MQTT client libraries available for different platforms/languages. You may find these handy when developing MQTT functionality for your devices. The following examples may also be of help:

Beyond MQTT.fx, you will also use the Device Simulator to send Actions to the MQTT client and monitor the state change after the client publishes its new state.

For this example, MQTT.fx publishes and subscribes on behalf of a "Example Simple Smart Light" device. The device type has simple fields and Actions, as seen below:

Simple Smart Light Manifest

Before establishing the MQTT session, first connect the device to your ARTIK Cloud account in My ARTIK Cloud, and then obtain the device ID and token to use later.

Establish a session

Start MQTT.fx and create a new connection profile. Fill in the ARTIK Cloud MQTT broker address and port and user credentials as follows: MQTT fx connection profile

Remember that the username and password are the device ID and device token you obtained from My ARTIK Cloud.

Click the "SSL/TLS" tab to enable SSL. The ARTIK Cloud MQTT broker uses a CA signed certificate. Select “Enable SSL/TLS” and choose "CA signed server certifcate", as below: MQTT fx SSL

Save this profile and click the "Connect" button: MQTT fx connect

Now MQTT.fx connects to the ARTIK Cloud MQTT broker and establishes a session.

Publish state of the smart light

Before publishing a message, start the Device Simulator and then run the ll command in the simulator to listen to messages sent by the smart light. ARTIK Cloud will notify the simulator of all messages sent by the light. Below is the corresponding display in the Simulator:

1
2
3
4
$ ll 0f8b45555555555555555
Using this token to connect: 3118b86da4c343b28da89a1c56f18c18
Opening live websocket on behalf of device 6a5bb957531f4704a5e3509a727573a5
WS -> Connected to wss://api.artik.cloud/v1.1/live?Authorization=bearer+3118b86da4c343b28da89a1c56f18c18&?sdid=0f8b45555555555555555

Fill in the publish path and MQTT message payload according as described above. Recall that you should use the device ID in the publish path. Your "Publish" tab should look like this: MQTT fx publish

Click the "Publish" button. The message should be sent to ARTIK Cloud. ARTIK Cloud will notify the Device Simulator, which displays the message as follows:

1
WS -> {"mid":"d5a23adbd36d4484af1a34d7ea568398","data":{"state":false},"ts":1432844166847,"sdtid":"xxx","cts":1432844166846,"uid":"someuidxxx","mv":1,"sdid":"0f8b45555555555555555"}

Enter sll in the Device Simulator to stop listening.

Subscribe to receive on/off actions

In MQTT.fx, fill in the subscription path to start receiving Actions targeted to this smart light. Recall that you need to use the device ID of the light in the subscription path. MQTT fx subscribe

In the Device Simulator, type the command tell <deviceID> (the device ID is the ID of the light) to send an Action to the smart light as follows:

1
2
3
$ tell 0f8b45555555555555555 setOn
$ Sending : {"actions":[{"name":"setOn","parameters":{}}]}
Got MID: 2713b144323c48ee8f7dd95044f31699

Then you should see the corresponding MQTT message received by MQTT.fx as follows: MQTT fx receive action

Best practices

A MQTT client cannot send Actions to ARTIK Cloud. To support a use case where an MQTT client triggers Actions on another MQTT client, we suggest that you set up ARTIK Cloud Rules using the Rules UI in My ARTIK Cloud or by programmatically calling Rules APIs.

Let's illustrate the point with example MQTT source and destination clients. The source MQTT client is a fire detector. It sends Boolean data "onFire" to ARTIK Cloud. The destination MQTT client is a smart light that can receive on/off actions.

To send Actions from the fire detector to the light, you would create a pair of Rules in ARTIK Cloud. The "TURN ON" Rule turns on the smart light if the fire detector detects the flame (i.e., "onFire" is true). The "TURN OFF" rule does the opposite. Then the MQTT fire detector can trigger Actions on the MQTT light when sending a new piece of data.

If the source device is not limited to MQTT, you have more options. For example, the source device can send Actions directly to the destination MQTT client using REST or WebSockets.

Limitations

At this point, the ARTIK Cloud MQTT broker has the following limitations:

  1. Only supports clean sessions. This means that ARTIK Cloud does not maintain MQTT state information between sessions. Therefore, a client that intends to receive Actions needs to resubscribe after establishing a new session.
  2. Does not retain Actions sent to a device when the device is disconnected. This means that ARTIK Cloud does not send the undelivered Actions to the device even after the device resumes the MQTT connection. As a workaround, the reconnected device can make a REST API call to get Actions from ARTIK Cloud.

ARTIK Cloud's MQTT functionality is continuously being developed and refined. Please check back to see when the above limitations have been removed.