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.
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.
AllThingsTalk allows clients to connect to the Broker and exchange information using MQTT and MQTTS endpoints:
MQTT (Non SSL connections)-h 'api.allthingstalk.io'
MQTTS (SSL connections)-h 'api.allthingstalk.io' -p 8883 --cert '<the_cert_file.pem>'
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.
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.
For example:
-u 'maker:4ExampleTokenqXpXzDng5Ivtx1'
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'
Message Broker understands these message formats:
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
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 IDasset/<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
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}'
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 Namedevice/<DEVICE_ID>/asset/<ASSET_NAME>/feed
To receive a feed of temperature
sensor states coming from device def456
:
mosquito_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}
Use Asset Commands topics to recieve actuation commands sent by the Broker.
Asset Command topic is suitable for clients that hold an Asset IDasset/<ASSET_ID>/command
Device Asset Command topic is suitable for clients that hold a Device ID and an Asset Namedevice/<DEVICE_ID>/asset/<ASSET_NAME>/command
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}
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'