Beebotte MQTT support opens the way for any MQTT capable device to interact with Beebotte.

Currently, Beebotte supports MQTT version v3.1.1 with QoS level 0 and QoS level 1.

Beebotte MQTT is accessible on mqtt.beebotte.com and accepts cleartext (port 1883) and secure (port 8883) connections.

Authentication

Beebotte provides three authentication schemes for MQTT connections:

Using IAM token Recommended

When establishing a connection, you provide your_iam_token as username and leave the password blank. If the given token is not valid, the connection will be dropped. This authentication provides read and write access to channels or resources associated with the IAM token. If you think the token was compromised, you can simply drop it and create a new one.

Using channel token Recommended

When establishing a connection, you provide your_channel_token as username and leave the password blank. If the given token is not valid (not associated to any channel), the connection will be dropped. This authentication provides read and write access to only one channel: the one the token is associated with. If you think the token was compromised, you can simply regenerate a new token for the corresponding channel.

• For older channel tokens not starting with token_ prefix, the username must be token:your_iam_token. This authentication scheme is kept for backward compatibility. Newer channel tokens start with the token_ prefix and can be used as username directly.

Using account's secret key:

When establishing a connection, you provide your secret key as username and leave the password blank. If the secret key is not valid, the connection is dropped. This authentication scheme provides read and write access to any user channel. Use this scheme only if you trust the device, and when connecting to Beebotte through encrypted connection (SSL).

MQTT connections from different users are isolated. This means that device A authenticated with secret key S1 publishing to topic "channel/resource" will not see its messages received by device B authenticated using secret key S2 and subscribing to the same topic. However, device C using the same secret key as A (owned by the same account) will receive the messages sent by A.

MQTT Billing

The following rules applies when accounting for messages over MQTT protocol

• connect, disconnect, subscribe and unsubsribe messages are accounted as regular publish/subscribe and billed as 1 message each.
• Messages published to Beebotte or delivered to active subscribers are billed per chunck of 1KB. That is a 4KB message publised to Beebotte and delivered to 10 subscribers will be accounted as 4 + 4 * 10 = 44 messages.

MQTT - Beebotte Bridge

Beebotte provides a transparent bridging between communications using Websockets, REST and MQTT as follows:

• REST Publish and Write messages will be received by MQTT and Websocket clients subscribed to the corresponding resources.
• Messages published using MQTT will be received by Websockets clients subscribed to the same topic (rules apply, See Considerations for details).
• Messages published using Websockets will be received by MQTT clients subscribed to the same topic.
• Messages published using MQTT are considered Private by default, whereas, messages published using Websockets are considered Public by default.

Considerations

Beebotte data model is based on channels and resources. We decided to soften the rules on MQTT usage to provide users the freedom to use it the way it suits them. The following rules apply:

• The user is free to select topics to register and publish to.
• In order to bridge MQTT with Beebotte, the topic MUST respect the following format: channel/resource.
• In order to persist a message sent using MQTT, the message payload MUST respect the following JSON format: {"data": object, "write": true}.
• As stated in the MQTT - Beebotte Bridge section earlier, MQTT messages are private by default. In order to publish a public message the message payload MUST respect the following format: {"data": object, "ispublic": true}.

Hello World Example

There are many MQTT client libraries available out there that you can use to build your application. We will use here the Eclipse Paho Project to build a simple Hello World example. To install Paho you can pip install paho-mqtt.

Publish and Subscribe Using MQTT

Note that if you Publish using the REST API a message to channel 'mychannel' and resource 'myresource', you will receive that message in MQTT as well. This is the bridging feature of Beebotte.

Hello World example in Nodejs

You can also use the MQTT.js Nodejs client library as follows: