Skip to main content

Setting up a Message Bridge

Overview#

Message bridging allows you to forward all your devices messages in nRFCloud into another MQTT broker using your account device. This broker can be run anywhere, but the easiest way to get started is with AWS IoT. This allows easy rule based management of your messages and makes the long term storage process very simple. This guide will walk you through setting up an MQTT bridge to AWS IoT using MQTT-bridge-mosquitto.

MQTT Bridge Overview

Message Bridge Setup#

Prerequisites#

  • Git
  • NodeJS 12+
    • You can find NodeJS installers here.
  • Yarn
    • Once you have NodeJS installed, you can easily add yarn with the following command.
    • npm i -g yarn
  • AWS account with admin credentials
    • You'll need full access to an AWS account and the key / secret configured locally on your system. Instructions

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 the project's dependencies.
    • yarn install
  3. Initialize the needed context variables. This creates account device credentials, pulls nRFCloud account info, creates certificates for the local AWS IoT broker, and saves the resulting keys to SSM parameters.
    • yarn bridge-init <nRFCloud api key>
  4. Deploy the application.
    • yarn deploy

Republished Topics#

The bridge republishes all device message data from nRFCloud into your AWS account. In practice, this means all messages under prod/<Tenant ID>/m/# will be bridged. For convenience, the nRFCloud account topic prefix is replaced with data/. This means a message published on prod/db3e3846-f604-42af-829e-fb3a2d0f0f56/m/d/nrf-1234/test would be republished to data/m/d/nrf-1234/test

Demo Stack Setup#

Introduction#

The demo stack is an additional cloud application included in the MQTT bridge repository. It is intended to be an example for how data from the MQTT bridge could be used. It mainly consists of a IoT rule to save data into AWS Timestream, which is then graphed and visualized by the included Grafana instance.

Prerequisites#

  • Git
  • NodeJS 12+
    • You can find NodeJS installers here
  • Yarn
    • Once you have NodeJS installed, you can easily add yarn with the following command.
    • npm i -g yarn
  • Docker
    • Docker installers can be found here.
  • AWS account with admin credentials
    • You'll need full access to an AWS account and the key / secret configured locally on your system. Instructions
  • MQTT bridge stack deployed in your AWS account

Steps#

The first two steps can be skipped if you still have the project installed from performing the bridge setup.

  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 the project's dependencies.
    • yarn install
  3. Deploy the demo project.
    • yarn deploy-demo
  4. From the "Outputs" section of the previous command, copy the DNS name labeled nRFCloud-MQTT-bridge-demo.grafanaendpoint. Paste this into your browser.
 ✅  nrfcloud-mqtt-bridge-demo
Outputs:nrfcloud-mqtt-bridge-demo.grafanaendpoint = <Your Grafana endpoint will be here>
  1. You should now see the Grafana login interface. Login using the default admin account.
    • Username: admin
    • Password: admin
    • Entering these will bring up a prompt to change your password, feel free to change it to whatever you like
  2. You should now see a map dashboard with the label "Device Tracking". This map will show the last recorded position and temperature data for your devices. You won't see anything here until you generate some test data.

Grafana Dashboard

Generating test data#

A good way to verify that the bridge and demo is working correctly is using the device simulator.

  1. Perform setup according to the instructions in the repository
  2. Start the device simulator with some sensors enabled
    • node dist/cli.js -k <nRFCloud api key> -a -s gps,temp

Viewing the test data#

If you haven't set up the demo#
  1. Navigate to AWS IoT core in the AWS console
  2. On the left sidebar, click "Test" > "MQTT test client"

MQTT test client 4. In the "Topic Filter" field, enter '#' and press subscribe 5. You should now see incoming device messages in the "Subscriptions" section

MQTT test client data

If you have set up the demo#

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

Grafana Data