SF MQTT API

Sometimes you need to send data without going through the SF Edge. This thing is possible by using the SF MQTT API Endpoint.

API Endpoint Structure

1. Topic

You can set different information at this level like 'tenant', 'thing' or 'compression-type' (separated by the '/').

Example: senseforce/crane1/lz4 senseforce=Tenant crane=Thing lz4 = Compression-Type

2. Payload

The payload is JSON-type data where you can set the events you want to be stored in the database. Example of a payload:

{
	"events": [
		{
			"id": "8a4c6063-91ce-441e-a41a-eff33f6f5d66",
			"timestamp": 1656597003349, //timestamp in miliseconds
			"type": "mqttfx_example",
			"data": {
				"temperature": "35"
			}
		}
	]
}

'events' - the array of the events [ { 'id' - id of the event 'timestamp' - timestamp of the event --> milliseconds 'type' - schema key created in the platform 'data' - contains the non-metadata columns from the event, the custom-created ones {'temperature' - custom attribute/column of the event schema} }, {...}, {...} ]

As a recommendation is better to "combine" several messages into one "events", rather than sending individual messages very often.

MQTT client

In order to be able to use the API, you have to set up a Message Queuing Telemetry Transport (MQTT) client. This client will connect to the SF MQTT Broker and then you can send data to the platform.

An example of such a tool is 'MQTTfx' which we will use in our example but of course, you can use any client you want. After following the installation steps from the client website (https://mqttfx.jensd.de/), you need to make sure you have the proper connection information set like: - Broker Address and Port - User Credentials - Certificate File (please contact Senseforce team related to this)

Once the connection is established you can send data to the platform.

Example of sending data

Before sending data to the platform, you need to have an event schema set up so the data can be stored. We will consider for this example the following event schema(published):

Using MQTTfx tool we can send data to the platform as described above:

Then you can check in the platform in the dataset editor if the data for your schema was inserted:

Frequently encountered problems

Timestamp format

The timestamp should be converted in UNIX time in milliseconds

Wrong usage of the Data property

The custom-created attributes at the event schema level will be set under the 'Data' property of the event item.

Connect an MQTT client without a certificate

This would be possible only if the certificate validation is disabled on the customer side. Synchronize with the Senseforce team.