Attention - INTERNATIONAL customers, USPS shipping services, including Express Mail continue to experience extended service delays.
We STRONGLY advise shipping using UPS for all URGENT orders. Click on the link to set up freight collect options for your account. Dismiss

You are using an unsupported browser!

Please upgrade your version of IE to at least 9, or use a modern browser such as Chrome or Firefox.

WiFi MQTT Sensor
User Guide

Introduction

MQTT allows the complete line of NCD WiFi sensors to communicate via the internet to any MQTT Broker service using a WiFi connection.  It only requires network connection credentials, connection information about the MQTT Host Broker, and authentication information for the MQTT connection if applicable.  

The WiFi Sensor for MQTT supports connection to MQTT Brokers via open connection, basic authentication, as well as TLS.  Topics and message payload formats are fully customizable for compatibility with your specific MQTT Broker service.  WiFi communication is also fully encrypted for your security. 

This guide is applicable to all of the NCD WiFi MQTT Sensors. Some information such as the displayed data at the end of this guide may differ depending on the sensor you are using. To get started using the WiFi MQTT Sensor, follow the steps outlined below. 

Setup Instuctions

Getting Started

This guide is broken up into 3 sections:

  1. MQTT Broker
  2. Web Interface Sensor Settings
  3. MQTT.fx 

Each sections contains step-by-step instructions on how to setup your WiFi Sensor for use with MQTT. Follow the sections in order for a stress free, easy setup. 

Step 1. Establish a MQTT Broker

When your WiFi sensor begins transmitting data, it needs a place to transmit that data to. It needs a broker. Therefore, we will be creating a channel on beebotte.com. You may prefer a different broker, but for this example, we will be using beebotte. It is a valid, free MQTT broker and is easy to use. 

To begin, go to Beebotte.com and register a new free account. 

Create a channel. The name of the channel is up to you, as well as the configured resources. 

 

My channel name is Josh_Cloud and the configured resource is Test_Hub.

 

Leave everything else as it is unless applicable.

 

Click Create channel 

You should then see your channel listed in the Channels tab.

If so, you have successfully created your first channel in Beebotte and you are almost ready to configure your sensor. 

Lastly, you will need the Channel Token of the channel you just made. 

To find this, open the channel you just made. I would click Josh_Cloud

After opening your channel, you will be brought to a screen like this. 

Here, we will need to copy the Channel Token. It is needed to configure the settings on our sensor. This token should not be shared with anyone. 

Be sure to copy from where it initially says Token in black lettering, all the way until the end of the token code. It will need to look like this when we enter it in later:

token:token_###########

Make sure token is undercase. I recommend making a small document or notepad that contains this token code, as well as the settings you will be configuring in step 2. That way if you ever have to do it again, you can copy and paste from your document. 

Step 2. Setup NCD WiFi Sensor

Now we will configure the sensor’s settings. Begin by getting the Sensor into Setup Mode and connecting to it. To do so, hold the configuration button (c) which is found on the WiFi module near the micro USB port. If the LED is flashing blue, it is already in setup mode and ready to be connected to. This NCD web interface is extremely beneficial and easy to use.

While the device is in setup mode, open the WiFi network preferences on your computer and scan for WiFi networks.  The Sensor should show up in the WiFi network scan as NCD_MQTT_Sensor

Connect to NCD_MQTT_Sensor.

When prompted for a password enter: 

NCDBeast

WiFi Networks Image

Once connected to the WiFi Sensor, a NCD browser window will appear on your screen.  If for some reason this browser window does not appear, open your browser and type the IP address 172.217.28.1 then press enter.

This browser interface tells the Sensor which WiFi network to connect to for internet access, the network’s password, and all connection information for the MQTT broker.

Reference the information below to configure the settings on this browser interface and click the Save Settings button. Once saved, wait for the light on your Sensor’s WiFi module to turn green and it will close the browser interface for you.

Sensor Configuration:

WiFi Settings -

 

Network:   Select the SSID that you want this device to connect to.

Hidden Network:   If you choose to use a hidden SSID, enter it here. 

Password:   Enter the password for the Network or Hidden Network this device will be connecting to.

DHCP Enabled:   Uncheck this if you wish to manually configure the settings below. Otherwise, move onto Soft AP. 

