B+B SmartWorx SmartSwarm 300 User manual

SmartSwarm 300 Series
User Manual
WWW.INFOPULSAS.LT / [email protected]

SmartSwarm 300 Series:
2
Advantech B+B SmartWorx Americas
707 Dayton Road
Ottawa, IL 61350 USA
Phone [phone]
Fax [phone]
Advantech B+B SmartWorx European Headquarters
Westlink Commercial Park
Oranmore, Co. Galway, Ireland
Phone [phone]
Fax [phone]
www.advantech-bb.com
[e-mail]
Document: SmartSwarm_300_R1_3416.docx

SmartSwarm 300 Series:
3
CONTENTS
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

SmartSwarm 300 Series:
4
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

SmartSwarm 300 Series:
5
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

SmartSwarm 300 Series:
6
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

SmartSwarm 300 Series:
7
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 OF 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

SmartSwarm 300 Series:
8
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

SmartSwarm 300 Series:
9
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

SmartSwarm 300 Series:
10
1. INTRODUCTION
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.

SmartSwarm 300 Series:
11
1.1 WHY ENRICH 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 WHY 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 WHY 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 SAMPLING 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.

SmartSwarm 300 Series:
12
2. DOCUMENT STRUCTURE
This document is organized in accordance with the following flow.
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

SmartSwarm 300 Series:
13

SmartSwarm 300 Series:
14
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.

SmartSwarm 300 Series:
15
3. EXAMPLE WORKFLOW
In this section we will walk through an example workflow.
3.1 CONNECT 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 CONFIGURE YOUR DEVICE’S CONNECTIVITY 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.

SmartSwarm 300 Series:
16
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.

SmartSwarm 300 Series:
17
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.

SmartSwarm 300 Series:
18
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 CONFIGURE 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.

SmartSwarm 300 Series:
19
Now configure the Modbus Settings so that they match the actual Modbus configuration of your Modbus network.
Apply the changes.

SmartSwarm 300 Series:
20
3.4 CONFIGURE 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.