ClearBlade Edge and Cloud Platform support Messaging via MQTT, which is a lightweight IoT Messaging protocol. We have also built an OAuth 2 security model into the MQTT Broker to provide out-of-the-box security around messaging.
This section covers the following topics:
Lightweight messaging is key to moving data around an IoT System at scale.
Workflow 1: Upon publish, process message with code services, which publishes output
Workflow 2: Code Service invoked, perform computation, then publishes output
|Quality of Service||Definition||Desc|
|0||At Most once||The message is only sent once whether it makes it to the subscriber or not|
|1||At least once||The message will be sent one or more times to the subscriber until the message is received|
|2||Exactly once||QoS will make sure that the message will be received by the subscriber exactly once|
How to Connect
To work with MQTT the following steps are involved:
You must have a user or device available with valid permissions to publish messages.
Please follow the instructions to do so:
- Log in or create a developer account on a ClearBlade platform instance.
- View or create a System
- View or create a User
- View or assign a role to the user
- View the Roles page
- Add a topic to list of Message Topics enabled for that role, example ‘mytopic’
A ClearBlade User Token is required to communicate with a broker. A token can be obtained via a REST endpoint call or via MQTT.
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.
Duplicate Client IDs
If you subscribe with same client ID as another subscriber, your subscribe will fail.
Topics are used to separate messages and keep them organized based on what they are about.
There are three types of topics:
Topics comprised of string literals:
Wildcard subscription means they are subscribed to multiple topics simultaneously. These are of two types:
Single Level (+)
The single level wildcard (+) allows a subscription to match an entire level of the topic’s path.
Multi Level (#)
The multi-level wildcard: “#” matches with all values following the #
The following subscribes to EVERY topic:
See the following example:
It’s important to note that a subscription topic like
/Foo/#/Bar is invalid. Once a hash is in the subscription, that hash is the last element in that subscription.
The ClearBlade Message Relay is a way for edge MQTT clients to communicate with the Novi MQTT clients as well as other Edge MQTT clients. In order to achieve this there are a few reserved MQTT topic paths that one needs to follow for the message relay to work. The message relay uses the following 6 topic paths to route messages between edges and their parent platform.
Message relay applies to communication between edges and platform within one single system
|Message Type||Topic Path|
|Edge to Platform||<TOPIC_NAME>/_platform|
|Platform to Edge||<TOPIC_NAME>/_edge/<NAME_OF_EDGE>|
|Edge to Edge||<TOPIC_NAME>/_edge/<NAME_OF_EDGE>|
|Platform to All Broadcast||<TOPIC_NAME>/_broadcast|
|Edge to All Broadcast message||<TOPIC_NAME>/_broadcast|
|Edge to Edge and Platform||<TOPIC_NAME>/_edgeAndPlatform/<NAME_OF_EDGE>|
These topic paths are for sending messages. To receive messages subscribe to the same topics, except for Edge to Edge Platform (which you need to subscribe to the same topics for both platform and edge).
Ports for MQTT and 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||TODO|
|8908||True||Auth over MQTT via Web-Sockets||TODO|
ClearBlade provides an authentication broker for obtaining a user token.
Step 1. Connect
|Required Keys||Description||Example Values|
|ClientId||<USER_EMAIL>:<PASSWORD> for User, <DEVICE_NAME>:<ACTIVE_KEY> for email@example.com:cl34r8l4d3 or temperature-sensor:faqb8fb60bc2c2b1c0e4bb9701|
Step 2. Subscribe
Subscribe to “auth” endpoint
Step 3. Token is received
ClearBlade publishes the user-token on the “auth” message topic with bit-level encoding.
The payload is of the following format:
- The length block is of 2 bytes usigned 16 bit integer
- The data block is utf-8 encoded bytes
Mapping of the blocks in the above packet structure:
|1||Length of the token|
|3||Length of the user-id or device-name|
|4||UserId or DeviceName|
|5||Length of the Messaging Url|
Once Client is Authenticated, the token can be extracted & the connection can be established.