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:
- Ensure you have an existing developer account on a ClearBlade platform instance.
- Create a “System” that will be your isolated messaging topic.
- Create a user in your System - here for how to create a new user.
Ports for MQTT & their Requirements
|8903||False||Web-Sockets, usually used by browser/applications (cannot communicate directly over MQTT)||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|
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.
- 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.
There are a few steps to get things going.
Part 1 - Register
- Sign up for access to ClearBlade, and log in https://www.platform.clearblade.com/
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.
Click the New button located in the top left part of the menu bar
Provide a name “Tutorial” and description “My First System”
View your system settings by clicking the gear icon located in the top right of your new system.
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.
Open the file index.html in your local browser
The final step of Part 1 is to initialize the ClearBlade Platform anonymously. Follow the instructions in your client UI to complete that task.
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:
- Click the Auth tab to Add a new user (email and password)
- Add a new user by Clicking the + User icon
- Set the user email to “email@example.com”
- Set the user password to “clearblade”
- Your user is now created and has been given the role of “Authenticated”. To learn more about users and roles see the documentation
- Go back to you client app and execute the Part 2 login action
Part 3 - Fetch User Token
- 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
The value for “user_token” will be used below as your
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.
To install mosquitto CLI see downloads
mosquitto_pub -P <SYSTEM_KEY> -u <AUTH_TOKEN> -h <PLATFORM_URL> -t <MQTT_TOPIC> -m <MQTT_BODY>
mosquitto_sub -h <PLATFORM_URL> -p <OPTIONAL_PORT_OVERRIDE> -t <MQTT_TOPIC> -u <USER_TOKEN> -P <SYSTEM_KEY>
mosquitto_pub -P mosquitto_pub -P deb2bXXXXXXXXXXc19501 -u 2uJaum6SoZsrJKJJJJJJJJJJJJJJJJJJJJJJCawJ4oDY8eBw== -h platform.clearblade.com -t topic1 -m ExampleMessageBody
Congratulations! You’ve published to your system!