Skip to main content
The features described in this section are currently in beta testing and are subject to change.

​
Before you start

  • Assign access capabilities to create a hosted MQTT extractor and for the extractor to write data points, time series, events, RAW rows and in to data models in the target CDF project, depending on the resource types you want the extractor to ingest.
You can use OpenID Connect and your existing identity provider (IdP) framework to manage access to CDF data securely. See setup and administration for extractors.

​
Deploy the extractor

1

Create a source

Create a Source by making a request to /api/v1/projects/{project}/hostedextractors/sources containing just the external ID of the extractor you want to create. See the Source API specification.
{
	"items": [{
		"type": "mqtt_broker",
		"externalId": "my_mqtt_broker_source"
	}]
}
Note that since this API is in beta, you will need to set the cdf-version header to beta in your request.
2

Create a job

Create a Job by making a request to /api/v1/projects/{project}/hostedextractors/jobs containing a destination external ID, the ID of the source you created in the previous step, and a config containing just topicFilter. This effectively subscribes to messages published by the user created in the previous step.
{
	"items": [{
		"externalId": "my_mqtt_broker_job",
		"sourceId": "my_mqtt_broker_source",
		"format": {
			"type": "custom",
			"mappingId": "my_custom_mapping"
		},
		"destinationId": "my_destination",
		"config": {
			"topicFilter": "/my/topics/+/data"
		}
	}]
}
Messages need to be transformed into a CDF resource, see Message formats below for details.
3

Connect to the broker

This step is highly dependent on the client you wish to use to connect to the MQTT broker. Clients will allow you to specify a host, a username, and a password. Use the credentials provided in step 1.

​
Message formats

MQTT is a generic message transport protocol agnostic to the message payloads, which can be on any format. The Cognite MQTT broker supports several pre-defined message formats. If you want to define your own custom mapping of MQTT messages, see custom data formats for hosted extractors. Custom formats used with MQTT jobs will receive an input argument containing the message as JSON, and a context argument containing the topic, for example: 
{
	"topic": "company/location3/machine/pressure"
}
The topic given in the context will be the actual topic the message arrived on, not the topic filter, so it can be used to distinguish identical messages arriving on different topics. Messages are published on topics. A topic can be any string of text, but usually it’s a hierarchical structure, separated by forward slashes, for example: 
company/location3/machine1/pressure
Clients can subscribe to messages by subscribing to topic filters. A topic filter can be a topic written verbatim, but it also allows for wildcards such that one subscription can yield data from multiple topics. MQTT supports single-level and multi-level wildcards. + denotes a single-level wildcard and matches any text between two slashes. For example, if you have several topics like these: 
company/location3/machine1/pressure
company/location3/machine2/pressure
company/location3/machine3/pressure
You can subscribe to all of them by subscribing to this topic filter: 
company/location3/+/pressure
# denotes a multi-level wildcard and matches any text. It has to be used at the end of the topic filter. For example, if you have several topics like the following: 
company/location3/machine1/pressure
company/location3/machine2/pressure
company/location3/machine1/temperature
You can subscribe to all of them by subscribing to this topic filter: 
company/location3#

​
Encryption

The MQTT broker only allows connections using Transport Layer Security (TLS) encryption. The certificate used by the broker is signed by Let’s Encrypt. Let’s Encrypt root certificates are included in most modern operating systems, so make sure that the device you run the MQTT client on has up-to-date TLS certificates. You can also obtain the root certificates from Let’s Encrypt.