Default Gateway:   If applicable, enter Default Gateway address.

Subnet Mask:   If applicable, enter Subnet Mask address.

DNS Primary:   If applicable, enter DNS Primary address.

DNS Secondary:   If applicable, enter DNS Secondary address.

Static IP:   If applicable, enter Static IP address.


Soft AP Settings -

 

Soft AP SSID:  This is where you can customize the SSID that the sensor will broadcast. Remember to use underscores or dashes instead of spaces if the ID you wish to create contains multiple words.

Soft AP Password:  This is the password that will need to be entered when trying to access this device’s network.

 

MQTT Server Settings -

Domain:  Enter the URL for your MQTT broker in this Field,  Alternatively you may enter the IP address for your MQTT broker in the IP field.  This field must be left blank if you intend to use the IP field

IP:  Enter the IP address for your MQTT broker if you prefer that to the Domain Field.  Leave this field set to 0.0.0.0 if you intend to use Domain instead.

Port: The Port number the MQTT broker listens on for inbound connections.

TLS Enabled:  If your MQTT broker implements TLS then be sure to check this box.

Root Certificate:  If applicable upload your Root CA Certificate here for TLS connections.

Private Key:  If applicable upload your private key for TLS connection here.

Device Cert:  If applicable upload your connection specific certificate for TLS connection here.

Root CAs are required for TLS connection so you must upload a Root CA if you require TLS on the connection.  Optionally you may also upload a Private Key and Device Certificate.  Note that Security on MQTT servers, as we have found, are wildly different in their authentication methods.  Some use TLS with a root CA but no private key, Some use TLS with a root CA but also require basic auth credentials, some just require a User name, etc.  There really is almost no way to make an off the shelf solution that will work with anything but the Gateway hopes to fulfill the need of 99% of users out there.  We cannot however guarantee that it will work with any MQTT broker so be sure to check the authentication procedure for your intended MQTT broker before purchasing this Gateway.  Also note that we sell gateways specifically designed for other cloud services such as Azure, AWS, Losant, etc.

MQTT Client Settings -

Client ID:  Enter a client ID to use for the MQTT connection from the Sensor.  If no Client ID is entered, then the MAC address of the Sensor will be used as the Client ID.  Also note that the Client ID may also be used in Topics and Messages depending on your customization of those.

User Name:  Enter a User Name for the MQTT connection.  Some MQTT servers use basic authentication for security.  The User Name can be found under User Credentials in the MQTT.fx application or on Beebotte.com.

Password:  Optionally, enter a Password for the MQTT connection.

Settings Topic:  Enter the Settings Topic that can be used to update new settings while in the MQTT broker. This example shows how JSON can be used to change the transmission interval of the device by publishing to the Settings Topic while in the MQTT broker. More keys are provided at the end of Step 3 further in this guide. 

MQTT Message Settings -

We have implemented a token replace system for MQTT topics and payloads in order to facility compatibility with numerous cloud based systems which implement MQTT.  This means you can embed information about the sensor or the data coming from the device into the topics and message payloads.  This is a very powerful feature of the WiFi Sensor for MQTT.

Message Format:  Token based formatting for the message payload sent when the sensor updates information about itself to the MQTT broker.  

Supported tokens are ::Sensor_ID:: and ::Sensor_Data::

Topic Format:  Token based formatting for the topic to which sensor information is written to on boot.  

Supported tokens are Your_Topic/::Sensor_ID::

Interval(mSec):  Customize the interval of transmission here. 8000 mSec in this setting means that data will be published to your topic from this sensor every 8 seconds. 

 

Below we have listed more acceptable Token Definitions for you to use in the message settings at your own preference.

 

Token Definitions:

  • ::Sensor_ID:: This is the unique identifier of the wireless sensor which triggered the MQTT Topic write currently occurring. Embed it into the message topic or message payload to suite your application.
  • ::Sensor_Type:: Each type of wireless sensor has a type identifier which is simply a number.  embed this token into the sensor message or topic as needed.
  • ::Sensor_Data:: This token will embed the data from the sensor as needed into the Sensor Message payload.  Note that sensor data is a keyed JSON object. 

Step 3. Stream Data on MQTT.fx

Open the MQTT.fx application if you have not already. This application is how we will stream our sensor data. 

 

Begin by clicking the settings icon next to the connect button. 

