Tinamous MQTT Broker

MQTT is a protocol that is popular in the Internet of Things world, it is a light weight, asynchronous, pub/sub protocol, it’s simple but powerful.

Tinamous now has a basic implementation of a MQTT Broker. At this time it supports only QOS0, No Last Will Testament, No SSL, nothing fancy. It does however allow you to use MQTT to talk to the Tinamous platform and makes it very easy to get your devices posting measurements or status messages.

Note: Because of the lack of SSL you should be careful when using the MQTT broker at this stage that nothing private/confidential is exposed.

The MQTT broker provides support for status messages, measurements and alerts as well as pub/sub for your own messages.  Status messages, measurements and alerts posted through the web site or REST API are published to the MQTT Broker and can be subscribed to.

Naturally MQTT doesn’t support the full Tinamous API, their is no support for clearing messages, getting historical measurements/status posts or adding users, however it does provide a real time stream of messages, measurements and alerts which is ideal for many small connected devices and saves you having to learn the Tinamous REST API.

Getting started with Tinamous MQTT:

  • Use the same account url as you do with the web browser (e.g. user demo.tinamous.com for MQTT and https://demo.tinamous.com for web browser)
  • Port 1883. SSL on 8883 is not supported at this time.
  • You can connect using a Tinamous user or device account.
  • Use username and password authentication. The username needs to include your account name as well.
    • e.g. if your Tinamous account is “MyAccount”, such that you connect at
       https://MyAccount.Tinamous.com and your username is “UserName” you need to use “UserName.MyAccount” as your MQTT username
  • Use a different ClientId for different clients (and different instances of the same client).
  • Topics are case sensitive.
  • Publishing to a /Tinamous/… topic will not fan out to subscribers as you would normally expect with MQTT. The message is taken in, processed and then pushed out via the appropriate Tinamous topics.
  • It’s a very very very early version so may have issues, please let me know if you find problems.
  • Use QOS0 only, other Qos’s may not work as expected (or at all!)

Tinamous Topics:

  • Device / Usernames do not include the account name in topics. This is needed only for authentication.
  • Wildcards (# and +) are supported for subscriptions on all topics but not on publish.

Status Posts:

  • Publish to: /Tinamous/V1/Status
    • The data should be the message to post to the timeline (e.g. “Hello World”)
  • Subscribe to: /Tinamous/V1/Status/[UserName]
    • Here the UserName is just the simple device/username, it does not need the account qualifier.
    • You can use wildcards to get status posts from all users (e.g. /Tinamous/V1/Status/+).
    • When you publish the message it will not be broadcast to subscribers on the /Tinamous/V1/Status topic but under the sub topic of the user you are connected as (e.g. /Tinamous/V1/Status/Thermistor)

Measurements:

You can publish measurements in two different ways, either as a simple measurement value to the appropriate device/channel/field or as a json object with multiple fields.

  • Publish to: /Tinamous/V1/Measurements
    • use a Json object representation of the measurements, this may contain up-to 12 fields as per the REST api.
  • Publish to: /Tinamous/V1/Measurements/[channel]/Field[n]
    • where channel is typically 0, but may be any user set value as per the API
    • and Fieldn is “Field1” to “Field12”
  • Subscribe to: /Tinamous/V1/Measurements/[device name]/[FieldName]
    • Where device User/Login Name is the user or device publishing measurements
    • FieldName is the friendly name configured for the field (Defaults to “Field 1”, but settable for devices, e.g. Temperature)
    • No channel information is included so if you have the same field name on different channels this will get mixed up
  • Subscribe to: /Tinamous/V1/Measurements/[device name]/[channel]/Field[n]
    • Where channel is the measurement channel number, typically 0.
    • Field[n] is “Field1” to “Field12” as per the REST API.
  • Subscribe to: /Tinamous/V1/Measurements/[device name]
    • Rich Json objects of the measurements are published to this topic.

Alerts:

Alerts support 3 levels, “Critical”, “Error” and “Warning”. With the alert a message is also added.
  • Publish to: /Tinamous/V1/Alerts/[Level]
    • These are not re-published to subscribers on this topic.
    • The message should be the message text to go with the alert (e.g. “Fridge power fail”)
  • Subscribe to: /Tinamous/V1/Alerts/[device or username]/[Level]
    • Use wildcards to get alerts of certain levels from any user. e.g. /Tinamous/V1/Alerts/+/Critical will capture all Critical alerts from any user.
    • The message will be the simple message text entered for the alert.
  • Subscribe to: /Tinamous/V1/Alerts/[device or username]
    • This publishes a rich json object describing the alert in more details.

Your Own Topics:

  • You can publish/subscribe to any topic you wish, however the /Tinamous namespace should not be used as more topics will be added.
  • You will only see published messages from users in your account.

 Give it a try:

All Tinamous accounts are MQTT enabled so you can dive in now with your own account, or you can give it a try using the demo account if you prefer.
  • broker url: demo.Tinamous.com
  • port: 1883
  • user: MqttDemoDevice (Username for authentication is MqttDemoDevice.demo)
  • password: MqttDemoPassword1

Tested clients:

Sample Code:

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s