MQTT Documentation

Datacake provides an TLS-enabled MQTT broker that can be used to both subscribe to Device measurements as well as record them.

The Datacake platform offers an MQTT broker with TLS encryption, which allows both subscription and recording of data.

With the help of this broker you can:

  • Forward incoming device data to external services via MQTT

  • Store data via MQTT into the Datacake Cloud

In conjunction with integrations such as Particle.io or TheThingsNetwork integration:

  • Set up a Device-to-MQTT-Bridge without any programming

Each Datacake device automatically publishes changes in the database fields via MQTT. If a new measured value is written into a database field, this is also published via MQTT.

Connecting to the Broker

The broker is running on mqtt.datacake.co on ports 1883 and 8883. Port 1883 is unsecured and should not be used in production environments. Port 8883 uses a CA signed server certificate.

Authentication

You will need an access token to log into the Datacake MQTT Broker. You can use your own personal token or create a token explicitly for individual devices or groups of devices.

We recommend that you use your personal Access Token only for development purposes. If you are using devices in the field through MQTT, it is recommended that you create your own token through Datacake Teams and API users.

All information about tokens can be found under the following link:

pageGenerate Access Token

Now use this token to log in to the Datacake MQTT Broker. To do this, enter your token as both username and password, as shown as an example in the following screenshot.

Manage Read/Write Access

If you create your own API Access Token, make sure that it has the required rights and roles.

Read more about how to create API Tokens and set permission here:

pageAPI Users

MQTT Client-ID

The Datacake Broker manages the client IDs internally. You do not need to worry about a client ID. If your client optionally supports the specification of a client ID, please leave this specification blank. Your client then creates a randomly generated ID.

If you still want to use (oder need to use) a unique client ID, it can happen that e.g. with multiple connections, the older connections are cut off. Therefore, make sure that your client ID is unique and is not used multiple times.

Topic structure

Subscribe

Data is published according to the following structure:

dtck/<product_slug>/<device_id>/<field_name>

Subscribe to topics using this structure to receive messages via MQTT when readings (via API or MQTT) arrive in the Datacake Cloud. Messages are published whenever there is a change to a corresponding database field.

Publish

To upload data into the Datacake Cloud and into a specific device, you publish the data to the respective topic structure.

Due to the nature of MQTT, the topic prefix differs as follows:

dtck-pub/<product_slug>/<device_id>/<field_name>

Pay attention to the prefix! Always use this prefix to import measured values:dtck-pub/

Topic Elements

The Product-Slug (/<product_slug>)

For each device you create on the Datacake platform, a corresponding product is created. In addition, multiple devices can inherit from only one product type.

For this reason, the name or path of the product must be specified in the Topic Structure. The reason for this is as follows:

If you manage a fleet of devices, which all originate from the same product type, then you can use this product path to receive the measurement changes and messages of all devices assigned to this product.

This would look like the following: dtck/<product_slug>/*/+

Are you interested in having your own product slugs for your devices? As this is an advanced feature, you will need to contact our sales team who will provide you with all the information you need to get started. Contact us: sales@datacake.de

Record Product Measurement Values

Publishing or importing product-wide measured values via dtck-pub/<product_slug>/*/+ is currently not supported. If you have such a requirement, please contact us.

Where do I find the product-slug specification?

Currently, you can find the specification of the Product-Slug in the metadata section of the device view.

Device-ID (/<device_id>)

By specifying the Device ID, you identify a specific Device via the topic. You can also find this ID in the metadata of the device view and also in the URL of the currently open device.

The Device ID is generated internally and is usually an absolutely unique UUID (exceptions are white label products of our customers).

Field-Name (/<field_name>)

The last element in the topic structure is the field name of the measured value, as it appears in the database or as it was created by you via e.g. an API device.

The upper/lower case of the field name is not important here, but it is recommended that you always use it in CAPITAL LETTERS, as specified in the portal.

The field name should not be mistaken for the displayed name of a field. The field name / field identifier is assigned once when the field is created and cannot be changed afterwards. If you still want to or have to change this identifier, you have to delete and recreate the field.

Examples

Subscription

To subscribe to all measurements of a Device with the Product slug my-product and the id 6b98a3bb-9ae1-418f-9375-f23091a849cd, subscribe to dtck/my-product/6b98a3bb-9ae1-418f-9375-f23091a849cd/+.

To subscribe to all temperature measurements of all Devices with the Product slug my-product, subscribe to dtck/my-product/+/TEMPERATURE.

Publish

To publish a single measurement to a specific Database Field of a Device with the Product-Slug my-product, the Device-ID 6b98a3bb-9ae1-418f-9375-f23091a849cd, and the Field-Identifier TEMPERATURE, publish a message to:

dtck-pub/my-product/6b98a3bb-9ae1-418f-9375-f23091a849cd/TEMPERATURE

The Payload is holding the Value which you want to be recorded into that specific Database-Field. 

publish("dtck-pub/my-product/6b98a3bb-9ae1-418f-9375-f23091a849cd/TEMPERATURE", 22.003)

M2M

You can use the Datacake MQTT Broker to exchange readings or messages between devices. The exchanged information is always related to the fields created for the device.

You can only exchange information that is stored in a field.

To exchange messages between two different devices, simply subscribe to a specific measured value field of the respective other device.

Example

The following example uses a pseudo code to show how you can use the Datacake MQTT structure to exchange messages between two devices.

In this example, this is the message transmission of a temperature from device 1, which sends the measurement data to the Datacake platform via MQTT.

Device 2 subscribed to the topic of device 1 and thus receives the measured value from device 1 as well.

Pseudo-Code for Device 1

# Device 1 (device id 000001):
publish("dtck-pub/my-product/000001/TEMPERATURE", 23.02)

Pseudo-Code for Device 2

# Device 2 (device id 000002):
subscribe("dtck/my-product/000001/+", handler)

def handler(topic, payload):
    print(f"Received Payload from Device 1: {payload}")

If the respective device now transmits one or more readings (whether via MQTT or API) to the Datacake platform, this change will be forwarded via MQTT to all subscribers who also subscribe to the device or topic.

Product-wide M2M

If your devices come from the same product type, you can also subscribe to the respective product on the devices to receive all messages from all devices in the field.

The following Pseudo-Code should clarify the concept:

subscribe("dtck/my-product/*/+", handler)

def handler(topic, payload):
    print(f"Received payload: {payload}, from Topic: {topic}")

Just make sure that your device has sufficient processing power if the number of active devices is large.

Since creating your own Product-IDs on Datacake is an advanced feature and if you have a use case for product-wide M2M, please contact our sales to arrange a discussion how we can set this up for you!

sales@datacake.de

Connecting external Brokers

If you want to use a client functionality from the Datacake Cloud, e.g. to connect (and exchange data with) an external broker, then usually an adapter is required, which brings the topic structure of the external broker to the structure of the Datacake Broker.

There are two different ways to do this:

  • Use Cake Red to use Node-RED and graphical programming to create an adapter to connect both brokers (foreign broker and datacake broker).

  • Develop a server-based service that connects both brokers in the background and that maps the topic structure programatically.

We can take over the development of such a Broker 2 Broker Adapter (via Cake Red or an independent service) for you or would be happy to support you in its implementation. Please contact us!

Last updated