MQTT

The ClearBlade Platform contains a fully compliant MQTT broker, including backlevel support to 3.0, for supporting high speed and large scale IoT solutions.

In addition to honoring the core specification, ClearBlade has added enhanced capability to secure assets in co-tenanted environments and to provide horizontal scalability. To connect standard MQTT clients you will need to use the following pattern:

Before Beginning:

  1. Ensure you have an existing developer account on a ClearBlade platform instance.
  2. Create a “System” that will be your isolated messaging topic.
  3. Create a user in your System - here for how to create a new user.

Ports for MQTT & their Requirements

Port TLS Information Requirements
1883 False MQTT Pub/Sub user-token
1884 True MQTT Pub/Sub user-token
8903 False Web-Sockets, usually used by browser/applications (cannot communicate directly over MQTT) dev-token
8904 True Web-Sockets dev-token
8905 False Auth over MQTT SystemKey, Secret, Username, Password, ClientId
8906 True Auth over MQTT
8907 False Auth over MQTT via Web-Sockets
8908 True Auth over MQTT via Web-Sockets

Authentication:

Before a client can communicate with a broker it must first obtain a ClearBlade Token. This token grants the user access and control to the System assets. A token can be obtained via a REST endpoint call or via MQTT.

Using REST Authentication:

In each language specific SDK, the init or login functions are provided. They all use the common REST endpoint found here.

Using MQTT Authentication:

Alternatively, ClearBlade provides an authentication broker for obtaining a user token. The auth broker ensures the integrity and security of the transaction to prevent other clients from subscribing to client specific auth topics.

TCP

  • URL: <PLATFORM_IP>
  • Port: 8905
  • Username: <SYSTEM_KEY>
  • Password: <SYSTEM_SECRET>
  • ClientId: <USER_EMAIL>:<PASSWORD>

The broker will reply back with

  • Work broker IP address
  • ClearBlade Auth Token

Establish a Connection

The MQTT protocol allows for the connect action to provide a username and password. We will modify the use of those fields to accomodate our oAuth styled token model.

  • URL: <URL_OF_BROKER>
  • PORT: <PORT>
  • Username: <USER_TOKEN>
  • Password: <SYSTEM_KEY>
  • ClientID: <UNIQUE_CLIENT_ID>

Example - URL: staging.clearblade.com - Port: 1883 - Username: abcdefabcdef01234567890 - Password: f0cbf0cbf0cbf0cbf0cbf0cbf0cb - ClientID: ksjdbfkasdbf

Duplicate Client IDs

If you subscribe with same client ID as another subscriber, your subscribe will fail.

With that configuration clients will now be able to connect to the broker as normal for publishing and subscribing to topics.

Tutorial

There are a few steps to get things going.  

Part 1 - Register

  1. Sign up for access to ClearBlade, and log in    https://www.platform.clearblade.com/  
  2. Once you have a login name and password, you’ll have to log in to the platform.  

    Part 2 - Create a System

In this first part we are going to build our first system. A system represents the backend components of application server, database, message broker, and user registry all brought together to be easily utilized and managed.

  1. Click the New button located in the top left part of the menu bar

  2. Provide a name “Tutorial” and description “My First System”

  3. Click Create!

  4. View your system settings by clicking the gear icon located in the top right of your new system.

  5. Capture your systemKey and systemSecret - we will use those values in our clients
    NOTE: User Session Token TTL - provides you the ability to customize how long the user tokens are operational.

  6. Open the file index.html in your local browser

  7. The final step of Part 1 is to initialize the ClearBlade Platform anonymously. Follow the instructions in your client UI to complete that task.

In some cases this tutorial will show examples of the client in Javascript. Expect comparable user interfaces to exist in the Android and iOS clients.

Part 3 - Create a user

The attribute that should be first in the minds of all enterprise platform developers is security. Before anything meaningful happens with ClearBlade we must start to define the permissions model. The permissions model in the ClearBlade platform is role-based.

Although you have already created a developer account to login to the platform, each system you create will have its own user registry. For Part 2 we will create our first user and then connect to our system as that user. To get the basic understanding of users:

  1. Click the Auth tab to Add a new user (email and password)

  2. Add a new user by Clicking the + User icon

  3. Set the user email to “test@clearblade.com”
  4. Set the user password to “clearblade”

  5. Your user is now created and has been given the role of “Authenticated”. To learn more about users and roles see the documentation
  6. Go back to you client app and execute the Part 2 login action

Part 3 - Fetch User Token 

  1. Once you have the system and user of the system, please use the Web Services API to get your user –token. Press Try it out, fill in the System Key and System Secret and then the user name, password and hit execute.    https://docs.clearblade.com/v/3/static/restapi/index.html#/User/AuthUser

Response

{"user_token":"2uJaum6SoZsrDXQc1i05pyZ6lUnkTXaqbfG4S7JUPGOOcYQlCxi8i62gPi6BuDNVIchdG7CawJ4oDY8eBw==","user_id":"9ed0b2970bf2c5c7a2b78389c8b901"}

The value for “user_token” will be used below as your <AUTH_TOKEN>   2. Once you have the user-token, you can use a program such as mosquitto to publish to a topic. It’d try publishing first and see if you can find the message in the “Message History” tab in ClearBlade.

Standard

To install mosquitto CLI see downloads  

mosquitto_pub -P <SYSTEM_KEY> -u <AUTH_TOKEN> -h <PLATFORM_URL> -t <MQTT_TOPIC> -m <MQTT_BODY>

  Advanced

mosquitto_sub -h <PLATFORM_URL> -p <OPTIONAL_PORT_OVERRIDE> -t <MQTT_TOPIC> -u <USER_TOKEN> -P <SYSTEM_KEY>

Example

mosquitto_pub -P mosquitto_pub -P deb2bXXXXXXXXXXc19501 -u 2uJaum6SoZsrJKJJJJJJJJJJJJJJJJJJJJJJCawJ4oDY8eBw== -h platform.clearblade.com -t topic1 -m ExampleMessageBody

Congratulations! You’ve published to your system!