Skip to content

Overview of the nRF Cloud MQTT API

MQTT is a lightweight publish-subscribe protocol for exchanging messages. nRF Cloud is built on AWS and uses the MQTT broker in AWS IoT Core to process MQTT messages sent and received over MQTT topics.

The publish-subscribe process over MQTT is as follows:

  1. A device, or the MQTT client running in the modem, connects to the nRF Cloud MQTT endpoint.
  2. The device publishes a JSON message on a topic.
  3. The MQTT broker receives the message. If a rule is specified, the rule is run, and if the rule's criteria are met, it triggers an action. Typical actions might include storing a message in a database or republishing a subset of the data to another topic.

MQTT connection information

To acquire the MQTT broker hostname, call the FetchAccountInfo endpoint. This method requires you to use the REST API. The JSON response includes two fields, the mqttEndpoint and mqttTopicPrefix. The endpoint is always the same for nRF Cloud operations. The topic prefix is unique to your team, as in the following example:

"mqttEndpoint": "mqtt.nrfcloud.com"
"mqttTopicPrefix": "prod/762bfc32-d338-4d5a-bd03-1e504e013846/"

If you do not want to use the REST API to get this information, you can also form the mqttTopicPrefix using your Team ID:

  1. Log in to the nRF Cloud portal.
  2. Click the drop-down menu in the upper right corner.
  3. Click Teams.
  4. Find the Team ID under the team name.
  5. The value of mqttTopicPrefix is prod/<teamID>.
  6. Use this value when calling the MQTT API.

Authentication

All connections to the AWS IoT MQTT broker must use Mutual TLS on port 8883. This means that devices using MQTT must have an X.509 device certificate and be onboarded to nRF Cloud.

Topics

In addition to AWS core topics, nRF Cloud includes MQTT topics for its own operations.