The NCD IoT Push Notification WiFi Sensor for MQTT was developed for industrial applications where WiFi is available. Great care was taken to ensure this device is easy to configure and use so even IoT beginners can set it up. This guide will thoroughly explain the setup and initial use of the entire line of WiFi Sensors for use with MQTT.
IoT Sensor Setup for MQTT
This section will demonstrate how to configure the NCD IoT WiFi Sensor for connection to your MQTT Broker
By default the Sensor will ship with factory default settings. This means as soon as it is powered on it will be in Setup Mode indicated by a Blue Flashing LED. In Setup Mode the sensor will appear as a WiFi Network you can connect to from you Computer, Phone, or Tablet. In the image to the right you will see the network NCD-6ADC. This is the sensor. The last 4 characters in the SSID will be unique to the sensor(6ADC in this case which is the last 2 bytes of the sensor’s Mac address).
Connect to this network. Once prompted enter the default Soft AP password of NCDBeast.
Once connected to the Sensor’s Soft AP network open your web browser(Chrome, Firefox, or Safari is recommended) and enter 192.168.0.1 this should open the sensor’s web interface for configuration.
Report Interval: The interval at which to publish sensor telemetry messages to the MQTT Broker. This settings is in milliseconds. 5000 would be an interval of 5 seconds. It is not recommended to set this setting below 50 milliseconds. Set Report Interval to 0 to disable reporting on interval.
Operation Mode: This device can be used in two different modes. A Pulse Counter mode which would be utilized to count the number of closures which have occurred since the last power on of the Push Notification device, or Push Notification mode where transmissions are sent immediately when input status changes. To utilize the device in Pulse Counter mode set the Operation Mode setting to 2. To utilize the device in Push Notification mode set the Operation Mode setting to 1.
Report Count: When in Pulse Counter mode this setting determines how often the device reports its count. For instance if this setting is set to 100 then the device will publish a message to the MQTT Broker after 100 pulses have occurred, again after 200 pulses, etc. It should be noted this does not disable the Report Interval however, the device will still report telemetry based on teh Report Interval setting as well.
These Settings configure how the sensor connects to the MQTT Broker, What format sensor data is published to the broker, what topic telemetry is published to, and what topic is subscribed to for remote sensor configuration.
MQTT Broker: The URL or IP address of the MQTT Broker to connect to.
Broker Port: The Port to establish connection to the Broker on. Typically 1883 or 8883.
Client ID: The MQTT Client ID to use when establishing connection to the MQTT Broker.
Username: The username used to authenticate connection to the MQTT Broker.
Password: The password used to authenticate connection to the MQTT Broker.
TLS Enabled: Check this box if the MQTT Broker requires TLS authentication.
Root Certificate: Upload Root Cert from Broker for TLS authentication.
Private Key: Upload Private Key from Broker for TLS authentication.
Device Cert: Upload Device Certificate from Broker for TLS authentication.
Settings Topic: The sensor will subscribe to this topic upon connection to the MQTT Broker. The sensor will evaluate messages published to this topic and will apply settings accordingly.
Message Format: This field allows token replacement to format sensor data as needed for different applications. This applies to message payloads published. Token format is covered in the following section. If this field is left blank the message will be published in the default format explained in the following section.
Topic Format: This field allows token replacement to format the topic which the sensor publishes sensor telemetry data to.
Message Format/Token Format
We have implemented a token replace system for MQTT topics and message payloads in order to facility compatibility with numerous cloud based systems which implement MQTT. This means you can embed information about the gateway, the device reporting through it, or the data coming from the device into the topics and message payloads. This is a very powerful feature of the MQTT Gateway.
Message Format: Token based formatting for the message payload sent when the sensor publishes to the MQTT Broker. Supported tokens are:
::Sensor_ID:: Variable Type: String This token, when entered in Message format, will be replaced with the MAC address of the sensor.
::Sensor_Data:: Variable Type: JSON Object This token, when entered in the message format, will be replaced with the telemetry data of the sensor readings.
::SSID:: Variable Type: String This token, when entered in the message format, will be replaced with the SSID of the WiFi network the sensor is configured to connect to.
::INFO:: Variable Type: JSON Object This token, when entered in the message format, will be replaced with all info about the sensor.
If the Message Format is left blank the message payload will contain the sensor data and info in a JSON object. Here is an example of a message published by the sensor with the Message Format field left blank:
Custom Message Format Example:
This would result in a payload with this format:
Topic Format Token Based formatting of the Publish topic used for sending telemetry to the MQTT Broker. Supported Tokens are:
::Sensor_ID:: Variable Type: String This token, when entered in Topic format, will be replaced with the MAC address of the sensor.
Token Format entry: /sensors/::Sensor_ID::
Result topic published to: /sensors/F0:08:D1:45:6A:DC
There are two LED’s on on the sensor. One is a solid red LED which will illuminate at all times when the sensor is supplied with power. The second LED is an RGB LED which is used to indicate the status of the sensor. Status states of the LED are:
Flashing Green Sensor has established connection to WiFi and MQTT broker. All systems nominal.
Solid White Sensor has established connection to the WiFi network but has not established connection with the MQTT Broker.
Flashing White Sensor is attempting to establish connection to the WiFi network.
Flashing Blue Sensor is in configuration mode and is broadcasting WiFi Soft AP.
Flashing Yellow Sensor is booting
Flashing Red Sensor failed to connect/authenticate with MQTT Broker.
Flashing Random Colors Sensor is applying factory default settings.
Enter Configuration Mode
The sensor can be forced into configuration mode at any time. This will force the sensor to disconnect from any WiFi network it is currently connected to, then it will begin broadcasting a Soft AP WiFi network that can be connected to by the user. To enter this configuration mode simply open the lid of the sensor and then press the CFG Button. Once the LED is flashing Blue search for WiFi networks from your computer, smart phone, or tablet. The sensor should appear as a WiFi network with and SSID of the format NCD-XXXX with XXXX being the last 4 digits of the sensor’s MAC address.
Factory Reset Recovery
The sensor can be factory reset at any time. Keep in mind any settings entered in the sensor will be lost and after reboot the sensor will be in Configuration Mode. To factory reset the sensor first enter Configuration Mode, then press and hold the CFG Button until the LED begins flashing random colors, now release the CFG Button. The sensor will now reboot and is now factory reset.
The sensor must be supplied with power at all times.
Power supply input connector is 2.1mm Barrel(Center Pin Positive)
Input voltage range: 5-24VDC(12VDC nominal)
Accessing the Web Interface for Configuration of settings
The Configuration Interface is accessed in two different ways depending on the state of the sensor.
If the sensor is currently connected to your WiFi network and you are also on that WiFi network you can access the web interface by opening your browser(Chrome, Firefox, or Safari is recommended) and entering ncd-XXXX.local with XXXX being replaced by the last 4 digits of the Sensor’s MAC address.
If the sensor is in configuration mode(Flashing Blue LED) then connect to the sensor’s Soft AP WiFi network, then open your web browser(Chrome, Firefox, or Safari is recommended) and enter 192.168.0.1
It may be desired, from time to time, to update the firmware on the sensor due to feature additions or bug fixes. This firmware update process requires that you have access to the sensor’s web interface as covered in the Accessing the Web Interface for Configuration of settings section above.
Start by downloading the firmware and data files to your computer. To do this open your browser and enter: https://github.com/ncd-io/WiFi_MQTT_Current_Monitor_Firmware On this page click the Code dropdown, then click Download ZIP. On your computer extract that zip folder and make note of the folder’s location on your computer. Inside this folder you may see multiple firmware version folders, each of which will contain a firmware.bin and spiffs.bin folder which correspond to that version of firmware.
To access the web interface for firmware update determine the URL to access the controller, either 192.168.0.1/update in configuration mode or ncd.XXXX.local/update if accessing over a WiFi network. The update interface will appear as shown.
Here we can upload the firmware.bin and spiffs.bin files for the desired firmware version to the device.
It is typically recommended to upload the firmware first, then upload spiffs. Keep in mind after the firmware file is uploaded the sensor will still run the settings it has currently, only if/when the spiffs file is uploaded will the settings be reset to factory defaults.
To upload the firmware.bin make sure Firmware is selected, then click Choose File, through the file browser that appears select the firmware.bin file for the firmware version you wish to apply. A progress bar will appear indicating the update state. Once complete it should say OTA Success and the device will reboot. If it reboots and re-establishes connection to the network(Solid White or Flashing Green) then you can proceed to click the Back Button.
Next you will upload the spiffs.bin file. Select FileSystem, then through the file browser that appears select the spiffs.bin file for the firmware version you wish to apply. After this progress is complete you will notice the sensor will reboot and will now be in configuration mode as it is now in factory default settings. This concludes the firmware update process.
The sensor has a built in web interface Status page where it is possible to view all relevant information about the device. If the Sensor is connected to a network ensure your computer/phone or tablet are connected to that page, then in your web browser enter the sensor’s local name URL followed by /Status(for example NCD-6ADC.local/Status). If the sensor is in configuration mode(blinking Blue LED) then ensure you are connected to the Sensor’s WiFi Soft AP network and in your browser enter 192.168.0.1/Status.