Menu
Menu
Menu
WiFi MQTT Temperature/Humidity Sensor User Guide
INTRODUCTION
The NCD IoT Temperature/Humidity 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
Access the Configuration Interface
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.
WiFi Configuration
This WiFi sensor supports connection to 2.4ghz WiFi networks with security types WPA/WPA2/WPA3/WPA2-Enterprise/OPEN
MAC address: Displays the MAC address of the sensor.
Version: Displays current firmware version installed on sensor.
Network: Selectable list of 2.4ghz WiFi networks.
Hidden Network: Manually enter SSID of network to connect to. Do not set this field if you intend to use one of the Networks displayed in the Network field above.
Password: Enter password for WiFi Network the sensor should connect to. Leave blank if this is an unsecured network.
DHCP Enabled: Uncheck if Static IP address configuration will be set in following fields.
Default Gateway: Default Gateway to be used for Static IP configuration.
Subnet Mask: Subnet Mask to be used for Static IP configuration.
Default Gateway: Default Gateway to be used for Static IP configuration.
DNS Primary: DNS Primary to be used for Static IP configuration.
DNS Secondary: DNS Secondary to be used for Static IP configuration.
Static IP: Static IP address to be used for Static IP configuration.
Soft AP Configuration
These settings allow for configuration of the sensor’s Soft AP
Soft AP SSID: SSID to broadcast when in Setup Mode. Leave Blank to broadcast NCD-XXXX.
Soft AP Password: Password to connect to sensor’s soft AP.
Sensor Settings Configuration
These Settings are specific to this sensor
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.
Auto Reboot: The sensor can be configured to automatically reboot on an interval. This way if there is a failure the sensor will do a reboot every so often. This setting is in seconds. So if you wanted the sensor to reboot once per hour you would set this value to 3600. The default value is 0, with this value the sensor will not automatically reboot.
MQTT Configuration
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 the sensor publishes sensor telemetry data to.
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:
{
“data”: {
“temperature_c”: 24.17,
“temperature_f”: 75.5,
“humidity”: 35.83,
“transmission_count”: 0,
“probe_connected”: 1,
“soft_reset_counter”: 0,
“hard_reset_counter”: 0
},
“info”: {
“ip”: “192.168.1.133”,
“ssid”: “Zoe-Wifi”,
“mac”: “48:E7:29:A6:0B:D4”,
“rssi”: -45,
“firmware”: “1.0.10”,
“interval”: 5000,
“name”: “NCD-0BD4”,
“timestamp”: 1731093903
}
}
Custom Message Format Example:
::SSID::/::Sensor_ID:::{::INFO::,::Sensor_Data::}
This would result in a payload with this format:
{
“STARLINK”:{
“F0:08:D1:45:6A:DC”:{
“INFO”:{
“ip”:”192.168.1.146″,
“ssid”:”STARLINK”,
“mac”:”F0:08:D1:45:6A:DC”,
“rssi”:-43,
“firmware”:”1.0.0″,
“interval”:5000,
“name”:”NCD-6ADC”,
“timestamp”:1647529700
},
“DATA”:{
“temperature_c”:22.96,
“temperature_f”:73.33,
“humidity”:39.08,
“transmission_count”:0
“probe_connected”: 1,
“soft_reset_counter”: 0,
“hard_reset_counter”: 0
}
}
}
}
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.
Example:
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.
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.
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 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_Temperature_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.
