To use the MQTT protocol adapter, configure your mqtt clients 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 reponsiveness 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
Warning: if you do not set the keep alive time, your mqtt session will be disconnected after 1.5 minutes of inactivity.
Supported and unsupported features
- We support 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, see https://support.ably.io/solution/articles/3000044639-connection-state-recovery
- No wildcard subscriptions of any kind are supported, see https://support.ably.io/solution/articles/3000063123-can-i-attach-and-subscribe-to-channels-using-wildcards- for the reason why. Subscribe requests containing either single or multi-level wildcards will be nack'd.
- Will messages and the Retain flag are not currently supported.
We support both ssl and non-ssl connections (which use 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 auth (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 email@example.com and we'll see what we can do.
If using token auth, 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, once the token expires, the server will abruptly disconnect the connection.
The MQTT adapter is our recommended way of interacting with Ably from devices which do not have a native Ably client library, such as Arduino platforms, C/C++ applications, and so on.
Anyone who has previously been using Pubnub or Pusher client libraries for this purpose may want to consider switching to MQTT. Compared to the Pubnub protocol, using MQTT will result in better performance with lower latency. Compared to the Pusher protocol, MQTT will give you connection state recovery.
We also recommend MQTT for use-cases where bandwidth is limited and you want to keep network traffic to a minimum.