MQTT Bridge
BlueForest ingestion implements MQTT 3.1.1 server functionality, and works with all popular MQTT client SDK and implementations.
MQTT (Message Queue Telemetry Transport) : is a machine-to-machine communication protocol particularly well suited for machine data and Internet of Things (IoT) applications.
MQTT is a publish-subscribe based messaging protocol. It works on top of the TCP/IP protocol.
Supported MQTT 3.1.1 features
- QoS0 and QoS1 publish & consume
- QoS2 publish (downgraded to QoS1)
- Last Will and Testament (LWT)
- TLS
- Session stickiness
- Retained messages
Usage
Client Id
Every MQTT Connection needs a unique client ID. With this unique client ID the broker can recognize when a client reconnects and can close an old potentially half-open TCP connection for the client. Also, the MQTT broker can hold a persistent session for MQTT clients if they desire to do so (cleanSession=false on CONNECT). If you disconnect and reconnect with the same client ID, you will receive all messages for your subscriptions you may have missed and the broker knows your old subscriptions for that client ID.
Client Id Format :
${tenantName}-${uniqueClientIdentifier}
| Parameter | Required | Description |
|---|---|---|
| tenantName | yes | Tenant unique name. Sub tenant names are supported. ie. : mytenant and mytenant_whatever are both supported |
| uniqueClientIdentifier | yes | Unique client ID. Could be a static string per client or a random string if you don’t need persistent session. |
Client Id Sample :
mytenant-client001
With sub tenant name :
mytenant_myproject-client001
With random string as unique client identifier :
mytenant-agfdok4fsf5458s3d15e6sd43fghthy
Topic standards
Information is organized in a hierarchy of topics.
Topic Format :
${tenantName}/${stream}/${channel}/${deviceId}/${path}
| Parameter | Required | Description |
|---|---|---|
| tenantName | yes | Tenant unique name. Sub tenant names are supported. ie. : mytenant and mytenant_whatever are both supported |
| stream | yes | Stream : ingestion ; alarms ; management ; … |
| channel | yes | Channel is a topic level that could be used to split (loadbalance) data flow into multiple channel . Default : use 0 |
| deviceId | no | BlueForest device Id |
| path | no | Path is the name that describe one of the device datapoint path. Path for a datapoint can include topic separator ‘/’ ie. : home/kitchen/temperature. Those separators in path allow you to organize datapoint in a hierachy. |
Topic Sample :
mytenant/ingestion/0/1234/home/kitchen/temperature
With sub tenant name :
mytenant_myproject/ingestion/0/1234/home/kitchen/temperature
Without device Id (a datachunk COULD embbed data from multiple devices) :
mytenant/ingestion/0/datachunk
Topic Best Practices :
- Avoid using space and non printable characters in a topic
- As topics are case sensitive, try using only lowercase topic.
- Keep the topic path short and concise.
Supported payload
Payload is the actual content of the message. As it is a binary based protocol, MQTT is data-agnostic. It is possible to send JSON message, CSV, images, text in any encoding, encrypted data, and every data you want in binary.
That said, to start ingesting with the MQTT protocol, ensure the following:
- Send data on ingestion stream topic :
${tenantName}/ingestion/${channel}/${deviceId}/${path} - The payload of MQTT message is formatted in one of the accepted input formats (
JSON Datachunk,msgPack Datachunk, …). More information here.
Quality of Service
BlueForest only implements MQTT Quality of Service (QoS) level zero and one :
- QoS0 : messages will be delivered at most once to the endpoint and processed by Blueforest.
- QoS1 : messages will be delivered at least once to the endpoint and processed by Blueforest.
- QoS2 : message with QoS2 are downgraded to QoS1.