How it Works
B+B SmartWorx
Loading...
SmartSwarm 300
User Manual
146 pgs7.72 Mb0

B+B SmartWorx SmartSwarm 300 User Manual

Download
SmartSwarm 300 Series
User Manual
WWW.INFOPULSAS.LT / info@infopulsas.lt
Advantech B+B SmartWorx Americas
707 Dayton Road
Ottawa, IL 61350 USA
Phone (815) 433-5100
Fax (815) 433-5105
Advantech B+B SmartWorx European Headquarters
Westlink Commercial Park
Oranmore, Co. Galway, Ireland
Phone +353 91-792444
Fax +353 91-792445
www.advantech-bb.com
support@advantech-bb.com
Document: SmartSwarm_300_R1_3416.docx
2
CONTEN T S
List of Tables .................................................................................................................................................................. 7
1. Introduction ............................................................................................................................................................. 10
1.1 Why Enrich Data? .............................................................................................................................................. 11
1.2 Why Aggregate Data? ........................................................................................................................................ 11
1.3 Why Filter Data? ................................................................................................................................................ 11
1.4 Sampling Theory ................................................................................................................................................ 11
2. Document Structure ................................................................................................................................................ 12
3. Example Workflow ................................................................................................................................................... 15
3.1 Connect Your Hardware .................................................................................................................................... 15
3.2 Configure Your Device’s Connectivity to SmartWorx Hub ................................................................................. 15
3.3 Configure the Modbus Interface ....................................................................................................................... 18
3.4 Configure the MQTT interface ........................................................................................................................... 20
3.5 Build Your Slave Maps ....................................................................................................................................... 21
3.5.1 Discover Your Slaves ................................................................................................................................... 22
3.5.2 Create/Import Your Slaves .......................................................................................................................... 23
3.5.3 Export Slave Maps ...................................................................................................................................... 28
3.6 Configure Rules and Topics ................................................................................................................................ 28
3.7 Verify Your Data Flow ........................................................................................................................................ 31
3.8 Optimize Your System ........................................................................................................................................ 31
4. Connect Your Hardware .......................................................................................................................................... 33
4.1 Mounting the device .......................................................................................................................................... 33
4.1.1 Installing/Removing from a DIN Rail ........................................................................................................... 33
3
4.2 Power Connector PWR ...................................................................................................................................... 34
4.3 Ethernet Port (ETH0 and ETH1) ......................................................................................................................... 34
4.4 Cellular Connection............................................................................................................................................ 36
4.4.1 Antenna Connectors ANT, DIV and GPS...................................................................................................... 36
4.4.2 SIM Card Reader ......................................................................................................................................... 37
4.5 RS-232 RS-485 Serial Interface - Connection to Modbus Network .................................................................... 38
4.5.1 Wire RS-485 connection ............................................................................................................................. 38
4.5.2 RS-232 Connection ..................................................................................................................................... 39
4.5.3 Wire RS-485 and RS-422 connection .......................................................................................................... 40
4.6 MicroSD Card Reader ......................................................................................................................................... 41
4.7 USB Port ............................................................................................................................................................. 41
4.8 I/O Port .............................................................................................................................................................. 41
4.9 LEDs ................................................................................................................................................................... 41
5. Configure Connectivity to SmartWorx Hub ............................................................................................................. 42
5.1 Step 1 - Connect to Local Webserver ................................................................................................................. 43
5.2 Step 2 - Configure the Cellular APN details ....................................................................................................... 43
5.3 Step 3 - Verify the Secure Connection with SmartWorx Hub ............................................................................ 43
5.4 Step 4 - Verify That Your Device is Available on SmartWorx Hub ..................................................................... 43
5.5 Factory Defaults ................................................................................................................................................. 44
6. SmartSwarm 351 on SmartWorx Hub...................................................................................................................... 45
6.1 Device Management .......................................................................................................................................... 45
6.2 The Modbus-to-MQTT application .................................................................................................................... 46
7. Configure the Modbus Interface ............................................................................................................................. 47
8. Configure the MQTT interface ................................................................................................................................ 48
9. Slave Maps and Enrichment .................................................................................................................................... 53
9.1 Discover ............................................................................................................................................................. 56
4
9.2 Create an Empty Slave Map ............................................................................................................................... 57
9.3 Import a Slave Map ............................................................................................................................................ 58
9.4 Editing Slaves ..................................................................................................................................................... 58
9.4.1 Understanding Your Slave Editor ................................................................................................................ 59
9.4.2 Meta Data ................................................................................................................................................... 60
9.4.3 Registers ..................................................................................................................................................... 61
9.4.4 Data Types .................................................................................................................................................. 68
9.4.5 Adding Registers ......................................................................................................................................... 70
9.4.6 Editing Registers ......................................................................................................................................... 70
9.4.7 Deleting Registers ....................................................................................................................................... 72
10. Rules and Topics .................................................................................................................................................... 73
10.1 Introduction ..................................................................................................................................................... 73
10.2 Events (WHEN) ................................................................................................................................................. 75
10.2.1 Read .......................................................................................................................................................... 76
10.2.2 Change ...................................................................................................................................................... 77
10.2.3 Delta ......................................................................................................................................................... 80
10.2.4 High Threshold .......................................................................................................................................... 82
10.2.5 Low Threshold .......................................................................................................................................... 84
10.2.6 High Rate .................................................................................................................................................. 86
10.2.7 Low Rate ................................................................................................................................................... 89
10.2.8 Scheduled ................................................................................................................................................. 91
10.2.9 Global Read ............................................................................................................................................... 92
10.2.10 Global Change ......................................................................................................................................... 92
10.3 Payloads (WHAT) ............................................................................................................................................. 93
10.3.1 Payload Examples ..................................................................................................................................... 94
10.4 Topics (HOW) ................................................................................................................................................. 102
5
10.4.1 Custom Topic Space ................................................................................................................................ 103
10.4.2 Default Topic Space ................................................................................................................................ 104
11. Verify your Data Flow .......................................................................................................................................... 107
12. Other Documentation .......................................................................................................................................... 109
13. Appendix 1 - Hardware Ratings ........................................................................................................................... 109
13.1 Environmental ............................................................................................................................................... 109
13.2 Type Tests ...................................................................................................................................................... 110
13.3 Cellular Module ............................................................................................................................................. 110
13.4 Other Technical Parameters .......................................................................................................................... 111
14. Appendix 2 - General Settings ............................................................................................................................. 112
14.1 Configurable Items......................................................................................................................................... 112
14.1.1 Settings ................................................................................................................................................... 112
14.1.2 DHCP ....................................................................................................................................................... 113
14.1.3 OpenVPN ................................................................................................................................................ 114
14.1.4 NTP Client ............................................................................................................................................... 117
14.2 Non-Configurable items ................................................................................................................................. 117
14.2.1 Firewall ................................................................................................................................................... 117
15. Appendix 3 - Diagnostics and Troubleshooting ................................................................................................... 119
15.1 The Local Web Interface ................................................................................................................................ 119
15.1.1 Home ...................................................................................................................................................... 120
15.1.2 Settings ................................................................................................................................................... 120
15.1.3 Troubleshooting ...................................................................................................................................... 120
15.1.4 Hub Client ............................................................................................................................................... 122
15.1.5 Cellular .................................................................................................................................................... 122
15.1.6 Logs ......................................................................................................................................................... 123
15.1.7 Modbus ................................................................................................................................................... 123
6
15.1.8 Debug and Agents ................................................................................................................................... 124
15.1.9 TSED ........................................................................................................................................................ 126
16. Appendix 4 - Slave Map Formats ......................................................................................................................... 128
16.1 Excel ............................................................................................................................................................... 128
16.2 JSON ............................................................................................................................................................... 131
17. Appendix 5 - Background Information ................................................................................................................. 133
17.1 Modbus Background ...................................................................................................................................... 133
17.2 MQTT Background ......................................................................................................................................... 136
18. Appendix 6 – Dashboards .................................................................................................................................... 139
18.1 Node-RED ....................................................................................................................................................... 139
Advantech B+B SmartWorx Technical Support ......................................................................................................... 146
LIST O F TABLES
Table 1. Example Modbus Slave Datasheet for Discrete Inputs .................................................................................. 25
Table 2. Example Excel sheet data derived from Slave Datasheet (Inputs) ................................................................. 25
Table 3. Example Modbus Slave Datasheet for Input Registers .................................................................................. 26
Table 4. Example Excel sheet data derived from Slave Datasheet (Input Registers) ................................................... 27
Table 5. Example Excel sheet Meta Data ..................................................................................................................... 27
Table 6. Power connector ............................................................................................................................................ 34
Table 7. Ethernet Ports ................................................................................................................................................ 35
Table 8. Ethernet Port Usage ....................................................................................................................................... 36
Table 9. RS-485 pinout ................................................................................................................................................. 39
Table 10. RS-232 pinout ............................................................................................................................................... 40
7
Table 11. LED indicators .............................................................................................................................................. 42
Table 12. The Modbus to MQTT application ............................................................................................................... 47
Table 13. Modbus Interface ......................................................................................................................................... 48
Table 14. MQTT Interface ............................................................................................................................................ 51
Table 15. MQTT Interface ............................................................................................................................................ 52
Table 16. Slave Map options ........................................................................................................................................ 55
Table 17. Editing Slave Maps ....................................................................................................................................... 59
Table 18. Editing Slave Maps - Rules ........................................................................................................................... 60
Table 19. Meta Data tab .............................................................................................................................................. 61
Table 20. Register Types .............................................................................................................................................. 61
Table 21. Input Register and Holding Register editable fields ..................................................................................... 65
Table 22. Discrete Input and Coil editable fields ......................................................................................................... 68
Table 23. Data Types and Field Values ........................................................................................................................ 69
Table 24. Rules and Topics fields ................................................................................................................................. 74
Table 25. Event Types .................................................................................................................................................. 75
Table 26. Events and Data Types: cross-reference ...................................................................................................... 76
Table 27. Read Event ................................................................................................................................................... 76
Table 28. Change Event ............................................................................................................................................... 77
Table 29. Delta Event ................................................................................................................................................... 81
Table 30. High Threshold Event ................................................................................................................................... 82
Table 31. Low Threshold Event .................................................................................................................................... 84
Table 32. High Rate Event ............................................................................................................................................ 86
Table 33. Low Rate Event ............................................................................................................................................ 90
Table 34. Global Read Event ........................................................................................................................................ 92
Table 35. Global Change Event .................................................................................................................................... 92
Table 36. Payload options............................................................................................................................................ 93
8
Table 37. Event / Payload matrix ................................................................................................................................. 93
Table 38. The Default Topic ....................................................................................................................................... 104
Table 39. Default Topic example ............................................................................................................................... 105
Table 40. Verify your Data Flow ................................................................................................................................ 108
Table 41. Other Documentation ................................................................................................................................ 109
Table 42. Environmental ............................................................................................................................................ 110
Table 43 Type Tests ................................................................................................................................................... 110
Table 44. Type Tests .................................................................................................................................................. 110
Table 45. Cellular Module .......................................................................................................................................... 111
Table 46. Technical Parameters ................................................................................................................................. 111
Table 47. OpenVPN fields .......................................................................................................................................... 116
Table 48. Firewall rules .............................................................................................................................................. 118
Table 49. Excel Sheet tabs ......................................................................................................................................... 128
Table 50. Excel sheet, Address tab ............................................................................................................................ 129
Table 51. Supported Modbus commands .................................................................................................................. 134
Table 52. Supported Data Types ................................................................................................................................ 135
Table 53. Examples for subscribing to different topics in a hierarchical name space .............................................. 137
Table 54. Node Red fields for Gauge node ................................................................................................................ 143
Table 55. Node Red fields for Chart node.................................................................................................................. 144
9
1. INT R O D UCTION
SmartSwarm 351 is an IoT Gateway appliance powered by B+B SmartWorx SmartSwarm technology. It is intended for use in applications where users need to pass data from legacy Modbus RTU installations into an IoT platform or application, but who can’t tolerate any disruption to the Modbus system in order to achieve this.
Using the notion of protocol eavesdropping to non-intrusively extract base data from the messages being sent between the existing master and slave devices in a Modbus network, it leverages the feature-rich data enrichment, filtering and aggregation capabilities of the SmartSwarm software stack to produce event-driven, semantically­searchable, contextualized information, which is passed to the enterprise using the widely-supported MQTT protocol.
10
1.1 W H Y E NRICH DATA?
Modbus data is impossible to interpret without very detailed knowledge of the devices producing the data and the sensors connected to them. Anyone looking at Modbus data can see that the value of unit 31, register 40075 is 2397 – but has no way to interpret this data without prior knowledge of its significance. This is not the way that IoT systems operate. One of the core concepts of an IoT architecture is that systems can request information based upon a semantic model – a user can ask for information about temperatures in the rooms of the buildings they manage, and will receive responses in a form which is self-declaring, for example B+B/Ottawa/Conference Room{temperature: 72 degF}. This conversion of raw, unintelligible register values into interpretable information is a fundamental operation in the integration of legacy devices into an IoT architecture.
1.2 W H Y AGGREGATE DATA?
Modbus is a poll-response protocol. The master device follows a scan pattern which constantly updates an internal database with the most recently recovered data in a particular unit, whether that data has changed or not. Once we start to convert this data into information that is to be sent over, for example, a cellular data link, it becomes important to regulate to flow of data to that which has value. The fact that the temperature in a room is the same as it was five seconds ago is of little value, and we can make significant savings in data transmission and upstream processing costs if we send aggregated data instead -- for example, the max, min and mean temperature each hour.
1.3 WH Y FILTER DATA?
Aggregating data is fine, of course, but there are certain events that we would want to be informed of on an urgent basis. Examples would include a temperature that has exceeded a threshold, has an excessive rate of change, or has moved by more than a deadband from the last transmitted value. This is the purpose of filtering. A series of event triggers may be configured and the recovered data compared against these triggers with any match resulting in an immediate action.
1.4 S A M P L ING THEORY
It is important to bear in mind that the SmartSwarm 351 is only eavesdropping on the Modbus network. It cannot influence the Modbus Slaves, or the Modbus Master in any way. Effectively, the SmartSwarm device is two levels removed from the actual process signals in which you may be interested. This is especially important if the original signal is analog.
The following example shows a “fast” analog signal that has some high frequency components: The signal is first digitized by a Modbus Slave, at a certain sampling rate, and the quantized values are saved in an Input Register:
This register is then polled by the Modbus Master, at another (slower) sampling rate, and the response values are used by a SCADA system:
The SmartSwarm 351 eavesdrops on the communication between the Modbus Master and Slave. It can only observe the same data that the Modbus Master observes. If the Slave sampling rate and/or the Master sampling rate is not fast enough to capture an event of interest, then that event will be missed.
11
Connect your Hardware
Configure your device’s connectivity to
Configure the Modbus interface
Configure the MQTT interface
Build your Slave Maps
Configure Rules and Topics
Verify your Data Flow
Optimize your System
2. DOCUM E N T STRUCTURE
This document is organized in accordance with the following flow.
12
13
The next chapter walks through an example workflow. This workflow is intended to be an example of how to get your Modbus data publishing to an MQTT server quickly, without getting stuck in the details.
The remaining chapters will provide the necessary details.
14
3. EXAMP L E WORKFLOW
In this section we will walk through an example workflow.
3.1 C O N NECT YOUR HARDWARE
First, ensure that your hardware is physically connected.
Connect your antennae to the ANT and DIV connectors.
Insert a valid and data-provisioned SIM card into SIM 1. In this example we will assume that your outbound WAN connection will be using a cellular connection. If this is not the case, and your uplink is solely via Ethernet, then it is not necessary to connect antennae or install a SIM.
In this example, we will connect to an RS-485 Modbus network (this will be the typical configuration).
Physically connect your device to your Modbus network, as per the instructions on the quick-start guide, and as described in the hardware section of this manual.
3.2 C O N FIGURE YOUR DEVICE’S CONNE C T I VITY TO SMARTWORX HUB
Use an Ethernet cable to connect your local laptop/desktop computer to your SmartSwarm device’s ETH0 port. The ETH0 port of the device has IP address 192.168.1.1
The ETH0 port of the device is a DHCP server, so it will automatically serve an IP Address in the 192.168.1.x range to your laptop/desktop computer: please ensure your laptop/desktop computer is configured to accept an IP address automatically from a DHCP server.
Open a web-browser, and browse to 192.168.1.1
Select “Settings”->”Cellular (WAN)”, and enter the appropriate APN and network authentication settings for your SIM card. In our example, we only need to enter an APN. Click EXECUTE.
15
That’s all you need to do:
The device will now attempt to (a) make a WAN connection using the cellular network; then (b) make a secure connection to SmartWorx Hub (on hub.bb-smartworx.com).
When (a) is successful, the WAN LED will turn on (yellow).
When (b) is successful, the USR LED will turn on (yellow).
The time it takes for (a) to be successful depends on your cellular network, but you should expect it to be successful within minutes.
If the WAN LED is not turning on you may have entered invalid APN or network credential information for that SIM card.
Please verify that you are using a valid SIM card and valid cellular settings.
When the USR LED is on (yellow), your device has a secure connection to SmartWorx Hub.
The following graphic shows that the WAN and USR LEDs are both on (yellow), and the RS-485 Modbus network is connected.
16
Open a browser page, and login to SmartWorx Hub on https://hub.bb-smartworx.com.
In this example, we assume that (a) you have an account to login with SmartWorx Hub, and (b) you are using the cloud instance of SmartWorx Hub to manage your devices.
17
Go to the “Devices”->”Claim Device” screen to bring your new SmartSwarm Device into your Device farm. Type in your Device’s Device-ID (this is written both on the Device itself and on the box that you took your Device out of) and select ‘Check Device ID’ to check that your device is available to be claimed by you. Assuming that it is,
you may then select “Claim Device”.
Your Device is now available for you to manage.
By selecting the ‘Devices/View Devices’ screen we can see that the device is available, and that it is currently
Online.
3.3 C O N FIGURE THE MODBUS INTERFACE
Select the Device (click the Device ID link).
Now you can navigate to the Modbus-to-MQTT application and modify the application settings.
18
Now configure the Modbus Settings so that they match the actual Modbus configuration of your Modbus network.
Apply the changes.
19
3.4 C O N FIGURE THE MQTT INTERFACE
Select MQTT from the list on the left hand pane and configure your MQTT interface.
We assume that you already have an MQTT broker that you can publish to. In our example we know we have an MQTT broker available at 52.51.11.241, using the default port 1883.
20
If you do not apply transport layer security settings, your data will be published to the MQTT server in plaintext. If you chose not to apply security settings now, please remember to do so later.
In this example we are not configuring any security in the MQTT interface. We recommend that you use “no security” only until you have verified your connection and data-flow.
Once you are confident that your MQTT connection settings are valid, we recommend that you enable TLS and configure a trusted, secure connection between the SmartSwarm device and your MQTT broker.
Remember to Apply your changes.
3.5 B U I L D Y O U R SLAVE MAPS
There are two main ways for you to build your Slave Maps: “Discover” or “Create”.
Both ways are useful, for different reasons. You can safely mix both methods in building your Slave Maps.
21
3.5.1 D I SCOVER YOUR SLAVES
Using the “Discover” option, you can let the SmartSwarm device self-learn the Modbus slave network. Actually, your SmartSwarm device has been self-learning already. Your device has been physically connected to the Modbus network since the beginning of this workflow. The Modbus configuration settings were deployed to the device in an earlier step.
The Device will continuously learn from the actual Modbus data traffic, even after the initial learning period. As the SmartSwarm device is a passive sniffer device, the time it takes for it to learn all of the Modbus slaves and registers is outside of the control of the device. It depends entirely upon how the Modbus Master is configured. We recommend that you initially leave your device running on the Modbus network for a period of time - maybe 10 or 15 minutes. At this time the device will have learned from the Modbus traffic. It is likely that it won’t have learned everything in this amount of time, but it should have learned enough to enable you to carry on to the enrichment steps.
Now go to the “Decoder” screen, and click on “Sync Maps”.
Refresh your SmartWorx Hub screen to see the discovered devices.
22
In our example, only one Slave device has been discovered on the Modbus network.
In this case the discovered slave is at address 1. We will refer to this slave as “Slave 1” later.
Although not shown in this example, you can now edit this slave, and enrich the discovered slave data. We will show some enrichment editing of Slave 1 a little later.
Next we will use the “import” method to get more slave maps into the system.
3.5.2 C R E ATE/IMPORT YOUR SLAVES
Using the “Create” option you can import a pre-prepared, pre-enriched set of Slave data, in either Excel or JSON format.
We provide a number of aids for you to use the “Create” option.
First, you can download templates directly from here using the “Download Templates” option. At the time of
writing we have templates in .xls, .xlsx, and .json formats.
Second, you can create a slave and enter all enrichment for it using the “New Map” option.
Third, you can import a pre-prepared, pre-enriched, set of slave data using the “Load Map” option. When importing slave data you must use one of the template formats provided by “Download Templates”.
23
In our example we are going to load a pre-prepared slave-map from a template file.
To create the pre-prepared slave-map we took the datasheet of a slave device (an Emerson Liebert nFinity UPS), and we populated the Template accordingly.
Here’s an example from the Modbus “Inputs” section of the actual device Datasheet:
24
Table 1. Example Modbus Slave Datasheet for Discrete Inputs
We derived the following “Inputs” Excel sheet information from this datasheet, using the provided Excel template. :
Table 2. Example Excel sheet data derived from Slave Datasheet (Inputs)
25
NOTE that the address field in our template is declared as the offset from the base address of the register type. In our example the device uses the 10,xxx range for its Input Status registers. (Other devices may use 10x,xxx.) So the first IS register (10,001) corresponds to offset 0. Hence the device register 10,003 becomes our IS register 2. Here’s an example of the Modbus “Input Registers” section of the datasheet:
Table 3. Example Modbus Slave Datasheet for Input Registers
We derived the following “Input Registers” Excel sheet information from this Datasheet, using the provided Excel Template:
26
Table 4. Example Excel sheet data derived from Slave Datasheet (Input Registers)
Next, optionally fill in the “Meta” data in the Excel sheet:
Table 5. Example Excel sheet Meta Data
Now, we’re going to import this pre-prepared Excel file into SmartWorx Hub.
We click on “Load Map”, then browse to the prepared Excel file. Select the file, and the Slave Map will be
immediately loaded.
27
Don’t forget to Apply Changes.
3.5.3 E X P O R T SL A VE MAPS
Once you have Slave Maps on your system - whether you created them manually, imported them, or discovered them and subsequently enriched them - you can then export them.
This is very useful if you have many Slave Devices of the same type. You can create (and enrich) one Slave, then export it to a .json format file.
You can edit the file offline (for example, to change the Meta Data, and Slave Address), then re-import it as a new slave.
All previously applied enrichment will be available immediately on your new slave.
When you use the export utility all of your existing slave maps will be exported into a single archive file (.zip), which goes directly into the “downloads” folder defined by your browser.
3.6 C O N FIGURE RULES AND TOPICS
Click on Edit to enrich a slave, and to apply Events, Rules and Topics.
We will now enrich the data in Slave 1.
First, add some Metadata enrichment. Remember to Save when you’re happy with the enrichment.
28
In our example there were some Input Registers discovered on Slave 1 during the “discovery” stage. Go to the Input Registers tab, and enrich the registers.
In our example we’re enriching the slave’s input register data from the slave’s datasheet (an Emerson power
monitoring UPS).
Don’t forget to “Save” as you go.
Now, we’re ready to apply some Rules and Topics. Select the Rules and Topics tab.
The first thing we notice is that the enrichment data we have previously provided has already been applied to this panel.
29
There’s a line entry in this table for every discovered register on this Slave (even for the non-enriched registers). The MQTT Topic has taken custom values, which are derived from the Meta data. You may leave these as-is, or you may override the custom-defaults and define an MQTT topic for every register-rule.
You define an event (“when” a matching data pattern occurs on the Modbus network) in the “Event” column.
You define the payload that will be published (“what” is published when an event occurs) in the “Payload” column.
You define the MQTT topic the payload will be published on (“how” the payload is published when an event occurs) in the “MQTT Topic” and “Default Topic” columns.
In our example we have created only one Event.
We want to know when the Nominal Input Frequency data value changes by 1 percent.
When that change-event occurs, publish the default payload data - that is, publish the Nominal Input Frequency value on this Input Register for this Slave Device.
30
Publish using the defined MQTT Topic “Server_Room/Power_Monitor/Liebert”, but do not also publish on the “Default Topic” (see chapter 10).
Save Rules next: This saves your enrichment and rules to the SmartWorx Hub database. Push Rules now: This applies the entire enrichment, including the defined event rules, to the device.
Your device will now apply the Events rules you have enabled, and it will start filtering the data and publishing data in accordance with the rules that you have defined.
In our example the device will publish the Nominal Input Frequency register value to the MQTT server at address
52.51.11.241, using the MQTT Topic “Server_Room/Power_Monitor/Liebert”, but only when the value of this register has changed by 1% since the last time it was polled on the Modbus network.
3.7 V E R IFY Y OUR DATA FLOW
The checkpoints for your data flow are:
1. You have a good physical connection between the SmartSwarm device and your Modbus network.
2. A secure connection has been established between your SmartSwarm device and SmartWorx Hub.
3. You have correctly configured the Modbus interface on your SmartSwarm device to correspond with your
Modbus network.
a. And you have applied your settings to the Device.
4. You have correctly configured the MQTT interface on your SmartSwarm device so that your device can
establish a connection with a valid MQTT broker.
a. And you have applied your settings to the Device.
5. You have created an Event that will actually trigger, based on matching actual data-conditions on your
Modbus network to the Event rule you have created.
a. And you have saved your enrichment. b. And you have pushed your enrichment to the Device.
When you are satisfied that you have verified all of these checkpoints, it’s a good time to go back over your setup and apply some optimizations.
3.8 O P T I M I ZE Y O UR SYSTEM
Some suggestions for optimizing your system are:
● Revisit your MQTT configuration settings, and enable security.
You have many security options. You will need to read the detailed chapter in this manual regarding MQTT configuration. We recommend that you also read some generally available MQTT security documentation from the OASIS pages (www.mqtt.org). It is important that the MQTT broker you chose to use supports the level of security that you wish to apply.
● Revisit your Slave Map enrichment pages.
You are free to enrich your slaves and slave-registers in any way you find most appropriate to your usage. It’s easy to change and re-apply your enrichment settings at any time. Feel free to prototype different enrichment scenarios until you find one that suits your need.
31
We recommend that you choose appropriate MQTT topics for your Slave registers, which enable ease-of­use for your solution domain. By defining your Topics carefully, you can enable ease-of-consumption of the data.
In some cases, you will want to consume the data on dashboards.
See Appendix 6 in this manual for an example of how to create your own dashboards using a server-side Node RED service.
● Revisit your Slave Map Rules
The data that will be published to your MQTT broker is entirely dependent on the rules that you create. We recommend that you do not enable a Read Rule for every register. The IoT environment for consuming data is not intended to be a real-time replica of your Modbus control network. Publishing every read to every register is not only extremely data-intensive across the entire system, it will also have real cost associated with it. We recommend that you do not enable a Read Rule for every register. The IoT environment for consuming data is not intended to be a real-time replica of your Modbus control network. Publishing every read to every register is not only extremely data-intensive across the entire system, it will also have real cost associated with it (e.g. data usage on cellular networks).
We recommend that you do enable appropriate Event Rules for any interesting or non-normal conditions that you want to keep track of, or be notified about.
We recommend that you do enable appropriate Schedule Rules for any data that you wish to monitor on a regular basis.
Again, it’s best to prototype different scenarios until you find one that suits your need.
It’s very easy to change and modify rules at any time, and to re-apply them in run-time without any
impact to your system.
32
4. CONNEC T Y O U R HARDWARE
4.1 MOUN T ING THE DEVICE
The unit may be mounted in any orientation. It can be simply placed on a flat surface, or it can be DIN rail mounted using the supplied CKD2 holder.
4.1.1 I NSTALLING/REMOVING FROM A D I N RAIL
The CKD2 holder, which is used for mounting the gateway on a DIN rail, should be mounted such that the smaller flange on the holder is at the top when the unit is mounted on a DIN rail.
Default orientation of the CKD2 holder
To insert into a DIN rail, hook the lower (longer) flange into the DIN rail then rotate the top of the unit towards the DIN rail until it clicks into place. To remove from the DIN rail, lightly push the IoT gateway upwards until the top part of the CKD2 holder clears the top of the DIN rail. The top of the gateway can then be pulled away from the DIN rail, which will in turn release the lower DIN connection point.
33
Pin
Ident
Description
1
GND(-)
Negative pole of DC supply voltage
2
VCC(+)
Positive pole of DC supply voltage (+10 to +60 V DC)
Circuit example:
4.2 P OWER CONN E CTOR PWR
Panel socket 2-pin
Table 6. Power connector
The unit accepts the connection of power supplies in the range +10 V to +60 V DC. Protection against reverse polarity connection is built into the device.
4.3 E T H E RNET PORT (ETH0 AND ETH1)
Panel socket RJ45.
34
PIN
Signal Mark
Description
Data Flow Direction
1
TXD+
Transmit Data – positive pole
Input/Output
2
TXD-
Transmit Data – negative pole
Input/Output
3
RXD+
Receive Data – positive pole
Input/Output
4
— — —
5
— — —
6
RXD-
Receive Data – negative pole
Input/Output
7
— — —
8
— — —
Table 7. Ethernet Ports
Ethernet cables plug directly into the sockets. Always use a cable with an operational locking tab to avoid intermittent communications problems.
The insulation strength is up to 1.5 kV.
By default, ETH0 is set up as a DHCP server and is intended for the connection of diagnostic devices. ETH1 is set up as a DHCP client, and may be used as an uplink for MQTT data being sent from the device.
35
Connector
Purpose
Default Setting
ETH0
LAN port (default) Connect your laptop or PC to this port to get a local web-server for device configuration and diagnostics.
DHCP Server IP Address:
192.168.1.1 NetMask:
255.255.255.0
ETH1
WAN port (default) Connect this port to your WAN to allow the device to obtain access to the remote device management service, SmartWorx Hub, over Ethernet.
DHCP Client The device will automatically obtain an IP address from your DHCP server, if you have a DHCP server provisioned to supply one.
Table 8. Ethernet Port Usage
If a connection exists via ETH1, it will take priority over a cellular connection for northbound data.
4.4 C E L L U L AR CONNECTION
If your device is cellular-enabled, you will need to attach the relevant antennae and install a data-enabled SIM card before you can use cellular connections.
4.4.1 A NTENNA CONNECTORS ANT, DIV AND G PS
If cellular communications are required, main and diversity antennas must be connected to the IoT Gateway via SMA connectors on the front panel. The ANT connector is used to connect the main antenna of the device. A second, diversity antenna, should be connected to the second cellular antenna connector (DIV) in order to improve the gateway radio performance at low signal strength, or in areas where the RF environment is constantly changing. (For example, near a road.) The third connector (GPS) is intended for GPS antenna connection and is not currently used by the SmartSwarm 351
The device cannot connect to cellular networks without an appropriate antenna connected to ANT
Antennae are connected by screwing to the SMA connector on the front panel of the IoT Gateway.
36
4.4.2 S IM C ARD READER
Two SIM card readers for 3 V and 1.8 V SIM cards are placed on the rear panel of the device. Only the first of these (SIM1) is currently supported by SmartSwarm 351. In order to operate on a cellular network it is necessary to insert an activated, data enabled SIM card with an unblocked PIN code.
4.4.2.1 INSERTING/REPLACING A SIM CARD:
Before inserting or removing the SIM card disconnect the device from power supply
Using a plastic opening tool, or your fingernail, press the SIM card into its slot until you hear a click.
To remove a SIM card press the SIM into the unit until you hear a click. After the click, release the card and it will pop out of its slot.
Remove the SIM card and push any other SIM card into the slot until it clicks in place.
Only SIM1 is supported in the initial release of SmartSwarm 351
37
RS-485 – Pinout
Pin
Signal
Description
Direction
1
Tx-
Transmit - (Do not connect)
Output
4.5 RS-232 RS- 4 8 5 SERIAL INTERFA CE - CONNECTION T O M OD BUS N ET W O RK
These interfaces are physically connected on five-pin and four-pin terminal block connectors on the front panel. The insulation strength is up to 2.5 kV. Attention, connectors are not isolated from each other and share a common ground pin. The RS-485 ground connection should be made to the RS-232 GND pin.
4.5.1 WIR E R S - 4 8 5 CONNECTION
RS-485 connector (4 pin)
38
2
Tx+
Transmit + (Do not connect)
Output
3
Rx-
Receive -
Input
4
Rx+
Receive +
Input
The RS-485 port provides a transmitter and a receiver. If you connect the transmitter to your Modbus network, you risk interfering with the Modbus communication should the transmitter ever become enabled by software. On this device, the transmitter is not enabled. Nevertheless, we recommend that you do not connect pins 1 and 2.
CONNECT ONLY TO THE RECEIVER, AS SHOWN ABOVE.
PIN
Signal
Direction
1
CTS
Output
Table 9. RS-485 pinout
NOTE: this device will only operate in Passive (receive-only) mode. It is not possible to configure it as a Modbus Master, or for it to transmit on the Modbus network.
4.5.2 R S - 2 3 2 CONNECTION
RS-232 connector (5 pin)
39
2
RTS
Input
3
GND
—
4
RXD
Input
5
TXD
Output
Table 10. RS-232 pinout
In order to operate on RS-232 based Modbus RTU networks, it is necessary to arrange for the SmartSwarm 351 to receive information from both the RS-232 Transmit and Receive signals, in order that it can monitor both the Modbus commands and the corresponding replies.
RS-232 data taps, B+B part number 9PCDT (9 pin) or 25PCDT (25 pin) are available for this purpose. The following description assumes the use of the 9 pin version.
The device should be inserted into the RS-232 communications line between the Modbus master and slave. Switches 1 & 2 should both be ON in order to pass both Rx and Tx data. In addition, switch 3 should be ON and switch 4 OFF. Connections should then be made between the data tap pin 5 and the SmartSwarm RS-232 connector pin 3, and the data tap pin 2 and the SmartSwarm RS-232 connector pin 4. No other connections are necessary.
The following image shows the correct configuration of DIP switches:
4.5.3 WIR E R S - 4 8 5 AND RS-422 CONNECTIO N
Please read Section 3.3.3.2 of the “Modbus Serial Line Protocol and Implementation Guide” (Modbus_over_serial_line_V1_02.pdf), which covers “Compatibility between 4-Wire and 2-Wire cabling” (see
http://www.modbus.org/docs/Modbus_over_serial_line_V1_02.pdf ). The RS-485 interface of the SmartSwarm
351 is effectively a 2-wire interface. In order to connect a 4-wire system to the device, you have to short the Transmit and Receive pairs together.
40
In some situations this is not an issue, but there are some risks with this approach.
● The SCADA master will see a repeat of its command, followed by the slave reply, and this
combination may be rejected as invalid depending upon the characteristics of the SCADA master driver.
● Similarly, the Modbus slave will see its own reply and may try to interpret this as a new
command and subsequently fail to recognize a valid command being sent by the host. For this reason, it is strongly recommended that if an alternative tap-in point exists which operates at either RS-232 or 2-wire RS-485 levels, this should be used.
LED
Color
State
Description
PWR
Green
Off
No power
On
Device is booting
Blinking
Device is in normal operating mode
Fast Blinking
Device is updating firmware. Do not power off
USR
Yellow
Off
The device does not have a working session established with SmartWorx Hub
On
The device has a working secure session established with SmartWorx Hub
PoE
Not Used
Not Used
Not Used
DAT
Red Off
There is no communication on the cellular interface at this moment
Blinking
There is communication in progress on the cellular interface
If there is no alternative to tapping into a 4-wire circuit, then the safest way is to use an RS-232 data tap as outlined above, and connect an RS-232 to RS-422 (or 4-wire RS-485 as appropriate) converter on either side of the data tap. Advantech B+B SmartWorx offers a range of such converters. Please determine the most suitable combination for your application.
4.6 M I C R O SD C ARD READER
The MicroSD card socket, located on the rear panel of the unit, is currently unused by SmartSwarm 351
4.7 U S B P ORT
The USB port, located on the front panel, is currently unused by SmartSwarm 351.
4.8 I / O P O R T
The I/O port, located on the front panel, is currently unused by SmartSwarm 351.
4.9 L E D S
The following table describes the LED operation on the SmartSwarm device
41
SIM
Green Off
Reset button pressed or the device is booting
On
Ready for operation. SIM 1 is enabled
WAN
Yellow
Off
There is no cellular connection between the SmartSwarm device and the cellular service provider
On
A cellular connection has been successfully established between the SmartSwarm device and the cellular service provider
IN0
Green Off
The default state
On
Binary input no. 0 is active (user defined)
IN1
Green Off
The default state
On
Binary input no. 1 is active (user defined)
Out
Yellow Off
The default state
On
Binary output is active (user defined)
ETH0
ETH1
Green
On
10 Mb/s
Off
100 Mb/s
ETH0
ETH1
Yellow
On
The network cable is connected
Off
Network cable is not connected
Blinking
Data transmission in progress
SmartWorx Hub is accessed via the primary uplink port on the SmartSwarm 351. This is ETH1 if it is connected to a local LAN providing outbound (internet) access, or the cellular connection if no outbound LAN connection exists. The connection status to SmartWorx Hub is indicated by the LEDs on the front panel. The USR LED will be solid ON (yellow) if a secure connection to SmartWorx Hub has been achieved.
Please refer to the ‘Verification’ section below for further details on how to confirm this connection
status.
Table 11. LED indicators
5. CONFI G URE C ONNECTIVIT Y TO SMARTWORX HUB
All major configuration of the SmartSwarm 351 is performed using the SmartWorx Hub cloud based management platform. If you do not already have a SmartWorx Hub account, please contact your local B+B representative to arrange for one to be set up. You will need to provide the following information in order for an account to be set up:
● An Administrator contact name and email address
● The Device ID of the SmartSwarm 351 devices you already have taken delivery of (from the SmartSwarm
351 product label on each device)
● The MAC ID of the first Ethernet port each device (from the SmartSwarm 351 product label on the
devices)
If the Internet connection is to be via cellular connection, ensure that appropriate antennae and SIM cards are inserted before moving on to the first step below.
42
5.1 S T E P 1 - C O NNECT TO LOCAL WEBSERVER
Connect a local laptop or desktop PC to ETH0. Open a browser and navigate to 192.168.1.1. Note that if you have another LAN connection (e.g. via Wi-Fi) you may need to disconnect this second session, depending upon your network settings and the domain of the LAN.
5.2 S T E P 2 - C O NFIGURE THE CELLULAR APN D ETAI L S
Enter the APN name and optional credentials as required by your SIM card provider / network operator. Apply it. The WAN LED will turn ON (yellow) when the cellular connection has been successfully established.
5.3 S T E P 3 - V E RIFY THE SECURE CONNECTION W I T H SMART WORX HUB
The USR LED will turn on (yellow) when the device successfully makes a secure connection with SmartWorx Hub (https://hub.bb-smartworx.com).
5.4 S T E P 4 - V E RIFY THAT YOUR DEVICE IS AVAILABLE O N SMARTWOR X H UB
In order to verify the installation, and to ensure that you have correctly claimed the device within your SmartWorx Hub account, please confirm that the device is shown as “Online” in SmartWorx Hub (For further information on SmartWorx Hub, please refer to the SmartWorx Hub user manual).
43
If a configuration for the device has already been created in SmartWorx Hub it will be automatically downloaded to the device during this first connection.
5.5 F A CTORY DEFAULTS
If the unit is not connecting as expected it may be reset to Factory Defaults at any time by pressing the Reset button on the back-panel of the device for more than 10 seconds.
44
Once you have Claimed your Device on SmartWorx Hub you may edit and configure it. If your device is currently offline, all changes you make are queued. All of your changes will be immediately applied as soon as the device comes online.
6. SMA R T SWARM 351 ON SMARTWORX HUB
6.1 D EVI C E M A NAGEMENT
Please refer to the SmartWorx Hub user manual for more detailed information on general Device Management.
Find the device that you wish to manage in the “View Devices” screen, and click on it to open the “Manage Device” screen.
45
Functional Area
Description
Reference
Modbus
Configure the Modbus interface of the SmartSwarm 351. This configuration must match the configuration of the Modbus network you’re monitoring.
See chapter 7.
MQTT
Configure the MQTT interface of the SmartSwarm 351.
See chapter 8.
Decoder
This section enables you to Build and Enrich the Slave Maps that are of interest to you. This section also enables you to define the Rules you wish to create to publish data on the MQTT interface, and the MQTT topics that you will publish that data on.
See chapter 9 for Building and Enriching Slave Maps.
See chapter 10 for defining Rules and Topics.
From here you may select the name of the application (“Modbus-to-MQTT”) in order to configure the Modbus-to­MQTT Application.
6.2 T H E M OD BUS -TO-MQTT APPLICATION
The settings for the Modbus-to-MQTT application are split into 3 functional areas:
46
Setting
Description
Port
RS-232 or RS-485. The SmartSwarm 351 can only ‘sniff’ on one of these physical ports at a time.
Baud Rate
1200 through 115200
Parity
None, Even or Odd
Databits
8
Stopbits
1 or 2
Table 12. The Modbus to MQTT application
7. CONFI G URE T HE MODBUS INTERFACE
When configuring the Modbus interface, please ensure that you match the Modbus Master configuration on the Modbus network you are monitoring.
47
Response Timeout
Specifies the maximum time interval, in seconds, in which a response to a command is expected from a connected slave device. If the interval is set too short, valid replies may be missed. If set too long, retries sent by the Master may be interpreted as a reply and cause valid exchanges to be missed. This will typically be set to a slightly lower value than the Modbus master timeout. (E.g. 1.5 seconds.)
The MQTT Broker is a 3rd party service: Advantech B+B SmartWorx does not provide this service. Any MQTT 3.1.1 compliant broker may be used.
For information on deploying MQTT in a secure manner we recommend that you refer to “MQTT and the NIST Cybersecurity Framework” which is available on the OASIS website (http://docs.oasis­open.org/mqtt/mqtt-nist-cybersecurity).
Table 13. Modbus Interface
8. CON F I G U R E THE MQTT INTERFACE
MQTT is an OASIS and IEC/ISO standard.
The configuration interface provided enables you to configure the MQTT Client that resides on the SmartSwarm
351. The MQTT Client will use this configuration to connect to, and to communicate with, an MQTT Broker. Once connected, the SmartSwarm 351 will publish data to the MQTT Broker.
The data published will be in accordance with the Rules and Topics that you will define for your Modbus environment: see chapters 9 and 10.
48
Setting
Description
Host
Enter the IP address of the MQTT broker. This is the address that the SmartSwarm 351 will publish MQTT Topics to.
Port
TCP/IP port used by the MQTT broker. The default port for MQTT is 1883 When TLS is enabled the default port is 8883.
Ensure that the port you use matches the port on the MQTT Broker.
49
Username/Password
Username and Password fields may be used to authenticate and authorize the client when connecting.
These fields are optional: If you setup your MQTT broker to require them, then you will require them here also.
The password is sent in plaintext if it isn’t encrypted or hashed by implementation, or
if TLS is not used.
We recommend that you use username and password together with a secure transport (i.e. Enable TLS).
Alternatively, you may choose to use the Client Certificate method for authentication. This is best if your broker supports it. In this case, no username and password are needed.
Client ID
Unique identifier, used by the broker to uniquely identify each client. This field is optional, and may be left blank.
The broker uses it for identifying the client and the current state of the client. If you
don’t need a state to be held by the broker, in MQTT 3.1.1 it is possible to send an
empty Client ID. This results in a connection without any state. A condition is that Clean Session is true, otherwise the connection will be rejected.
We recommend that you use a random number.
Timeout
Connection timeout in seconds. That is, the number of seconds that the client will persist in attempting to make an initial connection with the broker.
Retry Interval
The number of seconds after a QoS=1 or QoS=2 message has been sent that the publisher will wait before retrying when no response is received.
Keep Alive
The Keep Alive is a time interval used by the client to ensure the connection with the broker is kept open. The client sends a PING request to the broker as specified by this time interval. The broker responds with PING Response and this mechanism will allow both sides to determine if the other one is still alive and reachable.
Reliability
This is a Boolean value that controls how many messages can be in-flight simultaneously.
Setting Reliable to True means that a published message must be completed (acknowledgements received) before another can be sent.
Setting this flag to false allows up to 10 messages to be in-flight. This can increase overall throughput in some circumstances.
Clean Session
True: The broker won’t store anything for the client and will also purge all
information from a previous persistent session. This is required to be True if there is no Client ID used.
This is the recommended setting for SmartSwarm 351.
False: The broker will store all subscriptions for the client and also all missed messages, when subscribing with Quality of Service (QoS) 1 or 2.
50
Enable TLS
Enable TLSv1.2 as the secure transport layer. Security settings must match the broker settings.
Client Certificate
Valid X.509 Certificate containing the client’s public key. This certificate will be sent
to the broker when the SSL/TLS session is established.
Client Private Key
Valid Private key corresponding to the Client Certificate. This is not exchanged with the broker or any third party: it is only used locally on the SmartSwarm 351 device.
When using a Client Certificate, this field is required.
Passphrase
Optional passphrase for the private key.
Verify Server Cert
If this box is ticked, when the SSL/TLS session is established, the SmartSwarm 351
client will attempt to verify that the broker’s certificate is trusted. The Server Root CA
Cert must be provided in the field below. (For test purposes, it may be useful to disable this option. But it should be enabled for secure applications).
Server Root CA Cert
The Root CA cert used to sign the broker’s certificate. If Verify Server Cert is enabled, this field is required.
Mutual Authentication
Mutual authentication means that the broker will attempt to verify the client’s certificate when the SSL/TLS session is established. You must ensure that the Root CA cert used to create the client’s key-pair is on the broker.
Last Will and Testament Setting
Description
Topic
Topic on which the LWT is published. If left blank the default topic is [SwarmID]/[Serial Number]/[Status]
Any subscribing clients wishing to be notified when this SmartSwarm 351 goes online and/or offline will subscribe to this topic.
Online Message
The message the broker will send to any subscribing clients when this SmartSwarm 351 comes “online” (Successfully connects to the broker).
Offline Message
The message the broker will send to any subscribing clients when this SmartSwarm 351 goes “offline” (Disconnects unexpectedly from the broker).
Table 14. MQTT Interface
51
QOS
The Quality of Service level is an agreement between sender and receiver of a message regarding the guarantees of delivering a message. There are 3 QoS levels in MQTT:
● At most once (0)
● At least once (1)
● Exactly once (2)
With QoS for MQTT, there are always two different parts of delivering a message: publishing client to broker, and broker to subscribing client.
The QoS level for publishing client to broker depends on the QoS level the publishing client sets for the particular message.
When the broker transfers a message to a subscribing client it uses the QoS of the subscription made by the subscribing client.
That means that QoS guarantees can get downgraded for a particular receiving client if subscribed with a lower QoS.
In the case of SmartSwarm 351, we only need to consider the QoS for the publishing client to broker.
Retain
This flag determines whether the message will be saved by the broker for the specified topic as the last known good value.
New clients that subscribe to that topic will receive the last retained message on that topic instantly after subscribing.
These settings are the general MQTT connection settings. For each individual Rule and Topic that has an MQTT Publish associated with it, it is possible to specify the QoS, Retain, Topic and Payload for that individual Publish. This is configured within the “Rules and Topics” section..
Last Will and Testament messages are sent by the broker, to subscribing clients, when any of the following cases occur.
An I/O error or network failure is detected by the broker; The client fails to communicate within the Keep Alive time; The client closes the network connection without sending a DISCONNECT packet first; The server closes the network connection because of a protocol error
Table 15. MQTT Interface
52
slave Map
you have created
section
Empty Slave Map”
Slave Map” section
9. SLA V E MAPS AND ENRICHMENT
If you have some knowledge of the Modbus network that is being sniffed, you can “enrich” the Modbus data by
telling the SmartSwarm device how to interpret these addresses and substitute some more meaningful strings.
There are two fundamentally different ways to enter this enrichment information:
● Discover: o Allow the device to automatically learn the network and the memory maps of the various slaves
and present this information to you.
o Then edit this information with any extra knowledge that you have.
● Create or Import a Slave Map: o Use your prior knowledge of the Modbus network and the slaves to pre-configure the device. This
can be done in advance of connecting the device to a network.
It is possible to mix these two approaches in whatever way makes most sense for your application. Here, we will present one example of each.
Go to “Discover”
Discover
Discover
How do you want build the
Modbus Network?
Create an empty
Go to “Create an
Create or Import
Import a slave Map
Go to “Import a
53
The “Decoder” interface screen displays all the Modbus Slaves currently known by SmartWorx Hub for this device.
When you first use SmartWorx Hub to enrich your new SmartSwarm device the list of Slaves will be empty.
54
Option
Method
Description
Export Maps
Export your current maps. All of your existing Slave Maps will be exported to a .zip archive file. All maps are exported in .json format. There is one map file for each Slave.
The .zip archive will be stored into your Browser’s download
directory.
Download Templates
Download a .zip archive file of map templates in both .json and Excel formats. These templates can be used to create slave map files that can then be loaded using “Load Map”.
Sync Maps
Discover
When the SmartSwarm 351 device is connected to a live Modbus fieldbus it immediately begins to “Discover” the bus. It will automatically build up a Map of all Slaves and Registers that it sees.
You may upload this automatically discovered Modbus information from the device to SmartWorx Hub using Sync Maps. See section “Import a Slave Map”.
New Map
Create
You may already know the slave address(es) you wish to enrich for rules-and-publish purposes.
Use this option to build only the Modbus slaves and registers
that you are interested in. See section “Create an Empty Slave Map”.
Load Map
Import
You may import your entire Modbus information using the Load Map option. You may import Maps in either .json or Excel formats. See section “Import a Slave Map”.
Table 16. Slave Map options
Once you have some Slave maps in place, you may Edit or Delete ( - ) them.
55
9.1 D ISC O VER
In Discover Mode you simply wait for your device to learn the network. The time you need to wait depends on the configuration of the Modbus Master.
After waiting for an appropriate period of time, click on “Sync Maps”. This will pull the learned information into
SmartWorx Hub.
Clicking on Sync Maps tells the device to upload its discovered maps. This should be done after the application has discovered all slaves on the Modbus network and before enrichment data has been entered.
Any maps on the device which have already been enriched will retain their data. After syncing, the Slaves grid will be populated with the discovered maps. As no enrichment data is available, most fields will appear as undefined.
56
Entering a Slave number which already exists on the system will overwrite the existing map
You will now be able to edit these maps to add enrichment data and events. See Chapters 9.4, 10 on how to do this.
9.2 C R E ATE AN EMPTY SLAVE MAP
Clicking on New Map allows you to enter an empty slave map. Enter a slave number between 1 and 247 and click OK. The map is then displayed on the Decoder screen and may now be edited.
57
9.3 I M P O R T A SLAVE MAP
You may import a complete set of pre-prepared Slave and Register information, complete with full enrichment.
If you wish to do this we recommend that you begin by exporting as much of the mapping information as you can from your Modbus control system.
You will need to manipulate your exported data into one of the formats required by the SmartWorx Hub import utility.
Click on Load Map to import existing slave maps. You can import multiple maps using the Ctrl and Shift keys when selecting maps to be imported. Supported formats are .json, .xls and .xlsx. Please refer to Appendix 2 for more information.
Once imported, you can edit the data in-line on SmartWorx Hub, as described in section “Editing Slaves”.
9.4 E D I T I NG SLAVES
While editing Slaves, SmartWorx Hub will be in Editor Mode.
58
Editor Button
Description
Save
Save all current changes to the SmartWorx Hub Database.
Use this button when you want to save your current edits, but you don’t wish to push
your edits to the device just yet. If you get interrupted, or SmartWorx Hub times out and logs you off, you will be able to resume editing from where you last Saved.
Push to Device
Push the current state of configuration for everything in the Slave Editor tabs to the SmartSwarm device. Use this button when you want to deploy your edits, so that they take effect on the SmartSwarm device.
Exit Editor
Exit Slave Editor mode. Note that when you exit the Editor you will be prompted to Stay on page if you have unsaved changes. Please remember to Save your changes as you make them, and to Push them as often as necessary
When you exit the Editor you will be prompted to Stay or Leave page if you have unsaved changes. If you Choose Leave, your changes will not be saved.
Context Button
Tab
Description
Inputs (1x) Coils (0x) Input Registers (3x) Holding Registers (4x) Rules and Topics
Delete a row from the panel context.
Inputs (1x) Coils (0x) Input Registers (3x)
Add a row to the panel context.
9.4.1 U NDERSTANDING YOUR SLAVE EDITO R
Table 17. Editing Slave Maps
59
Holding Registers (4x) Rules and Topics
Save Rules
Rules and Topics
Save all current rules/events changes to the SmartWorx Hub database.
Use this button while you’re still editing your Rules
and Topics.
Push Rules
Rules and Topics
Push all existing (saved) rules/events to the SmartSwarm device, so that they can take effect.
Save does not write anything to the SmartSwarm device. You must push your changes to the device to apply the changes.
If Meta Data is populated the custom “MQTT Topic” will be composed of the text from the Location,
Description and Name fields as entered in the Meta Data tab: E.g. <Location>/<Description>/<Name>
When considering topic design, it is important that the topic hierarchy is carefully chosen to facilitate
searching and filtering using wildcards. In the example shown in the screenshot, the “MQTT Topic” is
Warehouse/Fan/Fan1.
The custom value that the “MQTT Topic” takes by default, using Meta Data, is not the same thing as the “Default Topic”.
Field
Map Property
Description
Description
description
User-defined text e.g. Fan
Install Date
installation_date
Date the slave was installed on your network
Table 18. Editing Slave Maps - Rules
9.4.2 M E T A DATA
The Meta tab allows you to add information about the Modbus slave. Some of this information is then automatically used (by default) to define the MQTT topic on which data will be published.
60
Location
location
User-defined text e.g. Warehouse/Room401
Manufacturer
manufacturer
User-defined text (Usually the manufacturer of the slave)
Name
name
User-defined text e.g. AHU Fan
Product Code
product_code
User-defined text e.g. Wil-Flex-450
Byte Order
value_byte_order
This is how Floating Point and 32-bit data is ordered when it is transmitted by the slave within the register. No Swap Swap Bytes and Words Swap Bytes only Swap Words only
Version
version
User-defined text e.g. 4.1
An MQTT Topic hierarchy can be specified by using the ‘/’ character inline in the text of the meta data
fields. This hierarchy is not limited to 3 levels of <Location>/<Description>/<Name>
E.g. the text “Warehouse/HoldingArea/Room401” can be entered into the Location field.
Register Type
Address Range
Modicon Address
Coil (0x)
0-65535
000001 to 065536
Discrete Input (1x)
0-65535
100001 to 165536
Input Registers (3x)
0-65535
300001 to 365536
Holding Registers (4x)
0-65535
400001 to 465536
Table 19. Meta Data tab
Click on a cell to enter edit-mode. Use the tab key to navigate between cells. If the data entered is invalid, the cell color will change to red. Pressing the ESC key while in edit-mode will restore the original value.
Changes are automatically saved when moving to a new tab.
9.4.3 R E G ISTERS
The application supports the 4 Modicon register types i.e. Coils, Discrete Inputs, Input Registers and Holding Registers.
Table 20. Register Types
61
On SmartWorx Hub, for each register type, the address entered corresponds with the Modbus register offset for that specific register type. E.g. Holding Register address 5 corresponds to register 400006
Item
Map Property
Description
Address
address
Index from the register type base address
Bit Offset
address_offset
Starting position within the register, counting from the least significant bit.
The default is 0, which is appropriate for all non-Enum Data Types.
An Enum Data Types is used to represent a register that is used for multiple purposes (e.g. using individual bits, or bit­fields).
In the case of an Enum Data Type, the Bit Offset, Width, Num Value, and String Value fields are relevant.
Click on the appropriate tab to view registers.
9.4.3.1 INPUT REGISTERS AND HOLDING REGISTERS
62
Name
name
A description of the register function e.g. Energy Meter
The Name field is not used for any algorithmic purpose within the Device: it will become part of the enrichment-data published for this Register.
Alias
alias
An alternate name for the register e.g. Power Usage
The Alias field is not used for any algorithmic purpose within the Device: it will become part of the enrichment-data published for this Register.
Data Type
datatype
Dropdown list of data types. See section “Data Types”.
Width
length
Register data width. For 16 and 32-bit data types this cannot be changed. For other types the width can be from 1 to 32.
For Enum types this is used in conjunction with Bit Offset. Width specifies the bit-width (e.g. “4” specifies a bit-width of 4 bits) within the register; Bit Offset specifies the starting position of those 4 bits within the register.
Zero Value
zero_value
Zero calibration value for this register.
This is an important value in converting from the Modbus Register Value to a context-aware Enriched Value.
The equation used to enrich the Modbus data is:
Enriched_Value = (Modbus_Register_Value
/ Scaling) + Zero_Value
See examples given below.
Max
max
The expected Maximum Enriched value for this register.
E.g. If we know that the register value represents temperature with a maximum value of 100 degrees Celsius, the value
entered here would be “100”.
This Max field value is not used for any algorithmic purpose within the Device. It will become part of the enrichment-data published for this register. It should be used as an indicator of what the maximum enriched value is expected to be.
Exception to this rule: For Counter Data Type, Max is the rollover value of the register.
63
Min
min
The expected Minimum Enriched value for this register.
For example, if we know that the register value represents temperature with a minimum value of 0 degrees Celsius, the
value entered here would be “0”.
This Min field value is not used for any algorithmic purpose within the Device. It will become part of the enrichment-data published for this register. It should be used as an indicator of what the minimum enriched value is expected to be.
Scaling
scaling
Data scaling factor to be used
This is an important value in converting from the Modbus Register Value to a context-aware Enriched Value.
The equation used to enrich the Modbus data is:
Enriched_Value = (Modbus_Register_Value
/ Scaling) + Zero_Value
See the examples given below.
Units
units
The unit of data e.g. kWh, Hz, Deg. C, Deg. F
For example, if we know that the register value represents temperature, and we want to represent the temperature in the
Celsius scale, we would enter “Deg C” here. This Units field value is not used for any algorithmic purpose within the Device. It will become part of the enrichment-data published for this register.
Num Value
num
This field is only relevant for Enum data types.
The Num Value field enables us to specify a numeric value that we can use to add contextualized meaning to each relevant state of bit-field data.
E.g. A 16 bit register may be represented by an Enum Data Type. Each bit of the register might have a unique and significant meaning. For each bit there can be two possible states: 0 or 1. We can create a row in the Register Table that represents each bit in the Register (using Bit Offset and Width fields). For each row, we can apply meaning:
Num Value = 0; Str Value = “Valve Closed” Num Value = 1; Str Value = “Valve Open”
This Num Value field is not used for any algorithmic purpose within the Device. It will become part of the enrichment-data published for this register.
64
Str Value
val
This field is only relevant for Enum data types.
The Str Value field enables us to specify a string value that we can use to add contextualized meaning to each relevant state of bit-field data.
E.g. A 16 bit register may be represented by an Enum Data Type. Each bit of the register might have a unique and significant meaning. For each bit, there can be two possible states: 0 or 1. We can create a row in the Register Table that represents each bit in the Register (using Bit Offset and Width fields). For each row, we can apply meaning:
Num Value = 0; Str Value = “Valve Closed” Num Value = 1; Str Value = “Valve Open”
This Str Value field is not used for any algorithmic purpose within the Device. It will become part of the enrichment-data published for this register.
Table 21. Input Register and Holding Register editable fields
9.4.3.1.1 EXAMPLE USE OF ZERO VALUE AND SCALING
Condiser an example where a Modbus slave uses a 12-bit ADC to digitize a 4-20mA loop sensor which is measuring temperature. The register value ranges from 819 to 4095, corresponding to a temperature range of 0 to +10°C.
The enriched value will be calculated as
(Modbus Register Value / Scaling) + Zero Value
It is recommended to draw the graph of input (raw Modbus register value) and output (enriched value) in order to calculate the Scaling and Zero Value. Note that we assume that the relationship is linear.
65
From the graph, we can calculate the slope as
 
The Scaling factor is the inverse of this. It can also be thought of as the “One in X” gradient of the graph.
 
The Zero Value is where the graph intersects the Y-axis. It can also be thought of as the Enriched value that corresponds to a Raw Modbus Register value of 0.



= 0.00305
= 327.6
66
 
     
We can repeat this same example using an Enriched Value in degrees Fahrenheit instead of degrees Celsius. The register value ranges from 819 to 4095, corresponding to a temperature range of 32 to 50F.
  
  
Now the calculations are as follows:
 
The Scaling factor is the inverse of this. It can also be thought of as the “One in X” gradient of the graph.
 



= 0.00549
= 182
67
Item
Map Property
Description
Address
address
Index from register type base address
Name
name
A description of the register function e.g. Pump Status
Alias
alias
An alternate name for the register e.g. Heating Pump 1
Str 0 Value
val0
Enriched string for a value of zero e.g. OFF
Str 1 Value
val1
Enriched string for a value of one e.g. ON
Data Type
Address
Bit
Offset
Name
Alias
Width
Zero
Value
Max
Min
Scaling
Units
Num
Value
Str
Value
ENUM
✔ ✔ ✔ ✔ ✔
✔
✔
UINT16
✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔
✔
The Zero Value is where the graph intersects the Y-axis. It can also be thought of as the Enriched value that corresponds to a Raw value of 0.
 
       
Here’s what these two examples would look like on SmartWorx Hub:
  
  
9.4.3.2 DISCRETE INPUTS AND COILS
Table 22. Discrete Input and Coil editable fields
9.4.4 D A T A TYPES
68
INT16
✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔
✔
UINT32
✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔
✔
INT32
✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔
✔
FLOAT32
✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔
✔
STRING
✔ ✔ ✔ ✔ ✔
✔
COUNTER
✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔
✔
Table 23. Data Types and Field Values
Registers which are discovered will have no meaningful information filled in. Some cells such as Num Value and Str Value are only applicable to ENUM data types and will have no effect if filled in for other data types. Moving the mouse over a cell will indicate if the cell is valid for the selected data type.
9.4.4.1 ENUM
Combination of bits representing a range of distinct named values. See section “Editing Registers”.
9.4.4.2 UNT16
Unsigned 16 bit integer, range 0 - 65535 .
9.4.4.3 INT16
Signed 16 bit integer, range -32,768 to 32,767 .
9.4.4.4 UINT32
Unsigned 32 bit integer, range 0 to 4,294,967,295 .
9.4.4.5 INT32
Signed 32 bit integer, range -2,147,483,648 to 2,147,483,647 .
9.4.4.6 FLOAT32
Signed 32 bit floating point, range -3.4E+38 to +3.4E+38 .
9.4.4.7 STRING
Collection of Registers representing 8-bit ASCII characters. The width of this field should be set to the length of the string multiplied by 8.
9.4.4.8 COUNTER
Combination of bits representing a roll-over counter. For example an 8-bit counter would range from 0 to 255. When it reaches 255, the next increment will cause it to roll-over to 0 again. A 16-bit counter would range from 0 to 65535.
For rules purposes, the counter is assumed to always increment, never decrement. For example, for an 8-bit counter a reading of 254 followed by a reading of 4 would be treated as an increment of 6: 254 - 255 - 0 - 1 - 2 - 3 ­4… The max value is not forced to be the maximum value determined by the bit width of the counter. It can be less if required. For example, if an 8-bit counter has a max value of 100, then the internal counter is assumed to rollover at 100. This allows digital counters to be handled, such as an electricity meter or vehicle odometer.
69
The nature of a counter also has implications for the type of event that can be triggered by it. See section “Events (WHEN)”.
9.4.5 A D D ING REGISTERS
To add a register click the + icon. This will create a new row with the same values as the current row. Enter the
Address and fill in the other fields as required.
9.4.6 E D I T ING REGISTERS
9.4.6.1 DISCRETE INPUTS AND COILS
Discrete Inputs and Coils can only have a value of zero or one. These can be enriched using the Str 0 Value and Str 1 Value columns.
9.4.6.2 INPUT REGISTERS AND HOLDING REGISTERS
By default, discovered Holding and Input registers will have a DataType of UINT16 when displayed. The user should select the correct Data Type for each register.
9.4.6.2.1 THE ENUM DATA TYPE
“ENUM” stands for enumerated type. It means that the register can have a finite set of named values. When entering ENUM data types, an entry must be made for each enum value. i.e. If there are 2 enums representing ON and OFF, then 2 rows must be entered for the register.
In the example below, Register 614 is an ENUM type which uses Bit 0 to encode 2 possible states: 0 and 1, which
have enriched values of “OFF” and “ON”. Note how we use the combination of “Bit offset” and “Width” to specify
bit zero of the register.
70
The Min, Max, Units, Num Value and Str Value fields are not used for any algorithmic purpose within the Device. The data entered for these fields will become part of the enriched-data published for the register. The Zero Value and Scaling fields are used to scale the raw Modbus value into an enriched value: For
In the next example, Register 40 is also an ENUM type which uses the first 3 bits of the register.
● Bit 0 has 2 states: “Pump Off” and “Pump On”.
● Bit 1 has 2 states: “Normal Operation” and “Min Speed”
● Bit 2 has 2 states: “Normal Operation” and “Max Speed”.
Note how one register configured as a “bit field” in this way can hold several independent states at the same time.
Another common ENUM scenario uses the value of the whole register to encode a single state. In the above screenshot Register 42 represents one state variable that can have multiple possible values.
71
ENUM data types this could alter the intended meaning of Modbus register. Unless you’re sure, we recommend leaving these fields in their default states (Zero Value = 0; Scaling = 1).
No changes will be made to the device until the Push to Device button has been clicked
In the above screenshot Registers 65 and 14 are ENUM types.
Register 65 uses two 2-bit values to represent the state of two Valves.
The 2-bit width allows up to four states for the Valves: in the example shown, only three states are defined.
Register 14 uses a 2-bit width to encode 4 states to represent the current status of a control-room door.
● Register 65, Bit Offset 0, has three states: “Valve Open”, “Valve Closed”, “Valve in Transition”
● Register 65, Bit Offset 2, has three states: “Valve Open”, “Valve Closed”, “Valve in Transition”
● Register 14, Bit Offset 8, has four states: “Door Closed”, “Door Open”, “Door Opening”, “Door Closing”.
9.4.7 D E L E T ING REGISTERS
To delete a register, Click the - icon. A confirmation dialog is displayed. Click OK to delete the register. The
register is now removed.
72
Enrichment is done before Rules are applied. This means that all Rules created will apply to the enriched data.
If scaling has been applied for a register during the enrichment process, the Rules you create will apply to the enriched and scaled data for that register.
If you have not applied enrichment for a register, the Rules you create for that register will apply to the raw Modbus register data.
10. RULE S AND TOPICS
10.1 I N T RODUCTION
The SmartSwarm 351 converts Modbus data to MQTT.
In the process it adds data enrichment, including scaling factors and meta-data.
By default, all data is blocked and nothing is published on MQTT until you specifically allow it.
Bear in mind that even a slow serial network, running continuously, can create a lot of data. A 9600-baud network running at 50% bus utilization generates 1.5GB of raw data every month: and this is significantly increased by the enrichment process. If you are transporting the MQTT data over cellular you probably cannot afford to publish everything, and it is unlikely that your cellular connection and cloud service would keep up with the sustained, enriched-data rate.
The “Decoder” interface on SmartWorx Hub enables you to first apply enrichment for your Modbus data, and then to apply rules for your enriched data.
If you want some specific data to be published on MQTT, you must add a filter “rule”. A rule has two parts:
● An event, which determines WHEN data will be published;
● A payload, which determines WHAT data will be published.
73
The published Payload data will have all of the enrichment data included.
Item
Description
Event
Select the event type from a dropdown menu
Payload
Select what to publish from a dropdown menu
QOS
Quality of Service
Retain
Instructs the broker to retain the last published message on this topic
MQTT Topic
Topic to publish on
Default Topic
The default topic will always be Swarm_ID/Device_ID/Port_ID/Slave_ID/Register_Type/Event E.g. 0/700000/1/1/HR/SCHEDULING. This can be turned on or off
–
Delete this rule
+
Add a new rule to this register
You then specify HOW you want the data to be published. For example, on what MQTT topic, with what QOS, etc.
The Rules and Topics screen is visible as a Tab in the editor for each slave. For example:
By default, only one event is displayed for each available register.
To add another event, click the ‘+’ sign on the required register. This will add a duplicate row for that register. Edit the event details and click Save Rules.
When saving rules, an error message will be displayed if any required parameters for an event are missing.
Once rules have been saved, click Push Rules to apply the rules to the device.
The following fields are editable in the Rules and Topics tab:
Table 24. Rules and Topics fields
74
Event
Description
None
The default selection. Nothing will be published.
Read
Trigger when the register is observed on the bus. Use with extreme caution as this can result in a substantial amount of MQTT data being published.
Change
Trigger when the enriched register value changes from the last observed value.
High Threshold
Trigger when the enriched register value goes above a threshold.
Low Threshold
Trigger when the enriched register value goes below a threshold.
Delta
Trigger when the enriched register value changes by a specified amount from the last published value.
High Rate
Trigger when the rate-of-change of the enriched register value increases by more than a specified amount in a specified period.
Low Rate
Trigger when the rate-of-change of the enriched register value decreases by more than a specified amount in a specified period.
Scheduled
Trigger periodically, on a user-defined interval.
Global Read
As for “Read”, but applies to ANY register of this type.
Global Change
As for “Change”, but applies to ANY register of this type.
10.2 E V E NTS (WHEN)
On any row in the Rules and Topics table, click the Event field to see the drop-down list of available events:
Note: Only one instance of each event type should be added to a register. Adding multiple events of the same type will have no effect, as only the first instance of the event will take effect.
The following table summarizes the available event types:
Table 25. Event Types
The following table summarizes how each event type may be used with each register type:
75
Inputs,
Coils
Input Registers,
Holding Registers
Event ENUM
Numeric1
STRING
COUNTER
Read
✔ ✔ ✔ ✔ ✔
Change
✔ ✔ ✔ ✔ ✔
High Threshold
✔
Low Threshold
✔
Delta ✔
✔
High Rate ✔
✔
Low Rate ✔
✔
Scheduled
✔ ✔ ✔ ✔ ✔
Global Read
✔ ✔ ✔ ✔
Global Change
✔ ✔ ✔ ✔
1
Inputs,
Coils
Input Registers,
Holding Registers
ENUM
Numeric
STRING
COUNTER
Read
✔ ✔ ✔ ✔ ✔
1
Table 26. Events and Data Types: cross-reference
“Numeric” means any of the following data types: UINT16, INT16, UINT32, INT32, FLOAT32
Each event type is discussed in more detail in the following sections.
10.2.1 READ
Trigger a publish when a register has been read (or written) by the Modbus master.
This event is applicable to any register type and any data type: For a counter it returns the raw value of the register, not the accumulated value.
Table 27. Read Event
“Numeric” means any of the following data types: UINT16, INT16, UINT32, INT32, FLOAT32
76
Inputs,
Coils
Input Registers,
Holding Registers
ENUM
Numeric
STRING
COUNTER
Change
✔ ✔ ✔ ✔ ✔
In SmartWorx Hub, when you select this Event type. No further configuration is required:
10.2.2 C HANGE
Trigger a publish when an enriched register value changes.
This event is applicable to any register type and any data type:
Table 28. Change Event
77
In SmartWorx Hub, when you select this Event type on an Input or a Coil, no further configuration is required. However, if it is selected on an Input Register or a Holding Register, an additional field appears at the top of the table:
In the “Change by” field, you may enter a percentage value. The MQTT publish will only be triggered if the
enriched register value has changed by more than this value. The default value is 0%, which means that ANY change will constitute a trigger event.
The following example shows a register that usually has a numeric value of 100, but with occasional deviations. The red annotations show when MQTT publishes will be triggered, assuming that a Change rule is applied, with “Change by” = 0%:
Note that we get only 13 MQTT messages, as opposed to 68 if we had used a Read rule.
For analog data it probably does not make sense to create a Change rule with “Change by” = 0%, as process noise
will inevitably cause the least-significant bits to change all the time. This will trigger a lot of MQTT publishes, which
may lead to a large cellular bill. The “Change by” field can be used to reject noise. Continuing the example above, if we apply a Change rule with “Change by” = 10% we can reduce the number of
MQTT messages from 13 to 4:
78
It is important to remember that the change is measured with respect to the last time the register was observed on Modbus, not to the last time it was published on MQTT.
In the diagram above, the green bars represent the ±10% change that is dynamically calculated after each new sample is received.
An MQTT publish will be triggered only if the next sample value lies outside of the allowed range, represented by the green bar. For the “Change” event type, only a percentage or relative change can be specified. That means the actual change in value required to trigger an event will vary.
79
Inputs,
Coils
Input Registers,
Holding Registers
ENUM
Numeric
STRING
COUNTER
The following example shows a numeric register that ramps monotonically from 0, incrementing by 1 on each Modbus master access. The red annotations show when MQTT publishes will be triggered, assuming that a Change
rule is applied, with “Change by” = 10%.
● If the register has not been seen on the bus before, then the first value of 0 is considered to be a change
of 100%. So the value of 0 triggers a publish.
● If the current enriched register value is 0, then any non-zero value is considered to be a change of 100%.
So the value of 1 triggers a publish.
● The next change from 1 to 2 represents a 100% change, which is greater than 10%.
● A change from 2 to 3 represents a 50% change, and so on.
● A change from 10 to 11 represents a 10% change, which is not greater than 10%. The value of 11 does not
trigger a publish.
● As the enriched register value increases further, the absolute change of 1 becomes smaller in percentage
terms. No further MQTT publishes are triggered.
For a slave waveform like this you probably want to specify an absolute change. See the Delta event type below.
10.2.3 D E L T A
Trigger when the enriched register value changes from the last published value.
This event is only applicable to Input Registers and Holding Registers, not Discrete Inputs and Coils.
It is only applicable to numeric data types, and the counter data type: It is only applicable to numeric data types, and the counter data type:
80
Delta ✔
✔
Table 29. Delta Event
Note: As explained in the Counter section, a counter is always increasing. A drop in value is assumed to indicate a
single roll-over event. Therefore, for an 8-bit counter (range 0 - 255), a change in value from 254 to 253 is an increase of 255, not a decrease of 1.
Like the Change event, you can enter a “Change by” value after selecting the Delta event type on a register:
The MQTT publish will only be triggered if the enriched register value has changed by greater than or equal to this value, compared to the last time it was published.
The following example shows a register that ramps monotonically from 0, incrementing by 1 on each Modbus master access. The red annotations show when MQTT publishes will be triggered, assuming that a Delta rule is applied, with “Change by” = 9.
81
Inputs,
Coils
Input Registers,
Holding Registers
ENUM
Numeric
STRING
COUNTER
High Threshold
✔
NOTE: This rule is significantly different from the previous rules discussed above, because it is STATEFUL. For example, when the High Threshold is crossed in either direction an MQTT publish will be triggered. But if the register remains above (or below) the threshold no further messages will be published. An MQTT publish will occur only on state transitions.
10.2.4 H IGH THRESHOLD
Trigger when the enriched register value increases above a fixed threshold.
This event is only applicable to Input Registers and Holding Registers, not Discrete Inputs and Coils.
It is applicable to numeric data types only. It is not applicable to a counter. A counter is a rollover data type and so we have no record of its true accumulated value on which to base the threshold.
Table 30. High Threshold Event
When you select the High Threshold event type on a register, you must enter two fields:
● The Threshold field specifies the value above which the register must increase in order to trigger an
MQTT publish.
● The Hysteresis field allows you to prevent multiple MQTT publishes due to process noise. Once the
register has crossed the Threshold value in the positive (increasing) direction, it must cross the value [Threshold - Hysteresis] in the negative direction before it is considered to have re-crossed.
82
The following rules are STATEFUL: High Threshold, Low Threshold, High Rate, Low Rate.
The following example shows a register that follows a sinusoidal waveform. The Modbus Master is polling the
register every 200ms. Assume that a “High Threshold” rule is applied, with Threshold = 40 and Hysteresis = 5. The
red dots show samples which are above the Threshold. The red callouts show when MQTT publishes will be triggered:
Note how only two MQTT messages are published:
● One when the value changes from below the threshold to above;
● One when the value changes from above the threshold to below (minus the hysteresis).
The default value of the Hysteresis field is 0 (zero), which means no hysteresis:
83
Inputs,
Coils
Input Registers,
Holding Registers
ENUM
Numeric
STRING
COUNTER
Low Threshold
✔
Note how 5 MQTT publishes are caused by the multiple threshold crossings.
Using a bigger value for Hysteresis provides more noise rejection:
10.2.5 L O W T HRESHOLD
Trigger when the enriched register value decreases below a fixed threshold..
This event is only applicable to Input Registers and Holding Registers, not Discrete Inputs and Coils.
It is applicable to numeric data types only. It is not applicable to a counter. A counter is a rollover data type and so we have no record of its true accumulated value on which to base the threshold.
Table 31. Low Threshold Event
84
●
NOTE: This rule is STATEFUL. For example, when the Low Threshold is crossed, in either direction, an MQTT publish will be triggered. But if the register remains below (or above) the threshold, no further messages will be published. An MQTT publish will occur only on state transmissions:
The following rules are STATEFUL: High Threshold, Low Threshold, High Rate, Low Rate.
When you select the Low Threshold event type on a register, you must enter two fields:
● The Threshold field specifies the value below which the register must decrease in order to trigger an
MQTT publish.
● The Hysteresis field allows you to prevent multiple MQTT publishes due to process noise. Once the
register has crossed the Threshold value in the negative (decreasing) direction it must cross the value [Threshold + Hysteresis] in the positive direction before it is considered to have re-crossed.
The following example shows the same register as before. The red callouts show when MQTT publishes will be triggered, assuming that a “Low Threshold” rule is applied, with Threshold = 15 and Hysteresis = 5:
85
Inputs,
Coils
Input Registers,
Holding Registers
ENUM
Numeric
STRING
COUNTER
High Rate ✔
Notes:
● On start-up, if the first value is already below the threshold, that is considered a state transition. In this
case, the first value of 0 will trigger an MQTT publish.
● When the value increases above the threshold (plus the hysteresis), we publish again.
● When the value decreases below the threshold, we publish again.
10.2.6 H IGH RATE
The “High Rate” rule will trigger on “high rate of change”. Trigger when the enriched register value has changed at a rate greater than a certain rate.
Note: A counter is always increasing. A drop in value is taken as a rollover. Therefore, for an 8 bit counter (range 0 -
255) a change in value from 254 to 253 is an increase of 255 not a decrease of 1
This event is only applicable to Input Registers and Holding Registers, not Discrete Inputs and Coils.
It is only applicable to numeric data types and the counter data type:
Note: a counter is always increasing. A drop in value is taken as a rollover. Therefore, for an 8 bit counter (range 0 -
255), a change in value from 254 to 253 is an increase of 255 and not a decrease of 1.
Table 32. High Rate Event
When you select the “High Rate” event type on a register, you must enter a “Change” value:
86
NOTE: This rule is STATEFUL. For example, when the Rate Threshold is crossed in either direction an MQTT publish will be triggered. But if the rate of change remains below (or above) the threshold no further messages will be published. An MQTT publish will only occur on state transitions:
The following rules are STATEFUL: High Threshold, Low Threshold, High Rate, Low Rate.
The Change value represents the instantaneous rate of change per second. The MQTT publish will only be triggered if the enriched register value has changed faster than this.
The following example shows a register that follows a sinusoidal waveform. The Modbus Master is polling the
register every 200ms. Assume that a “High Rate” rule is applied, with Change = 10 per second. The red dots show
samples that are above the Rate Threshold. The red callouts show when MQTT publishes will be triggered:
87
In the diagram above the green triangles represent the “10 per second” rate of change against which each new
sample is compared when it is received. At the top and bottom of a sine-wave the rate of change is low, so the trigger condition is not met.
Even though the Rate limit is specified in units per second, the system does not have to wait 1 second before deciding whether or not to publish. Whenever two consecutive samples are received, be they separated in time by less than or more than 1 second, the instantaneous rate of change is calculated. If the actual rate of change is greater than the programmed threshold, the MQTT publish will be triggered.
In the following example, the Modbus Master is polling the same register at a much slower rate: once every 4 seconds:
88

The second sample (actually, the first pair of samples) will trigger an MQTT publish, because
After this the system will remain in the “Alarm ON” state forever, because the rate of change is always greater
than the threshold. No further MQTT messages will be published.
The “High Rate” event type is roughly equivalent to the “High Threshold” event type, but it operates on the
derivative of the waveform. However, note that there is no equivalent for Rate “Hysteresis”. This means that if the
rate of change of a register happens to coincide with the selected Rate Threshold, timing jitter and/or process noise may lead to multiple MQTT publishes due to repeated state transitions.
10.2.7 L O W R ATE
Trigger when the enriched register value has changed at a rate less than a certain rate.
Note: a counter is always increasing. A drop in value is taken as a rollover. Therefore, for an 8 bit counter (range 0 -
255) a change in value from 254 to 253 is an increase of 255 and not a decrease of 1.
This event is only applicable to Input Registers and Holding Registers, not Discrete Inputs and Coils.
It is only applicable to numeric data types, and the counter data type:
Note: a counter is always increasing. A drop in value is taken as a rollover. Therefore, for an 8 bit counter (range 0 -
255) a change in value from 254 to 253 is an increase of 255 and not a decrease of 1.
 

89
Inputs,
Coils
Input Registers,
Holding Registers
ENUM
Numeric
STRING
COUNTER
Low Rate ✔
NOTE: This rule is STATEFUL. i.e. When the Rate Threshold is crossed in either direction, an MQTT publish will be triggered. But if the rate of change remains below (or above) the threshold, no further messages will be published. An MQTT publish will only occur on state transitions:
The following rules are STATEFUL: High Threshold, Low Threshold, High Rate, Low Rate.
Table 33. Low Rate Event
As for “High Rate”, when you select the “Low Rate” event type on a register you must enter a “Change” value,
which represents the rate of change per second:
The following example shows the same register as before, but with a “Low Rate” rule applied, with Change = 10
per second:
90
As expected, we get the complement of the previous result for the “High Rate” case.
The “Low Rate” event type is roughly equivalent to the “Low Threshold” event type, but it operates on the
derivative of the waveform. However, note that there is no equivalent for Rate “Hysteresis”. This means that if the rate of change of a register happens to coincide with the selected Rate Threshold, timing jitter and/or process noise may lead to multiple MQTT publishes due to repeated state transitions.
10.2.8 S C HEDULED
This event type allows you to specify an interval at which the data will be published on MQTT, and the time within that interval when the publish will take place, e.g. every hour and 17 minutes past the hour:
91
Inputs,
Coils
Input Registers,
Holding Registers
ENUM
Numeric
STRING
COUNTER
Read
✔ ✔ ✔ ✔ ✔
Inputs, Coils
Input Registers, Holding Registers
ENUM
Numeric
STRING
COUNTER
Change
✔ ✔ ✔ ✔ ✔
Global filters have the potential to generate a large number of MQTT publishes and should be avoided unless you are sure that this is what you intend.
10.2.9 G L O BAL READ
Trigger a publish when any register of the selected Type has been read (or written) by the Modbus master.
This event is applicable to any register type and any data type. For a counter it returns the raw value of the register, not the accumulated value.
Table 34. Global Read Event
Otherwise, this trigger will operate as per the description in the “Read” section.
10.2.1 0 G L O BAL CHANGE
Trigger a publish when the value of any register of the selected Type changes.
This event is applicable to any register type and any data type: For a counter it returns the raw value of the register, not the accumulated value.
Table 35. Global Change Event
Note that when a global filter is enabled, it is not possible to disable that filter for individual elements.
92
Payload
Description
Default
Only the register that triggered the event will be published.
Slave
All registers on this slave will be published.
HR
All Holding registers on this slave will be published.
IR
All Input registers on this slave will be published.
IS
All Discrete Input registers on this slave will be published.
CS
All Coils on this slave will be published.
Range
Registers within a range will be published.
Event
Default
Slave
HR
IR
IS
CS
Range
Read ✔
Change ✔
Delta
✔
✔ ✔ ✔ ✔ ✔
✔
High Threshold
✔
✔ ✔ ✔ ✔ ✔
✔
Low Threshold
✔
✔ ✔ ✔ ✔ ✔
✔
High Rate
✔
✔ ✔ ✔ ✔ ✔
✔
Low Rate
✔
✔ ✔ ✔ ✔ ✔
✔
Scheduled
✔
✔ ✔ ✔ ✔ ✔
✔
Global Read
✔
Global Change
✔
A payload will only be published if there has been actual data observed on the Modbus network for
the defined payload type. In other words, the device will not publish “enrichment” only, without an observed “num_value” (see payload examples below).
In the case of the “default” payload there will always be a publish to correspond with the event
trigger.
10.3 P AYL O A D S (WHAT)
For every event type, you can decide WHAT to publish when that event happens.
Table 36. Payload options
The “Default” payload can sometimes contain more than one register. In the case of a Global Read or Global Change rule, a single Modbus transaction may read or write more than one register. Every register that meets the Read or Change criteria will be published.
Not all payload selections are available for all event types, as the following table explains.
Table 37. Event / Payload matrix
93
10.3.1 P A Y L OAD EXAMPLES
10.3.1.1 THE DEFAULT PAYLOAD
With this rule, if the enriched value of Register 1 goes above 100 the payload for register 1 will be published.
The published payload data will be in .json format.
For this HR example, the actual enriched register value within the data payload will be in model.state.HR.0.num_value (see the published JSON schema below).
A sample of payload published from this rule might look like this:
{ "model": { "state": { "HR": [{ "value_from": "RESPONSE", "published_on": "HI\/ON", "name": "HR_1", "min": 0, "address_offset": 0, "max": 100, "zero_value": 0, "num_value": 101.000000, "scaling": 1, "alias": "Water Temperature", "state": "VALIDATED", "var_pct": 16.000000, "at": "2016-07-14T19:29:22.089Z", "address": 1, "units": "Deg C", "new_value": true, "new_read": true }] }, "meta": { "description": "Slave_1", "value_byte_order": "SNo", "name": "Power_Meter", "installation_date": "14\/07\/2016", "location": "Test_Rack", "address": { "DEVID": "6500004", "PORTID": 1, "SLAVEID": 10, "SWMID": 0 }, "manufacturer": "NA"
94
} }, "type": "ModbusSlave", "id": "10_HR_1_HI" }
10.3.1.2 THE HR PAYLOAD
With this rule, if the enriched value of Register 1 goes above 100 the payload data for all Holding registers will be published. The num_value in the payload for each of the holding-registers will be the actual value last seen by the SmartSwarm device on the Modbus network.
If there has not been any actual data seen on Modbus for a HR register it will not appear in the payload.
The published data will be in .json format.
A sample of payload published from this rule (assuming there are 3 Holding Registers for this Slave), might look like this:
{ "model": { "state": { "HR": [{ "value_from": "RESPONSE", "published_on": "HI\/ON", "name": "HR_1", "min": 0, "address_offset": 0, "max": 100, "zero_value": 0, "num_value": 103.000000, "scaling": 1, "alias": "Water Temperature", "state": "VALIDATED", "var_pct": 17.000000, "at": "2016-07-14T17:38:32.721Z", "address": 1, "units": "Deg C", "new_value": true, "new_read": true }, { "value_from": "RESPONSE", "published_on": "HI\/ON", "name": "HR_2", "min": -10, "address_offset": 0, "max": 40, "zero_value": 0, "num_value": 61.000000, "scaling": 1, "alias": "Air Temperature",
95
"state": "VALIDATED", "var_pct": 2.000000, "at": "2016-07-14T17:38:32.721Z", "address": 2, "units": "Deg C", "new_value": true, "new_read": true }, { "value_from": "RESPONSE", published_on": "HI\/ON", "name": "HR_3", "min": 0, "address_offset": 0, "max": 90, "zero_value": 0, "num_value": 0.000000, "scaling": 1, "alias": "Humidity", "state": "VALIDATED", "var_pct": 0, "at": "2016-07-14T17:38:32.721Z", "address": 3, "units": "%", "new_value": false, "new_read": true }] }, "meta": { "description": "Slave_1", "value_byte_order": "SNo", "name": "Power_Meter", "installation_date": "14\/07\/2016", "location": "Test_Rack", "address": { "DEVID": "6500004", "PORTID": 1, "SLAVEID": 10, "SWMID": 0 }, "manufacturer": "NA" } }, "type": "ModbusSlave", "id": "10_HR_1_HI" }
10.3.1.3 THE SLAVE PAYLOAD
With this rule, if the enriched value of Register 1 goes above 100 all registers from this Modbus slave will be published.
The num_value in the payload for each of the registers will be the actual value last seen by the SmartSwarm device on the Modbus network.
96
If there are no Input Registers, Discrete Inputs, or Coils defined for the slave, then there will be place-holders in the published JSON data schema to show where the data for those register values would be, if they existed.
If there has not been any actual data seen on Modbus for a slave register it will not appear in the payload.
Here’s an example payload, where there are only holding registers defined (and observed) for the Slave:
{ "model": { "state": { "CS": [], "HR": [{ "value_from": "RESPONSE", "published_on": "HI\/ON", "name": "HR_1", "min": 0, "address_offset": 0, "max": 100, "zero_value": 0, "num_value": 113.000000, "scaling": 1, "alias": "Water Temperature", "state": "VALIDATED", "var_pct": 31.000000, "at": "2016-07-14T19:36:29.127Z", "address": 1, "units": "Deg C", "new_value": true, "new_read": true }, { "value_from": "RESPONSE", "published_on": "HI\/ON", "name": "HR_2", "min": -10, "address_offset": 0, "max": 40, "zero_value": 0, "num_value": 23104.000000, "scaling": 1, "alias": "Air Temperature", "state": "VALIDATED", "var_pct": 0, "at": "2016-07-14T19:36:29.127Z", "address": 2, "units": "Deg C", "new_value": false, "new_read": true }, { "value_from": "RESPONSE", "published_on": "HI\/ON", "name": "HR_3", "min": 0, "address_offset": 0, "max": 90, "zero_value": 0, "num_value": 0.000000, "scaling": 1, "alias": "Humidity", "state": "VALIDATED", "var_pct": 0, "at": "2016-07-14T19:36:29.127Z", "address": 3, "units": "%", "new_value": false, "new_read": true
97
}], "IS": [], "IR": [] }, "meta": { "description": "Slave_1", "value_byte_order": "SNo", "name": "Power_Meter", "installation_date": "14\/07\/2016", "location": "Test_Rack", "address": { "DEVID": "6500004", "PORTID": 1, "SLAVEID": 10, "SWMID": 0 }, "manufacturer": "NA" } }, "type": "ModbusSlave", "id": "10_HR_1_HI" }
Here’s an example payload when there are Holding Registers, Coils, Discrete Inputs and Input Registers defined (or
observed) for the slave. In this example, there is 1 Coil, 3 Holding Registers, 2 Inputs, and 2 Input Registers (one of them is an ENUM, with 3 enumerated associated values):
{ "model": { "state": { "CS": [{ "published_on": "HI\/OFF", "name": "CoilExample", "str_value": "OutsideBounds", "num_value": 0, "value_from": "RESPONSE", "alias": "This is a Coil Example", "state": "VALIDATED", "var_pct": 0, "new_read": false, "address": 1, "new_value": false, "at": "2016-07-15T15:11:00.373Z" }], "HR": [{ "value_from": "RESPONSE", "published_on": "HI\/OFF", "name": "HR_1", "min": 0, "address_offset": 0, "max": 100, "zero_value": 0, "num_value": 89.000000, "scaling": 1, "alias": "Water Temperature", "state": "VALIDATED", "var_pct": 17.000000, "at": "2016-07-15T15:16:51.407Z", "address": 1, "units": "Deg C", "new_value": true, "new_read": true }, { "value_from": "RESPONSE", "published_on": "HI\/OFF", "name": "HR_2",
98
"value_from": "RESPONSE", "alias": "This is a Coil Example", "state": "VALIDATED", "var_pct": 0, "new_read": false, "address": 1, "new_value": false, "at": "2016-07-15T15:11:00.373Z" }], "HR": [{ "value_from": "RESPONSE", "published_on": "HI\/OFF", "name": "HR_1", "min": 0, "address_offset": 0, "max": 100, "zero_value": 0, "num_value": 89.000000, "scaling": 1, "alias": "Water Temperature", "state": "VALIDATED", "var_pct": 17.000000, "at": "2016-07-15T15:16:51.407Z", "address": 1, "units": "Deg C", "new_value": true, "new_read": true }, { "value_from": "RESPONSE", "published_on": "HI\/OFF", "name": "HR_2", "min": -10, "address_offset": 0, "max": 40, "zero_value": 0, "num_value": 115.000000, "scaling": 1, "alias": "Air Temperature", "state": "VALIDATED", "var_pct": 8.000000, "at": "2016-07-15T15:16:51.407Z", "address": 2, "units": "Deg C", "new_value": true, "new_read": true }, { "value_from": "RESPONSE", "published_on": "HI\/OFF", "name": "HR_3", "min": 0, "address_offset": 0, "max": 90, "zero_value": 0, "num_value": 31147.000000, "scaling": 1, "alias": "Humidity", "state": "VALIDATED", "var_pct": 86.000000, "at": "2016-07-15T15:16:51.407Z", "address": 3, "units": "%", "new_value": true, "new_read": true }], "IS": [{ "published_on": "HI\/OFF", "name": "Input Power Invertor",
99
"str_value": "On", "num_value": 1, "value_from": "RESPONSE", "alias": "IPV", "state": "VALIDATED", "var_pct": 100, "new_read": false, "address": 6, "new_value": false, "at": "2016-07-15T15:12:37.350Z" }, { "published_on": "HI\/OFF", "name": "Battery Status", "str_value": "Good", "num_value": 0, "value_from": "RESPONSE", "alias": "BS", "state": "VALIDATED", "var_pct": 100.000000, "new_read": false, "address": 7, "new_value": false, "at": "2016-07-15T15:12:37.350Z" "IR": [{ "published_on": "HI\/OFF", "name": "Num Battery Inputs", "address_offset": 0, "num_value": 13, "value_from": "RESPONSE", "alias": "Batt_Inputs", "state": "VALIDATED", "var_pct": 18.000000, "new_read": false, "address": 55, "new_value": false, "at": "2016-07-15T15:14:37.395Z" }, { "published_on": "HI\/OFF", "name": "Num Battery Outputs", "address_offset": 4, "num_value": 2, "value_from": "RESPONSE", "alias": "Batt_Outputs", "state": "VALIDATED", "var_pct": 0, "new_read": false, "address": 55, "new_value": false, "at": "2016-07-15T15:14:37.395Z" }, { "published_on": "HI\/OFF", "name": "Num Indicator Outputs", "address_offset": 8, "num_value": 0, "value_from": "RESPONSE", "alias": "Indicator_Outputs", "state": "VALIDATED", "var_pct": 0, "new_read": false, "address": 55, "new_value": false, "at": "2016-07-15T15:14:37.395Z" }, { "value_from": "RESPONSE", "published_on": "HI\/OFF", "name": "Operating Frequency", "address_offset": 0,
100
Loading...
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use