Introduction
If you are using the Atrium Gateway, please refer to the Atrium documentation here: Atrium IIoT Gateway User Guide
Wireless Gateway Sensor Messages
Here is a quick overview of the sensor messages identified by the msg.topic in Node-RED:
- modem_mac: This message indicates the unique address of the wireless module connected to the Wireless Gateway node. It is sent when Node-RED is deployed.
- sensor_mode RUN: This message indicates that the device has just powered up or reset and is successfully communicating with the wireless network.
- sensor_data: This is the primary packet sent when a sensor transmits regular operational readings over the wireless network.
- sync: This message indicates that the sensor is in RUN mode but has entered a temporary state where it can receive new configurations (Configuration Mode). The sensor sends a sync message upon booting (after the RUN and sensor_data messages) and automatically once an hour to check in.
Sensor Behavior
The configuration process allows users to change sensor settings using the Node-RED platform. Since most NCD sensors are designed for battery-powered use, their typical operational cycle is as follows:
- Wake Up: The sensor wakes up at your user-defined interval.
- Process: It reads and processes field variables (such as temperature, AC current, or vibration).
- Transmit: It wirelessly sends that data to the Gateway or Modem.
- Sleep: The sensor enters a low-power sleep mode to preserve battery life until the next scheduled interval.
This loop repeats indefinitely, ensuring long-term autonomous operation.
Sync / Configuration Mode
Configuration Mode (or Synchronization Mode) is a temporary state the sensor enters to allow updates to its configurable parameters, such as the Data Transmission Interval, Calibration, Node ID, or Network ID.
- Manual Entry: You can manually place the sensor into this mode by pressing and releasing the RESET button or activating the magnetic switch (if applicable). The device will enter RUN mode, transmit sensor_data (containing the field variable values), and finally enter Configuration Mode (Sync Mode).
- Automatic Entry: By default, the sensor automatically enters Configuration Mode once every hour. On some devices, this hourly sync interval can be customized.
Configuration Mode is temporary and is not intended for long-term operation. The device automatically returns to RUN mode after a successful configuration update, or immediately if no new settings are detected.
Reset Button and Magnetic Switch
Depending on your specific device type, it will feature a physical reset push button, a magnetic switch, or both. We highly recommend consulting the product’s datasheet to easily locate these components on your hardware.
When Should a User Configure Sensor Settings?
- During Initial Setup: When testing a new sensor, it is common to adjust settings to become familiar with the process. A typical starting point is modifying the Data Transmission Interval (how often the sensor reports data) or the Node ID. In this scenario, the user usually has physical access to the sensor.
- During Field Deployment: When a sensor is already mounted in an industrial environment, a user may need to adjust a threshold, calibration value, or transmission interval. In this scenario, the sensor is likely in a remote area where physical access is difficult.
In both cases, users can utilize the sync configuration process described in this guide to update their sensors.
Sync Messages
Sync Check-In Message
When the sensor transmits a sync_check_in message, it signals that the device has temporarily entered Configuration Mode. This message includes essential sensor information along with the exact settings currently active on the device, opening a brief window where it is ready to accept updates. The sensor sends this message during its initial boot sequence and continues to check in automatically once every hour.
The Configuration Window in Node-RED
If you have a Wireless Device node set up in Node-RED with the target sensor’s MAC Address—and the Auto Config, OTF Config, and Wait For Network Formation options are checked—Node-RED will listen for this sync_check_in message. Once received, Node-RED evaluates the sensor’s current settings against your desired settings. If updates are needed, Node-RED automatically transmits the new settings to the sensor.
Sync Acknowledgment Message
sync_acknowledgment is received from the sensor in response to a configuration command from Node-RED. It provides the current sensor status or reports any errors encountered during the update.
Sync End Message
This sync_end indicates the sync process has finished. The sensor reports its new values and resumes normal operations. Users can review the newly applied settings inside the human_readable property.
Sync Response Success Message
This sync_response_success confirms that the sync configuration was completed successfully and displays the specific values and properties applied to the device
Sync Response Skip Message
This sync_response_skip indicates that the settings currently configured in your Node-RED Wireless Device node already match the sensor’s actual settings. Consequently, the library bypasses the synchronization process to avoid redundant updates. If you see this message, it confirms your sensor is already perfectly configured to your desired settings.
Configuration Process Example
When acquiring a new NCD sensor, the initial setup is straightforward: once powered on, you will typically see sensor data in the Node-RED debug window within a few minutes. After this initial test, users often want to learn how to change sensor settings—most commonly, the Data Transmission Interval.
Below is an example of the configuration process you can use as a reference to perform updates on your own sensors.
Step 1: Build the Node-RED Flow
Open Node-RED. Drag and drop a Wireless Device node (located in the NCD group in the left-hand nodes palette) into your workspace. Then, drag and drop a Debug node (the green node) and connect it to the output of the Wireless Device node.
Step 2: Configure the Wireless Node
Double-click the Wireless Device node to open its properties.
Set the Serial Device and Serial Device for Config options to /dev/ttymxc2 if you are using an NCD Gateway (if using a Modem, select the corresponding config node).
Locate the MAC Address property and enter the MAC Address of your target sensor (found on the enclosure sticker). Alternatively, click the magnifying glass icon to select it from a list of discovered devices.
If the Sensor Type does not automatically populate when you select the MAC Address, select your specific sensor type from the dropdown menu.
Check the following three boxes. This allows the device to automatically pick up configuration changes during its next sync process:
- Auto Config: Tells Node-RED you want to actively configure the sensor using this node.
- OTF Config (On-The-Fly): Enables automatic configuration. The updates will be applied the very next time the sensor transmits a sync message.
- Wait for Network Formation: We recommend leaving this enabled so the wireless network has time to fully stabilize before sending configuration data.
Step 5: Select the Parameter to Modify
Scroll down through the node properties to view all available sensor settings. For this example, we will change the Node ID.
The Node ID is a custom, user-defined identifier (ranging from 0 to 255) used to easily distinguish a specific sensor within a network. By default, this value is 0.
To configure this, scroll down to the Node ID and Delay property and check the “Active” checkbox. This tells Node-RED that this specific parameter needs to be updated.
Step 6: Enter the New Value
Change the Node ID value to 12.
Step 7: Save Node Settings
Scroll up to the top of the properties window and click the red Done button to close the Wireless Device node.
Step 8: Deploy the Flow
Click the red Deploy button in the top right corner of the Node-RED interface to apply the flow updates.
Step 9: Trigger or Wait a Sync Message
If sensor is in remote location, wait for next sync transmission, sensor automatically transmit it every hour.
To speed up the process so you do not have to wait up to an hour for the automatic sync, press the physical RESET button on your sensor. You will see a series of messages in the debug window as the sensor boots: modem_mac, RUN, sensor_data, and finally sync_check_in.
Step 10: Automatic Configuration
From here, the process is fully automatic.
Once Node-RED receives the sync_check_in message, it compares the sensor’s current Node ID (0) with your new desired Node ID (12). Because they do not match, Node-RED automatically sends a master command to update the device. The sensor will respond with a sync_acknowledgment, followed by a sync_end, and finally a sync_response_success message indicating the process is complete.
Step 11: Verify the Updates
After the sync configuration finishes, you can verify the new settings by expanding the sync_end message in the Node-RED debug window. Look under the human_readable property to see the active configurations. Your Node ID will now correctly display as 12.
Reset Settings to Factory
A Factory Reset will revert all custom user configurations back to the original default settings from the factory.
Please refer to your specific sensor’s user manual for the exact physical steps required to perform a factory reset on your hardware.