MQTT Adapter

The Ably MQTT protocol adapter is able to translate back and forth between MQTT and Ably’s own protocol, allowing for seamless integration of any systems you may have. MQTT (MQ Telemetry Transport) is a publish/subscribe, lightweight messaging protocol designed for constrained devices and low-bandwidth networks. One of the major uses of MQTT is with IoT (Internet of Things), where these principles are key to having effective communication between various devices.

How to use MQTT with our adapter

To use the Ably MQTT protocol adapter, you’ll need to ensure you correctly configure your MQTT client as follows:

  • Set the host to “mqtt.ably.io”
  • Set SSL / TLS to true and the port to 8883. (If your MQTT client does not support SSL, you should instead use port 1883, but in this case we disallow api-key auth—see SSL usage note below)
  • Set the keep alive time to somewhere between 15 and 60 seconds. (60s will maximise battery life, 15s will maximise responsiveness to network issues. It must not be any higher than 60s to avoid our load balancer terminating the TCP socket for inactivity)
  • If using an API key, set the username to the part of the API key before the colon, and the password to the part after the colon
  • If using a token, set the username to the token, and leave the password blank

For example, in the NodeJS mqtt package, you’d need to specify the following:

{
  var options = {
    keepalive: 30,
    username: 'FIRST_HALF_OF_API_KEY',
    password: 'SECOND_HALF_OF_API_KEY',
    port: 8883
  };
  var client = mqtt.connect('mqtts:mqtt.ably.io', options);
}

This will connect using TLS through MQTT to Ably.

Decoding MQTT communication

Any data published through or received by the MQTT adapter will be binary encoded, due to MQTT being a binary protocol. This means that you’ll need to interpret the message to get the original contents out. For example, to interpret a message using Ably Realtime with JavaScript you’d need to do the following, using the text-encoding NPM module’s TextDecoder to decode from binary to text:

{
  var ably = new Ably.Realtime('REPLACE_WITH_YOUR_API_KEY');
  var decoder = new TextDecoder();
  var channel = ably.channels.get('input');
  channel.subscribe(function(message) {
    var command = decoder.decode(message.data);
  });
}

Or, if you wish to decode messages received through MQTT, you can use the following in NodeJS:
bc[nodejs]. {
const encoding = require(‘text-encoding’);
var decoder = new encoding.TextDecoder();

var client = mqtt.connect(‘mqtts:mqtt.ably.io’, options); client.on(‘connect’, function () { client.subscribe(‘input’); }); client.on(‘message’, function (topic, message) { console.log(decoder.decode(message)); });

}

In the above example, command will now contain the message in its original string form.

Recommended usage

We recommend you use MQTT to interact with Ably when:

  • Using devices which do not have a native Ably client library, such as Arduino platforms, C/C++ applications, and so on
  • If bandwidth is limited and you want to keep network traffic to a minimum

Supported features

Our MQTT adapter only supports features supported by both the MQTT protocol and the Ably platform. So:

  • It only supports MQTT 3.1.1 clients only. Connection attempts using earlier protocol versions will be rejected
  • Publishing supports QoS 0 or 1. Subscribing only supports QoS 0
  • Session resumption is supported within the usual Ably time limit of two minutes
  • It doesn’t support any MQTT features that aren’t normally supported by Ably, such as WILL messages, the RETAIN flag or wildcard channel subscriptions
  • It doesn’t support any Ably features that aren’t supported by the MQTT protocol, such as presence, history and push notifications (though presence may be supported soon). Of course, you can always use the Ably REST API in conjunction with the MQTT adapter to access features available over REST

Security

We recommend that you always make use of Token Authentication over Basic Authentication when trying to connect from devices you may not trust. In addition, if you’re using Basic Authentication you’ll be required to use SSL to connect to our adapter to ensure the API key cannot be accessed by someone listening in.

Token Authentication

For Token Authentication you’ll be required to create a token from your own servers. Once you have the token, you can simply pass it through when trying to connect to Ably as the connection’s username, leaving the password empty. In the future we will be extending our Token authentication scheme to support JWT (JSON Web Tokens).

If using Token Authentication, you can subscribe to a special topic, [mqtt]tokenevents, to get a warning when the current connection’s token is about to expire. This will be a single message, sent 30 seconds before the token expires, with the 13 byte payload expirywarning.

On receiving this, the client is recommended to get a new token, then disconnect and reconnect with the new token themselves. If this is not done, the server will abruptly disconnect the connection once the token expires.

An example of this with the NodeJS mqtt package would be:

{
  var client = mqtt.connect('mqtts:mqtt.ably.io', options);
  client.subscribe("[mqtt]tokenevents", {
    /* Create a new token called 'NEW_TOKEN' */
    client.end();
    options.username = NEW_TOKEN;
    client = mqtt.connect('mqtts:mqtt.ably.io', options);
  });
}

SSL

We support both SSL and non-SSL connections (the latter uses a different port, see above), but strongly recommend using SSL wherever possible. If you are not using SSL, note that the same restrictions apply as if you were using an Ably client without SSL. That is, connection attempts using Basic Authentication (i.e. an API key) are disallowed, and any namespaces which you’ve enabled ‘require TLS’ on will be inaccessible. If this is a problem for you, please do let us know at support@ably.io and we’ll see what we can do.

Adapter information

  • A protocol adapter inevitably adds some latency. Using the adapter will be a little slower than using Ably native client libraries. Typically the impact is in the low milliseconds
  • Behind the scenes, the adapter just uses the normal Ably service, so there is no problem with using MQTT and Ably client libraries side by side. You can mix and match as you like; for example, using MQTT on your IoT devices, but using the Ably Realtime API on your servers
  • While the adapter can be useful for devices which need to use MQTT, there are many benefits to using the Ably client libraries (e.g. continuity guarantees, fallback host support, history, presence) require the use of the Ably client libraries. As a result, if a native Ably library is available for your platform, we recommend you consider using the Ably client libraries instead.

Tutorials

If you would like to see the MQTT protocol adapter in action, we recommend you take a look at our MQTT snake tutorial.


API reference
Documentation

Get started now with our free plan

It includes 3m messages per month, 100 peak connections, 100 peak channels, and loads of features.

Create your free account