Setting up a message bridge

Message bridging allows you to forward all devices messages in nRF Cloud to another MQTT broker using your account device.

You can run this broker anywhere, but this guide recommends using AWS IoT. This allows rule-based management of your messages and long-term storage. This guide explains how to set up an MQTT bridge to AWS IoT using MQTT-bridge-mosquitto.

Prerequisites

• Git
• NodeJS 12 or later
• Yarn:
  • npm i -g yarn
• AWS account with admin credentials:
  • You need full access to an AWS account and the key and secret configured locally on your system.

Steps

1. Clone the MQTT-bridge-mosquitto repository to some local directory:
   • git clone https://github.com/nRFCloud/MQTT-bridge-mosquitto
2. From inside the cloned repository, install project dependencies:
   • yarn install
3. Initialize the needed context variables. This creates account device credentials, pulls nRF Cloud account info, creates certificates for the local AWS IoT broker, and saves the resulting keys to SSM parameters:
   • yarn bridge-init <nRF Cloud api key>
4. Deploy the application:
   • yarn deploy

Republished topics

The bridge republishes all device message data from nRF Cloud into your AWS account. This means all messages under prod/<Team ID>/m/# are bridged. The nRF Cloud account topic prefix is replaced with data/.

This means a message published on prod/db3e3846-f604-42af-829e-fb3a2d0f0f56/m/d/nrf-1234/test is republished to data/m/d/nrf-1234/test.

Demo stack setup

The demo stack is an additional cloud application in the MQTT bridge repository. It includes an IoT rule to save data into AWS Timestream. The data is then visualized by the included Grafana instance.

Prerequisites

• Git
• NodeJS 12 or later
• Yarn:
  • npm i -g yarn
• Docker
• AWS account with admin credentials:
  • You need full access to an AWS account and the key and secret configured locally on your system.
• MQTT bridge stack deployed in your AWS account.

Steps

You can skip the first two steps if you still have the project installed from the bridge setup.

1. Clone the MQTT-bridge-mosquitto repository to a local directory:
   • git clone https://github.com/nRFCloud/MQTT-bridge-mosquitto
2. From inside the cloned repository, install project dependencies:
   • yarn install
3. Deploy the demo project:
   • yarn deploy-demo

4. From the Outputs section of the previous command, copy the DNS name nRFCloud-MQTT-bridge-demo.grafanaendpoint. Paste this into your browser:

   ✅  nrfcloud-mqtt-bridge-demo
   
   Outputs:
   nrfcloud-mqtt-bridge-demo.grafanaendpoint = <Grafana endpoint>
   

5. You can now see the Grafana login interface. Log in using the default admin account:

   • Username: admin
   • Password: admin
6. You are prompted to change your password.

7. You can see a map dashboard with a Device Tracking label. This map shows the last recorded position and temperature data for your devices. It is empty until you generate test data.

   

Generating test data

Verify that the bridge and demo are working correctly using the device simulator:

1. Perform setup according to the instructions in the repository.

2. Start the device simulator with sensors enabled:

   • node dist/cli.js -k <nRF Cloud api key> -a -s gps,temp

Viewing the test data

The steps in this section depend on whether or not you have set up the demo.

No demo

1. Navigate to AWS IoT core in the AWS console.

2. On the left sidebar, click Test > MQTT test client.

   

3. In the Topic Filter field, enter # and press Subscribe.

4. You can see incoming device messages in the Subscriptions section.

   

Demo

Open the Grafana dashboard in your web browser and look at the map on the front page. You can see the locations of all your test devices.