MQTT Messaging API

The Broker

AllThingsTalk Message Broker enables sending and receiving of messages to and from AllThingsTalk Cloud. When communicating with the Cloud, a client sends a message addressed to a topic like /asset/temperature/state.
The Broker, in turn, publishes the message to all clients that have subscribed to receive messages for that topic.

This article explains how to use Messaging API based on MQTT protocol.

Get started

MQTT is a publish/subscribe based messaging protocol for use on top of the TCP/IP protocol. It is designed for connections with remote locations where a small code footprint is required or network bandwidth is limited.

To quickly get started with MQTT, we recommend that you use the Mosquitto command-line tools. Make sure to pick a suitable Binary installation.

Host

AllThingsTalk allows clients to connect to the Broker and exchange information using MQTT and MQTTS endpoints:

• MQTT (Non SSL connections)
  -h '<instance>.allthingstalk.io'

• MQTTS (SSL connections)
  -h '<instance>.allthingstalk.io' -p 8883 --cafile '<the_cert_file.pem>'

For ease of use, we’ll use api.allthingstalk.io in the following examples of this article.

If you want to use MQTTS secure endpoint, you might - depending on your client - need to provide the public SSL certificate. Download it here and include it in your call.

Authentication

The Broker requires that every client provides valid authentication credentials, either when publishing or subscribing for a message.

To authenticate your Device application with the Broker, you will need a Device token. ]
Similarly, for a Ground level application we suggest to use Ground token.

More about Tokens and Authentication →

Use Device token as username

For example:

-u 'maker:4ExampleTokenqXpXzDng5Ivtx1'

Use a random string as password

Although the Broker doesn’t check the password that clients send, some MQTT clients won’t send message if password is empty. To stay on the safe side, please provide any string

-P 'bfnbayv9'

Other MQTT connection configuration

We support MQTT 3.11 version.
When connecting to a broker, we recommend you use the following parameters:

• Keep Alive Interval = 15 seconds
• Clean session = True

You can use Clean session = False if you want to have a permanent connection. In this case, the broker will store all the undelivered messages in case of a broken connection, and will deliver those messages upon successful reconnection.

When subscribing and publishing to a topic, you can choose between QoS0 and QoS1, depending on your application and business rules.

Message formats

Message Broker understands these message formats:

• JSON
• CSV (values separated with “|”)
• CBOR
• Custom binary

More about Data formats →

Topics

When communicating with the Broker, your client needs to address the message to a certain topic.

Read more about MQTT Topics here: http://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices

Asset States

Use Asset States topics to hit the Broker with sensory data. There are two kinds:

• Asset State topic is suitable for clients that hold an Asset ID
  asset/<ASSET_ID>/state

• Device Asset State topic is suitable for clients that hold a Device ID and an Asset Name.
  device/<DEVICE_ID>/asset/<ASSET_NAME>/state

Examples

To publish to an asset abc123 a state of 20.1 (e. g. celsius degrees):

mosquitto_pub -h 'api.allthingstalk.io' -t 'asset/abc123/state' \
  -u 'maker:40lqFaaHjc8kWeqXpXzDng5Ivtx1' -P 'bfnbayv9' \
  -m '{"value": 20.1}'

You can also publish data to the same asset by identifing device and asset name, e. g. a temperature:

mosquitto_pub -h 'api.allthingstalk.io' -t 'device/def456/asset/temperature/state' \
  -u 'maker:40lqFaaHjc8kWeqXpXzDng5Ivtx1' -P 'bfnbayv9' \
  -m '{"value": 20.1}'

Asset Feeds

Use Asset Feeds topics to receive asset state changes in real time.

• Asset Feed topic is suitable for clients that hold an Asset ID.
  asset/<ASSET_ID/feed

• Device Asset Feed topic is suitable for clients that hold a Device ID and an Asset Name
  device/<DEVICE_ID>/asset/<ASSET_NAME>/feed

Examples

To receive a feed of temperature sensor states coming from device def456:

mosquitto_sub -h 'api.allthingstalk.io' -t 'device/def456/asset/temperature/feed' \
  -u 'maker:4ExampleTokenqXpXzDng5Ivtx1' -P 'bfnbayv9'

Messages (feeds) will arrive in JSON format:

{"at":"2017-06-01T15:43:00Z","value":20.1}
{"at":"2017-06-01T15:43:16Z","value":20.2}
{"at":"2017-06-01T15:43:42Z","value":21.4}

Asset Commands

Use Asset Commands topics to recieve actuation commands sent by the Broker.

• Asset Command topic is suitable for clients that hold an Asset ID
  asset/<ASSET_ID>/command

• Device Asset Command topic is suitable for clients that hold a Device ID and an Asset Name
  device/<DEVICE_ID>/asset/<ASSET_NAME>/command

Examples

Listening for a boolean command to control an actuator abc123.

mosquitto_sub -h 'api.allthingstalk.io' -t 'asset/abc123/command' \
  -u 'maker:4ExampleTokenqXpXzDng5Ivtx1' -P 'bfnbayv9'

Messages (commands) will arrive in JSON format:

{"at":"2017-06-01T17:31:51Z","value":true,"meta":null}

Use + wildcard in a topic to receive a command for any asset within a given device:

mosquitto_sub -h 'api.allthingstalk.io' -t 'device/def456/asset/+/command' \
  -u 'maker:4ExampleTokenqXpXzDng5Ivtx1' -P 'bfnbayv9'