Most of the settings are automatically generated for you. If it is easier to view, I have provided my settings below:

 

Profile Name: beebotte

Profile Type: MQTT Broker

Broker Address: mqtt.beebotte.com

Broker Port: 1883

Client ID: MQTT_FX_Client

 

 

When you are done editing the settings, select User Credentials as indicated in the image to the right. 

Take the token:token_#### that you copied earlier from your channel on beebotte and paste it for your User Name. 

 

Select Apply.

 

Return back to the main screen. 

1) Make sure beebotte is selected and Connect.

 

2) Then, under the Subscribe tab, type the channel name you created on beebotte followed by a forward slash. 

Note: After the forward slash, you can enter a # sign to subscribe to all topics you have listed under that channel. Otherwise, if you want to subscribe to a specific subtopic, type the name of that subtopic after the forward slash. In this case, my subtopic is this sensor. So I would need to type the MAC Address of the sensor after the forward slash to subscribe to it.

 

 

3) Wait for the sensor data payload to display on your screen. The sensor should send it’s first transmission within seconds of being powered on and connected. If you do not see any data transmissions within a minute, press the reset button and wait again.  

How it looks in MQTT.fx:

Optionally, you can change things such as the interval of transmission by publishing to the settings topic using JSON format. The settings topic will be what you entered in for Step 2 – Client Settings. My settings topic is Josh_Cloud/update, therefore, I can use valid JSON format and publish to Josh_Cloud/update while in MQTT.fx to change various settings.

As you can see on the right, I changed the interval from 5 seconds (5000 ms) to 8 seconds (8000 ms). Therefore under the subscribe tab where we can view incoming sensor data, we will see a new post every 8 seconds. 

Below is a list of keys you can use to change the settings while in MQTT.fx. Remember to make sure each key is in JSON format when you use it.

 

List of Settings Keys and Definitions:

WiFi:

  1. ssid – Updates the SSID of the network the device should connect to. 
  2. ssid_password – The Password which should be used to connect to the network specified by the SSID setting. 
  3. interval – The interval at which the device publishes it’s sensor telemetry to the Broker. 
  4. apSSID – Update the SSID used by the device during config mode.
  5. apPass – The password required to connect to the device’s Soft AP.

MQTT:

  1. host – The URL of the MQTT Broker
  2. host_ip – The IP Address of the MQTT Broker (ignored if host parameter is set)
  3. tls – Boolean Value (0 or 1). Whether or not to utilize TLS when connecting to the MQTT Broker. If this field is set, a root CA must be provided. 
  4. user_name – User Name to utilize for Basic AUTH with Broker. 
  5. password – Password to utilize for Basic AUTH with Broker. 
  6. user_topic_format – Topic which sensor telemetry data should be published to. Supports Token Replace Variables for Sensor ID and Sensor Type.
  7. message_format – Format which sensor data (payload) should be published to the topic. Supports Token Replace Variables for Sensor ID, Sensor Type, and Sensor Data.
  8. settings_update_topic – MQTT Topic that the sensor will subscribe to in order to receive settings update sent by the user. 

Hardware

Factory Reset:

  1. Hold Config button until it goes from flashing green to flashing blue, then release. 
  2. Hold Config button again until it stops flashing blue, then release.
  3. LED will flash multiple colors, wait for this process to complete. 
  4. Once LED is done flashing random colors, it will return to the flashing blue status. 
  5. After 1-4 is complete, the module is successfully factory reset.

LED Status:

  • Flashing Yellow – Sensor is booting up 
  • Flashing Blue – Sensor is in configuration (setup) mode
  • White – Sensor is attempting to connect to the WiFi Network
  • Flashing Green – Sensor has a valid connection to the MQTT Broker
  • Flashing Random Colors – Sensor is applying factory default settings
  • Repeated 3 Red Flash – Sensor is unable to communicate with MQTT Broker, check client credentials
  • Repeated 2 Red Flash – Sensor is unable to connect to WiFi Network

©2019 National Control Devices, LLC

ncd.io

Made in the USA
5 Year Warranty
Free Shipping on orders over $100
Free Shipping on orders over $100

To learn something new, take the path that you took yesterday. ~John Burroughs

*

Log in with your credentials

or    

Forgot your details?

Create Account